mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-02-17 14:32:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update the EVP_PKEY MAC documentation

Browse Source 
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)
This commit is contained in:
Matt Caswell 2020-08-27 12:52:17 +01:00
parent f271389305
commit 820d87bc98
8 changed files with 55 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/man3/EVP_DigestVerifyInit.pod
View File

@ -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.

15
doc/man3/EVP_MAC.pod
View File

@ -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

2
doc/man7/EVP_MAC-HMAC.pod
View File

@ -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().

4
doc/man7/EVP_MAC-Siphash.pod
View File

@ -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

10
doc/man7/EVP_PKEY-HMAC.pod
View File

@ -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

24
doc/man7/EVP_SIGNATURE-HMAC.pod
View File

@ -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

6
doc/man7/OSSL_PROVIDER-FIPS.pod
View File

@ -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

8
doc/man7/OSSL_PROVIDER-default.pod
View File

@ -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