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