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 <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14741)

3 files changed, 35 insertions, 19 deletions

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<ctx> flags.  See L</FLAGS> below for more information.
 
+=item EVP_Q_digest() is a quick one-shot digest function.
+It hashes I<count> bytes of data at I<data> using the digest algorithm I<name>,
+which is fetched using the optional I<libctx> and I<propq> parameters.
+The digest value is placed in I<md> and its length is written at I<size>
+if the pointer is not NULL. At most B<EVP_MAX_MD_SIZE> 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<EVP_MD> 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 <openssl/sha.h>
 
+ 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<OPENSSL_API_COMPAT> with a suitable version value, see
 L<openssl_user_macros(7)>:
@@ -18,38 +24,33 @@ L<openssl_user_macros(7)>:
  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<EVP_DigestInit_ex(3)>, L<EVP_DigestUpdate(3)>
-and L<EVP_DigestFinal_ex(3)>.
+and L<EVP_DigestFinal_ex(3)>, or the quick one-shot function L<EVP_Q_digest(3)>.
+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<EVP_Q_digest(3)>,
 L<EVP_DigestInit(3)>
 
 =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.