int wc_ChaCha20Poly1305_Encrypt(    const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE],    const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE],    const byte * inAAD,    word32 inAADLen,    const byte * inPlaintext,    word32 inPlaintextLen,    byte * outCiphertext,    byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE])

• wc_ChaCha20Poly1305_Decrypt
• wc_ChaCha_*
• wc_Poly1305*

Return:

• 0 Returned upon successfully encrypting the message
• BAD_FUNC_ARG returned if there is an error during the encryption process

Example

byte key[] = { // initialize 32 byte key };byte iv[]  = { // initialize 12 byte key };byte inAAD[] = { // initialize AAD };byte plain[] = { // initialize message to encrypt };byte cipher[sizeof(plain)];byte authTag[16];int ret = wc_ChaCha20Poly1305_Encrypt(key, iv, inAAD, sizeof(inAAD),plain, sizeof(plain), cipher, authTag);if(ret != 0) {    // error running encrypt}

function wc_ChaCha20Poly1305_Decrypt

int wc_ChaCha20Poly1305_Decrypt(    const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE],    const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE],    const byte * inAAD,    word32 inAADLen,    const byte * inCiphertext,    word32 inCiphertextLen,    const byte inAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE],    byte * outPlaintext)

This function decrypts input ciphertext, inCiphertext, using the ChaCha20 stream cipher, into the output buffer, outPlaintext. It also performs Poly-1305 authentication, comparing the given inAuthTag to an authentication generated with the inAAD (arbitrary length additional authentication data). If a nonzero error code is returned, the output data, outPlaintext, is undefined. However, callers must unconditionally zeroize the output buffer to guard against leakage of cleartext data.

Parameters:

• inKey pointer to a buffer containing the 32 byte key to use for decryption
• inIv pointer to a buffer containing the 12 byte iv to use for decryption
• inAAD pointer to the buffer containing arbitrary length additional authenticated data (AAD)
• inAADLen length of the input AAD
• inCiphertext pointer to the buffer containing the ciphertext to decrypt
• outCiphertextLen the length of the ciphertext to decrypt
• inAuthTag pointer to the buffer containing the 16 byte digest for authentication
• outPlaintext pointer to the buffer in which to store the plaintext

See:

• wc_ChaCha20Poly1305_Encrypt
• wc_ChaCha_*
• wc_Poly1305*

Return:

• 0 Returned upon successfully decrypting and authenticating the message
• BAD_FUNC_ARG Returned if any of the function arguments do not match what is expected
• MAC_CMP_FAILED_E Returned if the generated authentication tag does not match the supplied inAuthTag.
• MEMORY_E Returned if internal buffer allocation failed.
• CHACHA_POLY_OVERFLOW Can be returned if input is corrupted.

Example

byte key[]   = { // initialize 32 byte key };byte iv[]    = { // initialize 12 byte key };byte inAAD[] = { // initialize AAD };byte cipher[]    = { // initialize with received ciphertext };byte authTag[16] = { // initialize with received authentication tag };byte plain[sizeof(cipher)];int ret = wc_ChaCha20Poly1305_Decrypt(key, iv, inAAD, sizeof(inAAD),cipher, sizeof(cipher), authTag, plain);if(ret == MAC_CMP_FAILED_E) {    // error during authentication} else if( ret != 0) {    // error with function arguments}

function wc_ChaCha20Poly1305_CheckTag

int wc_ChaCha20Poly1305_CheckTag(    const byte authTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE],    const byte authTagChk[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE])

Compares two authentication tags in constant time to prevent timing attacks.

Parameters:

• authTag First authentication tag
• authTagChk Second authentication tag to compare

See:wc_ChaCha20Poly1305_Decrypt

Return:

• 0 If tags match
• MAC_CMP_FAILED_E If tags do not match

Example

byte tag1[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE];byte tag2[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE];int ret = wc_ChaCha20Poly1305_CheckTag(tag1, tag2);if (ret != 0) {    // tags do not match}

function wc_ChaCha20Poly1305_Init

int wc_ChaCha20Poly1305_Init(    ChaChaPoly_Aead * aead,    const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE],    const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE],    int isEncrypt)

Initializes a ChaChaPoly_Aead structure for incremental encryption or decryption operations.

Parameters:

• aead Pointer to ChaChaPoly_Aead structure to initialize
• inKey 32-byte encryption key
• inIV 12-byte initialization vector
• isEncrypt 1 for encryption, 0 for decryption

See:

• wc_ChaCha20Poly1305_UpdateAad
• wc_ChaCha20Poly1305_UpdateData
• wc_ChaCha20Poly1305_Final

Return:

• 0 On success
• BAD_FUNC_ARG If parameters are invalid

Example

ChaChaPoly_Aead aead;byte key[CHACHA20_POLY1305_AEAD_KEYSIZE];byte iv[CHACHA20_POLY1305_AEAD_IV_SIZE];int ret = wc_ChaCha20Poly1305_Init(&aead, key, iv, 1);if (ret != 0) {    // error initializing}

function wc_ChaCha20Poly1305_UpdateAad

int wc_ChaCha20Poly1305_UpdateAad(    ChaChaPoly_Aead * aead,    const byte * inAAD,    word32 inAADLen)

Updates the AEAD context with additional authenticated data (AAD). Must be called after Init and before UpdateData.

Parameters:

• aead Pointer to initialized ChaChaPoly_Aead structure
• inAAD Additional authenticated data
• inAADLen Length of AAD in bytes

See:

• wc_ChaCha20Poly1305_Init
• wc_ChaCha20Poly1305_UpdateData

Return:

• 0 On success
• BAD_FUNC_ARG If parameters are invalid

Example

ChaChaPoly_Aead aead;byte aad[]; // AAD datawc_ChaCha20Poly1305_Init(&aead, key, iv, 1);int ret = wc_ChaCha20Poly1305_UpdateAad(&aead, aad, sizeof(aad));if (ret != 0) {    // error updating AAD}

function wc_ChaCha20Poly1305_UpdateData

int wc_ChaCha20Poly1305_UpdateData(    ChaChaPoly_Aead * aead,    const byte * inData,    byte * outData,    word32 dataLen)

Encrypts or decrypts data incrementally. Can be called multiple times to process data in chunks.

Parameters:

• aead Pointer to initialized ChaChaPoly_Aead structure
• inData Input data (plaintext or ciphertext)
• outData Output buffer for result
• dataLen Length of data to process

See:

• wc_ChaCha20Poly1305_Init
• wc_ChaCha20Poly1305_Final

Return:

• 0 On success
• BAD_FUNC_ARG If parameters are invalid

Example

ChaChaPoly_Aead aead;byte plain[]; // plaintextbyte cipher[sizeof(plain)];wc_ChaCha20Poly1305_Init(&aead, key, iv, 1);wc_ChaCha20Poly1305_UpdateAad(&aead, aad, aadLen);int ret = wc_ChaCha20Poly1305_UpdateData(&aead, plain,                                         cipher, sizeof(plain));

function wc_ChaCha20Poly1305_Final

int wc_ChaCha20Poly1305_Final(    ChaChaPoly_Aead * aead,    byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE])

Finalizes the AEAD operation and generates the authentication tag.

Parameters:

• aead Pointer to ChaChaPoly_Aead structure
• outAuthTag Buffer to store 16-byte authentication tag

See:

• wc_ChaCha20Poly1305_Init
• wc_ChaCha20Poly1305_UpdateData

Return:

• 0 On success
• BAD_FUNC_ARG If parameters are invalid

Example

ChaChaPoly_Aead aead;byte authTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE];wc_ChaCha20Poly1305_Init(&aead, key, iv, 1);wc_ChaCha20Poly1305_UpdateAad(&aead, aad, aadLen);wc_ChaCha20Poly1305_UpdateData(&aead, plain, cipher, plainLen);int ret = wc_ChaCha20Poly1305_Final(&aead, authTag);

function wc_XChaCha20Poly1305_Init

int wc_XChaCha20Poly1305_Init(    ChaChaPoly_Aead * aead,    const byte * ad,    word32 ad_len,    const byte * inKey,    word32 inKeySz,    const byte * inIV,    word32 inIVSz,    int isEncrypt)

Initializes XChaCha20-Poly1305 AEAD with extended nonce. XChaCha20 uses a 24-byte nonce instead of 12-byte.

Parameters:

• aead Pointer to ChaChaPoly_Aead structure
• ad Additional authenticated data
• ad_len Length of AAD
• inKey Encryption key
• inKeySz Key size (must be 32)
• inIV Initialization vector
• inIVSz IV size (must be 24 for XChaCha20)
• isEncrypt 1 for encryption, 0 for decryption

See:

• wc_XChaCha20Poly1305_Encrypt
• wc_XChaCha20Poly1305_Decrypt

Return:

• 0 On success
• BAD_FUNC_ARG If parameters are invalid

Example

ChaChaPoly_Aead aead;byte key[32];byte iv[24];byte aad[]; // AADint ret = wc_XChaCha20Poly1305_Init(&aead, aad, sizeof(aad),                                    key, 32, iv, 24, 1);

function wc_XChaCha20Poly1305_Encrypt

int wc_XChaCha20Poly1305_Encrypt(    byte * dst,    size_t dst_space,    const byte * src,    size_t src_len,    const byte * ad,    size_t ad_len,    const byte * nonce,    size_t nonce_len,    const byte * key,    size_t key_len)

One-shot XChaCha20-Poly1305 encryption with 24-byte nonce.

Parameters:

• dst Output buffer for ciphertext and tag
• dst_space Size of output buffer
• src Input plaintext
• src_len Length of plaintext
• ad Additional authenticated data
• ad_len Length of AAD
• nonce 24-byte nonce
• nonce_len Nonce length (must be 24)
• key 32-byte encryption key
• key_len Key length (must be 32)

See:wc_XChaCha20Poly1305_Decrypt

Return:

• 0 On success
• BAD_FUNC_ARG If parameters are invalid
• BUFFER_E If dst_space is insufficient

Example

byte key[32], nonce[24];byte plain[]; // plaintextbyte cipher[sizeof(plain) + 16];int ret = wc_XChaCha20Poly1305_Encrypt(cipher, sizeof(cipher),                                       plain, sizeof(plain),                                       NULL, 0, nonce, 24,                                       key, 32);

function wc_XChaCha20Poly1305_Decrypt

int wc_XChaCha20Poly1305_Decrypt(    byte * dst,    size_t dst_space,    const byte * src,    size_t src_len,    const byte * ad,    size_t ad_len,    const byte * nonce,    size_t nonce_len,    const byte * key,    size_t key_len)

One-shot XChaCha20-Poly1305 decryption with 24-byte nonce.

Parameters:

• dst Output buffer for plaintext
• dst_space Size of output buffer
• src Input ciphertext with tag
• src_len Length of ciphertext plus tag
• ad Additional authenticated data
• ad_len Length of AAD
• nonce 24-byte nonce
• nonce_len Nonce length (must be 24)
• key 32-byte decryption key
• key_len Key length (must be 32)

See:wc_XChaCha20Poly1305_Encrypt

Return:

• 0 On success
• BAD_FUNC_ARG If parameters are invalid
• BUFFER_E If dst_space is insufficient
• MAC_CMP_FAILED_E If authentication fails

Example

byte key[32], nonce[24];byte cipher[]; // ciphertext + tagbyte plain[sizeof(cipher) - 16];int ret = wc_XChaCha20Poly1305_Decrypt(plain, sizeof(plain),                                       cipher, sizeof(cipher),                                       NULL, 0, nonce, 24,                                       key, 32);if (ret == MAC_CMP_FAILED_E) {    // authentication failed}

Updated on 2026-02-20 at 02:00:32 +0000