From e798248c8461893ba29d97410b7c0dcecbf23d82 Mon Sep 17 00:00:00 2001 From: slontis Date: Wed, 22 Feb 2023 10:11:33 +1000 Subject: [PATCH] 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 Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/20354) --- doc/man3/EVP_aes_128_gcm.pod | 7 ++++ doc/man3/EVP_aria_128_gcm.pod | 7 ++++ doc/man3/EVP_bf_cbc.pod | 7 ++++ doc/man3/EVP_blake2b512.pod | 17 +++++--- doc/man3/EVP_camellia_128_ecb.pod | 7 ++++ doc/man3/EVP_cast5_cbc.pod | 7 ++++ doc/man3/EVP_chacha20.pod | 7 ++++ doc/man3/EVP_des_cbc.pod | 7 ++++ doc/man3/EVP_desx_cbc.pod | 5 +++ doc/man3/EVP_idea_cbc.pod | 7 ++++ doc/man3/EVP_md2.pod | 6 +++ doc/man3/EVP_md4.pod | 6 +++ doc/man3/EVP_md5.pod | 6 +++ doc/man3/EVP_mdc2.pod | 7 ++++ doc/man3/EVP_rc2_cbc.pod | 7 ++++ doc/man3/EVP_rc4.pod | 7 ++++ doc/man3/EVP_rc5_32_12_16_cbc.pod | 7 ++++ doc/man3/EVP_ripemd160.pod | 7 ++++ doc/man3/EVP_seed_cbc.pod | 7 ++++ doc/man3/EVP_sha1.pod | 6 +++ doc/man3/EVP_sha224.pod | 6 +++ doc/man3/EVP_sha3_224.pod | 6 +++ doc/man3/EVP_sm3.pod | 6 +++ doc/man3/EVP_sm4_cbc.pod | 7 ++++ doc/man3/EVP_whirlpool.pod | 6 +++ doc/man7/crypto.pod | 70 ++++++++++++++++++++++++++++++- doc/man7/migration_guide.pod | 9 ++++ 27 files changed, 246 insertions(+), 8 deletions(-) diff --git a/doc/man3/EVP_aes_128_gcm.pod b/doc/man3/EVP_aes_128_gcm.pod index 0575901503..a8c1d06b00 100644 --- a/doc/man3/EVP_aes_128_gcm.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_aria_128_gcm.pod b/doc/man3/EVP_aria_128_gcm.pod index 6471acb249..a05c3346c1 100644 --- a/doc/man3/EVP_aria_128_gcm.pod +++ b/doc/man3/EVP_aria_128_gcm.pod @@ -92,6 +92,13 @@ correctly, see the L 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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_bf_cbc.pod b/doc/man3/EVP_bf_cbc.pod index 0338562087..89fd5c21a4 100644 --- a/doc/man3/EVP_bf_cbc.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_blake2b512.pod b/doc/man3/EVP_blake2b512.pod index 649a29c987..cc437325d8 100644 --- a/doc/man3/EVP_blake2b512.pod +++ b/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 instead. +See L 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 structure that contains the @@ -41,12 +52,6 @@ details of the B 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, diff --git a/doc/man3/EVP_camellia_128_ecb.pod b/doc/man3/EVP_camellia_128_ecb.pod index 4a57f79512..c70af300e3 100644 --- a/doc/man3/EVP_camellia_128_ecb.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_cast5_cbc.pod b/doc/man3/EVP_cast5_cbc.pod index e823a197f9..c8c1c9dabd 100644 --- a/doc/man3/EVP_cast5_cbc.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_chacha20.pod b/doc/man3/EVP_chacha20.pod index 060b1bfc25..6027a705b8 100644 --- a/doc/man3/EVP_chacha20.pod +++ b/doc/man3/EVP_chacha20.pod @@ -40,6 +40,13 @@ L 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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_des_cbc.pod b/doc/man3/EVP_des_cbc.pod index fe9d5e6a0e..651622df56 100644 --- a/doc/man3/EVP_des_cbc.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_desx_cbc.pod b/doc/man3/EVP_desx_cbc.pod index 01987bf28c..e1b4853425 100644 --- a/doc/man3/EVP_desx_cbc.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_idea_cbc.pod b/doc/man3/EVP_idea_cbc.pod index 2fa5a2925f..d7e0102c18 100644 --- a/doc/man3/EVP_idea_cbc.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_md2.pod b/doc/man3/EVP_md2.pod index 420bb15453..bb01005b87 100644 --- a/doc/man3/EVP_md2.pod +++ b/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 instead. +See L for further information. =head1 RETURN VALUES diff --git a/doc/man3/EVP_md4.pod b/doc/man3/EVP_md4.pod index a3d3beaaf8..682937fa87 100644 --- a/doc/man3/EVP_md4.pod +++ b/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 instead. +See L for further information. =head1 RETURN VALUES diff --git a/doc/man3/EVP_md5.pod b/doc/man3/EVP_md5.pod index 9d729601a0..aec1d8d820 100644 --- a/doc/man3/EVP_md5.pod +++ b/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 instead. +See L for further information. =head1 RETURN VALUES diff --git a/doc/man3/EVP_mdc2.pod b/doc/man3/EVP_mdc2.pod index 7ebed04c70..bc148079f3 100644 --- a/doc/man3/EVP_mdc2.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return a B structure that contains the diff --git a/doc/man3/EVP_rc2_cbc.pod b/doc/man3/EVP_rc2_cbc.pod index e6111ff3af..26966e34bb 100644 --- a/doc/man3/EVP_rc2_cbc.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_rc4.pod b/doc/man3/EVP_rc4.pod index 9deaab97f8..9f8e72c00b 100644 --- a/doc/man3/EVP_rc4.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_rc5_32_12_16_cbc.pod b/doc/man3/EVP_rc5_32_12_16_cbc.pod index 8ac23b4a9e..cbb8d71b8e 100644 --- a/doc/man3/EVP_rc5_32_12_16_cbc.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_ripemd160.pod b/doc/man3/EVP_ripemd160.pod index e559b03449..46eebf846d 100644 --- a/doc/man3/EVP_ripemd160.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return a B structure that contains the diff --git a/doc/man3/EVP_seed_cbc.pod b/doc/man3/EVP_seed_cbc.pod index eef7dd540d..07d03367ed 100644 --- a/doc/man3/EVP_seed_cbc.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return an B structure that contains the diff --git a/doc/man3/EVP_sha1.pod b/doc/man3/EVP_sha1.pod index f3e9e8d4fa..574b9d8ba8 100644 --- a/doc/man3/EVP_sha1.pod +++ b/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 instead. +See L for further information. =head1 RETURN VALUES diff --git a/doc/man3/EVP_sha224.pod b/doc/man3/EVP_sha224.pod index 97881b5463..1062e0c059 100644 --- a/doc/man3/EVP_sha224.pod +++ b/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 instead. +See L for further information. =head1 RETURN VALUES diff --git a/doc/man3/EVP_sha3_224.pod b/doc/man3/EVP_sha3_224.pod index 4c349f55d3..c59b4663ae 100644 --- a/doc/man3/EVP_sha3_224.pod +++ b/doc/man3/EVP_sha3_224.pod @@ -50,6 +50,12 @@ B 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 instead. +See L for further information. =head1 RETURN VALUES diff --git a/doc/man3/EVP_sm3.pod b/doc/man3/EVP_sm3.pod index 96997b1128..56cc25c6f3 100644 --- a/doc/man3/EVP_sm3.pod +++ b/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 instead. +See L for further information. =head1 RETURN VALUES diff --git a/doc/man3/EVP_sm4_cbc.pod b/doc/man3/EVP_sm4_cbc.pod index 51df4435bc..d1400ed347 100644 --- a/doc/man3/EVP_sm4_cbc.pod +++ b/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 instead. +See L for further information. + =head1 RETURN VALUES These functions return a B structure that contains the diff --git a/doc/man3/EVP_whirlpool.pod b/doc/man3/EVP_whirlpool.pod index 3aaf1d50ad..3b008ac990 100644 --- a/doc/man3/EVP_whirlpool.pod +++ b/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 instead. +See L for further information. =head1 RETURN VALUES diff --git a/doc/man7/crypto.pod b/doc/man7/crypto.pod index bcbb170007..f888ef6ac1 100644 --- a/doc/man7/crypto.pod +++ b/doc/man7/crypto.pod @@ -116,7 +116,8 @@ algorithm implementations in the default provider. 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 function. Where both +library context using the L or +L 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. @@ -164,7 +165,7 @@ functions that use them. For example the L function takes as a parameter an B object which may have been returned from an earlier call to L. -=head2 Implicit fetch +=head2 Implicit fetching OpenSSL has a number of functions that return an algorithm object with no associated implementation, such as L, L, @@ -210,6 +211,69 @@ property string from the B. =back +=head2 Performance + +If you perform the same operation many times then it is recommended to use +L to prefetch an algorithm once initially, +and then pass this created object to any operations that are currently +using L. +See an example of Explicit fetching in L. + +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 + +=item L + +=item L + +=item L + +=item L + +=item L + +=item L + +=item L + +=back + +The following methods are used internally when performing operations: + +=over 4 + +=item L + +=item L + +=item L + +=item L + +=back + +See L, and +for a list of algorithm names that +can be fetched. + =head1 FETCHING EXAMPLES The following section provides a series of examples of fetching algorithm @@ -404,6 +468,8 @@ encryption/decryption, signatures, message authentication codes, etc. * 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) diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod index c1d47737c1..bad1eab873 100644 --- a/doc/man7/migration_guide.pod +++ b/doc/man7/migration_guide.pod @@ -209,6 +209,15 @@ All new applications should use the new L interface. See also L and L. +=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, L and L. + =head4 Support for Linux Kernel TLS In order to use KTLS, support for it must be compiled in using the