aes.h

Functions

	Name
int	wc_AesSetKey(Aes * aes, const byte * key, word32 len, const byte * iv, int dir) This function initializes an AES structure by setting the key and then setting the initialization vector.
int	wc_AesSetIV(Aes * aes, const byte * iv) This function sets the initialization vector for a particular AES object. The AES object should be initialized before calling this function.
int	wc_AesCbcEncrypt(Aes * aes, byte * out, const byte * in, word32 sz) Encrypts a plaintext message from the input buffer in, and places the resulting cipher text in the output buffer out using cipher block chaining with AES. This function requires that the AES object has been initialized by calling AesSetKey before a message is able to be encrypted. This function assumes that the input message is AES block length aligned, and expects the input length to be a multiple of the block length, which will optionally be checked and enforced if WOLFSSL_AES_CBC_LENGTH_CHECKS is defined in the build configuration. In order to assure block-multiple input, PKCS#7 style padding should be added beforehand. This differs from the OpenSSL AES-CBC methods which add the padding for you. To make the wolfSSL and corresponding OpenSSL functions interoperate, one should specify the -nopad option in the OpenSSL command line function so that it behaves like the wolfSSL AesCbcEncrypt method and does not add extra padding during encryption.
int	wc_AesCbcDecrypt(Aes * aes, byte * out, const byte * in, word32 sz) Decrypts a cipher from the input buffer in, and places the resulting plain text in the output buffer out using cipher block chaining with AES. This function requires that the AES structure has been initialized by calling AesSetKey before a message is able to be decrypted. This function assumes that the original message was AES block length aligned, and expects the input length to be a multiple of the block length, which will optionally be checked and enforced if WOLFSSL_AES_CBC_LENGTH_CHECKS is defined in the build configuration. This differs from the OpenSSL AES-CBC methods, which add PKCS#7 padding automatically, and so do not require block-multiple input. To make the wolfSSL function and equivalent OpenSSL functions interoperate, one should specify the -nopad option in the OpenSSL command line function so that it behaves like the wolfSSL AesCbcEncrypt method and does not create errors during decryption.
int	wc_AesCtrEncrypt(Aes * aes, byte * out, const byte * in, word32 sz) Encrypts/Decrypts a message from the input buffer in, and places the resulting cipher text in the output buffer out using CTR mode with AES. This function is only enabled if WOLFSSL_AES_COUNTER is enabled at compile time. The AES structure should be initialized through AesSetKey before calling this function. Note that this function is used for both decryption and encryption. NOTE: Regarding using same API for encryption and decryption. User should differentiate between Aes structures for encrypt/decrypt.
int	wc_AesEncryptDirect(Aes * aes, byte * out, const byte * in) This function is a one-block encrypt of the input block, in, into the output block, out. It uses the key of the provided AES structure, which should be initialized with wc_AesSetKey before calling this function. wc_AesSetKey should have been called with the iv set to NULL. This is only enabled if the configure option WOLFSSL_AES_DIRECT is enabled. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible.
int	wc_AesDecryptDirect(Aes * aes, byte * out, const byte * in) This function is a one-block decrypt of the input block, in, into the output block, out. It uses the key of the provided AES structure, which should be initialized with wc_AesSetKey before calling this function. wc_AesSetKey should have been called with the iv set to NULL. This is only enabled if the configure option WOLFSSL_AES_DIRECT is enabled. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible.
int	wc_AesSetKeyDirect(Aes * aes, const byte * key, word32 len, const byte * iv, int dir) This function is used to set the AES keys for CTR mode with AES. It initializes an AES object with the given key, iv (initialization vector), and encryption dir (direction). It is only enabled if the configure option WOLFSSL_AES_DIRECT is enabled. Currently wc_AesSetKeyDirect uses wc_AesSetKey internally. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible.
int	wc_AesGcmSetKey(Aes * aes, const byte * key, word32 len) This function is used to set the key for AES GCM (Galois/Counter Mode). It initializes an AES object with the given key. It is only enabled if the configure option HAVE_AESGCM is enabled at compile time.
int	wc_AesGcmEncrypt(Aes * aes, byte * out, const byte * in, word32 sz, const byte * iv, word32 ivSz, byte * authTag, word32 authTagSz, const byte * authIn, word32 authInSz) This function encrypts the input message, held in the buffer in, and stores the resulting cipher text in the output buffer out. It requires a new iv (initialization vector) for each call to encrypt. It also encodes the input authentication vector, authIn, into the authentication tag, authTag.
int	wc_AesGcmDecrypt(Aes * aes, byte * out, const byte * in, word32 sz, const byte * iv, word32 ivSz, const byte * authTag, word32 authTagSz, const byte * authIn, word32 authInSz) This function decrypts the input cipher text, held in the buffer in, and stores the resulting message text in the output buffer out. It also checks the input authentication vector, authIn, against the supplied authentication tag, authTag. If a nonzero error code is returned, the output data is undefined. However, callers must unconditionally zeroize the output buffer to guard against leakage of cleartext data.
int	wc_GmacSetKey(Gmac * gmac, const byte * key, word32 len) This function initializes and sets the key for a GMAC object to be used for Galois Message Authentication.
int	wc_GmacUpdate(Gmac * gmac, const byte * iv, word32 ivSz, const byte * authIn, word32 authInSz, byte * authTag, word32 authTagSz) This function generates the Gmac hash of the authIn input and stores the result in the authTag buffer. After running wc_GmacUpdate, one should compare the generated authTag to a known authentication tag to verify the authenticity of a message.
int	wc_AesCcmSetKey(Aes * aes, const byte * key, word32 keySz) This function sets the key for an AES object using CCM (Counter with CBC_MAC). It takes a pointer to an AES structure and initializes it with supplied key.
int	wc_AesCcmEncrypt(Aes * aes, byte * out, const byte * in, word32 inSz, const byte * nonce, word32 nonceSz, byte * authTag, word32 authTagSz, const byte * authIn, word32 authInSz) This function encrypts the input message, in, into the output buffer, out, using CCM (Counter with CBC_MAC). It subsequently calculates and stores the authorization tag, authTag, from the authIn input.
int	wc_AesCcmDecrypt(Aes * aes, byte * out, const byte * in, word32 inSz, const byte * nonce, word32 nonceSz, const byte * authTag, word32 authTagSz, const byte * authIn, word32 authInSz) This function decrypts the input cipher text, in, into the output buffer, out, using CCM (Counter with CBC_MAC). It subsequently calculates the authorization tag, authTag, from the authIn input. If a nonzero error code is returned, the output data is undefined. However, callers must unconditionally zeroize the output buffer to guard against leakage of cleartext data.
int	wc_AesXtsInit(XtsAes * aes, void * heap, int devId) This is to initialize an AES-XTS context. It is up to user to call wc_AesXtsFree on aes key when done.
int	wc_AesXtsSetKeyNoInit(XtsAes * aes, const byte * key, word32 len, int dir) This is to help with setting keys to correct encrypt or decrypt type, after first calling wc_AesXtsInit(). It is up to user to call wc_AesXtsFree on aes key when done.
int	wc_AesXtsSetKey(XtsAes * aes, const byte * key, word32 len, int dir, void * heap, int devId) This is to help with setting keys to correct encrypt or decrypt type. It is up to user to call wc_AesXtsFree on aes key when done.
int	wc_AesXtsEncryptSector(XtsAes * aes, byte * out, const byte * in, word32 sz, word64 sector) Same process as wc_AesXtsEncrypt but uses a word64 type as the tweak value instead of a byte array. This just converts the word64 to a byte array and calls wc_AesXtsEncrypt.
int	wc_AesXtsDecryptSector(XtsAes * aes, byte * out, const byte * in, word32 sz, word64 sector) Same process as wc_AesXtsDecrypt but uses a word64 type as the tweak value instead of a byte array. This just converts the word64 to a byte array.
int	wc_AesXtsEncrypt(XtsAes * aes, byte * out, const byte * in, word32 sz, const byte * i, word32 iSz) AES with XTS mode. (XTS) XEX encryption with Tweak and cipher text Stealing.
int	wc_AesXtsDecrypt(XtsAes * aes, byte * out, const byte * in, word32 sz, const byte * i, word32 iSz) Same process as encryption but Aes key is AES_DECRYPTION type.
int	wc_AesXtsFree(XtsAes * aes) This is to free up any resources used by the XtsAes structure.
int	wc_AesInit(Aes * aes, void * heap, int devId) Initialize Aes structure. Sets heap hint to be used and ID for use with async hardware. It is up to the user to call wc_AesFree on the Aes structure when done.
void	wc_AesFree(Aes * aes) free resources associated with the Aes structure when applicable. Internally may sometimes be a no_op but still recommended to call in all cases as a general best_practice (IE if application code is ported for use on new environments where the call is applicable).
int	wc_AesCfbEncrypt(Aes * aes, byte * out, const byte * in, word32 sz) AES with CFB mode.
int	wc_AesCfbDecrypt(Aes * aes, byte * out, const byte * in, word32 sz) AES with CFB mode.
int	wc_AesSivEncrypt(const byte * key, word32 keySz, const byte * assoc, word32 assocSz, const byte * nonce, word32 nonceSz, const byte * in, word32 inSz, byte * siv, byte * out) This function performs SIV (synthetic initialization vector) encryption as described in RFC 5297.
int	wc_AesSivDecrypt(const byte * key, word32 keySz, const byte * assoc, word32 assocSz, const byte * nonce, word32 nonceSz, const byte * in, word32 inSz, byte * siv, byte * out) This function performs SIV (synthetic initialization vector) decryption as described in RFC 5297. If a nonzero error code is returned, the output data is undefined. However, callers must unconditionally zeroize the output buffer to guard against leakage of cleartext data.
WOLFSSL_API int	wc_AesEaxEncryptAuth(const byte * key, word32 keySz, byte * out, const byte * in, word32 inSz, const byte * nonce, word32 nonceSz, byte * authTag, word32 authTagSz, const byte * authIn, word32 authInSz) This function performs AES EAX encryption and authentication as described in "EAX: A Conventional Authenticated_Encryption Mode" (https://eprint.iacr.org/2003/069). It is a "one-shot" API that performs all encryption and authentication operations in one function call.
WOLFSSL_API int	wc_AesEaxDecryptAuth(const byte * key, word32 keySz, byte * out, const byte * in, word32 inSz, const byte * nonce, word32 nonceSz, const byte * authTag, word32 authTagSz, const byte * authIn, word32 authInSz) This function performs AES EAX decryption and authentication as described in "EAX: A Conventional Authenticated_Encryption Mode" (https://eprint.iacr.org/2003/069). It is a "one-shot" API that performs all decryption and authentication operations in one function call. If a nonzero error code is returned, the output data is undefined. However, callers must unconditionally zeroize the output buffer to guard against leakage of cleartext data.
WOLFSSL_API int	wc_AesEaxInit(AesEax * eax, const byte * key, word32 keySz, const byte * nonce, word32 nonceSz, const byte * authIn, word32 authInSz) This function initializes an AesEax object for use in authenticated encryption or decryption. This function must be called on an AesEax object before using it with any of the AES EAX incremental API functions. It does not need to be called if using the one_shot EAX API functions. All AesEax instances initialized with this function need to be freed with a call to wc_AesEaxFree() when done using the instance.
WOLFSSL_API int	wc_AesEaxEncryptUpdate(AesEax * eax, byte * out, const byte * in, word32 inSz, const byte * authIn, word32 authInSz) This function uses AES EAX to encrypt input data, and optionally, add more input data to the authentication stream. eax must have been previously initialized with a call to wc_AesEaxInit.
WOLFSSL_API int	wc_AesEaxDecryptUpdate(AesEax * eax, byte * out, const byte * in, word32 inSz, const byte * authIn, word32 authInSz) This function uses AES EAX to decrypt input data, and optionally, add more input data to the authentication stream. eax must have been previously initialized with a call to wc_AesEaxInit.
WOLFSSL_API int	wc_AesEaxAuthDataUpdate(AesEax * eax, const byte * authIn, word32 authInSz) This function adds input data to the authentication stream. eax must have been previously initialized with a call to wc_AesEaxInit.
WOLFSSL_API int	wc_AesEaxEncryptFinal(AesEax * eax, byte * authTag, word32 authTagSz) This function finalizes the encrypt AEAD operation, producing an auth tag over the current authentication stream. eax must have been previously initialized with a call to wc_AesEaxInit. When done using the AesEax context structure, make sure to free it using wc_AesEaxFree.
WOLFSSL_API int	wc_AesEaxDecryptFinal(AesEax * eax, const byte * authIn, word32 authInSz) This function finalizes the decrypt AEAD operation, finalizing the auth tag computation and checking it for validity against the user supplied tag. eax must have been previously initialized with a call to wc_AesEaxInit. When done using the AesEax context structure, make sure to free it using wc_AesEaxFree.
WOLFSSL_API int	wc_AesEaxFree(AesEax * eax) This frees up any resources, specifically keys, used by the Aes instance inside the AesEax wrapper struct. It should be called on the AesEax struct after it has been initialized with wc_AesEaxInit, and all desired EAX operations are complete.
int	wc_AesCtsEncrypt(const byte * key, word32 keySz, byte * out, const byte * in, word32 inSz, const byte * iv) This function performs AES encryption using Ciphertext Stealing (CTS) mode. It is a one-shot API that handles all operations in a single call.
int	wc_AesCtsDecrypt(const byte * key, word32 keySz, byte * out, const byte * in, word32 inSz, const byte * iv) This function performs AES decryption using Ciphertext Stealing (CTS) mode. It is a one-shot API that handles all operations in a single call.
int	wc_AesCtsEncryptUpdate(Aes * aes, byte * out, word32 * outSz, const byte * in, word32 inSz) This function performs an update step of the AES CTS encryption. It processes a chunk of plaintext and stores intermediate data.
int	wc_AesCtsEncryptFinal(Aes * aes, byte * out, word32 * outSz) This function finalizes the AES CTS encryption operation. It processes any remaining plaintext and completes the encryption.
int	wc_AesCtsDecryptUpdate(Aes * aes, byte * out, word32 * outSz, const byte * in, word32 inSz) This function performs an update step of the AES CTS decryption. It processes a chunk of ciphertext and stores intermediate data.
int	wc_AesCtsDecryptFinal(Aes * aes, byte * out, word32 * outSz) This function finalizes the AES CTS decryption operation. It processes any remaining ciphertext and completes the decryption.
int	wc_AesCfb1Encrypt(Aes * aes, byte * out, const byte * in, word32 sz) This function encrypts data using AES CFB_1 mode (1_bit feedback). It processes data one bit at a time, making it suitable for bit-oriented applications.
int	wc_AesCfb8Encrypt(Aes * aes, byte * out, const byte * in, word32 sz) This function encrypts data using AES CFB_8 mode (8_bit feedback). It processes data one byte at a time, making it suitable for byte-oriented stream encryption.
int	wc_AesCfb1Decrypt(Aes * aes, byte * out, const byte * in, word32 sz) This function decrypts data using AES CFB_1 mode (1_bit feedback). It processes data one bit at a time, making it suitable for bit-oriented applications.
int	wc_AesCfb8Decrypt(Aes * aes, byte * out, const byte * in, word32 sz) This function decrypts data using AES CFB_8 mode (8_bit feedback). It processes data one byte at a time, making it suitable for byte-oriented stream decryption.
int	wc_AesOfbEncrypt(Aes * aes, byte * out, const byte * in, word32 sz) This function encrypts data using AES OFB mode (Output Feedback). OFB mode turns a block cipher into a stream cipher by encrypting the IV and XORing with plaintext.
int	wc_AesOfbDecrypt(Aes * aes, byte * out, const byte * in, word32 sz) This function decrypts data using AES OFB mode (Output Feedback). In OFB mode, encryption and decryption are the same operation.
int	wc_AesEcbEncrypt(Aes * aes, byte * out, const byte * in, word32 sz) This function encrypts data using AES ECB mode (Electronic Codebook). Warning: ECB mode is not recommended for most use cases as it does not provide semantic security. Each block is encrypted independently.
int	wc_AesEcbDecrypt(Aes * aes, byte * out, const byte * in, word32 sz) This function decrypts data using AES ECB mode (Electronic Codebook). Warning: ECB mode is not recommended for most use cases as it does not provide semantic security. Each block is decrypted independently.
int	wc_AesCtrSetKey(Aes * aes, const byte * key, word32 len, const byte * iv, int dir) This function sets the key and IV for AES CTR mode. It initializes the AES structure for counter mode encryption or decryption.
int	wc_AesGcmSetKey_ex(Aes * aes, const byte * key, word32 len, word32 kup) This function sets the key for AES GCM with an extended key update parameter. It allows for key updates in certain hardware implementations.
int	wc_AesGcmInit(Aes * aes, const byte * key, word32 len, const byte * iv, word32 ivSz) This function initializes an AES GCM cipher with key and IV. It can be called with NULL key to only set the IV, or with NULL IV to only set the key.
int	wc_AesGcmEncryptInit(Aes * aes, const byte * key, word32 len, const byte * iv, word32 ivSz) This function initializes an AES GCM cipher for encryption. It is a convenience wrapper around wc_AesGcmInit for encryption operations.
int	wc_AesGcmEncryptInit_ex(Aes * aes, const byte * key, word32 len, byte * ivOut, word32 ivOutSz) This function initializes an AES GCM cipher for encryption and outputs the IV. This is useful when part of the IV is generated internally. Must call wc_AesGcmSetIV() before this function to set the fixed part of the IV.
int	wc_AesGcmEncryptUpdate(Aes * aes, byte * out, const byte * in, word32 sz, const byte * authIn, word32 authInSz) This function performs an update step of AES GCM encryption. It processes plaintext and/or additional authentication data (AAD) in a streaming fashion.
int	wc_AesGcmEncryptFinal(Aes * aes, byte * authTag, word32 authTagSz) This function finalizes AES GCM encryption and generates the authentication tag. This must be called after all data has been processed with wc_AesGcmEncryptUpdate.
int	wc_AesGcmDecryptInit(Aes * aes, const byte * key, word32 len, const byte * iv, word32 ivSz) This function initializes an AES GCM cipher for decryption. It is a convenience wrapper around wc_AesGcmInit for decryption operations.
int	wc_AesGcmDecryptUpdate(Aes * aes, byte * out, const byte * in, word32 sz, const byte * authIn, word32 authInSz) This function performs an update step of AES GCM decryption. It processes ciphertext and/or additional authentication data (AAD) in a streaming fashion.
int	wc_AesGcmDecryptFinal(Aes * aes, const byte * authTag, word32 authTagSz) This function finalizes AES GCM decryption and verifies the authentication tag. This must be called after all data has been processed with wc_AesGcmDecryptUpdate.
int	wc_AesGcmSetExtIV(Aes * aes, const byte * iv, word32 ivSz) This function sets an external IV for AES GCM. This allows using an IV that was generated externally or received from another source.
int	wc_AesGcmSetIV(Aes * aes, word32 ivSz, const byte * ivFixed, word32 ivFixedSz, WC_RNG * rng) This function sets the IV for AES GCM with optional random generation. It can generate part of the IV using an RNG, which is useful for ensuring IV uniqueness.
int	wc_AesGcmEncrypt_ex(Aes * aes, byte * out, const byte * in, word32 sz, byte * ivOut, word32 ivOutSz, byte * authTag, word32 authTagSz, const byte * authIn, word32 authInSz) This function performs AES GCM encryption with extended parameters, including IV output. This is a one-shot encryption function that outputs the generated IV.
int	wc_Gmac(const byte * key, word32 keySz, byte * iv, word32 ivSz, const byte * authIn, word32 authInSz, byte * authTag, word32 authTagSz, WC_RNG * rng) This function performs GMAC (Galois Message Authentication Code) generation. GMAC is essentially AES-GCM with no plaintext, used for authentication only.
int	wc_GmacVerify(const byte * key, word32 keySz, const byte * iv, word32 ivSz, const byte * authIn, word32 authInSz, const byte * authTag, word32 authTagSz) This function verifies a GMAC (Galois Message Authentication Code). It computes the GMAC and compares it with the provided tag.
int	wc_AesCcmSetNonce(Aes * aes, const byte * nonce, word32 nonceSz) This function sets the nonce for AES CCM mode. The nonce must be set before encryption or decryption operations.
int	wc_AesCcmEncrypt_ex(Aes * aes, byte * out, const byte * in, word32 sz, byte * ivOut, word32 ivOutSz, byte * authTag, word32 authTagSz, const byte * authIn, word32 authInSz) This function performs AES CCM encryption with extended parameters, including nonce output. This is useful when part of the nonce is generated internally.
int	wc_AesKeyWrap(const byte * key, word32 keySz, const byte * in, word32 inSz, byte * out, word32 outSz, const byte * iv) This function wraps a key using AES Key Wrap algorithm (RFC 3394). This is commonly used to securely transport cryptographic keys.
int	wc_AesKeyWrap_ex(Aes * aes, const byte * in, word32 inSz, byte * out, word32 outSz, const byte * iv) This function wraps a key using AES Key Wrap algorithm with an initialized AES structure. This allows reusing the same AES structure for multiple wrap operations.
int	wc_AesKeyUnWrap(const byte * key, word32 keySz, const byte * in, word32 inSz, byte * out, word32 outSz, const byte * iv) This function unwraps a key using AES Key Unwrap algorithm (RFC 3394). This is used to securely receive cryptographic keys that were wrapped.
int	wc_AesKeyUnWrap_ex(Aes * aes, const byte * in, word32 inSz, byte * out, word32 outSz, const byte * iv) This function unwraps a key using AES Key Unwrap algorithm with an initialized AES structure. This allows reusing the same AES structure for multiple unwrap operations.
int	wc_AesXtsEncryptConsecutiveSectors(XtsAes * aes, byte * out, const byte * in, word32 sz, word64 sector, word32 sectorSz) This function encrypts multiple consecutive sectors using AES XTS mode. It processes multiple sectors in sequence, automatically incrementing the sector number for each sector.
int	wc_AesXtsDecryptConsecutiveSectors(XtsAes * aes, byte * out, const byte * in, word32 sz, word64 sector, word32 sectorSz) This function decrypts multiple consecutive sectors using AES XTS mode. It processes multiple sectors in sequence, automatically incrementing the sector number for each sector.
int	wc_AesXtsEncryptInit(XtsAes * aes, const byte * i, word32 iSz, struct XtsAesStreamData * stream) This function initializes streaming AES XTS encryption. It sets up the context for processing data in multiple update calls.
int	wc_AesXtsDecryptInit(XtsAes * aes, const byte * i, word32 iSz, struct XtsAesStreamData * stream) This function initializes streaming AES XTS decryption. It sets up the context for processing data in multiple update calls.
int	wc_AesXtsEncryptUpdate(XtsAes * aes, byte * out, const byte * in, word32 sz, struct XtsAesStreamData * stream) This function performs an update step of streaming AES XTS encryption. It processes a chunk of data and can be called multiple times.
int	wc_AesXtsDecryptUpdate(XtsAes * aes, byte * out, const byte * in, word32 sz, struct XtsAesStreamData * stream) This function performs an update step of streaming AES XTS decryption. It processes a chunk of data and can be called multiple times.
int	wc_AesXtsEncryptFinal(XtsAes * aes, byte * out, const byte * in, word32 sz, struct XtsAesStreamData * stream) This function finalizes streaming AES XTS encryption. It processes any remaining data and completes the encryption operation.
int	wc_AesXtsDecryptFinal(XtsAes * aes, byte * out, const byte * in, word32 sz, struct XtsAesStreamData * stream) This function finalizes streaming AES XTS decryption. It processes any remaining data and completes the decryption operation.
int	wc_AesGetKeySize(Aes * aes, word32 * keySize) This function retrieves the key size from an initialized AES structure. It returns the size of the key currently set in the AES object.
int	wc_AesInit_Id(Aes * aes, unsigned char * id, int len, void * heap, int devId) This function initializes an AES structure with an ID. This is useful for tracking or identifying specific AES instances in applications that manage multiple AES contexts.
int	wc_AesInit_Label(Aes * aes, const char * label, void * heap, int devId) This function initializes an AES structure with a label string. This is useful for tracking or identifying specific AES instances with human-readable names.
Aes *	wc_AesNew(void * heap, int devId, int * result_code) This function allocates and initializes a new AES structure. It returns a pointer to the allocated structure, which must be freed with wc_AesDelete when no longer needed. These New/Delete functions are exposed to support allocation of the structure using dynamic memory to provide better ABI compatibility.
int	wc_AesDelete(Aes * aes, Aes ** aes_p) This function frees an AES structure that was allocated with wc_AesNew. It also sets the pointer to NULL to prevent use-after-free. These New/Delete functions are exposed to support allocation of the structure using dynamic memory to provide better ABI compatibility.
int	wc_AesSivEncrypt_ex(const byte * key, word32 keySz, const AesSivAssoc * assoc, word32 numAssoc, const byte * nonce, word32 nonceSz, const byte * in, word32 inSz, byte * siv, byte * out) This function performs AES_SIV (Synthetic IV) encryption with extended parameters. AES-SIV provides nonce-misuse resistance and deterministic authenticated encryption.
int	wc_AesSivDecrypt_ex(const byte * key, word32 keySz, const AesSivAssoc * assoc, word32 numAssoc, const byte * nonce, word32 nonceSz, const byte * in, word32 inSz, byte * siv, byte * out) This function performs AES_SIV (Synthetic IV) decryption with extended parameters. It verifies the SIV and decrypts the ciphertext.

Functions Documentation

function wc_AesSetKey

int wc_AesSetKey(
    Aes * aes,
    const byte * key,
    word32 len,
    const byte * iv,
    int dir
)

This function initializes an AES structure by setting the key and then setting the initialization vector.

Parameters:

• aes pointer to the AES structure to modify
• key 16, 24, or 32 byte secret key for encryption and decryption
• len length of the key passed in
• iv pointer to the initialization vector used to initialize the key
• dir Cipher direction. Set AES_ENCRYPTION to encrypt, or AES_DECRYPTION to decrypt. Direction for some modes (CFB and CTR) is always AES_ENCRYPTION.

See:

• wc_AesSetKeyDirect
• wc_AesSetIV

Return:

• 0 On successfully setting key and initialization vector.
• BAD_FUNC_ARG Returned if key length is invalid.

Example

Aes enc;
int ret = 0;
byte key[] = { some 16, 24 or 32 byte key };
byte iv[]  = { some 16 byte iv };
if (ret = wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID) != 0) {
    // failed to initialize aes key
}
if (ret = wc_AesSetKey(&enc, key, AES_BLOCK_SIZE, iv,
AES_ENCRYPTION) != 0) {
// failed to set aes key
}

function wc_AesSetIV

int wc_AesSetIV(
    Aes * aes,
    const byte * iv
)

This function sets the initialization vector for a particular AES object. The AES object should be initialized before calling this function.

Parameters:

• aes pointer to the AES structure on which to set the initialization vector
• iv initialization vector used to initialize the AES structure. If the value is NULL, the default action initializes the iv to 0.

See:

• wc_AesSetKeyDirect
• wc_AesSetKey

Return:

• 0 On successfully setting initialization vector.
• BAD_FUNC_ARG Returned if AES pointer is NULL.

Example

Aes enc;
// set enc key
byte iv[]  = { some 16 byte iv };
if (ret = wc_AesSetIV(&enc, iv) != 0) {
// failed to set aes iv
}

function wc_AesCbcEncrypt

int wc_AesCbcEncrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

Encrypts a plaintext message from the input buffer in, and places the resulting cipher text in the output buffer out using cipher block chaining with AES. This function requires that the AES object has been initialized by calling AesSetKey before a message is able to be encrypted. This function assumes that the input message is AES block length aligned, and expects the input length to be a multiple of the block length, which will optionally be checked and enforced if WOLFSSL_AES_CBC_LENGTH_CHECKS is defined in the build configuration. In order to assure block-multiple input, PKCS#7 style padding should be added beforehand. This differs from the OpenSSL AES-CBC methods which add the padding for you. To make the wolfSSL and corresponding OpenSSL functions interoperate, one should specify the -nopad option in the OpenSSL command line function so that it behaves like the wolfSSL AesCbcEncrypt method and does not add extra padding during encryption.

Parameters:

• aes pointer to the AES object used to encrypt data
• out pointer to the output buffer in which to store the ciphertext of the encrypted message
• in pointer to the input buffer containing message to be encrypted
• sz size of input message

See:

• wc_AesInit
• wc_AesSetKey
• wc_AesSetIV
• wc_AesCbcDecrypt

Return:

• 0 On successfully encrypting message.
• BAD_ALIGN_E: may be returned on block align error
• BAD_LENGTH_E will be returned if the input length isn't a multiple of the AES block length, when the library is built with WOLFSSL_AES_CBC_LENGTH_CHECKS.

Example

Aes enc;
int ret = 0;
// initialize enc with wc_AesInit and wc_AesSetKey, using direction
// AES_ENCRYPTION
byte msg[AES_BLOCK_SIZE * n]; // multiple of 16 bytes
// fill msg with data
byte cipher[AES_BLOCK_SIZE * n]; // Some multiple of 16 bytes
if ((ret = wc_AesCbcEncrypt(&enc, cipher, message, sizeof(msg))) != 0 ) {
// block align error
}

function wc_AesCbcDecrypt

int wc_AesCbcDecrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

Decrypts a cipher from the input buffer in, and places the resulting plain text in the output buffer out using cipher block chaining with AES. This function requires that the AES structure has been initialized by calling AesSetKey before a message is able to be decrypted. This function assumes that the original message was AES block length aligned, and expects the input length to be a multiple of the block length, which will optionally be checked and enforced if WOLFSSL_AES_CBC_LENGTH_CHECKS is defined in the build configuration. This differs from the OpenSSL AES-CBC methods, which add PKCS#7 padding automatically, and so do not require block-multiple input. To make the wolfSSL function and equivalent OpenSSL functions interoperate, one should specify the -nopad option in the OpenSSL command line function so that it behaves like the wolfSSL AesCbcEncrypt method and does not create errors during decryption.

Parameters:

• aes pointer to the AES object used to decrypt data.
• out pointer to the output buffer in which to store the plain text of the decrypted message. size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
• in pointer to the input buffer containing cipher text to be decrypted. size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
• sz size of input message.

See:

• wc_AesInit
• wc_AesSetKey
• wc_AesCbcEncrypt

Return:

• 0 On successfully decrypting message.
• BAD_ALIGN_E may be returned on block align error.
• BAD_LENGTH_E will be returned if the input length isn't a multiple of the AES block length, when the library is built with WOLFSSL_AES_CBC_LENGTH_CHECKS.

Example

Aes dec;
int ret = 0;
// initialize dec with wc_AesInit and wc_AesSetKey, using direction
// AES_DECRYPTION
byte cipher[AES_BLOCK_SIZE * n]; // some multiple of 16 bytes
// fill cipher with cipher text
byte plain [AES_BLOCK_SIZE * n];
if ((ret = wc_AesCbcDecrypt(&dec, plain, cipher, sizeof(cipher))) != 0 ) {
// block align error
}

function wc_AesCtrEncrypt

int wc_AesCtrEncrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

Encrypts/Decrypts a message from the input buffer in, and places the resulting cipher text in the output buffer out using CTR mode with AES. This function is only enabled if WOLFSSL_AES_COUNTER is enabled at compile time. The AES structure should be initialized through AesSetKey before calling this function. Note that this function is used for both decryption and encryption. NOTE: Regarding using same API for encryption and decryption. User should differentiate between Aes structures for encrypt/decrypt.

Parameters:

• aes pointer to the AES object used to decrypt data
• out pointer to the output buffer in which to store the cipher text of the encrypted message size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
• in pointer to the input buffer containing plain text to be encrypted size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
• sz size of the input plain text

See: wc_AesSetKey

Return: int integer values corresponding to wolfSSL error or success status

Example

Aes enc;
Aes dec;
// initialize enc and dec with wc_AesInit and wc_AesSetKeyDirect, using
// direction AES_ENCRYPTION since the underlying API only calls Encrypt
// and by default calling encrypt on a cipher results in a decryption of
// the cipher

byte msg[AES_BLOCK_SIZE * n]; //n being a positive integer making msg
some multiple of 16 bytes
// fill plain with message text
byte cipher[AES_BLOCK_SIZE * n];
byte decrypted[AES_BLOCK_SIZE * n];
wc_AesCtrEncrypt(&enc, cipher, msg, sizeof(msg)); // encrypt plain
wc_AesCtrEncrypt(&dec, decrypted, cipher, sizeof(cipher));
// decrypt cipher text

function wc_AesEncryptDirect

int wc_AesEncryptDirect(
    Aes * aes,
    byte * out,
    const byte * in
)

This function is a one-block encrypt of the input block, in, into the output block, out. It uses the key of the provided AES structure, which should be initialized with wc_AesSetKey before calling this function. wc_AesSetKey should have been called with the iv set to NULL. This is only enabled if the configure option WOLFSSL_AES_DIRECT is enabled. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible.

Parameters:

• aes pointer to the AES object used to encrypt data
• out pointer to the output buffer in which to store the cipher text of the encrypted message
• in pointer to the input buffer containing plain text to be encrypted

See:

• wc_AesDecryptDirect
• wc_AesSetKeyDirect

Return: int integer values corresponding to wolfSSL error or success status

Example

Aes enc;
// initialize enc with wc_AesInit and wc_AesSetKey, using direction
// AES_ENCRYPTION
byte msg [AES_BLOCK_SIZE]; // 16 bytes
// initialize msg with plain text to encrypt
byte cipher[AES_BLOCK_SIZE];
wc_AesEncryptDirect(&enc, cipher, msg);

function wc_AesDecryptDirect

int wc_AesDecryptDirect(
    Aes * aes,
    byte * out,
    const byte * in
)

This function is a one-block decrypt of the input block, in, into the output block, out. It uses the key of the provided AES structure, which should be initialized with wc_AesSetKey before calling this function. wc_AesSetKey should have been called with the iv set to NULL. This is only enabled if the configure option WOLFSSL_AES_DIRECT is enabled. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible.

Parameters:

• aes pointer to the AES object used to encrypt data
• out pointer to the output buffer in which to store the plain text of the decrypted cipher text
• in pointer to the input buffer containing cipher text to be decrypted

See:

• wc_AesEncryptDirect
• wc_AesSetKeyDirect

Return: int integer values corresponding to wolfSSL error or success status

Example

Aes dec;
// initialize enc with wc_AesInit and wc_AesSetKey, using direction
// AES_DECRYPTION
byte cipher [AES_BLOCK_SIZE]; // 16 bytes
// initialize cipher with cipher text to decrypt
byte msg[AES_BLOCK_SIZE];
wc_AesDecryptDirect(&dec, msg, cipher);

function wc_AesSetKeyDirect

int wc_AesSetKeyDirect(
    Aes * aes,
    const byte * key,
    word32 len,
    const byte * iv,
    int dir
)

This function is used to set the AES keys for CTR mode with AES. It initializes an AES object with the given key, iv (initialization vector), and encryption dir (direction). It is only enabled if the configure option WOLFSSL_AES_DIRECT is enabled. Currently wc_AesSetKeyDirect uses wc_AesSetKey internally. Warning: In nearly all use cases ECB mode is considered to be less secure. Please avoid using ECB API’s directly whenever possible.

Parameters:

• aes pointer to the AES object used to encrypt data
• key 16, 24, or 32 byte secret key for encryption and decryption
• len length of the key passed in
• iv initialization vector used to initialize the key
• dir Cipher direction. Set AES_ENCRYPTION to encrypt, or AES_DECRYPTION to decrypt. (See enum in wolfssl/wolfcrypt/aes.h) (NOTE: If using wc_AesSetKeyDirect with Aes Counter mode (Stream cipher) only use AES_ENCRYPTION for both encrypting and decrypting)

See:

• wc_AesEncryptDirect
• wc_AesDecryptDirect
• wc_AesSetKey

Return:

• 0 On successfully setting the key.
• BAD_FUNC_ARG Returned if the given key is an invalid length.

Example

Aes enc;
int ret = 0;
byte key[] = { some 16, 24, or 32 byte key };
byte iv[]  = { some 16 byte iv };

if (ret = wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID) != 0) {
    // failed to initialize aes key
}
if (ret = wc_AesSetKeyDirect(&enc, key, sizeof(key), iv,
AES_ENCRYPTION) != 0) {
// failed to set aes key
}

function wc_AesGcmSetKey

int wc_AesGcmSetKey(
    Aes * aes,
    const byte * key,
    word32 len
)

This function is used to set the key for AES GCM (Galois/Counter Mode). It initializes an AES object with the given key. It is only enabled if the configure option HAVE_AESGCM is enabled at compile time.

Parameters:

• aes pointer to the AES object used to encrypt data
• key 16, 24, or 32 byte secret key for encryption and decryption
• len length of the key passed in

See:

• wc_AesGcmEncrypt
• wc_AesGcmDecrypt

Return:

• 0 On successfully setting the key.
• BAD_FUNC_ARG Returned if the given key is an invalid length.

Example

Aes enc;
int ret = 0;
byte key[] = { some 16, 24,32 byte key };
if (ret = wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID) != 0) {
    // failed to initialize aes key
}
if (ret = wc_AesGcmSetKey(&enc, key, sizeof(key)) != 0) {
// failed to set aes key
}

function wc_AesGcmEncrypt

int wc_AesGcmEncrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    const byte * iv,
    word32 ivSz,
    byte * authTag,
    word32 authTagSz,
    const byte * authIn,
    word32 authInSz
)

This function encrypts the input message, held in the buffer in, and stores the resulting cipher text in the output buffer out. It requires a new iv (initialization vector) for each call to encrypt. It also encodes the input authentication vector, authIn, into the authentication tag, authTag.

Parameters:

• aes - pointer to the AES object used to encrypt data
• out pointer to the output buffer in which to store the cipher text size must match in's size (sz)
• in pointer to the input buffer holding the message to encrypt size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
• sz length of the input message to encrypt
• iv pointer to the buffer containing the initialization vector
• ivSz length of the initialization vector
• authTag pointer to the buffer in which to store the authentication tag
• authTagSz length of the desired authentication tag
• authIn pointer to the buffer containing the input authentication vector
• authInSz length of the input authentication vector

See:

• wc_AesGcmSetKey
• wc_AesGcmDecrypt

Return: 0 On successfully encrypting the input message

Example

Aes enc;
// initialize Aes structure by calling wc_AesInit() and wc_AesGcmSetKey

byte plain[AES_BLOCK_LENGTH * n]; //n being a positive integer
making plain some multiple of 16 bytes
// initialize plain with msg to encrypt
byte cipher[sizeof(plain)];
byte iv[] = // some 16 byte iv
byte authTag[AUTH_TAG_LENGTH];
byte authIn[] = // Authentication Vector

wc_AesGcmEncrypt(&enc, cipher, plain, sizeof(cipher), iv, sizeof(iv),
        authTag, sizeof(authTag), authIn, sizeof(authIn));

function wc_AesGcmDecrypt

int wc_AesGcmDecrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    const byte * iv,
    word32 ivSz,
    const byte * authTag,
    word32 authTagSz,
    const byte * authIn,
    word32 authInSz
)

This function decrypts the input cipher text, held in the buffer in, and stores the resulting message text in the output buffer out. It also checks the input authentication vector, authIn, against the supplied authentication tag, authTag. If a nonzero error code is returned, the output data is undefined. However, callers must unconditionally zeroize the output buffer to guard against leakage of cleartext data.

Parameters:

• aes pointer to the AES object used to encrypt data
• out pointer to the output buffer in which to store the message text size must match in's size (sz)
• in pointer to the input buffer holding the cipher text to decrypt size must be a multiple of AES_BLOCK_LENGTH, padded if necessary
• sz length of the cipher text to decrypt
• iv pointer to the buffer containing the initialization vector
• ivSz length of the initialization vector
• authTag pointer to the buffer containing the authentication tag
• authTagSz length of the desired authentication tag
• authIn pointer to the buffer containing the input authentication vector
• authInSz length of the input authentication vector

See:

• wc_AesGcmSetKey
• wc_AesGcmEncrypt

Return:

• 0 On successfully decrypting and authenticating the input message
• AES_GCM_AUTH_E If the authentication tag does not match the supplied authentication code vector, authTag.

Example

Aes enc; //can use the same struct as was passed to wc_AesGcmEncrypt
// initialize aes structure by calling wc_AesInit and wc_AesGcmSetKey
// if not already done

byte cipher[AES_BLOCK_LENGTH * n]; //n being a positive integer
making cipher some multiple of 16 bytes
// initialize cipher with cipher text to decrypt
byte output[sizeof(cipher)];
byte iv[] = // some 16 byte iv
byte authTag[AUTH_TAG_LENGTH];
byte authIn[] = // Authentication Vector

wc_AesGcmDecrypt(&enc, output, cipher, sizeof(cipher), iv, sizeof(iv),
        authTag, sizeof(authTag), authIn, sizeof(authIn));

function wc_GmacSetKey

int wc_GmacSetKey(
    Gmac * gmac,
    const byte * key,
    word32 len
)

This function initializes and sets the key for a GMAC object to be used for Galois Message Authentication.

Parameters:

• gmac pointer to the gmac object used for authentication
• key 16, 24, or 32 byte secret key for authentication
• len length of the key

See:

• wc_GmacUpdate
• wc_AesInit

Return:

• 0 On successfully setting the key
• BAD_FUNC_ARG Returned if key length is invalid.

Example

Gmac gmac;
key[] = { some 16, 24, or 32 byte length key };
wc_AesInit(gmac.aes, HEAP_HINT, INVALID_DEVID); // Make sure devId updated
wc_GmacSetKey(&gmac, key, sizeof(key));

function wc_GmacUpdate

int wc_GmacUpdate(
    Gmac * gmac,
    const byte * iv,
    word32 ivSz,
    const byte * authIn,
    word32 authInSz,
    byte * authTag,
    word32 authTagSz
)

This function generates the Gmac hash of the authIn input and stores the result in the authTag buffer. After running wc_GmacUpdate, one should compare the generated authTag to a known authentication tag to verify the authenticity of a message.

Parameters:

• gmac pointer to the gmac object used for authentication
• iv initialization vector used for the hash
• ivSz size of the initialization vector used
• authIn pointer to the buffer containing the authentication vector to verify
• authInSz size of the authentication vector
• authTag pointer to the output buffer in which to store the Gmac hash
• authTagSz the size of the output buffer used to store the Gmac hash

See:

• wc_GmacSetKey
• wc_AesInit

Return: 0 On successfully computing the Gmac hash.

Example

Gmac gmac;
key[] = { some 16, 24, or 32 byte length key };
iv[] = { some 16 byte length iv };

wc_AesInit(gmac.aes, HEAP_HINT, INVALID_DEVID); // Make sure devId updated
wc_GmacSetKey(&gmac, key, sizeof(key));
authIn[] = { some 16 byte authentication input };
tag[AES_BLOCK_SIZE]; // will store authentication code

wc_GmacUpdate(&gmac, iv, sizeof(iv), authIn, sizeof(authIn), tag,
sizeof(tag));

function wc_AesCcmSetKey

int wc_AesCcmSetKey(
    Aes * aes,
    const byte * key,
    word32 keySz
)

This function sets the key for an AES object using CCM (Counter with CBC-MAC). It takes a pointer to an AES structure and initializes it with supplied key.

Parameters:

• aes aes structure in which to store the supplied key
• key 16, 24, or 32 byte secret key for encryption and decryption
• keySz size of the supplied key

See:

• wc_AesCcmEncrypt
• wc_AesCcmDecrypt

Return: none

Example

Aes enc;
key[] = { some 16, 24, or 32 byte length key };

wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID); // Make sure devId updated
wc_AesCcmSetKey(&enc, key, sizeof(key));

function wc_AesCcmEncrypt

int wc_AesCcmEncrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 inSz,
    const byte * nonce,
    word32 nonceSz,
    byte * authTag,
    word32 authTagSz,
    const byte * authIn,
    word32 authInSz
)

This function encrypts the input message, in, into the output buffer, out, using CCM (Counter with CBC-MAC). It subsequently calculates and stores the authorization tag, authTag, from the authIn input.

Parameters:

• aes pointer to the AES object used to encrypt data
• out pointer to the output buffer in which to store the cipher text
• in pointer to the input buffer holding the message to encrypt
• sz length of the input message to encrypt
• nonce pointer to the buffer containing the nonce (number only used once)
• nonceSz length of the nonce
• authTag pointer to the buffer in which to store the authentication tag
• authTagSz length of the desired authentication tag
• authIn pointer to the buffer containing the input authentication vector
• authInSz length of the input authentication vector

See:

• wc_AesCcmSetKey
• wc_AesCcmDecrypt

Return: none

Example

Aes enc;
// initialize enc with wc_AesInit and wc_AesCcmSetKey

nonce[] = { initialize nonce };
plain[] = { some plain text message };
cipher[sizeof(plain)];

authIn[] = { some 16 byte authentication input };
tag[AES_BLOCK_SIZE]; // will store authentication code

wc_AesCcmEncrypt(&enc, cipher, plain, sizeof(plain), nonce, sizeof(nonce),
        tag, sizeof(tag), authIn, sizeof(authIn));

function wc_AesCcmDecrypt

int wc_AesCcmDecrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 inSz,
    const byte * nonce,
    word32 nonceSz,
    const byte * authTag,
    word32 authTagSz,
    const byte * authIn,
    word32 authInSz
)

This function decrypts the input cipher text, in, into the output buffer, out, using CCM (Counter with CBC-MAC). It subsequently calculates the authorization tag, authTag, from the authIn input. If a nonzero error code is returned, the output data is undefined. However, callers must unconditionally zeroize the output buffer to guard against leakage of cleartext data.

Parameters:

• aes pointer to the AES object used to encrypt data
• out pointer to the output buffer in which to store the cipher text
• in pointer to the input buffer holding the message to encrypt
• sz length of the input cipher text to decrypt
• nonce pointer to the buffer containing the nonce (number only used once)
• nonceSz length of the nonce
• authTag pointer to the buffer in which to store the authentication tag
• authTagSz length of the desired authentication tag
• authIn pointer to the buffer containing the input authentication vector
• authInSz length of the input authentication vector

See:

• wc_AesCcmSetKey
• wc_AesCcmEncrypt

Return:

• 0 On successfully decrypting the input message
• AES_CCM_AUTH_E If the authentication tag does not match the supplied authentication code vector, authTag.

Example

Aes dec;
// initialize dec with wc_AesInit and wc_AesCcmSetKey

nonce[] = { initialize nonce };
cipher[] = { encrypted message };
plain[sizeof(cipher)];

authIn[] = { some 16 byte authentication input };
tag[AES_BLOCK_SIZE] = { authentication tag received for verification };

int return = wc_AesCcmDecrypt(&dec, plain, cipher, sizeof(cipher),
nonce, sizeof(nonce),tag, sizeof(tag), authIn, sizeof(authIn));
if(return != 0) {
// decrypt error, invalid authentication code
}

function wc_AesXtsInit

int wc_AesXtsInit(
    XtsAes * aes,
    void * heap,
    int devId
)

This is to initialize an AES-XTS context. It is up to user to call wc_AesXtsFree on aes key when done.

Parameters:

• aes AES keys for encrypt/decrypt process
• heap heap hint to use for memory. Can be NULL
• devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

• wc_AesXtsSetKey
• wc_AesXtsSetKeyNoInit
• wc_AesXtsEncrypt
• wc_AesXtsDecrypt
• wc_AesXtsFree

Return: 0 Success

Example

XtsAes aes;

if(wc_AesXtsInit(&aes, NULL, INVALID_DEVID) != 0)
{
    // Handle error
}
if(wc_AesXtsSetKeyNoInit(&aes, key, sizeof(key), AES_ENCRYPTION) != 0)
{
    // Handle error
}
wc_AesXtsFree(&aes);

function wc_AesXtsSetKeyNoInit

int wc_AesXtsSetKeyNoInit(
    XtsAes * aes,
    const byte * key,
    word32 len,
    int dir
)

This is to help with setting keys to correct encrypt or decrypt type, after first calling wc_AesXtsInit(). It is up to user to call wc_AesXtsFree on aes key when done.

Parameters:

• aes AES keys for encrypt/decrypt process
• key buffer holding aes key | tweak key
• len length of key buffer in bytes. Should be twice that of key size. i.e. 32 for a 16 byte key.
• dir direction, either AES_ENCRYPTION or AES_DECRYPTION

See:

• wc_AesXtsEncrypt
• wc_AesXtsDecrypt
• wc_AesXtsFree

Return: 0 Success

Example

XtsAes aes;

if(wc_AesXtsInit(&aes, NULL, 0) != 0)
{
    // Handle error
}
if(wc_AesXtsSetKeyNoInit(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0)
   != 0)
{
    // Handle error
}
wc_AesXtsFree(&aes);

function wc_AesXtsSetKey

int wc_AesXtsSetKey(
    XtsAes * aes,
    const byte * key,
    word32 len,
    int dir,
    void * heap,
    int devId
)

This is to help with setting keys to correct encrypt or decrypt type. It is up to user to call wc_AesXtsFree on aes key when done.

Parameters:

• aes AES keys for encrypt/decrypt process
• key buffer holding aes key | tweak key
• len length of key buffer in bytes. Should be twice that of key size. i.e. 32 for a 16 byte key.
• dir direction, either AES_ENCRYPTION or AES_DECRYPTION
• heap heap hint to use for memory. Can be NULL
• devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

• wc_AesXtsInit
• wc_AesXtsSetKeyNoInit
• wc_AesXtsEncrypt
• wc_AesXtsDecrypt
• wc_AesXtsFree

Return: 0 Success

Example

XtsAes aes;

if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, INVALID_DEVID) != 0)
{
    // Handle error
}
wc_AesXtsFree(&aes);

function wc_AesXtsEncryptSector

int wc_AesXtsEncryptSector(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    word64 sector
)

Same process as wc_AesXtsEncrypt but uses a word64 type as the tweak value instead of a byte array. This just converts the word64 to a byte array and calls wc_AesXtsEncrypt.

Parameters:

• aes AES keys to use for block encrypt/decrypt
• out output buffer to hold cipher text
• in input plain text buffer to encrypt
• sz size of both out and in buffers
• sector value to use for tweak

See:

• wc_AesXtsEncrypt
• wc_AesXtsDecrypt
• wc_AesXtsInit
• wc_AesXtsSetKeyNoInit
• wc_AesXtsSetKey
• wc_AesXtsFree

Return: 0 Success

Example

XtsAes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];
word64 s = VALUE;

//set up keys with AES_ENCRYPTION as dir

if(wc_AesXtsEncryptSector(&aes, cipher, plain, SIZE, s) != 0)
{
    // Handle error
}
wc_AesXtsFree(&aes);

function wc_AesXtsDecryptSector

int wc_AesXtsDecryptSector(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    word64 sector
)

Same process as wc_AesXtsDecrypt but uses a word64 type as the tweak value instead of a byte array. This just converts the word64 to a byte array.

Parameters:

• aes AES keys to use for block encrypt/decrypt
• out output buffer to hold plain text
• in input cipher text buffer to decrypt
• sz size of both out and in buffers
• sector value to use for tweak

See:

• wc_AesXtsEncrypt
• wc_AesXtsDecrypt
• wc_AesXtsInit
• wc_AesXtsSetKeyNoInit
• wc_AesXtsSetKey
• wc_AesXtsFree

Return: 0 Success

Example

XtsAes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];
word64 s = VALUE;

//set up aes key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION

if(wc_AesXtsDecryptSector(&aes, plain, cipher, SIZE, s) != 0)
{
    // Handle error
}
wc_AesXtsFree(&aes);

function wc_AesXtsEncrypt

int wc_AesXtsEncrypt(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    const byte * i,
    word32 iSz
)

AES with XTS mode. (XTS) XEX encryption with Tweak and cipher text Stealing.

Parameters:

• aes AES keys to use for block encrypt/decrypt
• out output buffer to hold cipher text
• in input plain text buffer to encrypt
• sz size of both out and in buffers
• i value to use for tweak
• iSz size of i buffer, should always be AES_BLOCK_SIZE but having this input adds a sanity check on how the user calls the function.

See:

• wc_AesXtsDecrypt
• wc_AesXtsInit
• wc_AesXtsSetKeyNoInit
• wc_AesXtsSetKey
• wc_AesXtsFree

Return: 0 Success

Example

XtsAes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];
unsigned char i[AES_BLOCK_SIZE];

//set up key with AES_ENCRYPTION as dir

if(wc_AesXtsEncrypt(&aes, cipher, plain, SIZE, i, sizeof(i)) != 0)
{
    // Handle error
}
wc_AesXtsFree(&aes);

function wc_AesXtsDecrypt

int wc_AesXtsDecrypt(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    const byte * i,
    word32 iSz
)

Same process as encryption but Aes key is AES_DECRYPTION type.

Parameters:

• aes AES keys to use for block encrypt/decrypt
• out output buffer to hold plain text
• in input cipher text buffer to decrypt
• sz size of both out and in buffers
• i value to use for tweak
• iSz size of i buffer, should always be AES_BLOCK_SIZE but having this input adds a sanity check on how the user calls the function.

See:

• wc_AesXtsEncrypt
• wc_AesXtsInit
• wc_AesXtsSetKeyNoInit
• wc_AesXtsSetKey
• wc_AesXtsFree

Return: 0 Success

Example

XtsAes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];
unsigned char i[AES_BLOCK_SIZE];

//set up key with AES_DECRYPTION as dir and tweak with AES_ENCRYPTION

if(wc_AesXtsDecrypt(&aes, plain, cipher, SIZE, i, sizeof(i)) != 0)
{
    // Handle error
}
wc_AesXtsFree(&aes);

function wc_AesXtsFree

int wc_AesXtsFree(
    XtsAes * aes
)

This is to free up any resources used by the XtsAes structure.

Parameters:

• aes AES keys to free

See:

• wc_AesXtsEncrypt
• wc_AesXtsDecrypt
• wc_AesXtsInit
• wc_AesXtsSetKeyNoInit
• wc_AesXtsSetKey

Return: 0 Success

Example

XtsAes aes;

if(wc_AesXtsSetKey(&aes, key, sizeof(key), AES_ENCRYPTION, NULL, 0) != 0)
{
    // Handle error
}
wc_AesXtsFree(&aes);

function wc_AesInit

int wc_AesInit(
    Aes * aes,
    void * heap,
    int devId
)

Initialize Aes structure. Sets heap hint to be used and ID for use with async hardware. It is up to the user to call wc_AesFree on the Aes structure when done.

Parameters:

• aes aes structure in to initialize
• heap heap hint to use for malloc / free if needed
• devId ID to use with crypto callbacks or async hardware. Set to INVALID_DEVID (-2) if not used

See:

• wc_AesSetKey
• wc_AesSetIV
• wc_AesFree

Return: 0 Success

Example

Aes enc;
void* hint = NULL;
int devId = INVALID_DEVID; //if not using async INVALID_DEVID is default

//heap hint could be set here if used

wc_AesInit(&enc, hint, devId);

function wc_AesFree

void wc_AesFree(
    Aes * aes
)

free resources associated with the Aes structure when applicable. Internally may sometimes be a no-op but still recommended to call in all cases as a general best-practice (IE if application code is ported for use on new environments where the call is applicable).

Parameters:

• aes aes structure in to free

See: wc_AesInit

Return: no return (void function)

Example

Aes enc;
void* hint = NULL;
int devId = INVALID_DEVID; //if not using async INVALID_DEVID is default

//heap hint could be set here if used

wc_AesInit(&enc, hint, devId);
// ... do some interesting things ...
wc_AesFree(&enc);

function wc_AesCfbEncrypt

int wc_AesCfbEncrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

AES with CFB mode.

Parameters:

• aes AES keys to use for block encrypt/decrypt
• out output buffer to hold cipher text must be at least as large as inputbuffer)
• in input plain text buffer to encrypt
• sz size of input buffer

See:

• wc_AesCfbDecrypt
• wc_AesSetKey

Return: 0 Success and negative error values on failure

Example

Aes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];

//set up key with AES_ENCRYPTION as dir for both encrypt and decrypt

if(wc_AesCfbEncrypt(&aes, cipher, plain, SIZE) != 0)
{
    // Handle error
}

function wc_AesCfbDecrypt

int wc_AesCfbDecrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

AES with CFB mode.

Parameters:

• aes AES keys to use for block encrypt/decrypt
• out output buffer to hold decrypted text must be at least as large as inputbuffer)
• in input buffer to decrypt
• sz size of input buffer

See:

• wc_AesCfbEncrypt
• wc_AesSetKey

Return: 0 Success and negative error values on failure

Example

Aes aes;
unsigned char plain[SIZE];
unsigned char cipher[SIZE];

//set up key with AES_ENCRYPTION as dir for both encrypt and decrypt

if(wc_AesCfbDecrypt(&aes, plain, cipher, SIZE) != 0)
{
    // Handle error
}

function wc_AesSivEncrypt

int wc_AesSivEncrypt(
    const byte * key,
    word32 keySz,
    const byte * assoc,
    word32 assocSz,
    const byte * nonce,
    word32 nonceSz,
    const byte * in,
    word32 inSz,
    byte * siv,
    byte * out
)

This function performs SIV (synthetic initialization vector) encryption as described in RFC 5297.

Parameters:

• key Byte buffer containing the key to use.
• keySz Length of the key buffer in bytes.
• assoc Additional, authenticated associated data (AD).
• assocSz Length of AD buffer in bytes.
• nonce A number used once. Used by the algorithm in the same manner as the AD.
• nonceSz Length of nonce buffer in bytes.
• in Plaintext buffer to encrypt.
• inSz Length of plaintext buffer.
• siv The SIV output by S2V (see RFC 5297 2.4).
• out Buffer to hold the ciphertext. Should be the same length as the plaintext buffer.

See: wc_AesSivDecrypt

Return:

• 0 On successful encryption.
• BAD_FUNC_ARG If key, SIV, or output buffer are NULL. Also returned if the key size isn't 32, 48, or 64 bytes.
• Other Other negative error values returned if AES or CMAC operations fail.

Example

byte key[] = { some 32, 48, or 64 byte key };
byte assoc[] = {0x01, 0x2, 0x3};
byte nonce[] = {0x04, 0x5, 0x6};
byte plainText[] = {0xDE, 0xAD, 0xBE, 0xEF};
byte siv[AES_BLOCK_SIZE];
byte cipherText[sizeof(plainText)];
if (wc_AesSivEncrypt(key, sizeof(key), assoc, sizeof(assoc), nonce,
    sizeof(nonce), plainText, sizeof(plainText), siv, cipherText) != 0) {
    // failed to encrypt
}

function wc_AesSivDecrypt

int wc_AesSivDecrypt(
    const byte * key,
    word32 keySz,
    const byte * assoc,
    word32 assocSz,
    const byte * nonce,
    word32 nonceSz,
    const byte * in,
    word32 inSz,
    byte * siv,
    byte * out
)

This function performs SIV (synthetic initialization vector) decryption as described in RFC 5297. If a nonzero error code is returned, the output data is undefined. However, callers must unconditionally zeroize the output buffer to guard against leakage of cleartext data.

Parameters:

• key Byte buffer containing the key to use.
• keySz Length of the key buffer in bytes.
• assoc Additional, authenticated associated data (AD).
• assocSz Length of AD buffer in bytes.
• nonce A number used once. Used by the underlying algorithm in the same manner as the AD.
• nonceSz Length of nonce buffer in bytes.
• in Ciphertext buffer to decrypt.
• inSz Length of ciphertext buffer.
• siv The SIV that accompanies the ciphertext (see RFC 5297 2.4).
• out Buffer to hold the decrypted plaintext. Should be the same length as the ciphertext buffer.

See: wc_AesSivEncrypt

Return:

• 0 On successful decryption.
• BAD_FUNC_ARG If key, SIV, or output buffer are NULL. Also returned if the key size isn't 32, 48, or 64 bytes.
• AES_SIV_AUTH_E If the SIV derived by S2V doesn't match the input SIV (see RFC 5297 2.7).
• Other Other negative error values returned if AES or CMAC operations fail.

Example

byte key[] = { some 32, 48, or 64 byte key };
byte assoc[] = {0x01, 0x2, 0x3};
byte nonce[] = {0x04, 0x5, 0x6};
byte cipherText[] = {0xDE, 0xAD, 0xBE, 0xEF};
byte siv[AES_BLOCK_SIZE] = { the SIV that came with the ciphertext };
byte plainText[sizeof(cipherText)];
if (wc_AesSivDecrypt(key, sizeof(key), assoc, sizeof(assoc), nonce,
    sizeof(nonce), cipherText, sizeof(cipherText), siv, plainText) != 0) {
    // failed to decrypt
}

function wc_AesEaxEncryptAuth

WOLFSSL_API int wc_AesEaxEncryptAuth(
    const byte * key,
    word32 keySz,
    byte * out,
    const byte * in,
    word32 inSz,
    const byte * nonce,
    word32 nonceSz,
    byte * authTag,
    word32 authTagSz,
    const byte * authIn,
    word32 authInSz
)

This function performs AES EAX encryption and authentication as described in "EAX: A Conventional Authenticated-Encryption Mode" (https://eprint.iacr.org/2003/069). It is a "one-shot" API that performs all encryption and authentication operations in one function call.

Parameters:

• key buffer containing the key to use
• keySz length of the key buffer in bytes
• out buffer to hold the ciphertext. Should be the same length as the plaintext buffer
• in plaintext buffer to encrypt
• inSz length of plaintext buffer
• nonce the cryptographic nonce to use for EAX operations
• nonceSz length of nonce buffer in bytes
• authTag pointer to the buffer in which to store the authentication tag
• authTagSz length of the desired authentication tag
• authIn pointer to the buffer containing input data to authenticate
• authInSz length of the input authentication data

See: wc_AesEaxDecryptAuth

Return:

• 0 on successful encryption.
• BAD_FUNC_ARG if input or output buffers are NULL. Also returned if the key size isn't a valid AES key size (16, 24, or 32 bytes)
• other negative error values returned if AES or CMAC operations fail.

Example

byte key[] = { some 32, 48, or 64 byte key };
byte nonce[] = {0x04, 0x5, 0x6};
byte plainText[] = {0xDE, 0xAD, 0xBE, 0xEF};
byte authIn[] = {0x01, 0x2, 0x3};

byte cipherText[sizeof(plainText)]; // output ciphertext
byte authTag[length, up to AES_BLOCK_SIZE]; // output authTag

if (wc_AesEaxEncrypt(key, sizeof(key),
                     cipherText, plainText, sizeof(plainText),
                     nonce, sizeof(nonce),
                     authTag, sizeof(authTag),
                     authIn, sizeof(authIn)) != 0) {
    // failed to encrypt
}

function wc_AesEaxDecryptAuth

WOLFSSL_API int wc_AesEaxDecryptAuth(
    const byte * key,
    word32 keySz,
    byte * out,
    const byte * in,
    word32 inSz,
    const byte * nonce,
    word32 nonceSz,
    const byte * authTag,
    word32 authTagSz,
    const byte * authIn,
    word32 authInSz
)

This function performs AES EAX decryption and authentication as described in "EAX: A Conventional Authenticated-Encryption Mode" (https://eprint.iacr.org/2003/069). It is a "one-shot" API that performs all decryption and authentication operations in one function call. If a nonzero error code is returned, the output data is undefined. However, callers must unconditionally zeroize the output buffer to guard against leakage of cleartext data.

Parameters:

• key byte buffer containing the key to use
• keySz length of the key buffer in bytes
• out buffer to hold the plaintext. Should be the same length as the input ciphertext buffer
• in ciphertext buffer to decrypt
• inSz length of ciphertext buffer
• nonce the cryptographic nonce to use for EAX operations
• nonceSz length of nonce buffer in bytes
• authTag buffer that holds the authentication tag to check the authenticity of the data against
• authTagSz Length of the input authentication tag
• authIn pointer to the buffer containing input data to authenticate
• authInSz length of the input authentication data

See: wc_AesEaxEncryptAuth

Return:

• 0 on successful decryption
• BAD_FUNC_ARG if input or output buffers are NULL. Also returned if the key size isn't a valid AES key size (16, 24, or 32 bytes)
• AES_EAX_AUTH_E If the authentication tag does not match the supplied authentication code vector authTag
• other negative error values returned if AES or CMAC operations fail.

Example

byte key[] = { some 32, 48, or 64 byte key };
byte nonce[] = {0x04, 0x5, 0x6};
byte cipherText[] = {0xDE, 0xAD, 0xBE, 0xEF};
byte authIn[] = {0x01, 0x2, 0x3};

byte plainText[sizeof(cipherText)]; // output plaintext
byte authTag[length, up to AES_BLOCK_SIZE]; // output authTag

if (wc_AesEaxDecrypt(key, sizeof(key),
                     cipherText, plainText, sizeof(plainText),
                     nonce, sizeof(nonce),
                     authTag, sizeof(authTag),
                     authIn, sizeof(authIn)) != 0) {
    // failed to encrypt
}

function wc_AesEaxInit

WOLFSSL_API int wc_AesEaxInit(
    AesEax * eax,
    const byte * key,
    word32 keySz,
    const byte * nonce,
    word32 nonceSz,
    const byte * authIn,
    word32 authInSz
)

This function initializes an AesEax object for use in authenticated encryption or decryption. This function must be called on an AesEax object before using it with any of the AES EAX incremental API functions. It does not need to be called if using the one-shot EAX API functions. All AesEax instances initialized with this function need to be freed with a call to wc_AesEaxFree() when done using the instance.

Parameters:

• eax AES EAX structure holding the context of the AEAD operation
• key 16, 24, or 32 byte secret key for encryption and decryption
• keySz length of the supplied key in bytes
• nonce the cryptographic nonce to use for EAX operations
• nonceSz length of nonce buffer in bytes
• authIn (optional) input data to add to the authentication stream This argument should be NULL if not used
• authInSz size in bytes of the input authentication data

See:

• wc_AesEaxEncryptUpdate
• wc_AesEaxDecryptUpdate
• wc_AesEaxAuthDataUpdate
• wc_AesEaxEncryptFinal
• wc_AesEaxDecryptFinal
• wc_AesEaxFree

Return:

• 0 on success
• error code on failure

Example

AesEax eax;
key[]   = { some 16, 24, or 32 byte length key };
nonce[] = { some arbitrary length nonce };
authIn[] = { some data to add to the authentication stream };
plainText[] = {some plaintext data to encrypt};

cipherText[sizeof(plainText)]; // buffer to hold cipherText
authTag[length, up to AES_BLOCK_SIZE]; // buffer to hold computed auth data

AesEax eax;

if ((ret = wc_AesEaxInit(eax,
                         key, keySz,
                         nonce, nonceSz,
                         authIn, authInSz)) != 0) {
    goto cleanup;
}

// if we wanted to add more auth data, we could provide it at this point,
// otherwise we use NULL for the authIn parameter, with authIn size of 0
if ((ret = wc_AesEaxEncryptUpdate(eax,
                                  cipherText, plainText, sizeof(plainText),
                                  NULL, 0)) != 0) {
    goto cleanup;
}

if ((ret = wc_AesEaxEncryptFinal(eax, authTag, sizeof(authTag))) != 0) {
    goto cleanup;
}

cleanup:
    wc_AesEaxFree(eax);

function wc_AesEaxEncryptUpdate

WOLFSSL_API int wc_AesEaxEncryptUpdate(
    AesEax * eax,
    byte * out,
    const byte * in,
    word32 inSz,
    const byte * authIn,
    word32 authInSz
)

This function uses AES EAX to encrypt input data, and optionally, add more input data to the authentication stream. eax must have been previously initialized with a call to wc_AesEaxInit.

Parameters:

• eax AES EAX structure holding the context of the AEAD operation
• out output buffer holding the ciphertext
• in input buffer holding the plaintext to encrypt
• inSz size in bytes of the input data buffer
• authIn (optional) input data to add to the authentication stream This argument should be NULL if not used
• authInSz size in bytes of the input authentication data

See:

• wc_AesEaxInit
• wc_AesEaxDecryptUpdate
• wc_AesEaxAuthDataUpdate
• wc_AesEaxEncryptFinal
• wc_AesEaxDecryptFinal
• wc_AesEaxFree

Return:

• 0 on success
• error code on failure

Example

AesEax eax;
key[]   = { some 16, 24, or 32 byte length key };
nonce[] = { some arbitrary length nonce };
authIn[] = { some data to add to the authentication stream };
plainText[] = {some plaintext data to encrypt};

cipherText[sizeof(plainText)]; // buffer to hold cipherText
authTag[length, up to AES_BLOCK_SIZE]; // buffer to hold computed auth data

AesEax eax;

if ((ret = wc_AesEaxInit(eax,
                         key, keySz,
                         nonce, nonceSz,
                         authIn, authInSz)) != 0) {
    goto cleanup;
}

// if we wanted to add more auth data, we could provide it at this point,
// otherwise we use NULL for the authIn parameter, with authInSz of 0
if ((ret = wc_AesEaxEncryptUpdate(eax,
                                  cipherText, plainText, sizeof(plainText),
                                  NULL, 0)) != 0) {
    goto cleanup;
}

if ((ret = wc_AesEaxEncryptFinal(eax, authTag, sizeof(authTag))) != 0) {
    goto cleanup;
}

cleanup:
    wc_AesEaxFree(eax);

function wc_AesEaxDecryptUpdate

WOLFSSL_API int wc_AesEaxDecryptUpdate(
    AesEax * eax,
    byte * out,
    const byte * in,
    word32 inSz,
    const byte * authIn,
    word32 authInSz
)

This function uses AES EAX to decrypt input data, and optionally, add more input data to the authentication stream. eax must have been previously initialized with a call to wc_AesEaxInit.

Parameters:

• eax AES EAX structure holding the context of the AEAD operation
• out output buffer holding the decrypted plaintext
• in input buffer holding the ciphertext
• inSz size in bytes of the input data buffer
• authIn (optional) input data to add to the authentication stream This argument should be NULL if not used
• authInSz size in bytes of the input authentication data

See:

• wc_AesEaxInit
• wc_AesEaxEncryptUpdate
• wc_AesEaxAuthDataUpdate
• wc_AesEaxEncryptFinal
• wc_AesEaxDecryptFinal
• wc_AesEaxFree

Return:

• 0 on success
• error code on failure

Example

AesEax eax;
key[]   = { some 16, 24, or 32 byte length key };
nonce[] = { some arbitrary length nonce };
authIn[] = { some data to add to the authentication stream };
cipherText[] = {some encrypted data};

plainText[sizeof(cipherText)]; // buffer to hold decrypted data
// auth tag is generated elsewhere by the encrypt AEAD operation
authTag[length, up to AES_BLOCK_SIZE] = { the auth tag };

AesEax eax;

if ((ret = wc_AesEaxInit(eax,
                         key, keySz,
                         nonce, nonceSz,
                         authIn, authInSz)) != 0) {
    goto cleanup;
}

// if we wanted to add more auth data, we could provide it at this point,
// otherwise we use NULL for the authIn parameter, with authInSz of 0
if ((ret = wc_AesEaxDecryptUpdate(eax,
                                  plainText, cipherText, sizeof(cipherText),
                                  NULL, 0)) != 0) {
    goto cleanup;
}

if ((ret = wc_AesEaxDecryptFinal(eax, authTag, sizeof(authTag))) != 0) {
    goto cleanup;
}

cleanup:
    wc_AesEaxFree(eax);

function wc_AesEaxAuthDataUpdate

WOLFSSL_API int wc_AesEaxAuthDataUpdate(
    AesEax * eax,
    const byte * authIn,
    word32 authInSz
)

This function adds input data to the authentication stream. eax must have been previously initialized with a call to wc_AesEaxInit.

Parameters:

• eax AES EAX structure holding the context of the AEAD operation
• authIn input data to add to the authentication stream
• authInSz size in bytes of the input authentication data

See:

• wc_AesEaxInit
• wc_AesEaxEncryptUpdate
• wc_AesEaxDecryptUpdate
• wc_AesEaxEncryptFinal
• wc_AesEaxDecryptFinal
• wc_AesEaxFree

Return:

• 0 on success
• error code on failure

Example

AesEax eax;
key[]   = { some 16, 24, or 32 byte length key };
nonce[] = { some arbitrary length nonce };
authIn[] = { some data to add to the authentication stream };
cipherText[] = {some encrypted data};

plainText[sizeof(cipherText)]; // buffer to hold decrypted data
// auth tag is generated elsewhere by the encrypt AEAD operation
authTag[length, up to AES_BLOCK_SIZE] = { the auth tag };

AesEax eax;

// No auth data to add here
if ((ret = wc_AesEaxInit(eax,
                         key, keySz,
                         nonce, nonceSz,
                         NULL, 0)) != 0) {
    goto cleanup;
}

// No auth data to add here, added later with wc_AesEaxAuthDataUpdate
if ((ret = wc_AesEaxDecryptUpdate(eax,
                                  plainText, cipherText, sizeof(cipherText),
                                  NULL, 0)) != 0) {
    goto cleanup;
}

if ((ret = wc_AesEaxAuthDataUpdate(eax, authIn, sizeof(authIn))) != 0) {
    goto cleanup;
}

if ((ret = wc_AesEaxDecryptFinal(eax, authTag, sizeof(authTag))) != 0) {
    goto cleanup;
}

cleanup:
    wc_AesEaxFree(eax);

function wc_AesEaxEncryptFinal

WOLFSSL_API int wc_AesEaxEncryptFinal(
    AesEax * eax,
    byte * authTag,
    word32 authTagSz
)

This function finalizes the encrypt AEAD operation, producing an auth tag over the current authentication stream. eax must have been previously initialized with a call to wc_AesEaxInit. When done using the AesEax context structure, make sure to free it using wc_AesEaxFree.

Parameters:

• eax AES EAX structure holding the context of the AEAD operation
• authTag[out] buffer that will hold the computed auth tag
• authTagSz size in bytes of authTag

See:

• wc_AesEaxInit
• wc_AesEaxEncryptUpdate
• wc_AesEaxDecryptUpdate
• wc_AesEaxAuthDataUpdate
• wc_AesEaxDecryptFinal
• wc_AesEaxFree

Return:

• 0 on success
• error code on failure

Example

AesEax eax;
key[]   = { some 16, 24, or 32 byte length key };
nonce[] = { some arbitrary length nonce };
authIn[] = { some data to add to the authentication stream };
plainText[] = {some plaintext data to encrypt};

cipherText[sizeof(plainText)]; // buffer to hold cipherText
authTag[length, up to AES_BLOCK_SIZE]; // buffer to hold computed auth data

AesEax eax;

if ((ret = wc_AesEaxInit(eax,
                         key, keySz,
                         nonce, nonceSz,
                         authIn, authInSz)) != 0) {
    goto cleanup;
}

// if we wanted to add more auth data, we could provide it at this point,
// otherwise we use NULL for the authIn parameter, with authInSz of 0
if ((ret = wc_AesEaxEncryptUpdate(eax,
                                  cipherText, plainText, sizeof(plainText),
                                  NULL, 0)) != 0) {
    goto cleanup;
}

if ((ret = wc_AesEaxEncryptFinal(eax, authTag, sizeof(authTag))) != 0) {
    goto cleanup;
}

cleanup:
    wc_AesEaxFree(eax);

function wc_AesEaxDecryptFinal

WOLFSSL_API int wc_AesEaxDecryptFinal(
    AesEax * eax,
    const byte * authIn,
    word32 authInSz
)

This function finalizes the decrypt AEAD operation, finalizing the auth tag computation and checking it for validity against the user supplied tag. eax must have been previously initialized with a call to wc_AesEaxInit. When done using the AesEax context structure, make sure to free it using wc_AesEaxFree.

Parameters:

• eax AES EAX structure holding the context of the AEAD operation
• authIn input auth tag to check computed auth tag against
• authInSz size in bytes of authIn

See:

• wc_AesEaxInit
• wc_AesEaxEncryptUpdate
• wc_AesEaxDecryptUpdate
• wc_AesEaxAuthDataUpdate
• wc_AesEaxEncryptFinal
• wc_AesEaxFree

Return:

• 0 if data is authenticated successfully
• AES_EAX_AUTH_E if the authentication tag does not match the supplied authentication code vector authIn
• other error code on failure

Example

AesEax eax;
key[]   = { some 16, 24, or 32 byte length key };
nonce[] = { some arbitrary length nonce };
authIn[] = { some data to add to the authentication stream };
cipherText[] = {some encrypted data};

plainText[sizeof(cipherText)]; // buffer to hold decrypted data
// auth tag is generated elsewhere by the encrypt AEAD operation
authTag[length, up to AES_BLOCK_SIZE] = { the auth tag };

AesEax eax;

if ((ret = wc_AesEaxInit(eax,
                         key, keySz,
                         nonce, nonceSz,
                         authIn, authInSz)) != 0) {
    goto cleanup;
}

// if we wanted to add more auth data, we could provide it at this point,
// otherwise we use NULL for the authIn parameter, with authInSz of 0
if ((ret = wc_AesEaxDecryptUpdate(eax,
                                  plainText, cipherText, sizeof(cipherText),
                                  NULL, 0)) != 0) {
    goto cleanup;
}

if ((ret = wc_AesEaxDecryptFinal(eax, authTag, sizeof(authTag))) != 0) {
    goto cleanup;
}

cleanup:
    wc_AesEaxFree(eax);

function wc_AesEaxFree

WOLFSSL_API int wc_AesEaxFree(
    AesEax * eax
)

This frees up any resources, specifically keys, used by the Aes instance inside the AesEax wrapper struct. It should be called on the AesEax struct after it has been initialized with wc_AesEaxInit, and all desired EAX operations are complete.

Parameters:

• eaxAES EAX instance to free

See:

• wc_AesEaxInit
• wc_AesEaxEncryptUpdate
• wc_AesEaxDecryptUpdate
• wc_AesEaxAuthDataUpdate
• wc_AesEaxEncryptFinal
• wc_AesEaxDecryptFinal

Return: 0 Success

Example

AesEax eax;

if(wc_AesEaxInit(eax, key, keySz, nonce, nonceSz, authIn, authInSz) != 0) {
    // handle errors, then free
    wc_AesEaxFree(&eax);
}

function wc_AesCtsEncrypt

int wc_AesCtsEncrypt(
    const byte * key,
    word32 keySz,
    byte * out,
    const byte * in,
    word32 inSz,
    const byte * iv
)

This function performs AES encryption using Ciphertext Stealing (CTS) mode. It is a one-shot API that handles all operations in a single call.

Parameters:

• key pointer to the AES key used for encryption.
• keySz size of the AES key in bytes (16, 24, or 32 bytes).
• out buffer to hold the encrypted ciphertext. Must be at least the size of the input.
• in pointer to the plaintext input data to encrypt.
• inSz size of the plaintext input data in bytes.
• iv pointer to the initialization vector (IV) used for encryption. Must be 16 bytes.
• key pointer to the AES key used for encryption.
• keySz size of the AES key in bytes (16, 24, or 32 bytes).
• out buffer to hold the encrypted ciphertext. Must be at least the same size as the input plaintext.
• in pointer to the plaintext input data to encrypt.
• inSz size of the plaintext input data in bytes.
• iv pointer to the initialization vector (IV) used for encryption. Must be 16 bytes. Example

byte key[16] = { 0 };
byte iv[16] = { 0 };
byte plaintext[] = { 0x01, 0x02, 0x03, 0x04, 0x05 };
byte ciphertext[sizeof(plaintext)];
int ret = wc_AesCtsEncrypt(key, sizeof(key), ciphertext, plaintext,
                           sizeof(plaintext), iv);
if (ret != 0) {
    // handle encryption error
}

See:

• wc_AesCtsDecrypt
• wc_AesCtsDecrypt

Return:

• 0 on successful encryption.
• BAD_FUNC_ARG if input arguments are invalid.
• other negative error codes for encryption failures.
• 0 on successful encryption.
• BAD_FUNC_ARG if input arguments are invalid.
• other negative error codes for encryption failures.

Example

    byte key[16] = { 0 };
    byte iv[16] = { 0 };
    byte plaintext[] = { 0x01, 0x02, 0x03, 0x04, 0x05 };
    byte ciphertext[sizeof(plaintext)];

    int ret = wc_AesCtsEncrypt(key, sizeof(key), ciphertext, plaintext,
        sizeof(plaintext), iv);
    if (ret != 0) {
    // handle encryption error
}

function wc_AesCtsDecrypt

int wc_AesCtsDecrypt(
    const byte * key,
    word32 keySz,
    byte * out,
    const byte * in,
    word32 inSz,
    const byte * iv
)

This function performs AES decryption using Ciphertext Stealing (CTS) mode. It is a one-shot API that handles all operations in a single call.

Parameters:

• key pointer to the AES key used for decryption.
• keySz size of the AES key in bytes (16, 24, or 32 bytes).
• out buffer to hold the decrypted plaintext. Must be at least the same size as the input ciphertext.
• in pointer to the ciphertext input data to decrypt.
• inSz size of the ciphertext input data in bytes.
• iv pointer to the initialization vector (IV) used for decryption. Must be 16 bytes. Example

byte key[16] = { 0 };
byte iv[16] = { 0 };
byte ciphertext[] = { 0x01, 0x02, 0x03, 0x04, 0x05 };
byte plaintext[sizeof(ciphertext)];
int ret = wc_AesCtsDecrypt(key, sizeof(key), plaintext, ciphertext,
                           sizeof(ciphertext), iv);
if (ret != 0) {
    // handle decryption error
}

See: wc_AesCtsEncrypt

Return:

• 0 on successful decryption.
• BAD_FUNC_ARG if input arguments are invalid.
• other negative error codes for decryption failures.

function wc_AesCtsEncryptUpdate

int wc_AesCtsEncryptUpdate(
    Aes * aes,
    byte * out,
    word32 * outSz,
    const byte * in,
    word32 inSz
)

This function performs an update step of the AES CTS encryption. It processes a chunk of plaintext and stores intermediate data.

Parameters:

• aes pointer to the Aes structure holding the context of the operation.
• out buffer to hold the encrypted ciphertext. Must be large enough to store the output from this update step.
• outSz size in bytes of the output data written to the out buffer. On input, it should contain the maximum number of bytes that can be written to the out buffer.
• in pointer to the plaintext input data to encrypt.
• inSz size of the plaintext input data in bytes. Example

Aes aes;
wc_AesInit(&aes, NULL, INVALID_DEVID);
byte key[16] = { 0 };
byte iv[16] = { 0 };
byte plaintext[] = { ... };
byte ciphertext[sizeof(plaintext)];
word32 outSz = sizeof(ciphertext);
wc_AesSetKey(&aes, key, sizeof(key), iv, AES_ENCRYPTION);
int ret = wc_AesCtsEncryptUpdate(&aes, ciphertext, &outSz, plaintext, sizeof(plaintext));
if (ret != 0) {
    // handle error
}
wc_AesFree(&aes);

See: wc_AesCtsDecryptUpdate

Return:

• 0 on successful processing.
• BAD_FUNC_ARG if input arguments are invalid.

function wc_AesCtsEncryptFinal

int wc_AesCtsEncryptFinal(
    Aes * aes,
    byte * out,
    word32 * outSz
)

This function finalizes the AES CTS encryption operation. It processes any remaining plaintext and completes the encryption.

Parameters:

• aes pointer to the Aes structure holding the context of the operation.
• out buffer to hold the final encrypted ciphertext. Must be large enough to store any remaining ciphertext from this final step.
• outSz size in bytes of the output data written to the out buffer. On input, it should contain the maximum number of bytes that can be written to the out buffer. Example

Aes aes;
wc_AesInit(&aes, NULL, INVALID_DEVID);
byte key[16] = { 0 };
byte iv[16] = { 0 };
byte plaintext[] = { ... };
byte ciphertext[sizeof(plaintext)];
word32 outSz = sizeof(ciphertext);
wc_AesSetKey(&aes, key, sizeof(key), iv, AES_ENCRYPTION);
// Perform any required update steps using wc_AesCtsEncryptUpdate
int ret = wc_AesCtsEncryptFinal(&aes, ciphertext, &outSz);
if (ret != 0) {
    // handle error
}
wc_AesFree(&aes);

See: wc_AesCtsDecryptFinal

Return:

• 0 on successful encryption completion.
• BAD_FUNC_ARG if input arguments are invalid.

function wc_AesCtsDecryptUpdate

int wc_AesCtsDecryptUpdate(
    Aes * aes,
    byte * out,
    word32 * outSz,
    const byte * in,
    word32 inSz
)

This function performs an update step of the AES CTS decryption. It processes a chunk of ciphertext and stores intermediate data.

Parameters:

• aes pointer to the Aes structure holding the context of the operation.
• out buffer to hold the decrypted plaintext. Must be large enough to store the output from this update step.
• outSz size in bytes of the output data written to the out buffer. On input, it should contain the maximum number of bytes that can be written to the out buffer.
• in pointer to the ciphertext input data to decrypt.
• inSz size of the ciphertext input data in bytes. Example

Aes aes;
wc_AesInit(&aes, NULL, INVALID_DEVID);
byte key[16] = { 0 };
byte iv[16] = { 0 };
byte ciphertext[] = { ... };
byte plaintext[sizeof(ciphertext)];
word32 outSz = sizeof(plaintext);
wc_AesSetKey(&aes, key, sizeof(key), iv, AES_DECRYPTION);
int ret = wc_AesCtsDecryptUpdate(&aes, plaintext, &outSz, ciphertext, sizeof(ciphertext));
if (ret != 0) {
    // handle error
}
wc_AesFree(&aes);

See: wc_AesCtsEncryptUpdate

Return:

• 0 on successful processing.
• BAD_FUNC_ARG if input arguments are invalid.

function wc_AesCtsDecryptFinal

int wc_AesCtsDecryptFinal(
    Aes * aes,
    byte * out,
    word32 * outSz
)

This function finalizes the AES CTS decryption operation. It processes any remaining ciphertext and completes the decryption.

Parameters:

• aes pointer to the Aes structure holding the context of the operation.
• out buffer to hold the final decrypted plaintext. Must be large enough to store any remaining plaintext from this final step.
• outSz size in bytes of the output data written to the out buffer. On input, it should contain the maximum number of bytes that can be written to the out buffer. Example

Aes aes;
wc_AesInit(&aes, NULL, INVALID_DEVID);
byte key[16] = { 0 };
byte iv[16] = { 0 };
byte ciphertext[] = { ... };
byte plaintext[sizeof(ciphertext)];
word32 outSz = sizeof(plaintext);
wc_AesSetKey(&aes, key, sizeof(key), iv, AES_DECRYPTION);
// Perform any required update steps using wc_AesCtsDecryptUpdate
int ret = wc_AesCtsDecryptFinal(&aes, plaintext, &outSz);
if (ret != 0) {
    // handle error
}
wc_AesFree(&aes);

See: wc_AesCtsEncryptFinal

Return:

• 0 on successful decryption completion.
• BAD_FUNC_ARG if input arguments are invalid.

function wc_AesCfb1Encrypt

int wc_AesCfb1Encrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

This function encrypts data using AES CFB-1 mode (1-bit feedback). It processes data one bit at a time, making it suitable for bit-oriented applications.

Parameters:

• aes pointer to the AES structure containing the key
• out pointer to the output buffer to store encrypted data
• in pointer to the input buffer containing data to encrypt (packed to left, e.g., 101 is 0x90)
• sz size of input in bits

See:

• wc_AesCfb1Decrypt
• wc_AesCfb8Encrypt

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[16] = { }; // initialization vector
byte plaintext[1] = { 0x90 }; // bits 101
byte ciphertext[1];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
int ret = wc_AesCfb1Encrypt(&aes, ciphertext, plaintext, 3);
if (ret != 0) {
    // encryption failed
}
wc_AesFree(&aes);

function wc_AesCfb8Encrypt

int wc_AesCfb8Encrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

This function encrypts data using AES CFB-8 mode (8-bit feedback). It processes data one byte at a time, making it suitable for byte-oriented stream encryption.

Parameters:

• aes pointer to the AES structure containing the key
• out pointer to the output buffer to store encrypted data
• in pointer to the input buffer containing data to encrypt
• sz size of input in bytes

See:

• wc_AesCfb8Decrypt
• wc_AesCfb1Encrypt

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[16] = { }; // initialization vector
byte plaintext[10] = { }; // data to encrypt
byte ciphertext[10];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
int ret = wc_AesCfb8Encrypt(&aes, ciphertext, plaintext, 10);
if (ret != 0) {
    // encryption failed
}
wc_AesFree(&aes);

function wc_AesCfb1Decrypt

int wc_AesCfb1Decrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

This function decrypts data using AES CFB-1 mode (1-bit feedback). It processes data one bit at a time, making it suitable for bit-oriented applications.

Parameters:

• aes pointer to the AES structure containing the key
• out pointer to the output buffer to store decrypted data
• in pointer to the input buffer containing data to decrypt
• sz size of input in bits

See:

• wc_AesCfb1Encrypt
• wc_AesCfb8Decrypt

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[16] = { }; // initialization vector
byte ciphertext[1] = { }; // encrypted bits
byte plaintext[1];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
int ret = wc_AesCfb1Decrypt(&aes, plaintext, ciphertext, 3);
if (ret != 0) {
    // decryption failed
}
wc_AesFree(&aes);

function wc_AesCfb8Decrypt

int wc_AesCfb8Decrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

This function decrypts data using AES CFB-8 mode (8-bit feedback). It processes data one byte at a time, making it suitable for byte-oriented stream decryption.

Parameters:

• aes pointer to the AES structure containing the key
• out pointer to the output buffer to store decrypted data
• in pointer to the input buffer containing data to decrypt
• sz size of input in bytes

See:

• wc_AesCfb8Encrypt
• wc_AesCfb1Decrypt

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[16] = { }; // initialization vector
byte ciphertext[10] = { }; // encrypted data
byte plaintext[10];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
int ret = wc_AesCfb8Decrypt(&aes, plaintext, ciphertext, 10);
if (ret != 0) {
    // decryption failed
}
wc_AesFree(&aes);

function wc_AesOfbEncrypt

int wc_AesOfbEncrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

This function encrypts data using AES OFB mode (Output Feedback). OFB mode turns a block cipher into a stream cipher by encrypting the IV and XORing with plaintext.

Parameters:

• aes pointer to the AES structure containing the key
• out pointer to the output buffer to store encrypted data
• in pointer to the input buffer containing data to encrypt
• sz size of input in bytes

See:

• wc_AesOfbDecrypt
• wc_AesSetKey

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[16] = { }; // initialization vector
byte plaintext[100] = { }; // data to encrypt
byte ciphertext[100];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
int ret = wc_AesOfbEncrypt(&aes, ciphertext, plaintext, 100);
if (ret != 0) {
    // encryption failed
}
wc_AesFree(&aes);

function wc_AesOfbDecrypt

int wc_AesOfbDecrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

This function decrypts data using AES OFB mode (Output Feedback). In OFB mode, encryption and decryption are the same operation.

Parameters:

• aes pointer to the AES structure containing the key
• out pointer to the output buffer to store decrypted data
• in pointer to the input buffer containing data to decrypt
• sz size of input in bytes

See:

• wc_AesOfbEncrypt
• wc_AesSetKey

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[16] = { }; // initialization vector
byte ciphertext[100] = { }; // encrypted data
byte plaintext[100];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
int ret = wc_AesOfbDecrypt(&aes, plaintext, ciphertext, 100);
if (ret != 0) {
    // decryption failed
}
wc_AesFree(&aes);

function wc_AesEcbEncrypt

int wc_AesEcbEncrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

This function encrypts data using AES ECB mode (Electronic Codebook). Warning: ECB mode is not recommended for most use cases as it does not provide semantic security. Each block is encrypted independently.

Parameters:

• aes pointer to the AES structure containing the key
• out pointer to the output buffer to store encrypted data
• in pointer to the input buffer containing data to encrypt
• sz size of input in bytes (must be multiple of AES_BLOCK_SIZE)

See:

• wc_AesEcbDecrypt
• wc_AesSetKey

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte plaintext[32] = { }; // data to encrypt
byte ciphertext[32];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, 16, NULL, AES_ENCRYPTION);
int ret = wc_AesEcbEncrypt(&aes, ciphertext, plaintext, 32);
if (ret != 0) {
    // encryption failed
}
wc_AesFree(&aes);

function wc_AesEcbDecrypt

int wc_AesEcbDecrypt(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz
)

This function decrypts data using AES ECB mode (Electronic Codebook). Warning: ECB mode is not recommended for most use cases as it does not provide semantic security. Each block is decrypted independently.

Parameters:

• aes pointer to the AES structure containing the key
• out pointer to the output buffer to store decrypted data
• in pointer to the input buffer containing data to decrypt
• sz size of input in bytes (must be multiple of AES_BLOCK_SIZE)

See:

• wc_AesEcbEncrypt
• wc_AesSetKey

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte ciphertext[32] = { }; // encrypted data
byte plaintext[32];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, 16, NULL, AES_DECRYPTION);
int ret = wc_AesEcbDecrypt(&aes, plaintext, ciphertext, 32);
if (ret != 0) {
    // decryption failed
}
wc_AesFree(&aes);

function wc_AesCtrSetKey

int wc_AesCtrSetKey(
    Aes * aes,
    const byte * key,
    word32 len,
    const byte * iv,
    int dir
)

This function sets the key and IV for AES CTR mode. It initializes the AES structure for counter mode encryption or decryption.

Parameters:

• aes pointer to the AES structure to initialize
• key pointer to the key buffer (16, 24, or 32 bytes)
• len length of the key in bytes
• iv pointer to the initialization vector (16 bytes)
• dir cipher direction (always use AES_ENCRYPTION for CTR mode)

See:

• wc_AesCtrEncrypt
• wc_AesSetKey

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, key, or iv is NULL, or if key length is invalid.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[16] = { }; // initialization vector

wc_AesInit(&aes, NULL, INVALID_DEVID);
int ret = wc_AesCtrSetKey(&aes, key, 16, iv, AES_ENCRYPTION);
if (ret != 0) {
    // failed to set key
}
wc_AesFree(&aes);

function wc_AesGcmSetKey_ex

int wc_AesGcmSetKey_ex(
    Aes * aes,
    const byte * key,
    word32 len,
    word32 kup
)

This function sets the key for AES GCM with an extended key update parameter. It allows for key updates in certain hardware implementations.

Parameters:

• aes pointer to the AES structure to initialize
• key pointer to the key buffer (16, 24, or 32 bytes)
• len length of the key in bytes
• kup key update parameter for hardware implementations

See:

• wc_AesGcmSetKey
• wc_AesGcmInit

Return:

• 0 On success.
• BAD_FUNC_ARG If aes or key is NULL, or if key length is invalid.

Note: This function is currently only available when building with Xilinx hardware acceleration. It requires one of the following build options: WOLFSSL_XILINX_CRYPT (for Xilinx SecureIP integration) or WOLFSSL_AFALG_XILINX_AES (for Xilinx AF_ALG support). This API may be exposed for additional build configurations in the future.

Example

Aes aes;
byte key[16] = { }; // 128-bit key

wc_AesInit(&aes, NULL, INVALID_DEVID);
int ret = wc_AesGcmSetKey_ex(&aes, key, 16, 0);
if (ret != 0) {
    // failed to set key
}
wc_AesFree(&aes);

function wc_AesGcmInit

int wc_AesGcmInit(
    Aes * aes,
    const byte * key,
    word32 len,
    const byte * iv,
    word32 ivSz
)

This function initializes an AES GCM cipher with key and IV. It can be called with NULL key to only set the IV, or with NULL IV to only set the key.

Parameters:

• aes pointer to the AES structure to initialize
• key pointer to the key buffer, or NULL to skip key setting
• len length of the key in bytes
• iv pointer to the IV/nonce buffer, or NULL to skip IV setting
• ivSz length of the IV/nonce in bytes

See:

• wc_AesGcmSetKey
• wc_AesGcmEncrypt

Return:

• 0 On success.
• BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.
• MEMORY_E If dynamic memory allocation fails.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // 96-bit nonce

wc_AesInit(&aes, NULL, INVALID_DEVID);
int ret = wc_AesGcmInit(&aes, key, 16, iv, 12);
if (ret != 0) {
    // failed to initialize
}
wc_AesFree(&aes);

function wc_AesGcmEncryptInit

int wc_AesGcmEncryptInit(
    Aes * aes,
    const byte * key,
    word32 len,
    const byte * iv,
    word32 ivSz
)

This function initializes an AES GCM cipher for encryption. It is a convenience wrapper around wc_AesGcmInit for encryption operations.

Parameters:

• aes pointer to the AES structure to initialize
• key pointer to the key buffer, or NULL to skip key setting
• len length of the key in bytes
• iv pointer to the IV/nonce buffer, or NULL to skip IV setting
• ivSz length of the IV/nonce in bytes

See:

• wc_AesGcmInit
• wc_AesGcmEncryptUpdate

Return:

• 0 On success.
• BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // 96-bit nonce

wc_AesInit(&aes, NULL, INVALID_DEVID);
int ret = wc_AesGcmEncryptInit(&aes, key, 16, iv, 12);
if (ret != 0) {
    // failed to initialize
}
wc_AesFree(&aes);

function wc_AesGcmEncryptInit_ex

int wc_AesGcmEncryptInit_ex(
    Aes * aes,
    const byte * key,
    word32 len,
    byte * ivOut,
    word32 ivOutSz
)

This function initializes an AES GCM cipher for encryption and outputs the IV. This is useful when part of the IV is generated internally. Must call wc_AesGcmSetIV() before this function to set the fixed part of the IV.

Parameters:

• aes pointer to the AES structure to initialize
• key pointer to the key buffer, or NULL to skip key setting
• len length of the key in bytes
• ivOut pointer to buffer to receive the complete IV
• ivOutSz length of the IV output buffer in bytes

See:

• wc_AesGcmSetIV
• wc_AesGcmEncryptUpdate

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, ivOut is NULL, or if ivOutSz doesn't match the cached nonce size.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte ivFixed[4] = { }; // fixed part of IV
byte ivOut[12];
WC_RNG rng;

wc_InitRng(&rng);
wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesGcmSetIV(&aes, 12, ivFixed, 4, &rng);
int ret = wc_AesGcmEncryptInit_ex(&aes, key, 16, ivOut, 12);
if (ret != 0) {
    // failed to initialize
}
wc_AesFree(&aes);
wc_FreeRng(&rng);

function wc_AesGcmEncryptUpdate

int wc_AesGcmEncryptUpdate(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    const byte * authIn,
    word32 authInSz
)

This function performs an update step of AES GCM encryption. It processes plaintext and/or additional authentication data (AAD) in a streaming fashion.

Parameters:

• aes pointer to the AES structure
• out pointer to buffer to store ciphertext (can be NULL if sz=0)
• in pointer to plaintext to encrypt (can be NULL if sz=0)
• sz length of plaintext in bytes
• authIn pointer to additional authentication data (can be NULL)
• authInSz length of AAD in bytes

See:

• wc_AesGcmInit
• wc_AesGcmEncryptInit
• wc_AesGcmEncryptFinal

Return:

• 0 On success.
• BAD_FUNC_ARG If aes is NULL, or a length is non-zero but buffer is NULL.

All the AAD must be passed to update before the plaintext. The last part of AAD can be passed with the first part of plaintext.

Must set key and IV before calling this function. Must call wc_AesGcmInit() before calling this function.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // nonce
byte plaintext[100] = { }; // data
byte ciphertext[100];
byte aad[20] = { }; // additional data

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesGcmInit(&aes, key, 16, iv, 12);
int ret = wc_AesGcmEncryptUpdate(&aes, ciphertext, plaintext, 100,
                                 aad, 20);
if (ret != 0) {
    // encryption failed
}
wc_AesFree(&aes);

function wc_AesGcmEncryptFinal

int wc_AesGcmEncryptFinal(
    Aes * aes,
    byte * authTag,
    word32 authTagSz
)

This function finalizes AES GCM encryption and generates the authentication tag. This must be called after all data has been processed with wc_AesGcmEncryptUpdate.

Parameters:

• aes pointer to the AES structure
• authTag pointer to buffer to store the authentication tag
• authTagSz length of the authentication tag in bytes (typically 12 or 16)

See:

• wc_AesGcmEncryptUpdate
• wc_AesGcmDecryptFinal

Return:

• 0 On success.
• BAD_FUNC_ARG If aes or authTag is NULL, or if authTagSz is invalid.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // nonce
byte plaintext[100] = { }; // data
byte ciphertext[100];
byte authTag[16];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesGcmEncryptInit(&aes, key, 16, iv, 12);
wc_AesGcmEncryptUpdate(&aes, ciphertext, plaintext, 100, NULL, 0);
int ret = wc_AesGcmEncryptFinal(&aes, authTag, 16);
if (ret != 0) {
    // failed to generate tag
}
wc_AesFree(&aes);

function wc_AesGcmDecryptInit

int wc_AesGcmDecryptInit(
    Aes * aes,
    const byte * key,
    word32 len,
    const byte * iv,
    word32 ivSz
)

This function initializes an AES GCM cipher for decryption. It is a convenience wrapper around wc_AesGcmInit for decryption operations.

Parameters:

• aes pointer to the AES structure to initialize
• key pointer to the key buffer, or NULL to skip key setting
• len length of the key in bytes
• iv pointer to the IV/nonce buffer, or NULL to skip IV setting
• ivSz length of the IV/nonce in bytes

See:

• wc_AesGcmInit
• wc_AesGcmDecryptUpdate

Return:

• 0 On success.
• BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // 96-bit nonce

wc_AesInit(&aes, NULL, INVALID_DEVID);
int ret = wc_AesGcmDecryptInit(&aes, key, 16, iv, 12);
if (ret != 0) {
    // failed to initialize
}
wc_AesFree(&aes);

function wc_AesGcmDecryptUpdate

int wc_AesGcmDecryptUpdate(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    const byte * authIn,
    word32 authInSz
)

This function performs an update step of AES GCM decryption. It processes ciphertext and/or additional authentication data (AAD) in a streaming fashion.

Parameters:

• aes pointer to the AES structure
• out pointer to buffer to store plaintext (can be NULL if sz=0)
• in pointer to ciphertext to decrypt (can be NULL if sz=0)
• sz length of ciphertext in bytes
• authIn pointer to additional authentication data (can be NULL)
• authInSz length of AAD in bytes

See:

• wc_AesGcmInit
• wc_AesGcmDecryptInit
• wc_AesGcmDecryptFinal

Return:

• 0 On success.
• BAD_FUNC_ARG If aes is NULL, or a length is non-zero but buffer is NULL.

All the AAD must be passed to update before the ciphertext. The last part of AAD can be passed with the first part of ciphertext.

Must set key and IV before calling this function. Must call wc_AesGcmInit() before calling this function.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // nonce
byte ciphertext[100] = { }; // encrypted data
byte plaintext[100];
byte aad[20] = { }; // additional data

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesGcmInit(&aes, key, 16, iv, 12);
int ret = wc_AesGcmDecryptUpdate(&aes, plaintext, ciphertext, 100,
                                 aad, 20);
if (ret != 0) {
    // decryption failed
}
wc_AesFree(&aes);

function wc_AesGcmDecryptFinal

int wc_AesGcmDecryptFinal(
    Aes * aes,
    const byte * authTag,
    word32 authTagSz
)

This function finalizes AES GCM decryption and verifies the authentication tag. This must be called after all data has been processed with wc_AesGcmDecryptUpdate.

Parameters:

• aes pointer to the AES structure
• authTag pointer to the authentication tag to verify
• authTagSz length of the authentication tag in bytes

See:

• wc_AesGcmDecryptUpdate
• wc_AesGcmEncryptFinal

Return:

• 0 On success.
• AES_GCM_AUTH_E If authentication tag verification fails.
• BAD_FUNC_ARG If aes or authTag is NULL, or if authTagSz is invalid.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // nonce
byte ciphertext[100] = { }; // encrypted data
byte plaintext[100];
byte authTag[16] = { }; // received tag

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesGcmDecryptInit(&aes, key, 16, iv, 12);
wc_AesGcmDecryptUpdate(&aes, plaintext, ciphertext, 100, NULL, 0);
int ret = wc_AesGcmDecryptFinal(&aes, authTag, 16);
if (ret != 0) {
    // authentication failed
}
wc_AesFree(&aes);

function wc_AesGcmSetExtIV

int wc_AesGcmSetExtIV(
    Aes * aes,
    const byte * iv,
    word32 ivSz
)

This function sets an external IV for AES GCM. This allows using an IV that was generated externally or received from another source.

Parameters:

• aes pointer to the AES structure
• iv pointer to the IV/nonce buffer
• ivSz length of the IV/nonce in bytes

See:

• wc_AesGcmSetIV
• wc_AesGcmInit

Return:

• 0 On success.
• BAD_FUNC_ARG If aes or iv is NULL, or if ivSz is invalid.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // external nonce

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesGcmSetKey(&aes, key, 16);
int ret = wc_AesGcmSetExtIV(&aes, iv, 12);
if (ret != 0) {
    // failed to set IV
}
wc_AesFree(&aes);

function wc_AesGcmSetIV

int wc_AesGcmSetIV(
    Aes * aes,
    word32 ivSz,
    const byte * ivFixed,
    word32 ivFixedSz,
    WC_RNG * rng
)

This function sets the IV for AES GCM with optional random generation. It can generate part of the IV using an RNG, which is useful for ensuring IV uniqueness.

Parameters:

• aes pointer to the AES structure
• ivSz total length of the IV/nonce in bytes
• ivFixed pointer to the fixed part of the IV (can be NULL)
• ivFixedSz length of the fixed part in bytes
• rng pointer to initialized RNG for generating random part (can be NULL if ivFixedSz equals ivSz)

See:

• wc_AesGcmSetExtIV
• wc_AesGcmEncryptInit_ex

Return:

• 0 On success.
• BAD_FUNC_ARG If aes is NULL, or if parameters are invalid.
• Other negative values on RNG or other errors.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte ivFixed[4] = { }; // fixed part
WC_RNG rng;

wc_InitRng(&rng);
wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesGcmSetKey(&aes, key, 16);
int ret = wc_AesGcmSetIV(&aes, 12, ivFixed, 4, &rng);
if (ret != 0) {
    // failed to set IV
}
wc_AesFree(&aes);
wc_FreeRng(&rng);

function wc_AesGcmEncrypt_ex

int wc_AesGcmEncrypt_ex(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    byte * ivOut,
    word32 ivOutSz,
    byte * authTag,
    word32 authTagSz,
    const byte * authIn,
    word32 authInSz
)

This function performs AES GCM encryption with extended parameters, including IV output. This is a one-shot encryption function that outputs the generated IV.

Parameters:

• aes pointer to the AES structure
• out pointer to buffer to store ciphertext
• in pointer to plaintext to encrypt
• sz length of plaintext in bytes
• ivOut pointer to buffer to receive the IV
• ivOutSz length of the IV output buffer in bytes
• authTag pointer to buffer to store authentication tag
• authTagSz length of authentication tag in bytes
• authIn pointer to additional authentication data
• authInSz length of AAD in bytes

See:

• wc_AesGcmEncrypt
• wc_AesGcmSetIV

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte ivFixed[4] = { }; // fixed part
byte ivOut[12];
byte plaintext[100] = { }; // data
byte ciphertext[100];
byte authTag[16];
WC_RNG rng;

wc_InitRng(&rng);
wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesGcmSetKey(&aes, key, 16);
wc_AesGcmSetIV(&aes, 12, ivFixed, 4, &rng);
int ret = wc_AesGcmEncrypt_ex(&aes, ciphertext, plaintext, 100,
                              ivOut, 12, authTag, 16, NULL, 0);
if (ret != 0) {
    // encryption failed
}
wc_AesFree(&aes);
wc_FreeRng(&rng);

function wc_Gmac

int wc_Gmac(
    const byte * key,
    word32 keySz,
    byte * iv,
    word32 ivSz,
    const byte * authIn,
    word32 authInSz,
    byte * authTag,
    word32 authTagSz,
    WC_RNG * rng
)

This function performs GMAC (Galois Message Authentication Code) generation. GMAC is essentially AES-GCM with no plaintext, used for authentication only.

Parameters:

• key pointer to the key buffer
• keySz length of the key in bytes (16, 24, or 32)
• iv pointer to the IV/nonce buffer
• ivSz length of the IV/nonce in bytes
• authIn pointer to data to authenticate
• authInSz length of data to authenticate in bytes
• authTag pointer to buffer to store authentication tag
• authTagSz length of authentication tag in bytes
• rng pointer to initialized RNG (can be NULL if IV is complete)

See:

• wc_GmacVerify
• wc_AesGcmEncrypt

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // nonce
byte data[100] = { }; // data to authenticate
byte authTag[16];

int ret = wc_Gmac(key, 16, iv, 12, data, 100, authTag, 16, NULL);
if (ret != 0) {
    // GMAC generation failed
}

function wc_GmacVerify

int wc_GmacVerify(
    const byte * key,
    word32 keySz,
    const byte * iv,
    word32 ivSz,
    const byte * authIn,
    word32 authInSz,
    const byte * authTag,
    word32 authTagSz
)

This function verifies a GMAC (Galois Message Authentication Code). It computes the GMAC and compares it with the provided tag.

Parameters:

• key pointer to the key buffer
• keySz length of the key in bytes (16, 24, or 32)
• iv pointer to the IV/nonce buffer
• ivSz length of the IV/nonce in bytes
• authIn pointer to data to authenticate
• authInSz length of data to authenticate in bytes
• authTag pointer to the authentication tag to verify
• authTagSz length of authentication tag in bytes

See:

• wc_Gmac
• wc_AesGcmDecrypt

Return:

• 0 On successful verification.
• AES_GCM_AUTH_E If authentication tag verification fails.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

byte key[16] = { }; // 128-bit key
byte iv[12] = { }; // nonce
byte data[100] = { }; // data to authenticate
byte authTag[16] = { }; // received tag

int ret = wc_GmacVerify(key, 16, iv, 12, data, 100, authTag, 16);
if (ret != 0) {
    // GMAC verification failed
}

function wc_AesCcmSetNonce

int wc_AesCcmSetNonce(
    Aes * aes,
    const byte * nonce,
    word32 nonceSz
)

This function sets the nonce for AES CCM mode. The nonce must be set before encryption or decryption operations.

Parameters:

• aes pointer to the AES structure
• nonce pointer to the nonce buffer
• nonceSz length of the nonce in bytes (7-13 bytes for CCM)

See:

• wc_AesCcmEncrypt
• wc_AesCcmSetKey

Return:

• 0 On success.
• BAD_FUNC_ARG If aes or nonce is NULL, or if nonceSz is invalid.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte nonce[12] = { }; // nonce

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesCcmSetKey(&aes, key, 16);
int ret = wc_AesCcmSetNonce(&aes, nonce, 12);
if (ret != 0) {
    // failed to set nonce
}
wc_AesFree(&aes);

function wc_AesCcmEncrypt_ex

int wc_AesCcmEncrypt_ex(
    Aes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    byte * ivOut,
    word32 ivOutSz,
    byte * authTag,
    word32 authTagSz,
    const byte * authIn,
    word32 authInSz
)

This function performs AES CCM encryption with extended parameters, including nonce output. This is useful when part of the nonce is generated internally.

Parameters:

• aes pointer to the AES structure
• out pointer to buffer to store ciphertext
• in pointer to plaintext to encrypt
• sz length of plaintext in bytes
• ivOut pointer to buffer to receive the nonce
• ivOutSz length of the nonce output buffer in bytes
• authTag pointer to buffer to store authentication tag
• authTagSz length of authentication tag in bytes
• authIn pointer to additional authentication data
• authInSz length of AAD in bytes

See:

• wc_AesCcmEncrypt
• wc_AesCcmSetNonce

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
byte nonce[12];
byte plaintext[100] = { }; // data
byte ciphertext[100];
byte authTag[16];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesCcmSetKey(&aes, key, 16);
int ret = wc_AesCcmEncrypt_ex(&aes, ciphertext, plaintext, 100,
                              nonce, 12, authTag, 16, NULL, 0);
if (ret != 0) {
    // encryption failed
}
wc_AesFree(&aes);

function wc_AesKeyWrap

int wc_AesKeyWrap(
    const byte * key,
    word32 keySz,
    const byte * in,
    word32 inSz,
    byte * out,
    word32 outSz,
    const byte * iv
)

This function wraps a key using AES Key Wrap algorithm (RFC 3394). This is commonly used to securely transport cryptographic keys.

Parameters:

• key pointer to the key-encryption key
• keySz length of the key-encryption key in bytes
• in pointer to the key to wrap
• inSz length of the key to wrap in bytes
• out pointer to buffer to store wrapped key
• outSz size of output buffer in bytes
• iv pointer to IV (typically NULL to use default)

See:

• wc_AesKeyUnWrap
• wc_AesKeyWrap_ex

Return:

• Length of wrapped key in bytes on success.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

byte kek[16] = { }; // key-encryption key
byte keyToWrap[16] = { }; // key to wrap
byte wrappedKey[24];

int wrappedLen = wc_AesKeyWrap(kek, 16, keyToWrap, 16, wrappedKey,
                               24, NULL);
if (wrappedLen <= 0) {
    // key wrap failed
}

function wc_AesKeyWrap_ex

int wc_AesKeyWrap_ex(
    Aes * aes,
    const byte * in,
    word32 inSz,
    byte * out,
    word32 outSz,
    const byte * iv
)

This function wraps a key using AES Key Wrap algorithm with an initialized AES structure. This allows reusing the same AES structure for multiple wrap operations.

Parameters:

• aes pointer to initialized AES structure
• in pointer to the key to wrap
• inSz length of the key to wrap in bytes
• out pointer to buffer to store wrapped key
• outSz size of output buffer in bytes
• iv pointer to IV (typically NULL to use default)

See:

• wc_AesKeyWrap
• wc_AesKeyUnWrap_ex

Return:

• Length of wrapped key in bytes on success.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

Aes aes;
byte kek[16] = { }; // key-encryption key
byte keyToWrap[16] = { }; // key to wrap
byte wrappedKey[24];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, kek, 16, NULL, AES_ENCRYPTION);
int wrappedLen = wc_AesKeyWrap_ex(&aes, keyToWrap, 16, wrappedKey,
                                  24, NULL);
if (wrappedLen <= 0) {
    // key wrap failed
}
wc_AesFree(&aes);

function wc_AesKeyUnWrap

int wc_AesKeyUnWrap(
    const byte * key,
    word32 keySz,
    const byte * in,
    word32 inSz,
    byte * out,
    word32 outSz,
    const byte * iv
)

This function unwraps a key using AES Key Unwrap algorithm (RFC 3394). This is used to securely receive cryptographic keys that were wrapped.

Parameters:

• key pointer to the key-encryption key
• keySz length of the key-encryption key in bytes
• in pointer to the wrapped key
• inSz length of the wrapped key in bytes
• out pointer to buffer to store unwrapped key
• outSz size of output buffer in bytes
• iv pointer to IV (typically NULL to use default)

See:

• wc_AesKeyWrap
• wc_AesKeyUnWrap_ex

Return:

• Length of unwrapped key in bytes on success.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

byte kek[16] = { }; // key-encryption key
byte wrappedKey[24] = { }; // wrapped key
byte unwrappedKey[16];

int unwrappedLen = wc_AesKeyUnWrap(kek, 16, wrappedKey, 24,
                                   unwrappedKey, 16, NULL);
if (unwrappedLen <= 0) {
    // key unwrap failed
}

function wc_AesKeyUnWrap_ex

int wc_AesKeyUnWrap_ex(
    Aes * aes,
    const byte * in,
    word32 inSz,
    byte * out,
    word32 outSz,
    const byte * iv
)

This function unwraps a key using AES Key Unwrap algorithm with an initialized AES structure. This allows reusing the same AES structure for multiple unwrap operations.

Parameters:

• aes pointer to initialized AES structure
• in pointer to the wrapped key
• inSz length of the wrapped key in bytes
• out pointer to buffer to store unwrapped key
• outSz size of output buffer in bytes
• iv pointer to IV (typically NULL to use default)

See:

• wc_AesKeyUnWrap
• wc_AesKeyWrap_ex

Return:

• Length of unwrapped key in bytes on success.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

Aes aes;
byte kek[16] = { }; // key-encryption key
byte wrappedKey[24] = { }; // wrapped key
byte unwrappedKey[16];

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, kek, 16, NULL, AES_ENCRYPTION);
int unwrappedLen = wc_AesKeyUnWrap_ex(&aes, wrappedKey, 24,
                                      unwrappedKey, 16, NULL);
if (unwrappedLen <= 0) {
    // key unwrap failed
}
wc_AesFree(&aes);

function wc_AesXtsEncryptConsecutiveSectors

int wc_AesXtsEncryptConsecutiveSectors(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    word64 sector,
    word32 sectorSz
)

This function encrypts multiple consecutive sectors using AES XTS mode. It processes multiple sectors in sequence, automatically incrementing the sector number for each sector.

Parameters:

• aes pointer to the XtsAes structure
• out pointer to buffer to store encrypted data
• in pointer to plaintext data to encrypt
• sz total length of data in bytes
• sector starting sector number for the tweak
• sectorSz size of each sector in bytes

See:

• wc_AesXtsDecryptConsecutiveSectors
• wc_AesXtsEncryptSector

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL, or if sectorSz is 0, or if sz is less than AES_BLOCK_SIZE.
• Other negative values on error.

Example

XtsAes aes;
byte key[32] = { }; // 256-bit key
byte plaintext[1024] = { }; // data
byte ciphertext[1024];

wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID);
int ret = wc_AesXtsEncryptConsecutiveSectors(&aes, ciphertext,
                                             plaintext, 1024, 0, 512);
if (ret != 0) {
    // encryption failed
}
wc_AesXtsFree(&aes);

function wc_AesXtsDecryptConsecutiveSectors

int wc_AesXtsDecryptConsecutiveSectors(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    word64 sector,
    word32 sectorSz
)

This function decrypts multiple consecutive sectors using AES XTS mode. It processes multiple sectors in sequence, automatically incrementing the sector number for each sector.

Parameters:

• aes pointer to the XtsAes structure
• out pointer to buffer to store decrypted data
• in pointer to ciphertext data to decrypt
• sz total length of data in bytes
• sector starting sector number for the tweak
• sectorSz size of each sector in bytes

See:

• wc_AesXtsEncryptConsecutiveSectors
• wc_AesXtsDecryptSector

Return:

• 0 On success.
• BAD_FUNC_ARG If aes, out, or in is NULL, or if sectorSz is 0, or if sz is less than AES_BLOCK_SIZE.
• Other negative values on error.

Example

XtsAes aes;
byte key[32] = { }; // 256-bit key
byte ciphertext[1024] = { }; // encrypted data
byte plaintext[1024];

wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID);
int ret = wc_AesXtsDecryptConsecutiveSectors(&aes, plaintext,
                                             ciphertext, 1024, 0, 512);
if (ret != 0) {
    // decryption failed
}
wc_AesXtsFree(&aes);

function wc_AesXtsEncryptInit

int wc_AesXtsEncryptInit(
    XtsAes * aes,
    const byte * i,
    word32 iSz,
    struct XtsAesStreamData * stream
)

This function initializes streaming AES XTS encryption. It sets up the context for processing data in multiple update calls.

Parameters:

• aes pointer to the XtsAes structure
• i pointer to the tweak/IV buffer
• iSz length of the tweak/IV in bytes
• stream pointer to XtsAesStreamData structure for streaming state

See:

• wc_AesXtsEncryptUpdate
• wc_AesXtsEncryptFinal

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.

Example

XtsAes aes;
struct XtsAesStreamData stream;
byte key[32] = { }; // 256-bit key
byte tweak[16] = { }; // tweak value

wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID);
int ret = wc_AesXtsEncryptInit(&aes, tweak, 16, &stream);
if (ret != 0) {
    // initialization failed
}
wc_AesXtsFree(&aes);

function wc_AesXtsDecryptInit

int wc_AesXtsDecryptInit(
    XtsAes * aes,
    const byte * i,
    word32 iSz,
    struct XtsAesStreamData * stream
)

This function initializes streaming AES XTS decryption. It sets up the context for processing data in multiple update calls.

Parameters:

• aes pointer to the XtsAes structure
• i pointer to the tweak/IV buffer
• iSz length of the tweak/IV in bytes
• stream pointer to XtsAesStreamData structure for streaming state

See:

• wc_AesXtsDecryptUpdate
• wc_AesXtsDecryptFinal

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.

Example

XtsAes aes;
struct XtsAesStreamData stream;
byte key[32] = { }; // 256-bit key
byte tweak[16] = { }; // tweak value

wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID);
int ret = wc_AesXtsDecryptInit(&aes, tweak, 16, &stream);
if (ret != 0) {
    // initialization failed
}
wc_AesXtsFree(&aes);

function wc_AesXtsEncryptUpdate

int wc_AesXtsEncryptUpdate(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    struct XtsAesStreamData * stream
)

This function performs an update step of streaming AES XTS encryption. It processes a chunk of data and can be called multiple times.

Parameters:

• aes pointer to the XtsAes structure
• out pointer to buffer to store encrypted data
• in pointer to plaintext data to encrypt
• sz length of data in bytes
• stream pointer to XtsAesStreamData structure for streaming state

See:

• wc_AesXtsEncryptInit
• wc_AesXtsEncryptFinal

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.

Example

XtsAes aes;
struct XtsAesStreamData stream;
byte key[32] = { }; // 256-bit key
byte tweak[16] = { }; // tweak value
byte plaintext[100] = { }; // data
byte ciphertext[100];

wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID);
wc_AesXtsEncryptInit(&aes, tweak, 16, &stream);
int ret = wc_AesXtsEncryptUpdate(&aes, ciphertext, plaintext, 100,
                                 &stream);
if (ret != 0) {
    // encryption failed
}
wc_AesXtsFree(&aes);

function wc_AesXtsDecryptUpdate

int wc_AesXtsDecryptUpdate(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    struct XtsAesStreamData * stream
)

This function performs an update step of streaming AES XTS decryption. It processes a chunk of data and can be called multiple times.

Parameters:

• aes pointer to the XtsAes structure
• out pointer to buffer to store decrypted data
• in pointer to ciphertext data to decrypt
• sz length of data in bytes
• stream pointer to XtsAesStreamData structure for streaming state

See:

• wc_AesXtsDecryptInit
• wc_AesXtsDecryptFinal

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.

Example

XtsAes aes;
struct XtsAesStreamData stream;
byte key[32] = { }; // 256-bit key
byte tweak[16] = { }; // tweak value
byte ciphertext[100] = { }; // encrypted data
byte plaintext[100];

wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID);
wc_AesXtsDecryptInit(&aes, tweak, 16, &stream);
int ret = wc_AesXtsDecryptUpdate(&aes, plaintext, ciphertext, 100,
                                 &stream);
if (ret != 0) {
    // decryption failed
}
wc_AesXtsFree(&aes);

function wc_AesXtsEncryptFinal

int wc_AesXtsEncryptFinal(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    struct XtsAesStreamData * stream
)

This function finalizes streaming AES XTS encryption. It processes any remaining data and completes the encryption operation.

Parameters:

• aes pointer to the XtsAes structure
• out pointer to buffer to store final encrypted data
• in pointer to final plaintext data to encrypt
• sz length of final data in bytes
• stream pointer to XtsAesStreamData structure for streaming state

See:

• wc_AesXtsEncryptUpdate
• wc_AesXtsEncryptInit

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.

Example

XtsAes aes;
struct XtsAesStreamData stream;
byte key[32] = { }; // 256-bit key
byte tweak[16] = { }; // tweak value
byte plaintext[50] = { }; // final data
byte ciphertext[50];

wc_AesXtsSetKey(&aes, key, 32, AES_ENCRYPTION, NULL, INVALID_DEVID);
wc_AesXtsEncryptInit(&aes, tweak, 16, &stream);
// ... update calls ...
int ret = wc_AesXtsEncryptFinal(&aes, ciphertext, plaintext, 50,
                                &stream);
if (ret != 0) {
    // finalization failed
}
wc_AesXtsFree(&aes);

function wc_AesXtsDecryptFinal

int wc_AesXtsDecryptFinal(
    XtsAes * aes,
    byte * out,
    const byte * in,
    word32 sz,
    struct XtsAesStreamData * stream
)

This function finalizes streaming AES XTS decryption. It processes any remaining data and completes the decryption operation.

Parameters:

• aes pointer to the XtsAes structure
• out pointer to buffer to store final decrypted data
• in pointer to final ciphertext data to decrypt
• sz length of final data in bytes
• stream pointer to XtsAesStreamData structure for streaming state

See:

• wc_AesXtsDecryptUpdate
• wc_AesXtsDecryptInit

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.

Example

XtsAes aes;
struct XtsAesStreamData stream;
byte key[32] = { }; // 256-bit key
byte tweak[16] = { }; // tweak value
byte ciphertext[50] = { }; // final encrypted data
byte plaintext[50];

wc_AesXtsSetKey(&aes, key, 32, AES_DECRYPTION, NULL, INVALID_DEVID);
wc_AesXtsDecryptInit(&aes, tweak, 16, &stream);
// ... update calls ...
int ret = wc_AesXtsDecryptFinal(&aes, plaintext, ciphertext, 50,
                                &stream);
if (ret != 0) {
    // finalization failed
}
wc_AesXtsFree(&aes);

function wc_AesGetKeySize

int wc_AesGetKeySize(
    Aes * aes,
    word32 * keySize
)

This function retrieves the key size from an initialized AES structure. It returns the size of the key currently set in the AES object.

Parameters:

• aes pointer to the AES structure
• keySize pointer to word32 to store the key size in bytes

See:

• wc_AesSetKey
• wc_AesInit

Return:

• 0 On success.
• BAD_FUNC_ARG If aes or keySize is NULL.

Example

Aes aes;
byte key[16] = { }; // 128-bit key
word32 keySize;

wc_AesInit(&aes, NULL, INVALID_DEVID);
wc_AesSetKey(&aes, key, 16, NULL, AES_ENCRYPTION);
int ret = wc_AesGetKeySize(&aes, &keySize);
if (ret == 0) {
    // keySize now contains 16
}
wc_AesFree(&aes);

function wc_AesInit_Id

int wc_AesInit_Id(
    Aes * aes,
    unsigned char * id,
    int len,
    void * heap,
    int devId
)

This function initializes an AES structure with an ID. This is useful for tracking or identifying specific AES instances in applications that manage multiple AES contexts.

Parameters:

• aes pointer to the AES structure to initialize
• id pointer to the ID buffer
• len length of the ID in bytes
• heap pointer to heap hint for memory allocation (can be NULL)
• devId device ID for hardware acceleration (use INVALID_DEVID for software)

See:

• wc_AesInit
• wc_AesInit_Label

Return:

• 0 On success.
• BAD_FUNC_ARG If aes or id is NULL, or if len is invalid.

Note: This API is only available when WOLF_PRIVATE_KEY_ID is defined, which is set for PKCS11 support.

Example

Aes aes;
byte id[8] = { }; // unique identifier

int ret = wc_AesInit_Id(&aes, id, 8, NULL, INVALID_DEVID);
if (ret != 0) {
    // initialization failed
}
wc_AesFree(&aes);

function wc_AesInit_Label

int wc_AesInit_Label(
    Aes * aes,
    const char * label,
    void * heap,
    int devId
)

This function initializes an AES structure with a label string. This is useful for tracking or identifying specific AES instances with human-readable names.

Parameters:

• aes pointer to the AES structure to initialize
• label pointer to the null-terminated label string
• heap pointer to heap hint for memory allocation (can be NULL)
• devId device ID for hardware acceleration (use INVALID_DEVID for software)

See:

• wc_AesInit
• wc_AesInit_Id

Return:

• 0 On success.
• BAD_FUNC_ARG If aes or label is NULL.

Note: This API is only available when WOLF_PRIVATE_KEY_ID is defined, which is set for PKCS11 support.

Example

Aes aes;

int ret = wc_AesInit_Label(&aes, "MyAESContext", NULL, INVALID_DEVID);
if (ret != 0) {
    // initialization failed
}
wc_AesFree(&aes);

function wc_AesNew

Aes * wc_AesNew(
    void * heap,
    int devId,
    int * result_code
)

This function allocates and initializes a new AES structure. It returns a pointer to the allocated structure, which must be freed with wc_AesDelete when no longer needed. These New/Delete functions are exposed to support allocation of the structure using dynamic memory to provide better ABI compatibility.

Parameters:

• heap pointer to heap hint for memory allocation (can be NULL)
• devId device ID for hardware acceleration (use INVALID_DEVID for software)
• result_code pointer to int to store result code (can be NULL)

See:

• wc_AesDelete
• wc_AesInit

Return:

• Pointer to allocated Aes structure on success.
• NULL on allocation failure.

Note: This API is only available when WC_NO_CONSTRUCTORS is not defined. WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is defined.

Example

int result;
Aes* aes = wc_AesNew(NULL, INVALID_DEVID, &result);
if (aes == NULL || result != 0) {
    // allocation or initialization failed
}
// use aes...
wc_AesDelete(aes, &aes);

function wc_AesDelete

int wc_AesDelete(
    Aes * aes,
    Aes ** aes_p
)

This function frees an AES structure that was allocated with wc_AesNew. It also sets the pointer to NULL to prevent use-after-free. These New/Delete functions are exposed to support allocation of the structure using dynamic memory to provide better ABI compatibility.

Parameters:

• aes pointer to the AES structure to free
• aes_p pointer to the AES pointer (will be set to NULL)

See:

• wc_AesNew
• wc_AesFree

Return:

• 0 On success.
• BAD_FUNC_ARG If aes or aes_p is NULL.

Note: This API is only available when WC_NO_CONSTRUCTORS is not defined. WC_NO_CONSTRUCTORS is automatically defined when WOLFSSL_NO_MALLOC is defined.

Example

Aes* aes = wc_AesNew(NULL, INVALID_DEVID, NULL);
if (aes != NULL) {
    // use aes...
    int ret = wc_AesDelete(aes, &aes);
    // aes is now NULL
}

function wc_AesSivEncrypt_ex

int wc_AesSivEncrypt_ex(
    const byte * key,
    word32 keySz,
    const AesSivAssoc * assoc,
    word32 numAssoc,
    const byte * nonce,
    word32 nonceSz,
    const byte * in,
    word32 inSz,
    byte * siv,
    byte * out
)

This function performs AES-SIV (Synthetic IV) encryption with extended parameters. AES-SIV provides nonce-misuse resistance and deterministic authenticated encryption.

Parameters:

• key pointer to the key buffer (32, 48, or 64 bytes for SIV)
• keySz length of the key in bytes
• assoc pointer to array of associated data structures
• numAssoc number of associated data items
• nonce pointer to the nonce buffer (can be NULL)
• nonceSz length of the nonce in bytes
• in pointer to plaintext to encrypt
• inSz length of plaintext in bytes
• siv pointer to buffer to store the SIV (16 bytes)
• out pointer to buffer to store ciphertext

See:

• wc_AesSivDecrypt_ex
• wc_AesSivEncrypt

Return:

• 0 On success.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

byte key[32] = { }; // 256-bit key for AES-128-SIV
AesSivAssoc assoc[1];
byte aad[20] = { }; // associated data
byte nonce[12] = { }; // nonce
byte plaintext[100] = { }; // data
byte siv[16];
byte ciphertext[100];

assoc[0].data = aad;
assoc[0].sz = 20;

int ret = wc_AesSivEncrypt_ex(key, 32, assoc, 1, nonce, 12,
                              plaintext, 100, siv, ciphertext);
if (ret != 0) {
    // encryption failed
}

function wc_AesSivDecrypt_ex

int wc_AesSivDecrypt_ex(
    const byte * key,
    word32 keySz,
    const AesSivAssoc * assoc,
    word32 numAssoc,
    const byte * nonce,
    word32 nonceSz,
    const byte * in,
    word32 inSz,
    byte * siv,
    byte * out
)

This function performs AES-SIV (Synthetic IV) decryption with extended parameters. It verifies the SIV and decrypts the ciphertext.

Parameters:

• key pointer to the key buffer (32, 48, or 64 bytes for SIV)
• keySz length of the key in bytes
• assoc pointer to array of associated data structures
• numAssoc number of associated data items
• nonce pointer to the nonce buffer (can be NULL)
• nonceSz length of the nonce in bytes
• in pointer to ciphertext to decrypt
• inSz length of ciphertext in bytes
• siv pointer to the SIV to verify (16 bytes)
• out pointer to buffer to store plaintext

See:

• wc_AesSivEncrypt_ex
• wc_AesSivDecrypt

Return:

• 0 On successful decryption and verification.
• AES_SIV_AUTH_E If SIV verification fails.
• BAD_FUNC_ARG If parameters are invalid.
• Other negative values on error.

Example

byte key[32] = { }; // 256-bit key for AES-128-SIV
AesSivAssoc assoc[1];
byte aad[20] = { }; // associated data
byte nonce[12] = { }; // nonce
byte ciphertext[100] = { }; // encrypted data
byte siv[16] = { }; // received SIV
byte plaintext[100];

assoc[0].data = aad;
assoc[0].sz = 20;

int ret = wc_AesSivDecrypt_ex(key, 32, assoc, 1, nonce, 12,
                              ciphertext, 100, siv, plaintext);
if (ret != 0) {
    // decryption or verification failed
}

Source code

int  wc_AesSetKey(Aes* aes, const byte* key, word32 len,
                              const byte* iv, int dir);

int  wc_AesSetIV(Aes* aes, const byte* iv);

int  wc_AesCbcEncrypt(Aes* aes, byte* out,
                                  const byte* in, word32 sz);

int  wc_AesCbcDecrypt(Aes* aes, byte* out,
                                  const byte* in, word32 sz);

int wc_AesCtrEncrypt(Aes* aes, byte* out,
                                   const byte* in, word32 sz);

int wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in);

int wc_AesDecryptDirect(Aes* aes, byte* out, const byte* in);

int  wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len,
                                const byte* iv, int dir);

int  wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len);

int  wc_AesGcmEncrypt(Aes* aes, byte* out,
                                   const byte* in, word32 sz,
                                   const byte* iv, word32 ivSz,
                                   byte* authTag, word32 authTagSz,
                                   const byte* authIn, word32 authInSz);

int  wc_AesGcmDecrypt(Aes* aes, byte* out,
                                   const byte* in, word32 sz,
                                   const byte* iv, word32 ivSz,
                                   const byte* authTag, word32 authTagSz,
                                   const byte* authIn, word32 authInSz);

int wc_GmacSetKey(Gmac* gmac, const byte* key, word32 len);

int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz,
                               const byte* authIn, word32 authInSz,
                               byte* authTag, word32 authTagSz);

int  wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz);

int  wc_AesCcmEncrypt(Aes* aes, byte* out,
                                   const byte* in, word32 inSz,
                                   const byte* nonce, word32 nonceSz,
                                   byte* authTag, word32 authTagSz,
                                   const byte* authIn, word32 authInSz);

int  wc_AesCcmDecrypt(Aes* aes, byte* out,
                                   const byte* in, word32 inSz,
                                   const byte* nonce, word32 nonceSz,
                                   const byte* authTag, word32 authTagSz,
                                   const byte* authIn, word32 authInSz);

int wc_AesXtsInit(XtsAes* aes, void* heap, int devId);


int wc_AesXtsSetKeyNoInit(XtsAes* aes, const byte* key,
         word32 len, int dir);


int wc_AesXtsSetKey(XtsAes* aes, const byte* key,
         word32 len, int dir, void* heap, int devId);

int wc_AesXtsEncryptSector(XtsAes* aes, byte* out,
         const byte* in, word32 sz, word64 sector);

int wc_AesXtsDecryptSector(XtsAes* aes, byte* out,
         const byte* in, word32 sz, word64 sector);

int wc_AesXtsEncrypt(XtsAes* aes, byte* out,
         const byte* in, word32 sz, const byte* i, word32 iSz);

int wc_AesXtsDecrypt(XtsAes* aes, byte* out,
        const byte* in, word32 sz, const byte* i, word32 iSz);

int wc_AesXtsFree(XtsAes* aes);


int  wc_AesInit(Aes* aes, void* heap, int devId);

void wc_AesFree(Aes* aes);

int wc_AesCfbEncrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesCfbDecrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesSivEncrypt(const byte* key, word32 keySz, const byte* assoc,
                     word32 assocSz, const byte* nonce, word32 nonceSz,
                     const byte* in, word32 inSz, byte* siv, byte* out);

int wc_AesSivDecrypt(const byte* key, word32 keySz, const byte* assoc,
                     word32 assocSz, const byte* nonce, word32 nonceSz,
                     const byte* in, word32 inSz, byte* siv, byte* out);







WOLFSSL_API int  wc_AesEaxEncryptAuth(const byte* key, word32 keySz, byte* out,
                                      const byte* in, word32 inSz,
                                      const byte* nonce, word32 nonceSz,
                                      /* output computed auth tag */
                                      byte* authTag, word32 authTagSz,
                                      /* input data to authenticate */
                                      const byte* authIn, word32 authInSz);
WOLFSSL_API int  wc_AesEaxDecryptAuth(const byte* key, word32 keySz, byte* out,
                                      const byte* in, word32 inSz,
                                      const byte* nonce, word32 nonceSz,
                                      /* auth tag to verify against */
                                      const byte* authTag, word32 authTagSz,
                                      /* input data to authenticate */
                                      const byte* authIn, word32 authInSz);

WOLFSSL_API int  wc_AesEaxInit(AesEax* eax,
                               const byte* key, word32 keySz,
                               const byte* nonce, word32 nonceSz,
                               const byte* authIn, word32 authInSz);

WOLFSSL_API int  wc_AesEaxEncryptUpdate(AesEax* eax, byte* out,
                                        const byte* in, word32 inSz,
                                        const byte* authIn, word32 authInSz);

WOLFSSL_API int  wc_AesEaxDecryptUpdate(AesEax* eax, byte* out,
                                        const byte* in, word32 inSz,
                                        const byte* authIn, word32 authInSz);
WOLFSSL_API int  wc_AesEaxAuthDataUpdate(AesEax* eax,
                                       const byte* authIn, word32 authInSz);

WOLFSSL_API int wc_AesEaxEncryptFinal(AesEax* eax,
                                      byte* authTag, word32 authTagSz);

WOLFSSL_API int wc_AesEaxDecryptFinal(AesEax* eax,
                                      const byte* authIn, word32 authInSz);
WOLFSSL_API int wc_AesEaxFree(AesEax* eax);

int wc_AesCtsEncrypt(const byte* key, word32 keySz, byte* out,
                     const byte* in, word32 inSz,
                     const byte* iv);

int wc_AesCtsEncrypt(const byte* key, word32 keySz, byte* out,
                     const byte* in, word32 inSz,
                     const byte* iv);

int wc_AesCtsDecrypt(const byte* key, word32 keySz, byte* out,
                     const byte* in, word32 inSz,
                     const byte* iv);

int wc_AesCtsEncryptUpdate(Aes* aes, byte* out, word32* outSz,
                           const byte* in, word32 inSz);

int wc_AesCtsEncryptFinal(Aes* aes, byte* out, word32* outSz);

int wc_AesCtsDecryptUpdate(Aes* aes, byte* out, word32* outSz,
                           const byte* in, word32 inSz);

int wc_AesCtsDecryptFinal(Aes* aes, byte* out, word32* outSz);


int wc_AesCfb1Encrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesCfb8Encrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesCfb1Decrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesCfb8Decrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesOfbEncrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesOfbDecrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesEcbEncrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesEcbDecrypt(Aes* aes, byte* out, const byte* in, word32 sz);

int wc_AesCtrSetKey(Aes* aes, const byte* key, word32 len, const byte* iv,
                    int dir);

int wc_AesGcmSetKey_ex(Aes* aes, const byte* key, word32 len, word32 kup);

int wc_AesGcmInit(Aes* aes, const byte* key, word32 len, const byte* iv,
                  word32 ivSz);

int wc_AesGcmEncryptInit(Aes* aes, const byte* key, word32 len,
                         const byte* iv, word32 ivSz);

int wc_AesGcmEncryptInit_ex(Aes* aes, const byte* key, word32 len,
                            byte* ivOut, word32 ivOutSz);

int wc_AesGcmEncryptUpdate(Aes* aes, byte* out, const byte* in, word32 sz,
                           const byte* authIn, word32 authInSz);

int wc_AesGcmEncryptFinal(Aes* aes, byte* authTag, word32 authTagSz);

int wc_AesGcmDecryptInit(Aes* aes, const byte* key, word32 len,
                         const byte* iv, word32 ivSz);

int wc_AesGcmDecryptUpdate(Aes* aes, byte* out, const byte* in, word32 sz,
                           const byte* authIn, word32 authInSz);

int wc_AesGcmDecryptFinal(Aes* aes, const byte* authTag, word32 authTagSz);

int wc_AesGcmSetExtIV(Aes* aes, const byte* iv, word32 ivSz);

int wc_AesGcmSetIV(Aes* aes, word32 ivSz, const byte* ivFixed,
                   word32 ivFixedSz, WC_RNG* rng);

int wc_AesGcmEncrypt_ex(Aes* aes, byte* out, const byte* in, word32 sz,
                        byte* ivOut, word32 ivOutSz, byte* authTag,
                        word32 authTagSz, const byte* authIn,
                        word32 authInSz);

int wc_Gmac(const byte* key, word32 keySz, byte* iv, word32 ivSz,
            const byte* authIn, word32 authInSz, byte* authTag,
            word32 authTagSz, WC_RNG* rng);

int wc_GmacVerify(const byte* key, word32 keySz, const byte* iv,
                  word32 ivSz, const byte* authIn, word32 authInSz,
                  const byte* authTag, word32 authTagSz);

int wc_AesCcmSetNonce(Aes* aes, const byte* nonce, word32 nonceSz);

int wc_AesCcmEncrypt_ex(Aes* aes, byte* out, const byte* in, word32 sz,
                        byte* ivOut, word32 ivOutSz, byte* authTag,
                        word32 authTagSz, const byte* authIn,
                        word32 authInSz);

int wc_AesKeyWrap(const byte* key, word32 keySz, const byte* in,
                  word32 inSz, byte* out, word32 outSz, const byte* iv);

int wc_AesKeyWrap_ex(Aes *aes, const byte* in, word32 inSz, byte* out,
                     word32 outSz, const byte* iv);

int wc_AesKeyUnWrap(const byte* key, word32 keySz, const byte* in,
                    word32 inSz, byte* out, word32 outSz, const byte* iv);

int wc_AesKeyUnWrap_ex(Aes *aes, const byte* in, word32 inSz, byte* out,
                       word32 outSz, const byte* iv);

int wc_AesXtsEncryptConsecutiveSectors(XtsAes* aes, byte* out,
                                       const byte* in, word32 sz,
                                       word64 sector, word32 sectorSz);

int wc_AesXtsDecryptConsecutiveSectors(XtsAes* aes, byte* out,
                                       const byte* in, word32 sz,
                                       word64 sector, word32 sectorSz);

int wc_AesXtsEncryptInit(XtsAes* aes, const byte* i, word32 iSz,
                         struct XtsAesStreamData *stream);

int wc_AesXtsDecryptInit(XtsAes* aes, const byte* i, word32 iSz,
                         struct XtsAesStreamData *stream);

int wc_AesXtsEncryptUpdate(XtsAes* aes, byte* out, const byte* in,
                           word32 sz, struct XtsAesStreamData *stream);

int wc_AesXtsDecryptUpdate(XtsAes* aes, byte* out, const byte* in,
                           word32 sz, struct XtsAesStreamData *stream);

int wc_AesXtsEncryptFinal(XtsAes* aes, byte* out, const byte* in,
                          word32 sz, struct XtsAesStreamData *stream);

int wc_AesXtsDecryptFinal(XtsAes* aes, byte* out, const byte* in,
                          word32 sz, struct XtsAesStreamData *stream);

int wc_AesGetKeySize(Aes* aes, word32* keySize);

int wc_AesInit_Id(Aes* aes, unsigned char* id, int len, void* heap,
                  int devId);

int wc_AesInit_Label(Aes* aes, const char* label, void* heap, int devId);

Aes* wc_AesNew(void* heap, int devId, int *result_code);

int wc_AesDelete(Aes* aes, Aes** aes_p);

int wc_AesSivEncrypt_ex(const byte* key, word32 keySz,
                        const AesSivAssoc* assoc, word32 numAssoc,
                        const byte* nonce, word32 nonceSz, const byte* in,
                        word32 inSz, byte* siv, byte* out);

int wc_AesSivDecrypt_ex(const byte* key, word32 keySz,
                        const AesSivAssoc* assoc, word32 numAssoc,
                        const byte* nonce, word32 nonceSz, const byte* in,
                        word32 inSz, byte* siv, byte* out);

---

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