From: Matt Caswell Date: Thu, 27 Aug 2020 11:52:17 +0000 (+0100) Subject: Update the EVP_PKEY MAC documentation X-Git-Tag: openssl-3.0.0-alpha7~410 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=820d87bc98c254bb36c46891f3fe4e55bd47f2e7;p=thirdparty%2Fopenssl.git Update the EVP_PKEY MAC documentation Include more information about the new HMAC parameter. Also fill in some missing documentation about the EVP_PKEY MAC bridge. Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/12732) --- diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod index f0061f45482..f90fb2754f0 100644 --- a/doc/man3/EVP_DigestVerifyInit.pod +++ b/doc/man3/EVP_DigestVerifyInit.pod @@ -93,7 +93,7 @@ Support no digests (the digest B must be NULL) Supports any digest -=item CMAC, Poly1305 and SipHash +=item CMAC, Poly1305 and Siphash Will ignore any digest provided. diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod index 9e35d57c17b..dc90ee54217 100644 --- a/doc/man3/EVP_MAC.pod +++ b/doc/man3/EVP_MAC.pod @@ -248,6 +248,21 @@ EVP_MAC_final() should produce. The allowed sizes vary between MAC implementations, but must never exceed what can be given with a B. +=item "tls-data-size" (B) + +This parameter is only supported by HMAC. If set then special handling is +activated for calculating the MAC of a received mac-then-encrypt TLS record +where variable length record padding has been used (as in the case of CBC mode +ciphersuites). The value represents the total length of the record that is +having the MAC calculated including the received MAC and the record padding. + +When used EVP_MAC_update must be called precisely twice. The first time with +the 13 bytes of TLS "header" data, and the second time with the entire record +including the MAC itself and any padding. The entire record length must equal +the value passed in the "tls-data-size" parameter. The length passed in the +B parameter to EVP_MAC_update() should be equal to the length of the +record after the MAC and any padding has been removed. + =back All these parameters should be used before the calls to any of diff --git a/doc/man7/EVP_MAC-HMAC.pod b/doc/man7/EVP_MAC-HMAC.pod index 7f0ec35b43d..45ccd172112 100644 --- a/doc/man7/EVP_MAC-HMAC.pod +++ b/doc/man7/EVP_MAC-HMAC.pod @@ -36,6 +36,8 @@ The following parameter can be set with EVP_MAC_CTX_set_params(): =item "properties" (B) +=item "tls-data-size" (B) + =back The "flags" parameter is passed directly to HMAC_CTX_set_flags(). diff --git a/doc/man7/EVP_MAC-Siphash.pod b/doc/man7/EVP_MAC-Siphash.pod index d8013b33691..8b610c43831 100644 --- a/doc/man7/EVP_MAC-Siphash.pod +++ b/doc/man7/EVP_MAC-Siphash.pod @@ -2,11 +2,11 @@ =head1 NAME -EVP_MAC-Siphash - The SipHash EVP_MAC implementation +EVP_MAC-Siphash - The Siphash EVP_MAC implementation =head1 DESCRIPTION -Support for computing SipHash MACs through the B API. +Support for computing Siphash MACs through the B API. =head2 Identity diff --git a/doc/man7/EVP_PKEY-HMAC.pod b/doc/man7/EVP_PKEY-HMAC.pod index 7b6c52bb031..84b647e5305 100644 --- a/doc/man7/EVP_PKEY-HMAC.pod +++ b/doc/man7/EVP_PKEY-HMAC.pod @@ -2,22 +2,22 @@ =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-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 +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. +L, L, +L or L. =head2 Common MAC parameters diff --git a/doc/man7/EVP_SIGNATURE-HMAC.pod b/doc/man7/EVP_SIGNATURE-HMAC.pod index dd74fae88c2..6628d9ebc2b 100644 --- a/doc/man7/EVP_SIGNATURE-HMAC.pod +++ b/doc/man7/EVP_SIGNATURE-HMAC.pod @@ -2,7 +2,7 @@ =head1 NAME -EVP_SIGNATURE-HMAC, EVP_SIGNATURE-SIPHASH, EVP_SIGNATURE-POLY1305, +EVP_SIGNATURE-HMAC, EVP_SIGNATURE-Siphash, EVP_SIGNATURE-Poly1305, EVP_SIGNATURE-CMAC - The legacy B MAC signature implementations @@ -12,21 +12,29 @@ 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. +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. +The same signature parameters can be set using EVP_PKEY_CTX_set_params() as can +be set via EVP_MAC_CTX_set_params() for the underlying EVP_MAC. See +L, L, L and +L for details. + + 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, L, +L, +L, +L, +L, L, =head1 COPYRIGHT diff --git a/doc/man7/OSSL_PROVIDER-FIPS.pod b/doc/man7/OSSL_PROVIDER-FIPS.pod index fc9c191855f..d404716b235 100644 --- a/doc/man7/OSSL_PROVIDER-FIPS.pod +++ b/doc/man7/OSSL_PROVIDER-FIPS.pod @@ -120,6 +120,12 @@ This has the property "provider=fips,fips=no" =item DSA, see L +=item RSA, see L + +=item HMAC, see L + +=item CMAC, see L + =back =head2 Asymmetric Cipher diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod index 0b477b56c1a..a88c0be6e63 100644 --- a/doc/man7/OSSL_PROVIDER-default.pod +++ b/doc/man7/OSSL_PROVIDER-default.pod @@ -164,6 +164,14 @@ The OpenSSL default provider supports these operations and algorithms: =item RSA, see L +=item HMAC, see L + +=item SIPHASH, see L + +=item POLY1305, see L + +=item CMAC, see L + =back =head2 Asymmetric Cipher