X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FHMAC.pod;h=54db3ad66dbba078ea1943fe8624c738cbaeee03;hp=8cc3df9ab7eb201b25ec52e0c7fa223863085d7b;hb=dbde4726889a19af0a718fe9c5542f39c81acbd3;hpb=e9b77246879071308130cda42336338ddb63cbb4

diff --git a/doc/man3/HMAC.pod b/doc/man3/HMAC.pod
index 8cc3df9ab7..54db3ad66d 100644
--- a/doc/man3/HMAC.pod
+++ b/doc/man3/HMAC.pod
@@ -20,6 +20,10 @@ HMAC_size
 
  #include <openssl/hmac.h>
 
+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)>:
+
  unsigned char *HMAC(const EVP_MD *evp_md, const void *key,
                      int key_len, const unsigned char *d, int n,
                      unsigned char *md, unsigned int *md_len);
@@ -40,15 +44,19 @@ HMAC_size
 
  size_t HMAC_size(const HMAC_CTX *e);
 
-Deprecated:
+Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #if OPENSSL_API_COMPAT < 0x10100000L
  int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len,
                const EVP_MD *md);
- #endif
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated. Applications should
+instead use L<EVP_MAC_CTX_new(3)>, L<EVP_MAC_CTX_free(3)>, L<EVP_MAC_init(3)>,
+L<EVP_MAC_update(3)> and L<EVP_MAC_final(3)>.
+
 HMAC is a MAC (message authentication code), i.e. a keyed hash
 function used for message authentication, which is based on a hash
 function.
@@ -63,11 +71,13 @@ If B<md> is NULL, the digest is placed in a static array.  The size of
 the output is placed in B<md_len>, unless it is B<NULL>. Note: passing a NULL
 value for B<md>  to use the static array is not thread safe.
 
-B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc.
+B<evp_md> is a message digest such as EVP_sha1(), EVP_ripemd160() etc. HMAC does
+not support variable output length digests such as EVP_shake128() and
+EVP_shake256().
 
 HMAC_CTX_new() creates a new HMAC_CTX in heap memory.
 
-HMAC_CTX_reset() zeroes an existing B<HMAC_CTX> and associated
+HMAC_CTX_reset() clears an existing B<HMAC_CTX> and associated
 resources, making it suitable for new computations as if it was newly
 created with HMAC_CTX_new().
 
@@ -78,23 +88,21 @@ itself.
 The following functions may be used if the message is not completely
 stored in memory:
 
-HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash
-function B<evp_md> and the key B<key> which is B<key_len> bytes
-long. It is deprecated and only included for backward compatibility
-with OpenSSL 0.9.6b.
-
 HMAC_Init_ex() initializes or reuses a B<HMAC_CTX> structure to use the hash
-function B<evp_md> and key B<key>. If both are NULL (or B<evp_md> is the same
-as the previous digest used by B<ctx> and B<key> is NULL) the existing key is
+function B<evp_md> and key B<key>. If both are NULL, or if B<key> is NULL
+and B<evp_md> is the same as the previous call, then the
+existing key is
 reused. B<ctx> must have been created with HMAC_CTX_new() before the first use
-of an B<HMAC_CTX> in this function. B<N.B. HMAC_Init() had this undocumented
-behaviour in previous versions of OpenSSL - failure to switch to HMAC_Init_ex()
-in programs that expect it will cause them to stop working>.
+of an B<HMAC_CTX> in this function.
 
-B<NOTE:> If HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the
+If HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the
 same as the previous digest used by B<ctx> then an error is returned
 because reuse of an existing key with a different digest is not supported.
 
+HMAC_Init() initializes a B<HMAC_CTX> structure to use the hash
+function B<evp_md> and the key B<key> which is B<key_len> bytes
+long.
+
 HMAC_Update() can be called repeatedly with chunks of the message to
 be authenticated (B<len> bytes at B<data>).
 
@@ -138,21 +146,22 @@ L<SHA1(3)>, L<evp(7)>
 
 =head1 HISTORY
 
-HMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL versions 1.1.0.
+All of these functions were deprecated in OpenSSL 3.0.
+
+HMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL 1.1.0.
 
-HMAC_CTX_cleanup() existed in OpenSSL versions before 1.1.0.
+HMAC_CTX_cleanup() existed in OpenSSL before version 1.1.0.
 
-HMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL version
-1.1.0.
+HMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL 1.1.0.
 
 HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in
-versions of OpenSSL before 1.0.0.
+OpenSSL before version 1.0.0.
 
 =head1 COPYRIGHT
 
 Copyright 2000-2016 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>.