From: Matt Caswell Date: Wed, 10 Dec 2025 10:57:43 +0000 (+0000) Subject: Remove mentions of EVP_MD_meth* from the documentation X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=afe83c9a933dcdc85759a5846762a042e5636a24;p=thirdparty%2Fopenssl.git Remove mentions of EVP_MD_meth* from the documentation With the removal of EVP_MD_meth* we need to update the documentation accordingly. Reviewed-by: Shane Lontis Reviewed-by: Dmitry Belyavskiy (Merged from https://github.com/openssl/openssl/pull/29366) --- diff --git a/doc/build.info b/doc/build.info index 92da1e5757b..ca3b34d8289 100644 --- a/doc/build.info +++ b/doc/build.info @@ -1183,10 +1183,6 @@ DEPEND[html/man3/EVP_MAC.html]=man3/EVP_MAC.pod GENERATE[html/man3/EVP_MAC.html]=man3/EVP_MAC.pod DEPEND[man/man3/EVP_MAC.3]=man3/EVP_MAC.pod GENERATE[man/man3/EVP_MAC.3]=man3/EVP_MAC.pod -DEPEND[html/man3/EVP_MD_meth_new.html]=man3/EVP_MD_meth_new.pod -GENERATE[html/man3/EVP_MD_meth_new.html]=man3/EVP_MD_meth_new.pod -DEPEND[man/man3/EVP_MD_meth_new.3]=man3/EVP_MD_meth_new.pod -GENERATE[man/man3/EVP_MD_meth_new.3]=man3/EVP_MD_meth_new.pod DEPEND[html/man3/EVP_OpenInit.html]=man3/EVP_OpenInit.pod GENERATE[html/man3/EVP_OpenInit.html]=man3/EVP_OpenInit.pod DEPEND[man/man3/EVP_OpenInit.3]=man3/EVP_OpenInit.pod @@ -3353,7 +3349,6 @@ html/man3/EVP_KEM_free.html \ html/man3/EVP_KEYEXCH_free.html \ html/man3/EVP_KEYMGMT.html \ html/man3/EVP_MAC.html \ -html/man3/EVP_MD_meth_new.html \ html/man3/EVP_OpenInit.html \ html/man3/EVP_PBE_CipherInit.html \ html/man3/EVP_PKEY2PKCS8.html \ @@ -4028,7 +4023,6 @@ man/man3/EVP_KEM_free.3 \ man/man3/EVP_KEYEXCH_free.3 \ man/man3/EVP_KEYMGMT.3 \ man/man3/EVP_MAC.3 \ -man/man3/EVP_MD_meth_new.3 \ man/man3/EVP_OpenInit.3 \ man/man3/EVP_PBE_CipherInit.3 \ man/man3/EVP_PKEY2PKCS8.3 \ diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index c7392018bef..14d4f7fa9c1 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -432,9 +432,9 @@ returns B. This function is normally used when setting ASN1 OIDs. =item EVP_MD_CTX_get0_md_data() -Return the digest method private data for the passed B. -The space is allocated by OpenSSL and has the size originally set with -EVP_MD_meth_set_app_datasize(). +Return the digest method private data for the passed B. This +function exists for legacy backward compatibility reasons and always returns +NULL. =item EVP_MD_CTX_get0_md(), EVP_MD_CTX_get1_md() @@ -461,7 +461,8 @@ Returns the update function for I. =item EVP_MD_get_flags() Returns the I flags. Note that these are different from the B -ones. See L for more information. +ones. See the "flags" parameter as documented in L for a +description of the available flags. =item EVP_MD_get_pkey_type() @@ -821,7 +822,6 @@ digest name passed on the command line. =head1 SEE ALSO -L, L, L, L, diff --git a/doc/man3/EVP_MD_meth_new.pod b/doc/man3/EVP_MD_meth_new.pod deleted file mode 100644 index aac8a3a5580..00000000000 --- a/doc/man3/EVP_MD_meth_new.pod +++ /dev/null @@ -1,205 +0,0 @@ -=pod - -=head1 NAME - -EVP_MD_meth_new, EVP_MD_meth_dup, EVP_MD_meth_free, -EVP_MD_meth_set_input_blocksize, -EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize, -EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update, -EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup, -EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize, -EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize, -EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update, -EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup, -EVP_MD_meth_get_ctrl -- Routines to build up legacy EVP_MD methods - -=head1 SYNOPSIS - - #include - -The following functions have been deprecated since OpenSSL 3.0, and can be -hidden entirely by defining B with a suitable version value, -see L: - - EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type); - void EVP_MD_meth_free(EVP_MD *md); - EVP_MD *EVP_MD_meth_dup(const EVP_MD *md); - - int EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize); - int EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize); - int EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize); - int EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags); - int EVP_MD_meth_set_init(EVP_MD *md, int (*init)(EVP_MD_CTX *ctx)); - int EVP_MD_meth_set_update(EVP_MD *md, int (*update)(EVP_MD_CTX *ctx, - const void *data, - size_t count)); - int EVP_MD_meth_set_final(EVP_MD *md, int (*final)(EVP_MD_CTX *ctx, - unsigned char *md)); - int EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to, - const EVP_MD_CTX *from)); - int EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx)); - int EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd, - int p1, void *p2)); - - int EVP_MD_meth_get_input_blocksize(const EVP_MD *md); - int EVP_MD_meth_get_result_size(const EVP_MD *md); - int EVP_MD_meth_get_app_datasize(const EVP_MD *md); - unsigned long EVP_MD_meth_get_flags(const EVP_MD *md); - int (*EVP_MD_meth_get_init(const EVP_MD *md))(EVP_MD_CTX *ctx); - int (*EVP_MD_meth_get_update(const EVP_MD *md))(EVP_MD_CTX *ctx, - const void *data, - size_t count); - int (*EVP_MD_meth_get_final(const EVP_MD *md))(EVP_MD_CTX *ctx, - unsigned char *md); - int (*EVP_MD_meth_get_copy(const EVP_MD *md))(EVP_MD_CTX *to, - const EVP_MD_CTX *from); - int (*EVP_MD_meth_get_cleanup(const EVP_MD *md))(EVP_MD_CTX *ctx); - int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd, - int p1, void *p2); - -=head1 DESCRIPTION - -All of the functions described on this page are deprecated. -Applications should instead use the OSSL_PROVIDER APIs. - -The B type is a structure for digest method implementation. -It can also have associated public/private key signing and verifying -routines. - -EVP_MD_meth_new() creates a new B structure. -These B structures are reference counted. - -EVP_MD_meth_dup() creates a copy of B. - -EVP_MD_meth_free() decrements the reference count for the B structure. -If the reference count drops to 0 then the structure is freed. -If the argument is NULL, nothing is done. - -EVP_MD_meth_set_input_blocksize() sets the internal input block size -for the method B to B bytes. - -EVP_MD_meth_set_result_size() sets the size of the result that the -digest method in B is expected to produce to B bytes. - -The digest method may have its own private data, which OpenSSL will -allocate for it. EVP_MD_meth_set_app_datasize() should be used to -set the size for it to B. - -EVP_MD_meth_set_flags() sets the flags to describe optional -behaviours in the particular B. Several flags can be or'd -together. The available flags are: - -=over 4 - -=item EVP_MD_FLAG_ONESHOT - -This digest method can only handle one block of input. - -=item EVP_MD_FLAG_XOF - -This digest method is an extensible-output function (XOF) and supports -the B control. - -=item EVP_MD_FLAG_DIGALGID_NULL - -When setting up a DigestAlgorithmIdentifier, this flag will have the -parameter set to NULL by default. Use this for PKCS#1. I - -=item EVP_MD_FLAG_DIGALGID_ABSENT - -When setting up a DigestAlgorithmIdentifier, this flag will have the -parameter be left absent by default. I - -=item EVP_MD_FLAG_DIGALGID_CUSTOM - -Custom DigestAlgorithmIdentifier handling via ctrl, with -B as default. I -Currently unused. - -=item EVP_MD_FLAG_FIPS - -This digest method is suitable for use in FIPS mode. -Currently unused. - -=back - -EVP_MD_meth_set_init() sets the digest init function for B. -The digest init function is called by EVP_Digest(), EVP_DigestInit(), -EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit() -and EVP_VerifyInit_ex(). - -EVP_MD_meth_set_update() sets the digest update function for B. -The digest update function is called by EVP_Digest(), EVP_DigestUpdate() and -EVP_SignUpdate(). - -EVP_MD_meth_set_final() sets the digest final function for B. -The digest final function is called by EVP_Digest(), EVP_DigestFinal(), -EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal(). - -EVP_MD_meth_set_copy() sets the function for B to do extra -computations after the method's private data structure has been copied -from one B to another. If all that's needed is to copy -the data, there is no need for this copy function. -Note that the copy function is passed two B, the private -data structure is then available with EVP_MD_CTX_get0_md_data(). -This copy function is called by EVP_MD_CTX_copy() and -EVP_MD_CTX_copy_ex(). - -EVP_MD_meth_set_cleanup() sets the function for B to do extra -cleanup before the method's private data structure is cleaned out and -freed. -Note that the cleanup function is passed a B, the -private data structure is then available with EVP_MD_CTX_get0_md_data(). -This cleanup function is called by EVP_MD_CTX_reset() and -EVP_MD_CTX_free(). - -EVP_MD_meth_set_ctrl() sets the control function for B. -See L for the available controls. - -EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(), -EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(), -EVP_MD_meth_get_init(), EVP_MD_meth_get_update(), -EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(), -EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used -to retrieve the method data given with the EVP_MD_meth_set_*() -functions above. - -=head1 RETURN VALUES - -EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly -created B, or NULL on failure. -All EVP_MD_meth_set_*() functions return 1. -EVP_MD_get_input_blocksize(), EVP_MD_meth_get_result_size(), -EVP_MD_meth_get_app_datasize() and EVP_MD_meth_get_flags() return the -indicated sizes or flags. -All other EVP_MD_meth_get_*() functions return pointers to their -respective B function. - -=head1 SEE ALSO - -L, L, L - -=head1 HISTORY - -All of these functions were deprecated in OpenSSL 3.0. - -The B structure was openly available in OpenSSL before version -1.1. -The functions described here were added in OpenSSL 1.1. -The B structure created with these functions became reference -counted in OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2015-2024 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/man3/EVP_blake2b512.pod b/doc/man3/EVP_blake2b512.pod index 7bf08f6495f..b28d0fcb66f 100644 --- a/doc/man3/EVP_blake2b512.pod +++ b/doc/man3/EVP_blake2b512.pod @@ -44,8 +44,7 @@ but this is only available through L. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_md2.pod b/doc/man3/EVP_md2.pod index a6f3a010deb..cd7d6393cda 100644 --- a/doc/man3/EVP_md2.pod +++ b/doc/man3/EVP_md2.pod @@ -34,8 +34,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_md4.pod b/doc/man3/EVP_md4.pod index a4e1a7d0a6e..354da7c6d18 100644 --- a/doc/man3/EVP_md4.pod +++ b/doc/man3/EVP_md4.pod @@ -35,8 +35,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_md5.pod b/doc/man3/EVP_md5.pod index 42370fb3d0a..ff1f217b797 100644 --- a/doc/man3/EVP_md5.pod +++ b/doc/man3/EVP_md5.pod @@ -46,8 +46,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_mdc2.pod b/doc/man3/EVP_mdc2.pod index 3681bd06a63..0f111f46e8e 100644 --- a/doc/man3/EVP_mdc2.pod +++ b/doc/man3/EVP_mdc2.pod @@ -36,8 +36,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_ripemd160.pod b/doc/man3/EVP_ripemd160.pod index 5b96fd09f85..f29cbf32476 100644 --- a/doc/man3/EVP_ripemd160.pod +++ b/doc/man3/EVP_ripemd160.pod @@ -35,8 +35,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_sha1.pod b/doc/man3/EVP_sha1.pod index 6fc8f07b066..d9ad72ec3b0 100644 --- a/doc/man3/EVP_sha1.pod +++ b/doc/man3/EVP_sha1.pod @@ -35,8 +35,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_sha224.pod b/doc/man3/EVP_sha224.pod index be09e49ee39..8c3a55d4032 100644 --- a/doc/man3/EVP_sha224.pod +++ b/doc/man3/EVP_sha224.pod @@ -55,8 +55,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_sha3_224.pod b/doc/man3/EVP_sha3_224.pod index 93c0d0b9fb1..47b18fc1c40 100644 --- a/doc/man3/EVP_sha3_224.pod +++ b/doc/man3/EVP_sha3_224.pod @@ -60,8 +60,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_sm3.pod b/doc/man3/EVP_sm3.pod index 65be55e88db..89224359b24 100644 --- a/doc/man3/EVP_sm3.pod +++ b/doc/man3/EVP_sm3.pod @@ -34,8 +34,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man3/EVP_whirlpool.pod b/doc/man3/EVP_whirlpool.pod index c5d465b16f0..ef86d28b6cc 100644 --- a/doc/man3/EVP_whirlpool.pod +++ b/doc/man3/EVP_whirlpool.pod @@ -36,8 +36,7 @@ See L for further information. =head1 RETURN VALUES These functions return a B structure that contains the -implementation of the message digest. See L for -details of the B structure. +implementation of the message digest. =head1 CONFORMING TO diff --git a/doc/man7/EVP_MD-common.pod b/doc/man7/EVP_MD-common.pod index 5a6b5b94f79..b5b7ae14940 100644 --- a/doc/man7/EVP_MD-common.pod +++ b/doc/man7/EVP_MD-common.pod @@ -30,17 +30,48 @@ This value can also be retrieved with L. =item "flags" (B) Diverse flags that describe exceptional behaviour for the digest. -These flags are described in L. The length of the "flags" parameter should equal that of an B. -=begin comment +Several flags can be or'd together. The available flags are: -The description of these flags should probably be moved. Also, -EVP_MD_FLAG_FIPS isn't relevant any more. +=over 4 + +=item EVP_MD_FLAG_ONESHOT + +This digest method can only handle one block of input. + +=item EVP_MD_FLAG_XOF + +This digest method is an extensible-output function (XOF) and supports +the B control. + +=item EVP_MD_FLAG_DIGALGID_NULL + +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter set to NULL by default. Use this for PKCS#1. I -=end comment +=item EVP_MD_FLAG_DIGALGID_ABSENT + +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter be left absent by default. I + +=item EVP_MD_FLAG_DIGALGID_CUSTOM + +Custom DigestAlgorithmIdentifier handling via ctrl, with +B as default. I +Currently unused. + +=item EVP_MD_FLAG_FIPS + +This digest method is suitable for use in FIPS mode. +Currently unused. + +=back This value can also be retrieved with L. diff --git a/doc/man7/fips_module.pod b/doc/man7/fips_module.pod index c163120a0e7..a5c9863150b 100644 --- a/doc/man7/fips_module.pod +++ b/doc/man7/fips_module.pod @@ -32,8 +32,7 @@ Low level cryptographic APIs (use the high level APIs, such as EVP, instead) =item * Any functions that create or modify custom "METHODS" (for example -EVP_MD_meth_new(), EVP_PKEY_meth_new(), RSA_meth_new(), EC_KEY_METHOD_new(), -etc.) +EVP_PKEY_meth_new(), RSA_meth_new(), EC_KEY_METHOD_new(), etc.) =back diff --git a/doc/man7/ossl-guide-migration.pod b/doc/man7/ossl-guide-migration.pod index c615f239223..6f8552f9f5a 100644 --- a/doc/man7/ossl-guide-migration.pod +++ b/doc/man7/ossl-guide-migration.pod @@ -160,7 +160,7 @@ more information about providers. The refactoring to support Providers conflicts internally with the APIs used to support engines, including the ENGINE API and any function that creates or -modifies custom "METHODS" (for example L, +modifies custom "METHODS" (for example EVP_MD_meth_new(), EVP_CIPHER_meth_new(), L, L, L, etc.). These functions are being deprecated in OpenSSL 3.0, and users of these APIs should know that their use can likely