diff --git a/doc/dox_comments/header_files/aes.h b/doc/dox_comments/header_files/aes.h index 764c4d5f2..4d6561eec 100644 --- a/doc/dox_comments/header_files/aes.h +++ b/doc/dox_comments/header_files/aes.h @@ -416,9 +416,11 @@ int wc_AesGcmEncrypt(Aes* aes, byte* out, \brief 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. + 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. - \return 0 On successfully decrypting the input message + \return 0 On successfully decrypting and authenticating the input message \return AES_GCM_AUTH_E If the authentication tag does not match the supplied authentication code vector, authTag. @@ -609,8 +611,9 @@ int wc_AesCcmEncrypt(Aes* aes, byte* out, \brief 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. + 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. \return 0 On successfully decrypting the input message \return AES_CCM_AUTH_E If the authentication tag does not match the @@ -1134,7 +1137,9 @@ int wc_AesSivEncrypt(const byte* key, word32 keySz, const byte* assoc, /*! \ingroup AES \brief This function performs SIV (synthetic initialization vector) - decryption as described in RFC 5297. + 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. \return 0 On successful decryption. \return BAD_FUNC_ARG If key, SIV, or output buffer are NULL. Also returned @@ -1248,7 +1253,10 @@ WOLFSSL_API int wc_AesEaxEncryptAuth(const byte* key, word32 keySz, byte* out, \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. + 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. \return 0 on successful decryption \return BAD_FUNC_ARG if input or output buffers are NULL. Also returned diff --git a/doc/dox_comments/header_files/chacha20_poly1305.h b/doc/dox_comments/header_files/chacha20_poly1305.h index 5a7f81950..057d274c2 100644 --- a/doc/dox_comments/header_files/chacha20_poly1305.h +++ b/doc/dox_comments/header_files/chacha20_poly1305.h @@ -62,14 +62,18 @@ int wc_ChaCha20Poly1305_Encrypt( ChaCha20 stream cipher, into the output buffer, outPlaintext. It also performs Poly-1305 authentication, comparing the given inAuthTag to an authentication generated with the inAAD (arbitrary length additional - authentication data). Note: If the generated authentication tag does - not match the supplied authentication tag, the text is not decrypted. + authentication data). If a nonzero error code is returned, the output + data, outPlaintext, is undefined. However, callers must unconditionally + zeroize the output buffer to guard against leakage of cleartext data. - \return 0 Returned upon successfully decrypting the message + \return 0 Returned upon successfully decrypting and authenticating the + message \return BAD_FUNC_ARG Returned if any of the function arguments do not match what is expected \return MAC_CMP_FAILED_E Returned if the generated authentication tag does not match the supplied inAuthTag. + \return MEMORY_E Returned if internal buffer allocation failed. + \return CHACHA_POLY_OVERFLOW Can be returned if input is corrupted. \param inKey pointer to a buffer containing the 32 byte key to use for decryption diff --git a/wolfssl/wolfcrypt/aes.h b/wolfssl/wolfcrypt/aes.h index e5ac0c70e..127c2f97a 100644 --- a/wolfssl/wolfcrypt/aes.h +++ b/wolfssl/wolfcrypt/aes.h @@ -588,7 +588,7 @@ WOLFSSL_API int wc_AesEcbDecrypt(Aes* aes, byte* out, const byte* iv, word32 ivSz, byte* authTag, word32 authTagSz, const byte* authIn, word32 authInSz); - WOLFSSL_API int wc_AesGcmDecrypt(Aes* aes, byte* out, + WOLFSSL_API WARN_UNUSED_RESULT int wc_AesGcmDecrypt(Aes* aes, byte* out, const byte* in, word32 sz, const byte* iv, word32 ivSz, const byte* authTag, word32 authTagSz, @@ -610,8 +610,8 @@ WOLFSSL_API int wc_AesGcmDecryptInit(Aes* aes, const byte* key, word32 len, const byte* iv, word32 ivSz); WOLFSSL_API int wc_AesGcmDecryptUpdate(Aes* aes, byte* out, const byte* in, word32 sz, const byte* authIn, word32 authInSz); -WOLFSSL_API int wc_AesGcmDecryptFinal(Aes* aes, const byte* authTag, - word32 authTagSz); +WOLFSSL_API WARN_UNUSED_RESULT int wc_AesGcmDecryptFinal(Aes* aes, + const byte* authTag, word32 authTagSz); #endif #ifndef WC_NO_RNG @@ -648,7 +648,7 @@ WOLFSSL_API int wc_AesGcmDecryptFinal(Aes* aes, const byte* authTag, const byte* nonce, word32 nonceSz, byte* authTag, word32 authTagSz, const byte* authIn, word32 authInSz); - WOLFSSL_API int wc_AesCcmDecrypt(Aes* aes, byte* out, + WOLFSSL_API WARN_UNUSED_RESULT int wc_AesCcmDecrypt(Aes* aes, byte* out, const byte* in, word32 inSz, const byte* nonce, word32 nonceSz, const byte* authTag, word32 authTagSz, @@ -761,7 +761,7 @@ WOLFSSL_API 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); -WOLFSSL_API +WOLFSSL_API WARN_UNUSED_RESULT 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); @@ -770,7 +770,7 @@ WOLFSSL_API 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); -WOLFSSL_API +WOLFSSL_API WARN_UNUSED_RESULT 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); @@ -805,7 +805,8 @@ WOLFSSL_API int wc_AesEaxEncryptAuth(const byte* key, word32 keySz, byte* out, /* input data to authenticate (header) */ const byte* authIn, word32 authInSz); -WOLFSSL_API int wc_AesEaxDecryptAuth(const byte* key, word32 keySz, byte* out, +WOLFSSL_API WARN_UNUSED_RESULT 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 */ @@ -833,7 +834,7 @@ WOLFSSL_API int wc_AesEaxAuthDataUpdate(AesEax* eax, WOLFSSL_API int wc_AesEaxEncryptFinal(AesEax* eax, byte* authTag, word32 authTagSz); -WOLFSSL_API int wc_AesEaxDecryptFinal(AesEax* eax, +WOLFSSL_API WARN_UNUSED_RESULT int wc_AesEaxDecryptFinal(AesEax* eax, const byte* authIn, word32 authInSz); WOLFSSL_API int wc_AesEaxFree(AesEax* eax); diff --git a/wolfssl/wolfcrypt/chacha20_poly1305.h b/wolfssl/wolfcrypt/chacha20_poly1305.h index c7694dbdb..7f9ac1643 100644 --- a/wolfssl/wolfcrypt/chacha20_poly1305.h +++ b/wolfssl/wolfcrypt/chacha20_poly1305.h @@ -95,7 +95,7 @@ int wc_ChaCha20Poly1305_Encrypt( byte* outCiphertext, byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]); -WOLFSSL_ABI WOLFSSL_API +WOLFSSL_ABI WOLFSSL_API WARN_UNUSED_RESULT int wc_ChaCha20Poly1305_Decrypt( const byte inKey[CHACHA20_POLY1305_AEAD_KEYSIZE], const byte inIV[CHACHA20_POLY1305_AEAD_IV_SIZE], @@ -104,7 +104,7 @@ int wc_ChaCha20Poly1305_Decrypt( const byte inAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE], byte* outPlaintext); -WOLFSSL_API +WOLFSSL_API WARN_UNUSED_RESULT int wc_ChaCha20Poly1305_CheckTag( const byte authTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE], const byte authTagChk[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]); @@ -121,7 +121,7 @@ WOLFSSL_API int wc_ChaCha20Poly1305_UpdateAad(ChaChaPoly_Aead* aead, const byte* inAAD, word32 inAADLen); WOLFSSL_API int wc_ChaCha20Poly1305_UpdateData(ChaChaPoly_Aead* aead, const byte* inData, byte* outData, word32 dataLen); -WOLFSSL_API int wc_ChaCha20Poly1305_Final(ChaChaPoly_Aead* aead, +WOLFSSL_API WARN_UNUSED_RESULT int wc_ChaCha20Poly1305_Final(ChaChaPoly_Aead* aead, byte outAuthTag[CHACHA20_POLY1305_AEAD_AUTHTAG_SIZE]); #ifdef HAVE_XCHACHA @@ -140,7 +140,7 @@ WOLFSSL_API int wc_XChaCha20Poly1305_Encrypt( const byte *nonce, size_t nonce_len, const byte *key, size_t key_len); -WOLFSSL_API int wc_XChaCha20Poly1305_Decrypt( +WOLFSSL_API WARN_UNUSED_RESULT int wc_XChaCha20Poly1305_Decrypt( byte *dst, size_t dst_space, const byte *src, size_t src_len, const byte *ad, size_t ad_len,