From 9cef2a70b151b6a92eb1770ceb5fa90331305934 Mon Sep 17 00:00:00 2001 From: Todd Short Date: Mon, 6 Jun 2022 11:46:36 -0400 Subject: [PATCH] Update SIV mode documentation Fixes #18440 Reviewed-by: Shane Lontis Reviewed-by: Tomas Mraz Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/18485) --- doc/man3/EVP_EncryptInit.pod | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index cd520791d7..4069866a9f 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -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 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 bytes of the tag value to the buffer indicated by I. -This call can only be made when encrypting data and B all data has been -processed (e.g. after an EVP_EncryptFinal() call). For SIV mode the taglen must -be 16. +Writes I bytes of the tag value (the Synthetic Initialization Vector) +to the buffer indicated by I. This call can only be made when encrypting +data and B 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 bytes from I. This call is only legal -when decrypting data and must be made B 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 +bytes from I. This call is only legal when decrypting data and must be +made B 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 set to a non-B value. A call to EVP_Decrypt_Final() or +with I set to a non-B value. A call to EVP_DecryptFinal() or EVP_CipherFinal() is not required, but will indicate if the update operation succeeded.