Skip to content

Commit

Permalink
Clarify EVP_CipherUpdate() authenticated bytes behavior
Browse files Browse the repository at this point in the history
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 openssl/openssl#24961)
  • Loading branch information
erbsland-dev authored and t8m committed Sep 5, 2024
1 parent 71ae466 commit d15077d
Showing 1 changed file with 9 additions and 0 deletions.
9 changes: 9 additions & 0 deletions doc/man3/EVP_EncryptInit.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit d15077d

Please sign in to comment.