WolfSSL
/
wolfssl
mirror of https://github.com/wolfSSL/wolfssl.git
1
0
Fork 0
Code Issues Releases Wiki Activity

update documentation for AEAD decrypt methods, specifically noting that nonzero retval means output data is undefined, and noting requirement to zeroize the output data unconditionally.

pull/8624/head
Daniel Pouzzner 2025-04-02 13:36:59 -05:00
parent b8ece68b17
commit 91e9e8f65f
2 changed files with 21 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/dox_comments/header_files/aes.h
View File

@ -416,9 +416,11 @@ int wc_AesGcmEncrypt(Aes* aes, byte* out,
\brief This function decrypts the input cipher text, held in the buffer \brief This function decrypts the input cipher text, held in the buffer
in, and stores the resulting message text in the output buffer out. in, and stores the resulting message text in the output buffer out.
It also checks the input authentication vector, authIn, against the 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 \return AES_GCM_AUTH_E If the authentication tag does not match the
supplied authentication code vector, authTag. 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 \brief This function decrypts the input cipher text, in, into
the output buffer, out, using CCM (Counter with CBC-MAC). It the output buffer, out, using CCM (Counter with CBC-MAC). It
subsequently calculates the authorization tag, authTag, from the subsequently calculates the authorization tag, authTag, from the
authIn input. If the authorization tag is invalid, it sets the authIn input. If a nonzero error code is returned, the output data is
output buffer to zero and returns the error: AES_CCM_AUTH_E. 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 the input message
\return AES_CCM_AUTH_E If the authentication tag does not match the \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 \ingroup AES
\brief This function performs SIV (synthetic initialization vector) \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 0 On successful decryption.
\return BAD_FUNC_ARG If key, SIV, or output buffer are NULL. Also returned \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 \brief This function performs AES EAX decryption and authentication as
described in "EAX: A Conventional Authenticated-Encryption Mode" described in "EAX: A Conventional Authenticated-Encryption Mode"
(https://eprint.iacr.org/2003/069). It is a "one-shot" API that performs (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 0 on successful decryption
\return BAD_FUNC_ARG if input or output buffers are NULL. Also returned \return BAD_FUNC_ARG if input or output buffers are NULL. Also returned

10
doc/dox_comments/header_files/chacha20_poly1305.h
View File

@ -62,14 +62,18 @@ int wc_ChaCha20Poly1305_Encrypt(
ChaCha20 stream cipher, into the output buffer, outPlaintext. It also ChaCha20 stream cipher, into the output buffer, outPlaintext. It also
performs Poly-1305 authentication, comparing the given inAuthTag to an performs Poly-1305 authentication, comparing the given inAuthTag to an
authentication generated with the inAAD (arbitrary length additional authentication generated with the inAAD (arbitrary length additional
authentication data). Note: If the generated authentication tag does authentication data). If a nonzero error code is returned, the output
not match the supplied authentication tag, the text is not decrypted. 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 \return BAD_FUNC_ARG Returned if any of the function arguments do not
match what is expected match what is expected
\return MAC_CMP_FAILED_E Returned if the generated authentication tag \return MAC_CMP_FAILED_E Returned if the generated authentication tag
does not match the supplied inAuthTag. 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 \param inKey pointer to a buffer containing the 32 byte key to use for
decryption decryption