ascon.h

Functions

	Name
int	wc_AsconHash256_Init(wc_AsconHash256 * a) This function initializes the ASCON context for hashing.
int	wc_AsconHash256_Update(wc_AsconHash256 * a, const byte * data, word32 dataSz) This function updates the ASCON hash with the input data.
int	wc_AsconHash256_Final(wc_AsconHash256 * a, byte * hash) This function finalizes the ASCON hash and produces the output.
wc_AsconAEAD128 *	wc_AsconAEAD128_New(void ) This function allocates and initializes a new Ascon AEAD context.
void	wc_AsconAEAD128_Free(wc_AsconAEAD128 * a) This function frees the resources associated with the Ascon AEAD context.
int	wc_AsconAEAD128_Init(wc_AsconAEAD128 * a) This function initializes an Ascon AEAD context.
void	wc_AsconAEAD128_Clear(wc_AsconAEAD128 * a) This function deinitializes an Ascon AEAD context. It does not free the context.
int	wc_AsconAEAD128_SetKey(wc_AsconAEAD128 * a, const byte * key) This function sets the key for the Ascon AEAD context.
int	wc_AsconAEAD128_SetNonce(wc_AsconAEAD128 * a, const byte * nonce) This function sets the nonce for the Ascon AEAD context.
int	wc_AsconAEAD128_SetAD(wc_AsconAEAD128 * a, const byte * ad, word32 adSz) This function sets the associated data for the Ascon AEAD context.
int	wc_AsconAEAD128_EncryptUpdate(wc_AsconAEAD128 * a, byte * out, const byte * in, word32 inSz) This function encrypts a plaintext message using Ascon AEAD. The output is stored in the out buffer. The length of the output is equal to the length of the input.
int	wc_AsconAEAD128_EncryptFinal(wc_AsconAEAD128 * a, byte * tag) This function finalizes the encryption process using Ascon AEAD and produces the authentication tag.
int	wc_AsconAEAD128_DecryptUpdate(wc_AsconAEAD128 * a, byte * out, const byte * in, word32 inSz) This function updates the decryption process using Ascon AEAD. The output is stored in the out buffer. The length of the output is equal to the length of the input.
int	wc_AsconAEAD128_DecryptFinal(wc_AsconAEAD128 * a, const byte * tag) This function finalizes the decryption process using Ascon AEAD and verifies the authentication tag.
wc_AsconHash256 *	wc_AsconHash256_New(void ) This function allocates and initializes a new Ascon Hash256 context. The returned context must be freed with wc_AsconHash256_Free when no longer needed.
void	wc_AsconHash256_Free(wc_AsconHash256 * a) This function frees an Ascon Hash256 context that was allocated with wc_AsconHash256_New. It clears the context before freeing to prevent information leakage.
void	wc_AsconHash256_Clear(wc_AsconHash256 * a) This function clears an Ascon Hash256 context by zeroing all internal state. This should be called to securely erase sensitive data from memory.

Functions Documentation

function wc_AsconHash256_Init

int wc_AsconHash256_Init(
    wc_AsconHash256 * a
)

This function initializes the ASCON context for hashing.

Parameters:

• a pointer to the ASCON context to initialize.

See:

• wc_AsconHash256_Update
• wc_AsconHash256_Final

Return:

• 0 on success.
• BAD_FUNC_ARG if the context pointer is NULL.

Example

wc_AsconHash256 a;
byte data[] = {0x01, 0x02, 0x03};
byte hash[ASCON_HASH256_SZ];

if (wc_AsconHash256_Init(&a) != 0)
    // handle error
if (wc_AsconHash256_Update(&ctx, data, sizeof(data)) != 0)
    // handle error
if (wc_AsconHash256_Final(&ctx, hash, sizeof(hash)) != 0)
    // handle error
// hash contains the final hash

function wc_AsconHash256_Update

int wc_AsconHash256_Update(
    wc_AsconHash256 * a,
    const byte * data,
    word32 dataSz
)

This function updates the ASCON hash with the input data.

Parameters:

• ctx pointer to the ASCON context.
• in pointer to the input data.
• inSz size of the input data.

See:

• wc_AsconHash256_Init
• wc_AsconHash256_Final

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or input pointer is NULL.

Example

wc_AsconHash256 a;
byte data[] = {0x01, 0x02, 0x03};
byte hash[ASCON_HASH256_SZ];

if (wc_AsconHash256_Init(&a) != 0)
    // handle error
if (wc_AsconHash256_Update(&ctx, data, sizeof(data)) != 0)
    // handle error
if (wc_AsconHash256_Final(&ctx, hash, sizeof(hash)) != 0)
    // handle error
// hash contains the final hash

function wc_AsconHash256_Final

int wc_AsconHash256_Final(
    wc_AsconHash256 * a,
    byte * hash
)

This function finalizes the ASCON hash and produces the output.

Parameters:

• ctx pointer to the ASCON context.
• out pointer to the output buffer.
• outSz size of the output buffer, should be at least ASCON_HASH256_SZ.

See:

• wc_AsconHash256_Init
• wc_AsconHash256_Update

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or output pointer is NULL.

Example

wc_AsconHash256 a;
byte data[] = {0x01, 0x02, 0x03};
byte hash[ASCON_HASH256_SZ];

if (wc_AsconHash256_Init(&a) != 0)
    // handle error
if (wc_AsconHash256_Update(&ctx, data, sizeof(data)) != 0)
    // handle error
if (wc_AsconHash256_Final(&ctx, hash, sizeof(hash)) != 0)
    // handle error
// hash contains the final hash

function wc_AsconAEAD128_New

wc_AsconAEAD128 * wc_AsconAEAD128_New(
    void 
)

This function allocates and initializes a new Ascon AEAD context.

See:

• wc_AsconAEAD128_Free
• wc_AsconAEAD128_Free
• wc_AsconAEAD128_Init

Return:

• pointer to the newly allocated Ascon AEAD context
• NULL on failure.
• Pointer to allocated wc_AsconAEAD128 structure on success.
• NULL on allocation or initialization failure.

This function allocates and initializes a new Ascon AEAD128 context. The returned context must be freed with wc_AsconAEAD128_Free when no longer needed.

Example

wc_AsconAEAD128* a = wc_AsconAEAD128_New();
if (a == NULL) {
    // handle allocation error
}
wc_AsconAEAD128_Free(a);

Example

wc_AsconAEAD128* aead = wc_AsconAEAD128_New();
if (aead == NULL) {
    // handle allocation error
}
byte key[ASCON_AEAD128_KEY_SZ] = { }; // key
byte nonce[ASCON_AEAD128_NONCE_SZ] = { }; // nonce
wc_AsconAEAD128_SetKey(aead, key);
wc_AsconAEAD128_SetNonce(aead, nonce);
// perform encryption/decryption
wc_AsconAEAD128_Free(aead);

function wc_AsconAEAD128_Free

void wc_AsconAEAD128_Free(
    wc_AsconAEAD128 * a
)

This function frees the resources associated with the Ascon AEAD context.

Parameters:

• a pointer to the Ascon AEAD context to free.

See: wc_AsconAEAD128_New

Example

wc_AsconAEAD128* a = wc_AsconAEAD128_New();
if (a == NULL) {
    // handle allocation error
}
// Use the context
wc_AsconAEAD128_Free(a);

function wc_AsconAEAD128_Init

int wc_AsconAEAD128_Init(
    wc_AsconAEAD128 * a
)

This function initializes an Ascon AEAD context.

Parameters:

• a pointer to the Ascon AEAD context to initialize.

See:

• wc_AsconAeadEncrypt
• wc_AsconAeadDecrypt

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or output pointer is NULL.

Example

AsconAead a;

if (wc_AsconAEAD128_Init(&a) != 0)
    // handle error

function wc_AsconAEAD128_Clear

void wc_AsconAEAD128_Clear(
    wc_AsconAEAD128 * a
)

This function deinitializes an Ascon AEAD context. It does not free the context.

Parameters:

• a pointer to the Ascon AEAD context to deinitialize.

See:

• wc_AsconAeadEncrypt
• wc_AsconAeadDecrypt

Example

AsconAead a;

if (wc_AsconAEAD128_Init(&a) != 0)
    // handle error
wc_AsconAEAD128_Clear(&a);

function wc_AsconAEAD128_SetKey

int wc_AsconAEAD128_SetKey(
    wc_AsconAEAD128 * a,
    const byte * key
)

This function sets the key for the Ascon AEAD context.

Parameters:

• a pointer to the initialized Ascon AEAD context.
• key pointer to the key buffer of length ASCON_AEAD128_KEY_SZ.

See:

• wc_AsconAEAD128_Init
• wc_AsconAEAD128_SetNonce
• wc_AsconAEAD128_SetAD

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or key pointer is NULL.
• BAD_STATE_E if the key has already been set.

Example

wc_AsconAEAD128 a;
byte key[ASCON_AEAD128_KEY_SZ] = { ... };

if (wc_AsconAEAD128_Init(&a) != 0)
    // handle error
if (wc_AsconAEAD128_SetKey(&a, key) != 0)
    // handle error

function wc_AsconAEAD128_SetNonce

int wc_AsconAEAD128_SetNonce(
    wc_AsconAEAD128 * a,
    const byte * nonce
)

This function sets the nonce for the Ascon AEAD context.

Parameters:

• a pointer to the initialized Ascon AEAD context.
• nonce pointer to the nonce buffer of length ASCON_AEAD128_NONCE_SZ.

See:

• wc_AsconAEAD128_Init
• wc_AsconAEAD128_SetKey
• wc_AsconAEAD128_SetAD

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or nonce pointer is NULL.
• BAD_STATE_E if the nonce has already been set.

Example

wc_AsconAEAD128 a;
byte nonce[ASCON_AEAD128_NONCE_SZ] = { ... };

if (wc_AsconAEAD128_Init(&a) != 0)
    // handle error
if (wc_AsconAEAD128_SetNonce(&a, nonce) != 0)
    // handle error

function wc_AsconAEAD128_SetAD

int wc_AsconAEAD128_SetAD(
    wc_AsconAEAD128 * a,
    const byte * ad,
    word32 adSz
)

This function sets the associated data for the Ascon AEAD context.

Parameters:

• a pointer to the initialized Ascon AEAD context.
• ad pointer to the associated data buffer.
• adSz size of the associated data buffer.

See:

• wc_AsconAEAD128_Init
• wc_AsconAEAD128_SetKey
• wc_AsconAEAD128_SetNonce

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or associated data pointer is NULL.
• BAD_STATE_E if the key or nonce has not been set.

Example

wc_AsconAEAD128 a;
byte key[ASCON_AEAD128_KEY_SZ] = { ... };
byte nonce[ASCON_AEAD128_NONCE_SZ] = { ... };
byte ad[] = { ... };

if (wc_AsconAEAD128_Init(&a) != 0)
    // handle error
if (wc_AsconAEAD128_SetKey(&a, key) != 0)
    // handle error
if (wc_AsconAEAD128_SetNonce(&a, nonce) != 0)
    // handle error
if (wc_AsconAEAD128_SetAD(&a, ad, sizeof(ad)) != 0)
    // handle error

function wc_AsconAEAD128_EncryptUpdate

int wc_AsconAEAD128_EncryptUpdate(
    wc_AsconAEAD128 * a,
    byte * out,
    const byte * in,
    word32 inSz
)

This function encrypts a plaintext message using Ascon AEAD. The output is stored in the out buffer. The length of the output is equal to the length of the input.

Parameters:

• a pointer to the initialized Ascon AEAD context.
• out pointer to the output buffer to store the ciphertext.
• in pointer to the input buffer containing the plaintext message.
• inSz length of the input buffer.

See:

• wc_AsconAeadInit
• wc_AsconAEAD128_Clear
• wc_AsconAEAD128_SetKey
• wc_AsconAEAD128_SetNonce
• wc_AsconAEAD128_SetAD
• wc_AsconAEAD128_EncryptFinal
• wc_AsconAEAD128_DecryptUpdate
• wc_AsconAEAD128_DecryptFinal

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or output pointer is NULL or the input is NULL while the input size is greater than 0.
• BAD_STATE_E if the key, nonce, or additional data has not been set or the context was previously used for decryption.

Example

wc_AsconAEAD128 a;
byte key[ASCON_AEAD128_KEY_SZ] = { ... };
byte nonce[ASCON_AEAD128_NONCE_SZ] = { ... };
byte plaintext[PLAIN_TEXT_SIZE] = { ... };
byte ciphertext[CIPHER_TEXT_SIZE];
byte tag[ASCON_AEAD128_TAG_SZ] = { ... };

if (wc_AsconAeadInit(&a) != 0)
    // handle error
if (wc_AsconAEAD128_SetKey(&a, key) != 0)
    // handle error
if (wc_AsconAEAD128_SetNonce(&a, nonce) != 0)
    // handle error
if (wc_AsconAEAD128_SetAD(&a, ad, sizeof(ad)) != 0)
    // handle error
if (wc_AsconAEAD128_EncryptUpdate(&a, ciphertext, plaintext,
                                  sizeof(plaintext)) != 0)
    // handle error
if (wc_AsconAEAD128_EncryptFinal(&a, tag) != 0)
    // handle error

function wc_AsconAEAD128_EncryptFinal

int wc_AsconAEAD128_EncryptFinal(
    wc_AsconAEAD128 * a,
    byte * tag
)

This function finalizes the encryption process using Ascon AEAD and produces the authentication tag.

Parameters:

• a pointer to the initialized Ascon AEAD context.
• tag pointer to the output buffer to store the authentication tag.

See:

• wc_AsconAEAD128_Init
• wc_AsconAEAD128_SetKey
• wc_AsconAEAD128_SetNonce
• wc_AsconAEAD128_SetAD
• wc_AsconAEAD128_EncryptUpdate
• wc_AsconAEAD128_DecryptUpdate
• wc_AsconAEAD128_DecryptFinal

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or output pointer is NULL or the input is NULL while the input size is greater than 0.
• BAD_STATE_E if the key, nonce, or additional data has not been set or the context was previously used for decryption.

Example

wc_AsconAEAD128 a;
byte key[ASCON_AEAD128_KEY_SZ] = { ... };
byte nonce[ASCON_AEAD128_NONCE_SZ] = { ... };
byte plaintext[PLAIN_TEXT_SIZE] = { ... };
byte ciphertext[CIPHER_TEXT_SIZE];
byte tag[ASCON_AEAD128_TAG_SZ] = { ... };

if (wc_AsconAeadInit(&a) != 0)
    // handle error
if (wc_AsconAEAD128_SetKey(&a, key) != 0)
    // handle error
if (wc_AsconAEAD128_SetNonce(&a, nonce) != 0)
    // handle error
if (wc_AsconAEAD128_SetAD(&a, ad, sizeof(ad)) != 0)
    // handle error
if (wc_AsconAEAD128_EncryptUpdate(&a, ciphertext, plaintext,
                                  sizeof(plaintext)) != 0)
    // handle error
if (wc_AsconAEAD128_EncryptFinal(&a, tag) != 0)
    // handle error

function wc_AsconAEAD128_DecryptUpdate

int wc_AsconAEAD128_DecryptUpdate(
    wc_AsconAEAD128 * a,
    byte * out,
    const byte * in,
    word32 inSz
)

This function updates the decryption process using Ascon AEAD. The output is stored in the out buffer. The length of the output is equal to the length of the input.

Parameters:

• a pointer to the initialized Ascon AEAD context.
• out pointer to the output buffer to store the plaintext.
• in pointer to the input buffer containing the ciphertext message.
• inSz length of the input buffer.

See:

• wc_AsconAEAD128_Init
• wc_AsconAEAD128_SetKey
• wc_AsconAEAD128_SetNonce
• wc_AsconAEAD128_SetAD
• wc_AsconAEAD128_EncryptUpdate
• wc_AsconAEAD128_EncryptFinal
• wc_AsconAEAD128_DecryptFinal

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or output pointer is NULL or the input is NULL while the input size is greater than 0.
• BAD_STATE_E if the key, nonce, or additional data has not been set or the context was previously used for encryption.

Example

wc_AsconAEAD128 a;
byte key[ASCON_AEAD128_KEY_SZ] = { ... };
byte nonce[ASCON_AEAD128_NONCE_SZ] = { ... };
byte ciphertext[CIPHER_TEXT_SIZE] = { ... };
byte plaintext[PLAIN_TEXT_SIZE];
byte tag[ASCON_AEAD128_TAG_SZ] = { ... };

if (wc_AsconAeadInit(&a) != 0)
    // handle error
if (wc_AsconAEAD128_SetKey(&a, key) != 0)
    // handle error
if (wc_AsconAEAD128_SetNonce(&a, nonce) != 0)
    // handle error
if (wc_AsconAEAD128_SetAD(&a, ad, sizeof(ad)) != 0)
    // handle error
if (wc_AsconAEAD128_DecryptUpdate(&a, plaintext, ciphertext,
                                  sizeof(ciphertext)) != 0)
    // handle error
if (wc_AsconAEAD128_DecryptFinal(&a, tag) != 0)
    // handle error

function wc_AsconAEAD128_DecryptFinal

int wc_AsconAEAD128_DecryptFinal(
    wc_AsconAEAD128 * a,
    const byte * tag
)

This function finalizes the decryption process using Ascon AEAD and verifies the authentication tag.

Parameters:

• a pointer to the initialized Ascon AEAD context.
• tag pointer to the buffer containing the authentication tag to verify

See:

• wc_AsconAEAD128_Init
• wc_AsconAEAD128_SetKey
• wc_AsconAEAD128_SetNonce
• wc_AsconAEAD128_SetAD
• wc_AsconAEAD128_DecryptUpdate
• wc_AsconAEAD128_EncryptUpdate
• wc_AsconAEAD128_EncryptFinal

Return:

• 0 on success.
• BAD_FUNC_ARG if the context or tag pointer is NULL.
• BAD_STATE_E if the key, nonce, or additional data has not been set or the context was previously used for encryption.
• ASCON_AUTH_E if the authentication tag does not match.

Example

wc_AsconAEAD128 a;
byte key[ASCON_AEAD128_KEY_SZ] = { ... };
byte nonce[ASCON_AEAD128_NONCE_SZ] = { ... };
byte ciphertext[CIPHER_TEXT_SIZE] = { ... };
byte plaintext[PLAIN_TEXT_SIZE];
byte tag[ASCON_AEAD128_TAG_SZ] = { ... };

if (wc_AsconAeadInit(&a) != 0)
    // handle error
if (wc_AsconAEAD128_SetKey(&a, key) != 0)
    // handle error
if (wc_AsconAEAD128_SetNonce(&a, nonce) != 0)
    // handle error
if (wc_AsconAEAD128_SetAD(&a, ad, sizeof(ad)) != 0)
    // handle error
if (wc_AsconAEAD128_DecryptUpdate(&a, plaintext, ciphertext,
                                  sizeof(ciphertext)) != 0)
    // handle error
if (wc_AsconAEAD128_DecryptFinal(&a, tag) != 0)
    // handle error

function wc_AsconHash256_New

wc_AsconHash256 * wc_AsconHash256_New(
    void 
)

This function allocates and initializes a new Ascon Hash256 context. The returned context must be freed with wc_AsconHash256_Free when no longer needed.

See:

• wc_AsconHash256_Free
• wc_AsconHash256_Init

Return:

• Pointer to allocated wc_AsconHash256 structure on success.
• NULL on allocation or initialization failure.

Example

wc_AsconHash256* hash = wc_AsconHash256_New();
if (hash == NULL) {
    // handle allocation error
}
byte data[]; // data to hash
wc_AsconHash256_Update(hash, data, sizeof(data));
byte digest[ASCON_HASH256_SZ];
wc_AsconHash256_Final(hash, digest);
wc_AsconHash256_Free(hash);

function wc_AsconHash256_Free

void wc_AsconHash256_Free(
    wc_AsconHash256 * a
)

This function frees an Ascon Hash256 context that was allocated with wc_AsconHash256_New. It clears the context before freeing to prevent information leakage.

Parameters:

• a pointer to the wc_AsconHash256 structure to free

See:

• wc_AsconHash256_New
• wc_AsconHash256_Clear

Return: none No return value.

Example

wc_AsconHash256* hash = wc_AsconHash256_New();
if (hash != NULL) {
    // use hash context
    wc_AsconHash256_Free(hash);
}

function wc_AsconHash256_Clear

void wc_AsconHash256_Clear(
    wc_AsconHash256 * a
)

This function clears an Ascon Hash256 context by zeroing all internal state. This should be called to securely erase sensitive data from memory.

Parameters:

• a pointer to the wc_AsconHash256 structure to clear

See:

• wc_AsconHash256_Init
• wc_AsconHash256_Free

Return: none No return value.

Example

wc_AsconHash256 hash;
wc_AsconHash256_Init(&hash);
byte data[]; // data to hash
wc_AsconHash256_Update(&hash, data, sizeof(data));
byte digest[ASCON_HASH256_SZ];
wc_AsconHash256_Final(&hash, digest);
wc_AsconHash256_Clear(&hash);

Source code

int wc_AsconHash256_Init(wc_AsconHash256* a);

int wc_AsconHash256_Update(wc_AsconHash256* a, const byte* data, word32 dataSz);

int wc_AsconHash256_Final(wc_AsconHash256* a, byte* hash);

wc_AsconAEAD128* wc_AsconAEAD128_New(void);

void wc_AsconAEAD128_Free(wc_AsconAEAD128 *a);


int wc_AsconAEAD128_Init(wc_AsconAEAD128* a);

void wc_AsconAEAD128_Clear(wc_AsconAEAD128 *a);

int wc_AsconAEAD128_SetKey(wc_AsconAEAD128* a, const byte* key);

int wc_AsconAEAD128_SetNonce(wc_AsconAEAD128* a, const byte* nonce);

int wc_AsconAEAD128_SetAD(wc_AsconAEAD128* a, const byte* ad, word32 adSz);

int wc_AsconAEAD128_EncryptUpdate(wc_AsconAEAD128* a, byte* out, const byte* in,
                                  word32 inSz);

int wc_AsconAEAD128_EncryptFinal(wc_AsconAEAD128* a, byte* tag);

int wc_AsconAEAD128_DecryptUpdate(wc_AsconAEAD128* a, byte* out, const byte* in,
                                  word32 inSz);

int wc_AsconAEAD128_DecryptFinal(wc_AsconAEAD128* a, const byte* tag);

wc_AsconHash256* wc_AsconHash256_New(void);

void wc_AsconHash256_Free(wc_AsconHash256* a);

void wc_AsconHash256_Clear(wc_AsconHash256* a);

wc_AsconAEAD128* wc_AsconAEAD128_New(void);

---

Updated on 2025-12-31 at 01:16:03 +0000