From 4d49b68504cc494e552bce8e0b82ec8b501d5abe Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Mon, 29 Mar 2021 19:32:48 +0200 Subject: Crypto: Add deprecation compatibility declarations for SHA* message digest functions Also add hints to SHA256_Init.pod and CHANGES.md how to replace SHA256() etc. Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/14741) --- doc/man3/EVP_DigestInit.pod | 24 +++++++++++++++++++----- doc/man3/SHA256_Init.pod | 28 +++++++++++++++------------- doc/man7/provider-digest.pod | 2 +- 3 files changed, 35 insertions(+), 19 deletions(-) (limited to 'doc') diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod index a405c2be59..4b6aaeeb1c 100644 --- a/doc/man3/EVP_DigestInit.pod +++ b/doc/man3/EVP_DigestInit.pod @@ -10,7 +10,7 @@ EVP_MD_CTX_set_params, EVP_MD_CTX_get_params, EVP_MD_settable_ctx_params, EVP_MD_gettable_ctx_params, EVP_MD_CTX_settable_params, EVP_MD_CTX_gettable_params, EVP_MD_CTX_set_flags, EVP_MD_CTX_clear_flags, EVP_MD_CTX_test_flags, -EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, +EVP_Q_digest, EVP_Digest, EVP_DigestInit_ex2, EVP_DigestInit_ex, EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_DigestFinalXOF, EVP_DigestFinal, EVP_MD_is_a, EVP_MD_name, EVP_MD_description, EVP_MD_number, EVP_MD_names_do_all, EVP_MD_provider, @@ -49,6 +49,9 @@ EVP_MD_do_all_provided void EVP_MD_CTX_clear_flags(EVP_MD_CTX *ctx, int flags); int EVP_MD_CTX_test_flags(const EVP_MD_CTX *ctx, int flags); + int EVP_Q_digest(OSSL_LIB_CTX *libctx, const char *name, const char *propq, + const void *data, size_t count, + unsigned char *md, unsigned int *size); int EVP_Digest(const void *data, size_t count, unsigned char *md, unsigned int *size, const EVP_MD *type, ENGINE *impl); int EVP_DigestInit_ex2(EVP_MD_CTX *ctx, const EVP_MD *type, @@ -216,6 +219,12 @@ as a parameter descriptor. Sets, clears and tests I flags. See L below for more information. +=item EVP_Q_digest() is a quick one-shot digest function. +It hashes I bytes of data at I using the digest algorithm I, +which is fetched using the optional I and I parameters. +The digest value is placed in I and its length is written at I +if the pointer is not NULL. At most B bytes will be written. + =item EVP_Digest() A wrapper around the Digest Init_ex, Update and Final_ex functions. @@ -528,12 +537,16 @@ Returns a pointer to a B for success or NULL for failure. Returns 1 for success or 0 for failure. -=item EVP_DigestInit_ex2(), +=item EVP_Q_digest(), +EVP_Digest(), +EVP_DigestInit_ex2(), EVP_DigestInit_ex(), EVP_DigestUpdate(), -EVP_DigestFinal_ex() +EVP_DigestFinal_ex(), +EVP_DigestFinalXOF(), and +EVP_DigestFinal() -Returns 1 for +return 1 for success and 0 for failure. =item EVP_MD_CTX_ctrl() @@ -698,7 +711,8 @@ The EVP_dss1() function was removed in OpenSSL 1.1.0. The EVP_MD_CTX_set_pkey_ctx() function was added in OpenSSL 1.1.1. -The EVP_DigestInit_ex2(), EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), +The EVP_Q_digest(), EVP_DigestInit_ex2(), +EVP_MD_fetch(), EVP_MD_free(), EVP_MD_up_ref(), EVP_MD_get_params(), EVP_MD_CTX_set_params(), EVP_MD_CTX_get_params(), EVP_MD_gettable_params(), EVP_MD_gettable_ctx_params(), EVP_MD_settable_ctx_params(), EVP_MD_CTX_settable_params() and diff --git a/doc/man3/SHA256_Init.pod b/doc/man3/SHA256_Init.pod index c8ac28de83..ee96cd2381 100644 --- a/doc/man3/SHA256_Init.pod +++ b/doc/man3/SHA256_Init.pod @@ -11,6 +11,12 @@ SHA512_Final - Secure Hash Algorithm #include + unsigned char *SHA1(const void *data, size_t count, unsigned char *md_buf); + unsigned char *SHA224(const void *data, size_t count, unsigned char *md_buf); + unsigned char *SHA256(const void *data, size_t count, unsigned char *md_buf); + unsigned char *SHA384(const void *data, size_t count, unsigned char *md_buf); + unsigned char *SHA512(const void *data, size_t count, unsigned char *md_buf); + Deprecated since OpenSSL 3.0, can be hidden entirely by defining B with a suitable version value, see L: @@ -18,38 +24,33 @@ L: int SHA1_Init(SHA_CTX *c); int SHA1_Update(SHA_CTX *c, const void *data, size_t len); int SHA1_Final(unsigned char *md, SHA_CTX *c); - unsigned char *SHA1(const unsigned char *d, size_t n, - unsigned char *md); int SHA224_Init(SHA256_CTX *c); int SHA224_Update(SHA256_CTX *c, const void *data, size_t len); int SHA224_Final(unsigned char *md, SHA256_CTX *c); - unsigned char *SHA224(const unsigned char *d, size_t n, - unsigned char *md); int SHA256_Init(SHA256_CTX *c); int SHA256_Update(SHA256_CTX *c, const void *data, size_t len); int SHA256_Final(unsigned char *md, SHA256_CTX *c); - unsigned char *SHA256(const unsigned char *d, size_t n, - unsigned char *md); int SHA384_Init(SHA512_CTX *c); int SHA384_Update(SHA512_CTX *c, const void *data, size_t len); int SHA384_Final(unsigned char *md, SHA512_CTX *c); - unsigned char *SHA384(const unsigned char *d, size_t n, - unsigned char *md); int SHA512_Init(SHA512_CTX *c); int SHA512_Update(SHA512_CTX *c, const void *data, size_t len); int SHA512_Final(unsigned char *md, SHA512_CTX *c); - unsigned char *SHA512(const unsigned char *d, size_t n, - unsigned char *md); =head1 DESCRIPTION -All of the functions described on this page are deprecated. +All of the functions described on this page +except for SHA1(), SHA224(), SHA256(), SHA384() and SHA512() are deprecated. Applications should instead use L, L -and L. +and L, or the quick one-shot function L. +SHA1(), SHA224(), SHA256(), SHA384(), and SHA256() +can continue to be used. They can also be replaced by, e.g., + + (EVP_Q_digest(d, n, md, NULL, NULL, "SHA256", NULL) ? md : NULL) SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a 160 bit output. @@ -95,11 +96,12 @@ ANSI X9.30 =head1 SEE ALSO +L, L =head1 HISTORY -All of these functions were deprecated in OpenSSL 3.0. +All of these functions except SHA*() were deprecated in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man7/provider-digest.pod b/doc/man7/provider-digest.pod index e92991afa8..bacdbf4821 100644 --- a/doc/man7/provider-digest.pod +++ b/doc/man7/provider-digest.pod @@ -255,7 +255,7 @@ algorithm. =head1 BUGS -The EVP_Digest() and EVP_DigestFinal_ex() libcrypto API calls do not +The EVP_Q_digest(), EVP_Digest() and EVP_DigestFinal_ex() API calls do not expect the digest size to be larger than EVP_MAX_MD_SIZE. Any algorithm which produces larger digests is unusable with those API calls. -- cgit v1.2.3