diff options
Diffstat (limited to 'extra/wolfssl/wolfssl/doc/dox_comments/header_files/aes.h')
| -rw-r--r-- | extra/wolfssl/wolfssl/doc/dox_comments/header_files/aes.h | 685 |
1 files changed, 670 insertions, 15 deletions
diff --git a/extra/wolfssl/wolfssl/doc/dox_comments/header_files/aes.h b/extra/wolfssl/wolfssl/doc/dox_comments/header_files/aes.h index 3a9b974f..997bc58c 100644 --- a/extra/wolfssl/wolfssl/doc/dox_comments/header_files/aes.h +++ b/extra/wolfssl/wolfssl/doc/dox_comments/header_files/aes.h @@ -20,6 +20,9 @@ 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 @@ -94,7 +97,8 @@ int wc_AesSetIV(Aes* aes, const byte* iv); \code Aes enc; int ret = 0; - // initialize enc with AesSetKey, using direction AES_ENCRYPTION + // 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 @@ -103,6 +107,7 @@ int wc_AesSetIV(Aes* aes, const byte* iv); } \endcode + \sa wc_AesInit \sa wc_AesSetKey \sa wc_AesSetIV \sa wc_AesCbcDecrypt @@ -146,7 +151,8 @@ int wc_AesCbcEncrypt(Aes* aes, byte* out, \code Aes dec; int ret = 0; - // initialize dec with AesSetKey, using direction AES_DECRYPTION + // 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]; @@ -155,6 +161,7 @@ int wc_AesCbcEncrypt(Aes* aes, byte* out, } \endcode + \sa wc_AesInit \sa wc_AesSetKey \sa wc_AesCbcEncrypt */ @@ -187,11 +194,10 @@ int wc_AesCbcDecrypt(Aes* aes, byte* out, \code Aes enc; Aes dec; - // initialize enc and dec with 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 + // 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 @@ -229,7 +235,8 @@ int wc_AesCtrEncrypt(Aes* aes, byte* out, _Example_ \code Aes enc; - // initialize enc with AesSetKey, using direction AES_ENCRYPTION + // 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]; @@ -263,7 +270,8 @@ int wc_AesEncryptDirect(Aes* aes, byte* out, const byte* in); _Example_ \code Aes dec; - // initialize enc with AesSetKey, using direction AES_DECRYPTION + // 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]; @@ -303,6 +311,10 @@ int wc_AesDecryptDirect(Aes* aes, byte* out, const byte* in); 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 @@ -335,6 +347,9 @@ int wc_AesSetKeyDirect(Aes* aes, const byte* key, word32 len, 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 } @@ -373,7 +388,7 @@ int wc_AesGcmSetKey(Aes* aes, const byte* key, word32 len); _Example_ \code Aes enc; - // initialize aes structure by calling wc_AesGcmSetKey + // 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 @@ -424,7 +439,8 @@ int wc_AesGcmEncrypt(Aes* aes, byte* out, _Example_ \code Aes enc; //can use the same struct as was passed to wc_AesGcmEncrypt - // initialize aes structure by calling wc_AesGcmSetKey if not already done + // 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 @@ -529,7 +545,8 @@ int wc_GmacUpdate(Gmac* gmac, const byte* iv, word32 ivSz, Aes enc; key[] = { some 16, 24, or 32 byte length key }; - wc_AesCcmSetKey(&aes, key, sizeof(key)); + wc_AesInit(&enc, HEAP_HINT, INVALID_DEVID); // Make sure devId updated + wc_AesCcmSetKey(&enc, key, sizeof(key)); \endcode \sa wc_AesCcmEncrypt @@ -564,7 +581,7 @@ int wc_AesCcmSetKey(Aes* aes, const byte* key, word32 keySz); _Example_ \code Aes enc; - // initialize enc with wc_AesCcmSetKey + // initialize enc with wc_AesInit and wc_AesCcmSetKey nonce[] = { initialize nonce }; plain[] = { some plain text message }; @@ -616,7 +633,7 @@ int wc_AesCcmEncrypt(Aes* aes, byte* out, _Example_ \code Aes dec; - // initialize dec with wc_AesCcmSetKey + // initialize dec with wc_AesInit and wc_AesCcmSetKey nonce[] = { initialize nonce }; cipher[] = { encrypted message }; @@ -644,6 +661,82 @@ int wc_AesCcmDecrypt(Aes* aes, byte* out, /*! \ingroup AES + \brief This is to initialize an AES-XTS context. It is up to user to call + wc_AesXtsFree on aes key when done. + + \return 0 Success + + \param aes AES keys for encrypt/decrypt process + \param heap heap hint to use for memory. Can be NULL + \param devId id to use with async crypto. Can be 0 + + _Example_ + \code + XtsAes aes; + + if(wc_AesXtsInit(&aes, NULL, 0) != 0) + { + // Handle error + } + if(wc_AesXtsSetKeyNoInit(&aes, key, sizeof(key), AES_ENCRYPTION) != 0) + { + // Handle error + } + wc_AesXtsFree(&aes); + \endcode + + \sa wc_AesXtsSetKey + \sa wc_AesXtsSetKeyNoInit + \sa wc_AesXtsEncrypt + \sa wc_AesXtsDecrypt + \sa wc_AesXtsFree +*/ +int wc_AesXtsInit(XtsAes* aes, void* heap, int devId); + + +/*! + \ingroup AES + + \brief 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. + + \return 0 Success + + \param aes AES keys for encrypt/decrypt process + \param key buffer holding aes key | tweak key + \param len length of key buffer in bytes. Should be twice that of + key size. + i.e. 32 for a 16 byte key. + \param dir direction, either AES_ENCRYPTION or AES_DECRYPTION + + _Example_ + \code + 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); + \endcode + + \sa wc_AesXtsEncrypt + \sa wc_AesXtsDecrypt + \sa wc_AesXtsFree +*/ +int wc_AesXtsSetKeyNoInit(XtsAes* aes, const byte* key, + word32 len, int dir); + + +/*! + \ingroup AES + \brief 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. @@ -669,6 +762,8 @@ int wc_AesCcmDecrypt(Aes* aes, byte* out, wc_AesXtsFree(&aes); \endcode + \sa wc_AesXtsInit + \sa wc_AesXtsSetKeyNoInit \sa wc_AesXtsEncrypt \sa wc_AesXtsDecrypt \sa wc_AesXtsFree @@ -709,6 +804,8 @@ int wc_AesXtsSetKey(XtsAes* aes, const byte* key, \sa wc_AesXtsEncrypt \sa wc_AesXtsDecrypt + \sa wc_AesXtsInit + \sa wc_AesXtsSetKeyNoInit \sa wc_AesXtsSetKey \sa wc_AesXtsFree */ @@ -748,6 +845,8 @@ int wc_AesXtsEncryptSector(XtsAes* aes, byte* out, \sa wc_AesXtsEncrypt \sa wc_AesXtsDecrypt + \sa wc_AesXtsInit + \sa wc_AesXtsSetKeyNoInit \sa wc_AesXtsSetKey \sa wc_AesXtsFree */ @@ -788,6 +887,8 @@ int wc_AesXtsDecryptSector(XtsAes* aes, byte* out, \endcode \sa wc_AesXtsDecrypt + \sa wc_AesXtsInit + \sa wc_AesXtsSetKeyNoInit \sa wc_AesXtsSetKey \sa wc_AesXtsFree */ @@ -827,6 +928,8 @@ int wc_AesXtsEncrypt(XtsAes* aes, byte* out, \endcode \sa wc_AesXtsEncrypt + \sa wc_AesXtsInit + \sa wc_AesXtsSetKeyNoInit \sa wc_AesXtsSetKey \sa wc_AesXtsFree */ @@ -855,6 +958,8 @@ int wc_AesXtsDecrypt(XtsAes* aes, byte* out, \sa wc_AesXtsEncrypt \sa wc_AesXtsDecrypt + \sa wc_AesXtsInit + \sa wc_AesXtsSetKeyNoInit \sa wc_AesXtsSetKey */ int wc_AesXtsFree(XtsAes* aes); @@ -1035,7 +1140,7 @@ int wc_AesSivEncrypt(const byte* key, word32 keySz, const byte* assoc, \return BAD_FUNC_ARG If key, SIV, or output buffer are NULL. Also returned if the key size isn't 32, 48, or 64 bytes. \return AES_SIV_AUTH_E If the SIV derived by S2V doesn't match the input - SIV (see RFC 5297 2.7). + SIV (see RFC 5297 2.7). \return Other Other negative error values returned if AES or CMAC operations fail. @@ -1072,3 +1177,553 @@ int wc_AesSivEncrypt(const byte* key, word32 keySz, const byte* assoc, 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); + + + + + + + +/*! + \ingroup AES + + \brief 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. + + \return 0 on successful encryption. + \return 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) + \return other negative error values returned if AES or CMAC operations + fail. + + \param key buffer containing the key to use + \param keySz length of the key buffer in bytes + \param[out] out buffer to hold the ciphertext. Should be the same length as + the plaintext buffer + \param in plaintext buffer to encrypt + \param inSz length of plaintext buffer + \param nonce the cryptographic nonce to use for EAX operations + \param nonceSz length of nonce buffer in bytes + \param[out] authTag pointer to the buffer in which to store the + authentication tag + \param authTagSz length of the desired authentication tag + \param authIn pointer to the buffer containing input data to authenticate + \param authInSz length of the input authentication data + + _Example_ + \code + 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 + } + + \endcode + + \sa wc_AesEaxDecryptAuth + +*/ +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); +/*! + \ingroup AES + + \brief 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. + + \return 0 on successful decryption + \return 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) + \return AES_EAX_AUTH_E If the authentication tag does not match the + supplied authentication code vector \c authTag + \return other negative error values returned if AES or CMAC operations + fail. + + \param key byte buffer containing the key to use + \param keySz length of the key buffer in bytes + \param[out] out buffer to hold the plaintext. Should be the same length as + the input ciphertext buffer + \param in ciphertext buffer to decrypt + \param inSz length of ciphertext buffer + \param nonce the cryptographic nonce to use for EAX operations + \param nonceSz length of nonce buffer in bytes + \param authTag buffer that holds the authentication tag to check the + authenticity of the data against + \param authTagSz Length of the input authentication tag + \param authIn pointer to the buffer containing input data to authenticate + \param authInSz length of the input authentication data + + _Example_ + \code + 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 + } + + \endcode + + \sa wc_AesEaxEncryptAuth + +*/ +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); + +/*! + \ingroup AES + \brief 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. + + \return 0 on success + \return error code on failure + + \param eax AES EAX structure holding the context of the AEAD operation + \param key 16, 24, or 32 byte secret key for encryption and decryption + \param keySz length of the supplied key in bytes + \param nonce the cryptographic nonce to use for EAX operations + \param nonceSz length of nonce buffer in bytes + \param authIn (optional) input data to add to the authentication stream + This argument should be NULL if not used + \param authInSz size in bytes of the input authentication data + + _Example_ + \code + 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); + \endcode + + \sa wc_AesEaxEncryptUpdate + \sa wc_AesEaxDecryptUpdate + \sa wc_AesEaxAuthDataUpdate + \sa wc_AesEaxEncryptFinal + \sa wc_AesEaxDecryptFinal + \sa wc_AesEaxFree + +*/ +WOLFSSL_API int wc_AesEaxInit(AesEax* eax, + const byte* key, word32 keySz, + const byte* nonce, word32 nonceSz, + const byte* authIn, word32 authInSz); + +/*! + \ingroup AES + \brief This function uses AES EAX to encrypt input data, and optionally, add + more input data to the authentication stream. \c eax must have been + previously initialized with a call to \ref wc_AesEaxInit. + + \return 0 on success + \return error code on failure + + \param eax AES EAX structure holding the context of the AEAD operation + \param[out] out output buffer holding the ciphertext + \param in input buffer holding the plaintext to encrypt + \param inSz size in bytes of the input data buffer + \param authIn (optional) input data to add to the authentication stream + This argument should be NULL if not used + \param authInSz size in bytes of the input authentication data + + _Example_ + \code + 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); + \endcode + + \sa wc_AesEaxInit + \sa wc_AesEaxDecryptUpdate + \sa wc_AesEaxAuthDataUpdate + \sa wc_AesEaxEncryptFinal + \sa wc_AesEaxDecryptFinal + \sa wc_AesEaxFree + +*/ +WOLFSSL_API int wc_AesEaxEncryptUpdate(AesEax* eax, byte* out, + const byte* in, word32 inSz, + const byte* authIn, word32 authInSz); + +/*! + \ingroup AES + \brief This function uses AES EAX to decrypt input data, and optionally, add + more input data to the authentication stream. \c eax must have been + previously initialized with a call to \ref wc_AesEaxInit. + + \return 0 on success + \return error code on failure + + \param eax AES EAX structure holding the context of the AEAD operation + \param[out] out output buffer holding the decrypted plaintext + \param in input buffer holding the ciphertext + \param inSz size in bytes of the input data buffer + \param authIn (optional) input data to add to the authentication stream + This argument should be NULL if not used + \param authInSz size in bytes of the input authentication data + + + _Example_ + \code + 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); + \endcode + + \sa wc_AesEaxInit + \sa wc_AesEaxEncryptUpdate + \sa wc_AesEaxAuthDataUpdate + \sa wc_AesEaxEncryptFinal + \sa wc_AesEaxDecryptFinal + \sa wc_AesEaxFree + +*/ +WOLFSSL_API int wc_AesEaxDecryptUpdate(AesEax* eax, byte* out, + const byte* in, word32 inSz, + const byte* authIn, word32 authInSz); +/*! + \ingroup AES + \brief This function adds input data to the authentication stream. + \c eax must have been previously initialized with a call to + \ref wc_AesEaxInit. + + \return 0 on success + \return error code on failure + + \param eax AES EAX structure holding the context of the AEAD operation + \param authIn input data to add to the authentication stream + \param authInSz size in bytes of the input authentication data + + _Example_ + \code + 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); + \endcode + + \sa wc_AesEaxInit + \sa wc_AesEaxEncryptUpdate + \sa wc_AesEaxDecryptUpdate + \sa wc_AesEaxEncryptFinal + \sa wc_AesEaxDecryptFinal + \sa wc_AesEaxFree + +*/ +WOLFSSL_API int wc_AesEaxAuthDataUpdate(AesEax* eax, + const byte* authIn, word32 authInSz); + +/*! + \ingroup AES + \brief This function finalizes the encrypt AEAD operation, producing an auth + tag over the current authentication stream. \c eax must have been previously + initialized with a call to \ref wc_AesEaxInit. When done using the \c AesEax + context structure, make sure to free it using \ref wc_AesEaxFree. + + \return 0 on success + \return error code on failure + + \param eax AES EAX structure holding the context of the AEAD operation + \param authTag[out] buffer that will hold the computed auth tag + \param authTagSz size in bytes of \c authTag + + _Example_ + \code + 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); + \endcode + + \sa wc_AesEaxInit + \sa wc_AesEaxEncryptUpdate + \sa wc_AesEaxDecryptUpdate + \sa wc_AesEaxAuthDataUpdate + \sa wc_AesEaxDecryptFinal + \sa wc_AesEaxFree + +*/ +WOLFSSL_API int wc_AesEaxEncryptFinal(AesEax* eax, + byte* authTag, word32 authTagSz); + +/*! + \ingroup AES + \brief This function finalizes the decrypt AEAD operation, finalizing the + auth tag computation and checking it for validity against the user supplied + tag. \c eax must have been previously initialized with a call to + \ref wc_AesEaxInit. When done using the \c AesEax context structure, make + sure to free it using \ref wc_AesEaxFree. + + \return 0 if data is authenticated successfully + \return AES_EAX_AUTH_E if the authentication tag does not match the + supplied authentication code vector \c authIn + \return other error code on failure + + \param eax AES EAX structure holding the context of the AEAD operation + \param authIn input auth tag to check computed auth tag against + \param authInSz size in bytes of \c authIn + + _Example_ + \code + 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); + \endcode + + \sa wc_AesEaxInit + \sa wc_AesEaxEncryptUpdate + \sa wc_AesEaxDecryptUpdate + \sa wc_AesEaxAuthDataUpdate + \sa wc_AesEaxEncryptFinal + \sa wc_AesEaxFree + +*/ +WOLFSSL_API int wc_AesEaxDecryptFinal(AesEax* eax, + const byte* authIn, word32 authInSz); +/*! + \ingroup AES + + \brief 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. + + \return 0 Success + + \param eaxAES EAX instance to free + + _Example_ + \code + AesEax eax; + + if(wc_AesEaxInit(eax, key, keySz, nonce, nonceSz, authIn, authInSz) != 0) { + // handle errors, then free + wc_AesEaxFree(&eax); + } + \endcode + + \sa wc_AesEaxInit + \sa wc_AesEaxEncryptUpdate + \sa wc_AesEaxDecryptUpdate + \sa wc_AesEaxAuthDataUpdate + \sa wc_AesEaxEncryptFinal + \sa wc_AesEaxDecryptFinal +*/ +WOLFSSL_API int wc_AesEaxFree(AesEax* eax); + + + |