Add provider pre-fetching documentation

Clearly document that implicit fetching is slower when using providers,
and explain prefetching. Added to crypto.pod and migration_guide.pod
links to it.

Add a link to EVP_default_properties_enable_fips() in crypto.pod.

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from #20354)

doc/man3/EVP_aes_128_gcm.pod

@@ -169,6 +169,13 @@ the XTS "tweak" value.
 
 =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

doc/man3/EVP_aria_128_gcm.pod

@@ -92,6 +92,13 @@ correctly, see the L<EVP_EncryptInit(3)/AEAD Interface> section for details.
 
 =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

doc/man3/EVP_bf_cbc.pod

@@ -37,6 +37,13 @@ Blowfish encryption algorithm in CBC, CFB, ECB and OFB modes respectively.
 
 =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

doc/man3/EVP_blake2b512.pod

@@ -31,6 +31,17 @@ The BLAKE2b algorithm that produces a 512-bit output from a given input.
 
 =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
@@ -41,12 +52,6 @@ details of the B<EVP_MD> structure.
 
 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)>,

doc/man3/EVP_camellia_128_ecb.pod

@@ -75,6 +75,13 @@ Camellia for 128, 192 and 256 bit keys in the following modes: CBC, CFB with
 
 =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

doc/man3/EVP_cast5_cbc.pod

@@ -37,6 +37,13 @@ CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
 
 =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

doc/man3/EVP_chacha20.pod

@@ -40,6 +40,13 @@ L<EVP_EncryptInit(3)/AEAD Interface> section for more information.
 
 =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

doc/man3/EVP_des_cbc.pod

@@ -85,6 +85,13 @@ Triple-DES key wrap according to RFC 3217 Section 3.
 
 =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

doc/man3/EVP_desx_cbc.pod

@@ -29,6 +29,11 @@ implementation.
 
 =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

doc/man3/EVP_idea_cbc.pod

@@ -35,6 +35,13 @@ The IDEA encryption algorithm in CBC, CFB, ECB and OFB modes respectively.
 
 =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

doc/man3/EVP_md2.pod

@@ -24,6 +24,12 @@ The MD2 algorithm which produces a 128-bit output from a given input.
 
 =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
 

doc/man3/EVP_md4.pod

@@ -25,6 +25,12 @@ The MD4 algorithm which produces a 128-bit output from a given input.
 
 =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
 

doc/man3/EVP_md5.pod

@@ -36,6 +36,12 @@ WARNING: this algorithm is not intended for non-SSL usage.
 
 =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
 

doc/man3/EVP_mdc2.pod

@@ -26,6 +26,13 @@ The MDC-2DES algorithm of using MDC-2 with the DES block cipher. It produces a
 
 =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

doc/man3/EVP_rc2_cbc.pod

@@ -51,6 +51,13 @@ functions to set the key length and effective key length.
 
 =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

doc/man3/EVP_rc4.pod

@@ -43,6 +43,13 @@ interface.
 
 =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

doc/man3/EVP_rc5_32_12_16_cbc.pod

@@ -56,6 +56,13 @@ is an int.
 
 =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

doc/man3/EVP_ripemd160.pod

@@ -25,6 +25,13 @@ The RIPEMD-160 algorithm which produces a 160-bit output from a given input.
 
 =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

doc/man3/EVP_seed_cbc.pod

@@ -37,6 +37,13 @@ The SEED encryption algorithm in CBC, CFB, ECB and OFB modes respectively.
 
 =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

doc/man3/EVP_sha1.pod

@@ -25,6 +25,12 @@ The SHA-1 algorithm which produces a 160-bit output from a given input.
 
 =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
 

doc/man3/EVP_sha224.pod

@@ -45,6 +45,12 @@ their outputs are of the same size.
 
 =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
 

doc/man3/EVP_sha3_224.pod

@@ -50,6 +50,12 @@ B<EVP_shake256> provides that of 256 bits.
 
 =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
 

doc/man3/EVP_sm3.pod

@@ -24,6 +24,12 @@ The SM3 hash function.
 
 =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
 

doc/man3/EVP_sm4_cbc.pod

@@ -41,6 +41,13 @@ respectively.
 
 =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

doc/man3/EVP_whirlpool.pod

@@ -26,6 +26,12 @@ input.
 
 =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