diff options
author | Todd Short <tshort@akamai.com> | 2022-06-06 11:46:36 -0400 |
---|---|---|
committer | Pauli <pauli@openssl.org> | 2022-06-09 13:29:49 +1000 |
commit | 060f2bcae10617fcc85591718ee09228b50759de (patch) | |
tree | f613ba4d8fda5091d3b9451c4fa99a358b6074b3 /doc | |
parent | 187963b945a1e9db1d47de8da0f5b0066592f835 (diff) |
Update SIV mode documentation
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)
(cherry picked from commit 9cef2a70b151b6a92eb1770ceb5fa90331305934)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/EVP_EncryptInit.pod | 29 |
1 files changed, 20 insertions, 9 deletions
diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 7f9c44b107..f925e9bd49 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -1373,28 +1373,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. |