Fix documentation around AAD and return values in EVP_Cipher*

Fixes #21485

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21494)

(cherry picked from commit 51a7066e2092b062a502e29166adfcc297803058)

diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index b2a63a0bee3a77a602dae306dbbacc2b9ac1853b..56b29b52e1185597d75f4fa695c6df21668600c8 100644 (file)
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -1210,10 +1210,11 @@ EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success.
 EVP_CipherInit_ex2() and EVP_CipherUpdate() return 1 for success and 0 for failure.
 EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success.
 
-EVP_Cipher() returns the amount of encrypted / decrypted bytes, or -1
-on failure if the flag B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is set for the
-cipher.  EVP_Cipher() returns 1 on success or 0 on failure, if the flag
+EVP_Cipher() returns 1 on success or 0 on failure, if the flag
 B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is not set for the cipher.
+EVP_Cipher() returns the number of bytes written to I<out> for encryption / decryption, or
+the number of bytes authenticated in a call specifying AAD for an AEAD cipher, if the flag
+B<EVP_CIPH_FLAG_CUSTOM_CIPHER> is set for the cipher.
 
 EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure.
 
@@ -1284,7 +1285,8 @@ depending on the mode specified.
 
 To specify additional authenticated data (AAD), a call to EVP_CipherUpdate(),
 EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
-parameter I<out> set to B<NULL>.
+parameter I<out> set to B<NULL>. In this case, on success, the parameter
+I<outl> is set to the number of bytes authenticated.
 
 When decrypting, the return value of EVP_DecryptFinal() or EVP_CipherFinal()
 indicates whether the operation was successful. If it does not indicate success,