=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
+While the BLAKE2b and BLAKE2s algorithms supports a variable length digest,
+this implementation outputs a digest of a fixed length (the maximum length
+supported), which is 512-bits for BLAKE2b and 256-bits for BLAKE2s.
+
=head1 RETURN VALUES
These functions return a B<EVP_MD> structure that contains the
RFC 7693.
-=head1 NOTES
-
-While the BLAKE2b and BLAKE2s algorithms supports a variable length digest,
-this implementation outputs a digest of a fixed length (the maximum length
-supported), which is 512-bits for BLAKE2b and 256-bits for BLAKE2s.
-
=head1 SEE ALSO
L<evp(7)>,
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+Developers should be aware of the negative performance implications of
+calling this function multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling this function multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
=head1 RETURN VALUES
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling this function multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
=head1 RETURN VALUES
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
=head1 RETURN VALUES
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling this function multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return a B<EVP_MD> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling this function multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return a B<EVP_MD> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return an B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling this function multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
=head1 RETURN VALUES
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
=head1 RETURN VALUES
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
=head1 RETURN VALUES
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling this function multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
=head1 RETURN VALUES
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling these functions multiple times and should consider using
+L<EVP_CIPHER_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
+
=head1 RETURN VALUES
These functions return a B<EVP_CIPHER> structure that contains the
=back
+=head1 NOTES
+
+Developers should be aware of the negative performance implications of
+calling this function multiple times and should consider using
+L<EVP_MD_fetch(3)> instead.
+See L<crypto(7)/Performance> for further information.
=head1 RETURN VALUES
Property query strings can be specified explicitly as an argument to a function.
It is also possible to specify a default property query string for the whole
-library context using the L<EVP_set_default_properties(3)> function. Where both
+library context using the L<EVP_set_default_properties(3)> or
+L<EVP_default_properties_enable_fips(3)> functions. Where both
default properties and function specific properties are specified then they are
combined. Function specific properties will override default properties where
there is a conflict.
as a parameter an B<EVP_MD> object which may have been returned from an earlier
call to L<EVP_MD_fetch(3)>.
-=head2 Implicit fetch
+=head2 Implicit fetching
OpenSSL has a number of functions that return an algorithm object with no
associated implementation, such as L<EVP_sha256(3)>, L<EVP_aes_128_cbc(3)>,
=back
+=head2 Performance
+
+If you perform the same operation many times then it is recommended to use
+L</Explicit fetching> to prefetch an algorithm once initially,
+and then pass this created object to any operations that are currently
+using L</Implicit fetching>.
+See an example of Explicit fetching in L</USING ALGORITHMS IN APPLICATIONS>.
+
+Prior to OpenSSL 3.0, constant method tables (such as EVP_sha256()) were used
+directly to access methods. If you pass one of these convenience functions
+to an operation the fixed methods are ignored, and only the name is used to
+internally fetch methods from a provider.
+
+If the prefetched object is not passed to operations, then any implicit
+fetch will use the internally cached prefetched object, but it will
+still be slower than passing the prefetched object directly.
+
+Fetching via a provider offers more flexibility, but it is slower than the
+old method, since it must search for the algorithm in all loaded providers,
+and then populate the method table using provider supplied methods.
+Internally OpenSSL caches similar algorithms on the first fetch
+(so loading a digest caches all digests).
+
+The following methods can be used for prefetching:
+
+=over 4
+
+=item L<EVP_MD_fetch(3)>
+
+=item L<EVP_CIPHER_fetch(3)>
+
+=item L<EVP_KDF_fetch(3)>
+
+=item L<EVP_MAC_fetch(3)>
+
+=item L<EVP_KEM_fetch(3)>
+
+=item L<OSSL_ENCODER_fetch(3)>
+
+=item L<OSSL_DECODER_fetch(3)>
+
+=item L<EVP_RAND_fetch(3)>
+
+=back
+
+The following methods are used internally when performing operations:
+
+=over 4
+
+=item L<EVP_KEYMGMT_fetch(3)>
+
+=item L<EVP_KEYEXCH_fetch(3)>
+
+=item L<EVP_SIGNATURE_fetch(3)>
+
+=item L<OSSL_STORE_LOADER_fetch(3)>
+
+=back
+
+See L<OSSL_PROVIDER-default(7)>, <OSSL_PROVIDER-fips(7)> and
+<OSSL_PROVIDER-legacy(7)>for a list of algorithm names that
+can be fetched.
+
=head1 FETCHING EXAMPLES
The following section provides a series of examples of fetching algorithm
* we're not supplying any particular search criteria for our SHA256
* implementation (second NULL parameter). Any SHA256 implementation will
* do.
+ * In a larger application this fetch would just be done once, and could
+ * be used for multiple calls to other operations such as EVP_DigestInit_ex().
*/
sha256 = EVP_MD_fetch(NULL, "SHA256", NULL);
if (sha256 == NULL)
See also L<OSSL_PROVIDER-default(7)/Message Authentication Code (MAC)>
and L<OSSL_PROVIDER-FIPS(7)/Message Authentication Code (MAC)>.
+=head4 Algorithm Fetching
+
+Using calls to convenience functions such as EVP_sha256() and EVP_aes_256_gcm() may
+incur a performance penalty when using providers.
+Retrieving algorithms from providers involves searching for an algorithm by name.
+This is much slower than directly accessing a method table.
+It is recommended to prefetch algorithms if an algorithm is used many times.
+See L<crypto(7)/Performance>, L<crypto(7)/Explicit fetching> and L<crypto(7)/Implicit fetching>.
+
=head4 Support for Linux Kernel TLS
In order to use KTLS, support for it must be compiled in using the
projects / openssl.git / commitdiff