From: slontis <shane.lontis@oracle.com>
Date: Wed, 7 Dec 2022 22:16:03 +0000 (+1000)
Subject: Update HMAC() documentation.
X-Git-Tag: openssl-3.2.0-alpha1~1578
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d1ebd99397e18de367918c201c25c389f1f07005;p=thirdparty%2Fopenssl.git

Update HMAC() documentation.

Fixes #19782

Clarify that EVP_Q_MAC() can be used as an alternative that allows
setting of the libctx.

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19855)
---

diff --git a/doc/man3/HMAC.pod b/doc/man3/HMAC.pod
index 43aca065f0d..87a567242f6 100644
--- a/doc/man3/HMAC.pod
+++ b/doc/man3/HMAC.pod
@@ -71,6 +71,9 @@ I<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() uses the default B<OSSL_LIB_CTX>.
+Use L<EVP_Q_mac(3)> instead if a library context is required.
+
 All of the functions described below 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)>
diff --git a/doc/man7/migration_guide.pod b/doc/man7/migration_guide.pod
index d8c9b98107b..75c8ed700c8 100644
--- a/doc/man7/migration_guide.pod
+++ b/doc/man7/migration_guide.pod
@@ -1074,7 +1074,8 @@ See L<EVP_MAC(3)>, L<EVP_MAC-HMAC(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
 L<EVP_MAC-KMAC(7)>, L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-Poly1305(7)> and
 L<EVP_MAC-Siphash(7)> for additional information.
 
-Note that the one-shot method HMAC() is still available for compatibility purposes.
+Note that the one-shot method HMAC() is still available for compatibility purposes,
+but this can also be replaced by using EVP_Q_MAC if a library context is required.
 
 =head4 Deprecated low-level validation functions