From: Tomas Mraz <tmraz@fedoraproject.org>
Date: Wed, 18 Nov 2020 15:22:08 +0000 (+0100)
Subject: Documentation improvements for EVP_DigestInit_ex and related functions
X-Git-Tag: openssl-3.0.0-alpha10~255
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=2b407d050868c24ee36172e1abcfbfa0f003a98d;p=thirdparty%2Fopenssl.git

Documentation improvements for EVP_DigestInit_ex and related functions

Documenting when EVP_MD_CTX_reset() is implicitly called and when
type can be set to NULL.

Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13402)
---

diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 0af06869aa8..082f26370c2 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -208,6 +208,10 @@ value explicitly fetched with EVP_MD_fetch().
 If I<impl> is non-NULL, its implementation of the digest I<type> is used if
 there is one, and if not, the default implementation is used.
 
+The I<type> parameter can be NULL if I<ctx> has been already initialized
+with another EVP_DigestInit_ex() call and has not been reset with
+EVP_MD_CTX_reset().
+
 =item EVP_DigestUpdate()
 
 Hashes I<cnt> bytes of data at I<d> into the digest context I<ctx>. This
@@ -239,12 +243,13 @@ few bytes.
 =item EVP_DigestInit()
 
 Behaves in the same way as EVP_DigestInit_ex() except it always uses the
-default digest implementation and calls EVP_MD_CTX_reset().
+default digest implementation and calls EVP_MD_CTX_reset() so it cannot
+be used with an I<type> of NULL.
 
 =item EVP_DigestFinal()
 
-Similar to EVP_DigestFinal_ex() except the digest context I<ctx> is
-automatically cleaned up.
+Similar to EVP_DigestFinal_ex() except after computing the digest
+the digest context I<ctx> is automatically cleaned up with EVP_MD_CTX_reset().
 
 =item EVP_MD_CTX_copy()