1=pod
2
3=head1 NAME
4
5EVP_PKEY-HMAC, EVP_KEYMGMT-HMAC, EVP_PKEY-Siphash, EVP_KEYMGMT-Siphash,
6EVP_PKEY-Poly1305, EVP_KEYMGMT-Poly1305, EVP_PKEY-CMAC, EVP_KEYMGMT-CMAC
7- EVP_PKEY legacy MAC keytypes and algorithm support
8
9=head1 DESCRIPTION
10
11The B<HMAC> and B<CMAC> key types are implemented in OpenSSL's default and FIPS
12providers. Additionally the B<Siphash> and B<Poly1305> key types are implemented
13in the default provider. Performing MAC operations via an EVP_PKEY
14is considered legacy and are only available for backwards compatibility purposes
15and for a restricted set of algorithms. The preferred way of performing MAC
16operations is via the EVP_MAC APIs. See L<EVP_MAC_init(3)>.
17
18For further details on using EVP_PKEY based MAC keys see
19L<EVP_SIGNATURE-HMAC(7)>, L<EVP_SIGNATURE-Siphash(7)>,
20L<EVP_SIGNATURE-Poly1305(7)> or L<EVP_SIGNATURE-CMAC(7)>.
21
22=head2 Common MAC parameters
23
24All the B<MAC> keytypes support the following parameters.
25
26=over 4
27
28=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
29
30The MAC key value.
31
32=item "properties" (B<OSSL_PKEY_PARAM_PROPERTIES>) <UTF8 string>
33
34A property query string to be used when any algorithms are fetched.
35
36=back
37
38=head2 CMAC parameters
39
40As well as the parameters described above, the B<CMAC> keytype additionally
41supports the following parameters.
42
43=over 4
44
45=item "cipher" (B<OSSL_PKEY_PARAM_CIPHER>) <UTF8 string>
46
47The name of a cipher to be used when generating the MAC.
48
49=item "engine" (B<OSSL_PKEY_PARAM_ENGINE>) <UTF8 string>
50
51The name of an engine to be used for the specified cipher (if any).
52
53=back
54
55=head2 Common MAC key generation parameters
56
57MAC key generation is unusual in that no new key is actually generated. Instead
58a new provider side key object is created with the supplied raw key value. This
59is done for backwards compatibility with previous versions of OpenSSL.
60
61=over 4
62
63=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
64
65The MAC key value.
66
67=back
68
69=head2 CMAC key generation parameters
70
71In addition to the common MAC key generation parameters, the CMAC key generation
72additionally recognises the following.
73
74=over 4
75
76=item "cipher" (B<OSSL_PKEY_PARAM_CIPHER>) <UTF8 string>
77
78The name of a cipher to be used when generating the MAC.
79
80=back
81
82=head1 SEE ALSO
83
84L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>
85
86=head1 COPYRIGHT
87
88Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
89
90Licensed under the Apache License 2.0 (the "License").  You may not use
91this file except in compliance with the License.  You can obtain a copy
92in the file LICENSE in the source distribution or at
93L<https://www.openssl.org/source/license.html>.
94
95=cut
96