mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-02-11 14:22:43 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update SIV mode documentation

Browse Source 
Fixes #18440

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/18485)
This commit is contained in:
Todd Short 2022-06-06 11:46:36 -04:00 committed by Pauli
parent 7d6aad832b
commit 9cef2a70b1
1 changed files with 20 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
doc/man3/EVP_EncryptInit.pod
View File

@ -1391,28 +1391,39 @@ indicates if 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.
The following ctrls are supported in both SIV modes.
The API does not store the the SIV (Synthetic Initialization Vector) in
the cipher text. Instead, it is stored as the tag within the EVP_CIPHER_CTX.
The SIV must be retrieved from the context after encryption, and set into
the context before decryption.
This differs from RFC5297 in that the cipher output from encryption, and
the cipher input to decryption, does not contain the SIV. This also means
that the plain text and cipher text lengths are identical.
The following ctrls are supported in SIV mode, and are used to get and set
the Synthetic Initialization Vector:
=over 4
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag);
Writes I<taglen> bytes of the tag value to the buffer indicated by I<tag>.
This call can only be made when encrypting data and B<after> all data has been
processed (e.g. after an EVP_EncryptFinal() call). For SIV mode the taglen must
be 16.
Writes I<taglen> bytes of the tag value (the Synthetic Initialization Vector)
to the buffer indicated by I<tag>. This call can only be made when encrypting
data and B<after> all data has been processed (e.g. after an EVP_EncryptFinal()
call). For SIV mode the taglen must be 16.
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag);
Sets the expected tag to I<taglen> bytes from I<tag>. This call is only legal
when decrypting data and must be made B<before> any data is processed (e.g.
before any EVP_DecryptUpdate() call). For SIV mode the taglen must be 16.
Sets the expected tag (the Synthetic Initialization Vector) to I<taglen>
bytes from I<tag>. This call is only legal when decrypting data and must be
made B<before> any data is processed (e.g. before any EVP_DecryptUpdate()
calls). For SIV mode the taglen must be 16.
=back
SIV mode makes two passes over the input data, thus, only one call to
EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made
with I<out> set to a non-B<NULL> value. A call to EVP_Decrypt_Final() or
with I<out> set to a non-B<NULL> value. A call to EVP_DecryptFinal() or
EVP_CipherFinal() is not required, but will indicate if the update
operation succeeded.