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