Raise an error on syscall failure in tls_retry_write_records

[openssl.git] / doc / man3 / SHA256_Init.pod

diff --git a/doc/man3/SHA256_Init.pod b/doc/man3/SHA256_Init.pod
index 6a8f2fa0db0eb2422bd223607b15245476edcac5..3d647c381b4e5513b43a28c2b1797c22b5761c51 100644 (file)
--- a/doc/man3/SHA256_Init.pod
+++ b/doc/man3/SHA256_Init.pod
@@ -11,41 +11,46 @@ SHA512_Final - Secure Hash Algorithm
 
  #include <openssl/sha.h>
 
+ unsigned char *SHA1(const unsigned char *data, size_t count, unsigned char *md_buf);
+ unsigned char *SHA224(const unsigned char *data, size_t count, unsigned char *md_buf);
+ unsigned char *SHA256(const unsigned char *data, size_t count, unsigned char *md_buf);
+ unsigned char *SHA384(const unsigned char *data, size_t count, unsigned char *md_buf);
+ unsigned char *SHA512(const unsigned char *data, size_t count, unsigned char *md_buf);
+
+The following functions have been deprecated since OpenSSL 3.0, and can be
+hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
+see 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
 
-Applications should use the higher level functions
-L<EVP_DigestInit(3)> etc. instead of calling the hash
-functions directly.
+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)>, 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.
@@ -75,9 +80,6 @@ SHA512_DIGEST_LENGTH). Also note that, as for the SHA1() function above, the
 SHA224(), SHA256(), SHA384() and SHA512() functions are not thread safe if
 B<md> is NULL.
 
-The predecessor of SHA-1, SHA, is also implemented, but it should be
-used only when backward compatibility is required.
-
 =head1 RETURN VALUES
 
 SHA1(), SHA224(), SHA256(), SHA384() and SHA512() return a pointer to the hash
@@ -94,13 +96,18 @@ ANSI X9.30
 
 =head1 SEE ALSO
 
+L<EVP_Q_digest(3)>,
 L<EVP_DigestInit(3)>
 
+=head1 HISTORY
+
+All of these functions except SHA*() were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+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<https://www.openssl.org/source/license.html>.