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)

(cherry picked from commit d15077d336e4b6144f8a5fdb0c1bb58ca9d3552f)

diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod
index 5192ad8e727d3b829696f9769725898d151bb584..cb0603a87f60d07eb196eb34440341970719fd8e 100644 (file)
--- a/doc/man3/EVP_EncryptInit.pod
+++ b/doc/man3/EVP_EncryptInit.pod
@@ -1302,6 +1302,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.