In documentation, consistently refer to OpenSSL 3.0

[openssl.git] / doc / man3 / EVP_DigestVerifyInit.pod

diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod
index 352ab8462e475a2c074955eca699d42cec3f7070..97bb773722625be5ecdba4b49b2cee9e6b465f0e 100644 (file)
--- a/doc/man3/EVP_DigestVerifyInit.pod
+++ b/doc/man3/EVP_DigestVerifyInit.pod
@@ -23,9 +23,17 @@ The EVP signature routines are a high level interface to digital signatures.
 
 EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest
 B<type> from ENGINE B<e> and public key B<pkey>. B<ctx> must be created
-with EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the
+with EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL, the
 EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this
-can be used to set alternative verification options.
+can be used to set alternative verification options. Note that any existing
+value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed
+directly by the application if B<ctx> is not assigned an EVP_PKEY_CTX value before
+being passed to EVP_DigestVerifyInit() (which means the EVP_PKEY_CTX is created
+inside EVP_DigestVerifyInit() and it will be freed automatically when the
+EVP_MD_CTX is freed).
+
+No B<EVP_PKEY_CTX> will be created by EVP_DigestSignInit() if the passed B<ctx>
+has already been assigned one via L<EVP_MD_CTX_set_ctx(3)>. See also L<SM2(7)>.
 
 EVP_DigestVerifyUpdate() hashes B<cnt> bytes of data at B<d> into the
 verification context B<ctx>. This function can be called several times on the
@@ -68,14 +76,15 @@ and public key algorithms. This meant that "clone" digests such as EVP_dss1()
 needed to be used to sign using SHA1 and DSA. This is no longer necessary and
 the use of clone digest is now discouraged.
 
-For some key types and parameters the random number generator must be seeded
-or the operation will fail.
+For some key types and parameters the random number generator must be seeded.
+If the automatic seeding or reseeding of the OpenSSL CSPRNG fails due to
+external circumstances (see L<RAND(7)>), the operation will fail.
 
 The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest
 context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can
 be called later to digest and verify additional data.
 
-Since only a copy of the digest context is ever finalized the context must
+Since only a copy of the digest context is ever finalized, the context must
 be cleaned up after use by calling EVP_MD_CTX_free() or a memory leak
 will occur.
 
@@ -85,18 +94,19 @@ L<EVP_DigestSignInit(3)>,
 L<EVP_DigestInit(3)>,
 L<evp(7)>, L<HMAC(3)>, L<MD2(3)>,
 L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>,
-L<SHA1(3)>, L<dgst(1)>
+L<SHA1(3)>, L<dgst(1)>,
+L<RAND(7)>
 
 =head1 HISTORY
 
 EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal()
-were first added to OpenSSL 1.0.0.
+were added in OpenSSL 1.0.0.
 
 =head1 COPYRIGHT
 
 Copyright 2006-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.