Update Documentation for EVP_DigestSign, EVP_DigestVerify.

Fixes #23075

In OpenSSL 3.2 EVP_DigestSign and EVP_DigestVerify
were changed so that a flag is set once these functions
do a one-shot sign or verify operation. This PR updates the
documentation to match the behaviour.

Investigations showed that prior to 3.2 different key
type behaved differently if multiple calls were done.

By accident X25519 and X448 would produce the same signature,
but ECDSA and RSA remembered the digest state between calls,
so the signature was different when multiple calls were done.

Because of this undefined behaviour something needed to be done,
so keeping the 'only allow it to be called once' behaviour
seems a reasonable approach.

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/23834)

diff --git a/doc/man3/EVP_DigestSignInit.pod b/doc/man3/EVP_DigestSignInit.pod
index 07e99db231a2f4abc71add4e5233a90d4768b6bd..9916cf0f10fa099928101dd8154ce4e2780c357b 100644 (file)
--- a/doc/man3/EVP_DigestSignInit.pod
+++ b/doc/man3/EVP_DigestSignInit.pod
@@ -128,13 +128,12 @@ I<siglen> parameter should contain the length of the I<sig> buffer. If the
 call is successful the signature is written to I<sig> and the amount of data
 written to I<siglen>.
 
-EVP_DigestSign() signs I<tbslen> bytes of data at I<tbs> and places the
-signature in I<sig> and its length in I<siglen> in a similar way to
-EVP_DigestSignFinal(). In the event of a failure EVP_DigestSign() cannot be
-called again without reinitialising the EVP_MD_CTX. If I<sig> is NULL before the
-call then I<siglen> will be populated with the required size for the I<sig>
-buffer. If I<sig> is non-NULL before the call then I<siglen> should contain the
-length of the I<sig> buffer.
+EVP_DigestSign() is similar to a single call to EVP_DigestSignUpdate() and
+EVP_DigestSignFinal().
+Unless I<sig> is NULL, EVP_DigestSign() signs the data I<tbs> of length I<tbslen>
+bytes and places the signature in a buffer I<sig> of size I<siglen>.
+If I<sig> is NULL, the maximum necessary size of the signature buffer is written
+to the I<siglen> parameter.
 
 =head1 RETURN VALUES
 
@@ -179,6 +178,10 @@ multiple times on a context and the parameters set by previous calls should be
 preserved if the I<pkey> parameter is NULL. The call then just resets the state
 of the I<ctx>.
 
+EVP_DigestSign() can not be called again, once a signature is generated (by
+passing I<sig> as non NULL), unless the B<EVP_MD_CTX> is reinitialised by
+calling EVP_DigestSignInit_ex().
+
 Ignoring failure returns of EVP_DigestSignInit() and EVP_DigestSignInit_ex()
 functions can lead to subsequent undefined behavior when calling
 EVP_DigestSignUpdate(), EVP_DigestSignFinal(), or EVP_DigestSign().

diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod
index c927b7e4e82a8c1eb6de2203ffef4fac4bd9a914..84401a8c8030eabf3817a792436781864a6d231b 100644 (file)
--- a/doc/man3/EVP_DigestVerifyInit.pod
+++ b/doc/man3/EVP_DigestVerifyInit.pod
@@ -168,6 +168,9 @@ multiple times on a context and the parameters set by previous calls should be
 preserved if the I<pkey> parameter is NULL. The call then just resets the state
 of the I<ctx>.
 
+EVP_DigestVerify() can only be called once, and cannot be used again without
+reinitialising the B<EVP_MD_CTX> by calling EVP_DigestVerifyInit_ex().
+
 Ignoring failure returns of EVP_DigestVerifyInit() and EVP_DigestVerifyInit_ex()
 functions can lead to subsequent undefined behavior when calling
 EVP_DigestVerifyUpdate(), EVP_DigestVerifyFinal(), or EVP_DigestVerify().