Ignore entropy from RAND_add()/RAND_seed() in FIPS mode

[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..cba3bc4f0ba5693d170bcb704764e0221b5137a7 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,13 +35,15 @@ 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)>
-for information about providers.
+satisfying the search criteria specified in the B<properties> parameter
+combined with the default search criteria will be looked for within the
+available providers and returned.
+See L<EVP_set_default_properties(3)> for information on default search criteria
+and L<OSSL_PROVIDER(3)> for information about providers.
 
 =item User defined
 
@@ -83,6 +85,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
@@ -144,7 +158,8 @@ other providers:
 =head1 SEE ALSO
 
 L<EVP_DigestInit(3)>, L<EVP_MD_meth_new(3)>, L<EVP_MD_meth_free(3)>,
-L<EVP_MD_upref(3)>, L<OSSL_PROVIDER_load(3)>, L<OPENSSL_CTX(3)>
+L<EVP_MD_upref(3)>, L<OSSL_PROVIDER_load(3)>, L<OPENSSL_CTX(3)>,
+L<EVP_set_default_properties(3)>
 
 =head1 HISTORY