1.\" $OpenBSD: EVP_PKEY_new_CMAC_key.3,v 1.1 2024/11/12 20:00:36 schwarze Exp $
2.\"
3.\" Copyright (c) 2024 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: November 12 2024 $
18.Dt EVP_PKEY_NEW_CMAC_KEY 3
19.Os
20.Sh NAME
21.Nm EVP_PKEY_new_CMAC_key
22.Nd CMAC in the EVP framework
23.Sh SYNOPSIS
24.In openssl/evp.h
25.Ft EVP_PKEY *
26.Fo EVP_PKEY_new_CMAC_key
27.Fa "ENGINE *engine"
28.Fa "const unsigned char *key"
29.Fa "size_t key_len"
30.Fa "const EVP_CIPHER *cipher"
31.Fc
32.Sh DESCRIPTION
33.Fn EVP_PKEY_new_CMAC_key
34allocates a new
35.Vt EVP_PKEY
36object, sets its type to
37.Dv EVP_PKEY_CMAC ,
38and configures it as a wrapper around the low-level functions documented in
39.Xr CMAC_Init 3
40using the block
41.Fa cipher
42with the symmetric
43.Fa key
44that is
45.Fa key_len
46bytes long.
47.Pp
48Functions to obtain suitable
49.Vt EVP_CIPHER
50objects are listed in the CIPHER LISTING section of the
51.Xr EVP_EncryptInit 3
52manual page.
53Always use an object that implements the CBC mode of operation.
54As in
55.Xr CMAC_Init 3 ,
56only ciphers with a block size of either 64 or 128 bits
57are supported by this implementation.
58.Pp
59The
60.Fa engine
61argument is ignored; passing
62.Dv NULL
63is recommended.
64.Sh RETURN VALUES
65.Fn EVP_PKEY_new_CMAC_key
66returns the newly allocated
67.Vt EVP_PKEY
68structure or
69.Dv NULL
70if an error occurred.
71.Sh EXAMPLES
72The following code digests a message with AES-CMAC
73using the key length of 128 bits specified in RFC 4493.
74.Bd -literal -offset indent
75/* Bogus key: would normally be set from another source. */
76const unsigned char key[] = "symmetric secret";
77const size_t key_len = strlen(key);  /* 16 = 128/8 */
78
79const char *msg = "Hello World!";
80const size_t msg_len = strlen(msg);
81
82unsigned char out_mac[16];
83size_t out_len = sizeof(out_mac);
84size_t i;
85
86EVP_PKEY *pkey;
87EVP_MD_CTX *md_ctx;
88
89pkey = EVP_PKEY_new_CMAC_key(NULL, key, key_len, EVP_aes_128_cbc());
90if (pkey == NULL)
91	err(1, "EVP_PKEY_new_CMAC_key");
92md_ctx = EVP_MD_CTX_new();
93if (md_ctx == NULL)
94	err(1, "EVP_MD_CTX_new");
95
96if (EVP_DigestSignInit(md_ctx, NULL, NULL, NULL, pkey) == 0)
97	err(1, "EVP_DigestSignInit");
98if (EVP_DigestSign(md_ctx, out_mac, &out_len, msg, msg_len) == 0)
99	err(1, "EVP_DigestSign");
100EVP_MD_CTX_free(md_ctx);
101EVP_PKEY_free(pkey);
102
103printf(" MAC = ");
104for (i = 0; i < out_len; i++)
105	printf("%02x:", out_mac[i]);
106printf("\en");
107.Ed
108.Pp
109Consider the following details:
110.Bl -bullet -width 1n
111.It
112Even though the type name
113.Vt EVP_PKEY
114was originally intended to stand for
115.Dq private key
116and the
117.Xr EVP_DigestSignInit 3
118API was designed for digital signatures in the context
119of public key cryptography, both are also used here because a MAC
120also requires a key, even though that is a symmetric key.
121.It
122In contrast to digital signing which requires both a digest algorithm
123and a private key, the CMAC algorithm only requires a block cipher
124and a shared key, both of which are stored in the somewhat abused
125.Vt EVP_PKEY
126object.
127Consequently, the
128.Vt "EVP_MD *type"
129argument of
130.Xr EVP_DigestSignInit 3
131has to be set to
132.Dv NULL .
133.It
134The size of the resulting message digest equals the block size
135of the used cipher.
136.It
137The function
138.Xr EVP_DigestSignInit 3
139does not transfer ownership of the
140.Fa pkey
141object to
142.Ft md_ctx
143but merely increments the reference count.
144Consequently, the caller is responsible for freeing the
145.Vt EVP_PKEY
146object when it is no longer needed.
147.El
148.Sh SEE ALSO
149.Xr CMAC_Init 3 ,
150.Xr evp 3 ,
151.Xr EVP_DigestSignInit 3 ,
152.Xr EVP_EncryptInit 3 ,
153.Xr EVP_PKEY_new 3
154.Sh STANDARDS
155RFC 4493: The AES-CMAC Algorithm
156.Sh HISTORY
157.Fn EVP_PKEY_new_CMAC_key
158first appeared in OpenSSL 1.1.1 and has been available since
159.Ox 6.9 .
160