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 43aca065f0d285ed98d4d5a197bd792d52b3afa4..87a567242f60fad579a8b42a7a445e8732db7aa4 100644 (file)
--- 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 d8c9b98107ba4e098dacd37017d0cf6311e1948b..75c8ed700c898cd0222b8500f13993455a40d790 100644 (file)
--- 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