From: Matt Caswell Date: Mon, 17 Aug 2020 16:25:37 +0000 (+0100) Subject: Add some documentation about the EVP_PKEY MAC interface X-Git-Tag: openssl-3.0.0-alpha7~445 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=52ae0f8fc23570b6b7cc98d1cb0d6f6dd53ea98a;p=thirdparty%2Fopenssl.git Add some documentation about the EVP_PKEY MAC interface Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/12637) --- diff --git a/doc/man3/EVP_PKEY_new.pod b/doc/man3/EVP_PKEY_new.pod index c008cfff404..05436007047 100644 --- a/doc/man3/EVP_PKEY_new.pod +++ b/doc/man3/EVP_PKEY_new.pod @@ -104,9 +104,9 @@ EVP_PKEY_new_raw_private_key() except it is only for the B algorithm type. In addition to the raw private key data, it also takes a cipher algorithm to be used during creation of a CMAC in the I argument. The cipher should be a standard encryption only cipher. For example AEAD and XTS -ciphers should not be used. Finally it also take a library context I -and property query I used when fetching any cryptographic algorithms -which may be NULL to use the default values. +ciphers should not be used. Finally it also takes a library context I +and property query I which are used when fetching any cryptographic +algorithms which may be NULL to use the default values. EVP_PKEY_new_CMAC_key() is the same as EVP_PKEY_new_CMAC_key_with_libctx() except that the default values are used for I and I. @@ -172,7 +172,7 @@ EVP_PKEY_get_raw_public_key() functions were added in OpenSSL 1.1.1. The EVP_PKEY_new_raw_private_key_with_libctx(), EVP_PKEY_new_raw_public_key_with_libctx() and -EVP_PKEY_new_CMAC_key_with_libctx()functions were added in OpenSSL 3.0. +EVP_PKEY_new_CMAC_key_with_libctx() functions were added in OpenSSL 3.0. =head1 COPYRIGHT diff --git a/doc/man7/EVP_PKEY-HMAC.pod b/doc/man7/EVP_PKEY-HMAC.pod new file mode 100644 index 00000000000..7b6c52bb031 --- /dev/null +++ b/doc/man7/EVP_PKEY-HMAC.pod @@ -0,0 +1,95 @@ +=pod + +=head1 NAME + +EVP_PKEY-HMAC, EVP_KEYMGMT-HMAC, EVP_PKEY-SIPHASH, EVP_KEYMGMT-SIPHASH, +EVP_PKEY-POLY1305, EVP_KEYMGMT-POLY1305, EVP_PKEY-CMAC, EVP_KEYMGMT-CMAC +- EVP_PKEY legacy MAC keytypes and algorithm support + +=head1 DESCRIPTION + +The B and B key types are implemented in OpenSSL's default and FIPS +providers. Additionally the B and B key types are implemented +in the default provider. Performing MAC operations via an EVP_PKEY +is considered legacy and are only available for backwards compatibility purposes +and for a restricted set of algorithms. The preferred way of performing MAC +operations is via the EVP_MAC APIs. See L. + +For further details on using EVP_PKEY based MAC keys see +L, L, +L or L. + +=head2 Common MAC parameters + +All the B keytypes support the following parameters. + +=over 4 + +=item "priv" (B) + +The MAC key value. + +=item "properties" (B) + +A property query string to be used when any algorithms are fetched. + +=back + +=head2 CMAC parameters + +As well as the parameters described above, the B keytype additionally +supports the following parameters. + +=over 4 + +=item "cipher" (B) + +The name of a cipher to be used when generating the MAC. + +=item "engine" (B) + +The name of an engine to be used for the specified cipher (if any). + +=back + +=head2 Common MAC key generation parameters + +MAC key generation is unusual in that no new key is actually generated. Instead +a new provider side key object is created with the supplied raw key value. This +is done for backwards compatibility with previous versions of OpenSSL. + +=over 4 + +=item "priv" (B) + +The MAC key value. + +=back + +=head2 CMAC key generation parameters + +In addition to the common MAC key generation parameters, the CMAC key generation +additionally recognises the following. + +=over 4 + +=item "cipher" (B) + +The name of a cipher to be used when generating the MAC. + +=back + +=head1 SEE ALSO + +L, L, L + +=head1 COPYRIGHT + +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man7/EVP_SIGNATURE-HMAC.pod b/doc/man7/EVP_SIGNATURE-HMAC.pod new file mode 100644 index 00000000000..dd74fae88c2 --- /dev/null +++ b/doc/man7/EVP_SIGNATURE-HMAC.pod @@ -0,0 +1,41 @@ +=pod + +=head1 NAME + +EVP_SIGNATURE-HMAC, EVP_SIGNATURE-SIPHASH, EVP_SIGNATURE-POLY1305, +EVP_SIGNATURE-CMAC +- The legacy B MAC signature implementations + +=head1 DESCRIPTION + +The algorithms described here have legacy support for creating MACs using +L and related functions. This is not the preferred way of +creating MACs. Instead you should use the newer L functions. +This mechanism is provided for backwards compatibility with older versions of +OpenSSL. + +There are no parameters supported by the legacy EVP_PKEY MAC signature +algorithms. See L, L, +L or L for details about parameters that +are supported during the creation of an EVP_PKEY. + +=head1 SEE ALSO + +L, +L, +L, +L, +L, +L, +L, + +=head1 COPYRIGHT + +Copyright 2020 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut