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 <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/12732)

diff --git a/doc/man3/EVP_DigestVerifyInit.pod b/doc/man3/EVP_DigestVerifyInit.pod
index f0061f45482421aed005cd8778fbd40fe7c0dbeb..f90fb2754f0a1ce3cf37e7d719adbe11b355f07b 100644 (file)
--- a/doc/man3/EVP_DigestVerifyInit.pod
+++ b/doc/man3/EVP_DigestVerifyInit.pod
@@ -93,7 +93,7 @@ Support no digests (the digest B<type> 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 9e35d57c17bc84d1463bf47b79ca86cb4028fc87..dc90ee5421738af3291572b9464ab929f57eb106 100644 (file)
--- 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<size_t>.
 
+=item "tls-data-size" (B<OSSL_MAC_PARAM_TLS_DATA_SIZE>) <unsigned integer>
+
+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<datalen> 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 7f0ec35b43ddaa273478d370cfc5a97a4c63ab2b..45ccd17211216463948e66a01f73de1d32885507 100644 (file)
--- 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<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
 
+=item "tls-data-size" (B<OSSL_MAC_PARAM_TLS_DATA_SIZE>) <unsigned integer>
+
 =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 d8013b33691b702dfd851863384a8bf40c6d7b05..8b610c43831924a8c83577603194f7b81687f91d 100644 (file)
--- 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<EVP_MAC> API.
+Support for computing Siphash MACs through the B<EVP_MAC> API.
 
 =head2 Identity
 

diff --git a/doc/man7/EVP_PKEY-HMAC.pod b/doc/man7/EVP_PKEY-HMAC.pod
index 7b6c52bb031dfd1fe3b24b2445cad2d5621d2224..84b647e53055150079732bd2cbc6780a9eace53a 100644 (file)
--- 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<HMAC> and B<CMAC> key types are implemented in OpenSSL's default and FIPS
-providers. Additionally the B<SIPHASH> and B<POLY1305> key types are implemented
+providers. Additionally the B<Siphash> and B<Poly1305> 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<EVP_MAC_init(3)>.
 
 For further details on using EVP_PKEY based MAC keys see
-L<EVP_SIGNATURE-HMAC(7)>, L<EVP_SIGNATURE-SIPHASH(7)>,
-L<EVP_SIGNATURE-POLY1305(7)> or L<EVP_SIGNATURE-CMAC(7)>.
+L<EVP_SIGNATURE-HMAC(7)>, L<EVP_SIGNATURE-Siphash(7)>,
+L<EVP_SIGNATURE-Poly1305(7)> or L<EVP_SIGNATURE-CMAC(7)>.
 
 =head2 Common MAC parameters
 

diff --git a/doc/man7/EVP_SIGNATURE-HMAC.pod b/doc/man7/EVP_SIGNATURE-HMAC.pod
index dd74fae88c2a38b48a94550231de35679f56425a..6628d9ebc2bcfecd474074ddc932741b3340a711 100644 (file)
--- 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<EVP_PKEY> MAC signature implementations
 
@@ -12,21 +12,29 @@ The algorithms described here have legacy support for creating MACs using
 L<EVP_DigestSignInit(3)> and related functions. This is not the preferred way of
 creating MACs. Instead you should use the newer L<EVP_MAC_init(3)> 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<EVP_PKEY-HMAC(7)>, L<EVP_PKEY-SIPHASH(7)>,
-L<EVP_PKEY-POLY1305(7)> or L<EVP_PKEY-CMAC(7)> 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<EVP_MAC-HMAC(7)>, L<EVP_MAC-Siphash(7)>, L<EVP_MAC-Poly1305(7)> and
+L<EVP_MAC-CMAC(7)> for details.
+
+ See L<EVP_PKEY-HMAC(7)>, L<EVP_PKEY-Siphash(7)>, L<EVP_PKEY-Poly1305(7)> or
+ L<EVP_PKEY-CMAC(7)> for details about parameters that are supported during the
+ creation of an EVP_PKEY.
 
 =head1 SEE ALSO
 
 L<EVP_MAC_init(3)>,
 L<EVP_DigestSignInit(3)>,
 L<EVP_PKEY-HMAC(7)>,
-L<EVP_PKEY-SIPHASH(7)>,
-L<EVP_PKEY-POLY1305(7)>,
+L<EVP_PKEY-Siphash(7)>,
+L<EVP_PKEY-Poly1305(7)>,
 L<EVP_PKEY-CMAC(7)>,
+L<EVP_MAC-HMAC(7)>,
+L<EVP_MAC-Siphash(7)>,
+L<EVP_MAC-Poly1305(7)>,
+L<EVP_MAC-CMAC(7)>,
 L<provider-signature(7)>,
 
 =head1 COPYRIGHT

diff --git a/doc/man7/OSSL_PROVIDER-FIPS.pod b/doc/man7/OSSL_PROVIDER-FIPS.pod
index fc9c191855f25578f3b8ee866ebad6e2f606609c..d404716b235706e0a7d80eb1aead99a221bae8c1 100644 (file)
--- 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<EVP_KEYEXCH-DSA(7)>
 
+=item RSA, see L<EVP_SIGNATURE-RSA(7)>
+
+=item HMAC, see L<EVP_SIGNATURE-HMAC(7)>
+
+=item CMAC, see L<EVP_SIGNATURE-CMAC(7)>
+
 =back
 
 =head2 Asymmetric Cipher

diff --git a/doc/man7/OSSL_PROVIDER-default.pod b/doc/man7/OSSL_PROVIDER-default.pod
index 0b477b56c1acee02c75f734a98b6976fc8931273..a88c0be6e63752da966114accabb2a1a116f8493 100644 (file)
--- 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<EVP_SIGNATURE-RSA(7)>
 
+=item HMAC, see L<EVP_SIGNATURE-HMAC(7)>
+
+=item SIPHASH, see L<EVP_SIGNATURE-Siphash(7)>
+
+=item POLY1305, see L<EVP_SIGNATURE-Poly1305(7)>
+
+=item CMAC, see L<EVP_SIGNATURE-CMAC(7)>
+
 =back
 
 =head2 Asymmetric Cipher