Add a paragraph about HMAC because that algorithm also involves

parameters that can be controlled with EVP_PKEY_CTX_ctrl(3).
But rather than providing a detailed despription, instead
point to what application programs should use instead and explain
why using the control constant directly would be a particularly bad
idea in this case.

1 files changed, 15 insertions, 3 deletions

diff --git a/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3 b/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
index fe70acd03d..137e576c46 100644
--- a/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
+++ b/src/lib/libcrypto/man/EVP_PKEY_CTX_ctrl.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.27 2024/12/06 14:27:49 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_CTX_ctrl.3,v 1.28 2024/12/10 14:54:20 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\" Parts were split out into RSA_pkey_ctx_ctrl(3).
@@ -6,7 +6,7 @@
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2019, 2023 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2019, 2023, 2024 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -69,7 +69,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 6 2024 $
+.Dd $Mdocdate: December 10 2024 $
 .Dt EVP_PKEY_CTX_CTRL 3
 .Os
 .Sh NAME
@@ -484,6 +484,18 @@ and
 .Xr EVP_DigestSign 3
 as usual.
 .El
+.Ss HMAC parameters
+Application programs normally implement HMAC as described in
+.Xr EVP_PKEY_new_raw_private_key 3 .
+While it is possible to instead use
+.Dv EVP_PKEY_CTRL_SET_MAC_KEY
+directly, similar to the above description for CMAC,
+that is strongly discouraged.
+It's essentially what the deprecated function
+.Xr EVP_PKEY_new_mac_key 3
+does internally, and compared to the direct approach with
+.Xr EVP_PKEY_new_raw_private_key 3 ,
+it requires a lot of cumbersome and unnecessary work.
 .Ss Other parameters
 The
 .Fn EVP_PKEY_CTX_set1_id ,