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. |
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 the authorization tag is invalid, it sets the output buffer to zero and returns the error: AES_CCM_AUTH_E. |
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. |
int | 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. |
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. |
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. |
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:
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:
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:
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:
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:
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:
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:
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:
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:
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.
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:
Return:
- 0 On successfully decrypting 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:
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:
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:
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:
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 the authorization tag is invalid, it sets the output buffer to zero and returns the error: AES_CCM_AUTH_E.
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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
int 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:
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:
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.
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.
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);
}
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);
int 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);
Updated on 2024-11-07 at 01:17:40 +0000