Ensure EVP_MD_CTX_md returns the EVP_MD originally used

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

diff --git a/doc/man3/EVP_MD_fetch.pod b/doc/man3/EVP_MD_fetch.pod
index 17481089f065db27a088f6c7f8f3e0a6b95ad06d..96536048bcd178863a7774905a808fe6b36287eb 100644 (file)
--- a/doc/man3/EVP_MD_fetch.pod
+++ b/doc/man3/EVP_MD_fetch.pod
@@ -21,13 +21,13 @@ calculate the digest of input data using functions such as
 L<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)> and L<EVP_DigestFinal_ex(3)>.
 
 Digest implementations may be obtained in one of three ways, i.e. implicit
-lookup, explicit lookup or user defined.
+fetch, explicit fetch or user defined.
 
 =over 4
 
-=item Implicit Lookup
+=item Implicit Fetch
 
-With implicit lookup an application can use functions such as L<EVP_sha256(3)>,
+With implicit fetch an application can use functions such as L<EVP_sha256(3)>,
 L<EVP_sha512(3)> or L<EVP_blake2b512(3)> to obtain an B<EVP_MD> object. When
 used in a function like L<EVP_DigestInit_ex(3)> the actual implementation to
 be used will be fetched implicitly using default search criteria. Typically,
@@ -35,9 +35,9 @@ be used will be fetched implicitly using default search criteria. Typically,
 have been loaded), this will return an implementation of the appropriate
 algorithm from the default provider.
 
-=item Explicit Lookup
+=item Explicit Fetch
 
-With explicit lookup an application uses the EVP_MD_fetch() function to obtain
+With explicit fetch an application uses the EVP_MD_fetch() function to obtain
 an algorithm implementation. An implementation with the given name and
 satisfying the search criteria specified in the B<properties> parameter will be
 looked for within the available providers and returned. See L<OSSL_PROVIDER(3)>
@@ -83,6 +83,18 @@ The return value from a call to EVP_MD_fetch() must be freed by the caller using
 L<EVP_MD_meth_free(3)>. Note that EVP_MD objects are reference counted. See
 L<EVP_MD_upref(3)>.
 
+=head1 NOTES
+
+Where an application that previously used implicit fetch is converted to use
+explicit fetch care should be taken with the L<EVP_MD_CTX_md(3)> function.
+Specifically, this function returns the EVP_MD object orginally passed to
+EVP_DigestInit_ex() (or other similar function). With implicit fetch the
+returned EVP_MD object is guaranteed to be available throughout the application
+lifetime. However, with explicit fetch EVP_MD objects are reference counted.
+EVP_MD_CTX_md does not increment the reference count and so the returned EVP_MD
+object may not be accessible beyond the lifetime of the EVP_MD_CTX it is
+associated with.
+
 =head1 RETURN VALUES
 
 EVP_MD_fetch() returns a pointer to the algorithm implementation represented by