Document EVP_PKEY_new_CMAC_key(3) in sufficient detail such that readers

stand a chance of using the API correctly.

Admittedly, having so much text below EXAMPLES is somewhat unusual.
While all that information is required to use the function correctly,
strictly speaking, it is not part of the specification of what
EVP_PKEY_new_CMAC_key(3) does, so it woundn't really belong
in the DESCRIPTION.

Now, designing an API function in such a way that using it correctly
requires lots of information about *other* functions and such that
all that additional information does not belong into the manual pages
of those other functions (both because that would cause distractions
in various other manual pages and because it would scatter required
information around lots of different pages) is certainly not stellar
API design.  But we can't help that because these APIs were all
originally designed by OpenSSL.

Significant feedback and OK tb@.

1 files changed, 159 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/EVP_PKEY_new_CMAC_key.3 b/src/lib/libcrypto/man/EVP_PKEY_new_CMAC_key.3
new file mode 100644
index 0000000000..d09af3a012
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_PKEY_new_CMAC_key.3
@@ -0,0 +1,159 @@
+.\" $OpenBSD: EVP_PKEY_new_CMAC_key.3,v 1.1 2024/11/12 20:00:36 schwarze Exp $
+.\"
+.\" Copyright (c) 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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: November 12 2024 $
+.Dt EVP_PKEY_NEW_CMAC_KEY 3
+.Os
+.Sh NAME
+.Nm EVP_PKEY_new_CMAC_key
+.Nd CMAC in the EVP framework
+.Sh SYNOPSIS
+.In openssl/evp.h
+.Ft EVP_PKEY *
+.Fo EVP_PKEY_new_CMAC_key
+.Fa "ENGINE *engine"
+.Fa "const unsigned char *key"
+.Fa "size_t key_len"
+.Fa "const EVP_CIPHER *cipher"
+.Fc
+.Sh DESCRIPTION
+.Fn EVP_PKEY_new_CMAC_key
+allocates a new
+.Vt EVP_PKEY
+object, sets its type to
+.Dv EVP_PKEY_CMAC ,
+and configures it as a wrapper around the low-level functions documented in
+.Xr CMAC_Init 3
+using the block
+.Fa cipher
+with the symmetric
+.Fa key
+that is
+.Fa key_len
+bytes long.
+.Pp
+Functions to obtain suitable
+.Vt EVP_CIPHER
+objects are listed in the CIPHER LISTING section of the
+.Xr EVP_EncryptInit 3
+manual page.
+Always use an object that implements the CBC mode of operation.
+As in
+.Xr CMAC_Init 3 ,
+only ciphers with a block size of either 64 or 128 bits
+are supported by this implementation.
+.Pp
+The
+.Fa engine
+argument is ignored; passing
+.Dv NULL
+is recommended.
+.Sh RETURN VALUES
+.Fn EVP_PKEY_new_CMAC_key
+returns the newly allocated
+.Vt EVP_PKEY
+structure or
+.Dv NULL
+if an error occurred.
+.Sh EXAMPLES
+The following code digests a message with AES-CMAC
+using the key length of 128 bits specified in RFC 4493.
+.Bd -literal -offset indent
+/* Bogus key: would normally be set from another source. */
+const unsigned char key[] = "symmetric secret";
+const size_t key_len = strlen(key);  /* 16 = 128/8 */
+
+const char *msg = "Hello World!";
+const size_t msg_len = strlen(msg);
+
+unsigned char out_mac[16];
+size_t out_len = sizeof(out_mac);
+size_t i;
+
+EVP_PKEY *pkey;
+EVP_MD_CTX *md_ctx;
+
+pkey = EVP_PKEY_new_CMAC_key(NULL, key, key_len, EVP_aes_128_cbc());
+if (pkey == NULL)
+        err(1, "EVP_PKEY_new_CMAC_key");
+md_ctx = EVP_MD_CTX_new();
+if (md_ctx == NULL)
+        err(1, "EVP_MD_CTX_new");
+
+if (EVP_DigestSignInit(md_ctx, NULL, NULL, NULL, pkey) == 0)
+        err(1, "EVP_DigestSignInit");
+if (EVP_DigestSign(md_ctx, out_mac, &out_len, msg, msg_len) == 0)
+        err(1, "EVP_DigestSign");
+EVP_MD_CTX_free(md_ctx);
+EVP_PKEY_free(pkey);
+
+printf(" MAC = ");
+for (i = 0; i < out_len; i++)
+        printf("%02x:", out_mac[i]);
+printf("\en");
+.Ed
+.Pp
+Consider the following details:
+.Bl -bullet -width 1n
+.It
+Even though the type name
+.Vt EVP_PKEY
+was originally intended to stand for
+.Dq private key
+and the
+.Xr EVP_DigestSignInit 3
+API was designed for digital signatures in the context
+of public key cryptography, both are also used here because a MAC
+also requires a key, even though that is a symmetric key.
+.It
+In contrast to digital signing which requires both a digest algorithm
+and a private key, the CMAC algorithm only requires a block cipher
+and a shared key, both of which are stored in the somewhat abused
+.Vt EVP_PKEY
+object.
+Consequently, the
+.Vt "EVP_MD *type"
+argument of
+.Xr EVP_DigestSignInit 3
+has to be set to
+.Dv NULL .
+.It
+The size of the resulting message digest equals the block size
+of the used cipher.
+.It
+The function
+.Xr EVP_DigestSignInit 3
+does not transfer ownership of the
+.Fa pkey
+object to
+.Ft md_ctx
+but merely increments the reference count.
+Consequently, the caller is responsible for freeing the
+.Vt EVP_PKEY
+object when it is no longer needed.
+.El
+.Sh SEE ALSO
+.Xr CMAC_Init 3 ,
+.Xr evp 3 ,
+.Xr EVP_DigestSignInit 3 ,
+.Xr EVP_EncryptInit 3 ,
+.Xr EVP_PKEY_new 3
+.Sh STANDARDS
+RFC 4493: The AES-CMAC Algorithm
+.Sh HISTORY
+.Fn EVP_PKEY_new_CMAC_key
+first appeared in OpenSSL 1.1.1 and has been available since
+.Ox 6.9 .