Clarify EVP_CipherUpdate() authenticated bytes behavior

Fixes #8310: Document that the number of authenticated bytes returned by EVP_CipherUpdate() varies with the cipher used. Mention that stream ciphers like ChaCha20 can handle 1 byte at a time, while OCB mode requires processing data one block at a time. Ensure it's clear that passing unpadded data in one call is safe.

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

diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index b38e82059893afb1cdd213625b95825d2fbcdf86..fe63051d4d173c52d00181e09241d89154835fb2 100644 (file)
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -1390,6 +1390,15 @@ indicates whether the operation was successful. If it does not indicate success,
 the authentication operation has failed and any output data B<MUST NOT> be used
 as it is corrupted.
 
+Please note that the number of authenticated bytes returned by
+EVP_CipherUpdate() depends on the cipher used. Stream ciphers, such as ChaCha20
+or ciphers in GCM mode, can handle 1 byte at a time, resulting in an effective
+"block" size of 1. Conversely, ciphers in OCB mode must process data one block
+at a time, and the block size is returned.
+
+Regardless of the returned size, it is safe to pass unpadded data to an
+EVP_CipherUpdate() call in a single operation.
+
 =head2 GCM and OCB Modes
 
 The following I<ctrl>s are supported in GCM and OCB modes.