chacha20_poly1305.h

Functions

	Name
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]) This function encrypts an input message, inPlaintext, using the ChaCha20 stream cipher, into the output buffer, outCiphertext. It also performs Poly_1305 authentication (on the cipher text), and stores the generated authentication tag in the output buffer, outAuthTag.
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.
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.
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.
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.
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.
int	wc_ChaCha20Poly1305_Final(ChaChaPoly_Aead * aead, byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]) Finalizes the AEAD operation and generates the authentication tag.
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.
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.
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.

Functions Documentation

function wc_ChaCha20Poly1305_Encrypt

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]
)

This function encrypts an input message, inPlaintext, using the ChaCha20 stream cipher, into the output buffer, outCiphertext. It also performs Poly-1305 authentication (on the cipher text), and stores the generated authentication tag in the output buffer, outAuthTag.

Parameters:

inKey pointer to a buffer containing the 32 byte key to use for encryption
inIv pointer to a buffer containing the 12 byte iv to use for encryption
inAAD pointer to the buffer containing arbitrary length additional authenticated data (AAD)
inAADLen length of the input AAD
inPlaintext pointer to the buffer containing the plaintext to encrypt
inPlaintextLen the length of the plain text to encrypt
outCiphertext pointer to the buffer in which to store the ciphertext
outAuthTag pointer to a 16 byte wide buffer in which to store the authentication tag

See:

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:

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:

Return:

0 On success
BAD_FUNC_ARG If parameters are invalid

Example

ChaChaPoly_Aead aead;
byte aad[]; // AAD data

wc_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:

Return:

0 On success
BAD_FUNC_ARG If parameters are invalid

Example

ChaChaPoly_Aead aead;
byte plain[]; // plaintext
byte 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:

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:

Return:

0 On success
BAD_FUNC_ARG If parameters are invalid

Example

ChaChaPoly_Aead aead;
byte key[32];
byte iv[24];
byte aad[]; // AAD

int 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[]; // plaintext
byte 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 + tag
byte 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
}

Source code


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]);

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);

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

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

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

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

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

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);

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);

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);

Updated on 2026-01-01 at 01:18:53 +0000