[openssl] master update
Richard Levitte
levitte at openssl.org
Wed Mar 3 13:44:50 UTC 2021
The branch master has been updated
via 8593ff00cc66e330228164ae5422f80ef93ed35d (commit)
from cb54d1b9d7f0d386aa22550d8b12ecd43e248a3f (commit)
- Log -----------------------------------------------------------------
commit 8593ff00cc66e330228164ae5422f80ef93ed35d
Author: Richard Levitte <levitte at openssl.org>
Date: Mon Mar 1 18:46:20 2021 +0100
DOCS: Fix provider-mac.pod and the docs of our implementations
The idea being that doc/man7/provider-mac.pod is for provider authors,
while provider users find the documentation for each implementation in
doc/man7/EVP_MAC-*.pod, the documentation of parameters wasn't quite
aligned. This change re-arranges the parameter documentation to be
more aligned with this idea.
Reviewed-by: Shane Lontis <shane.lontis at oracle.com>
(Merged from https://github.com/openssl/openssl/pull/14380)
-----------------------------------------------------------------------
Summary of changes:
doc/man7/EVP_MAC-BLAKE2.pod | 23 ++++++++-------
doc/man7/EVP_MAC-CMAC.pod | 12 ++++++++
doc/man7/EVP_MAC-GMAC.pod | 16 +++++++++++
doc/man7/EVP_MAC-HMAC.pod | 26 ++++++++++++++---
doc/man7/EVP_MAC-KMAC.pod | 9 ++++++
doc/man7/EVP_MAC-Poly1305.pod | 5 ++++
doc/man7/EVP_MAC-Siphash.pod | 5 ++++
doc/man7/provider-mac.pod | 65 ++++++++++++-------------------------------
8 files changed, 100 insertions(+), 61 deletions(-)
diff --git a/doc/man7/EVP_MAC-BLAKE2.pod b/doc/man7/EVP_MAC-BLAKE2.pod
index 51bac880b5..042e2bfaa0 100644
--- a/doc/man7/EVP_MAC-BLAKE2.pod
+++ b/doc/man7/EVP_MAC-BLAKE2.pod
@@ -36,25 +36,28 @@ The length of the "size" parameter should not exceed that of a B<size_t>.
=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
-This may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and
-at least 1 byte in both cases.
+Sets the MAC key.
+It may be at most 64 bytes for BLAKE2BMAC or 32 for BLAKE2SMAC and at
+least 1 byte in both cases.
+Setting this parameter is identical to passing a I<key> to L<EVP_MAC_init(3)>.
=item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <octet string>
-This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
-BLAKE2SMAC.
-It is empty by default.
+Sets the custom value.
+It is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
+BLAKE2SMAC, and is empty by default.
=item "salt" (B<OSSL_MAC_PARAM_SALT>) <octet string>
-This is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
-BLAKE2SMAC.
-It is empty by default.
+Sets the salt.
+It is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
+BLAKE2SMAC, and is empty by default.
=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
-When set, this can be any number between between 1 and 32 for
-EVP_MAC_BLAKE2S or 64 for EVP_MAC_BLAKE2B.
+Sets the MAC size.
+It can be any number between 1 and 32 for EVP_MAC_BLAKE2S or between 1
+and 64 for EVP_MAC_BLAKE2B.
It is 32 and 64 respectively by default.
=back
diff --git a/doc/man7/EVP_MAC-CMAC.pod b/doc/man7/EVP_MAC-CMAC.pod
index 4d05919b8f..3c6af827b9 100644
--- a/doc/man7/EVP_MAC-CMAC.pod
+++ b/doc/man7/EVP_MAC-CMAC.pod
@@ -8,6 +8,9 @@ EVP_MAC-CMAC - The CMAC EVP_MAC implementation
Support for computing CMAC MACs through the B<EVP_MAC> API.
+This implementation uses EVP_CIPHER functions to get access to the underlying
+cipher.
+
=head2 Identity
This implementation is identified with this name and properties, to be
@@ -30,10 +33,19 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
+Sets the MAC key.
+Setting this parameter is identical to passing a I<key> to L<EVP_MAC_init(3)>.
+
=item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string>
+Sets the name of the underlying cipher to be used.
+
=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
+Sets the properties to be queried when trying to fetch the underlying cipher.
+This must be given together with the cipher naming parameter to be considered
+valid.
+
=back
The following parameters can be retrieved with
diff --git a/doc/man7/EVP_MAC-GMAC.pod b/doc/man7/EVP_MAC-GMAC.pod
index d662e7d5d2..a392cf3dfe 100644
--- a/doc/man7/EVP_MAC-GMAC.pod
+++ b/doc/man7/EVP_MAC-GMAC.pod
@@ -8,6 +8,9 @@ EVP_MAC-GMAC - The GMAC EVP_MAC implementation
Support for computing GMAC MACs through the B<EVP_MAC> API.
+This implementation uses EVP_CIPHER functions to get access to the underlying
+cipher.
+
=head2 Identity
This implementation is identified with this name and properties, to be
@@ -30,12 +33,23 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
+Sets the MAC key.
+Setting this parameter is identical to passing a I<key> to L<EVP_MAC_init(3)>.
+
=item "iv" (B<OSSL_MAC_PARAM_IV>) <octet string>
+Sets the IV of the underlying cipher, when applicable.
+
=item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string>
+Sets the name of the underlying cipher to be used.
+
=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
+Sets the properties to be queried when trying to fetch the underlying cipher.
+This must be given together with the cipher naming parameter to be considered
+valid.
+
=back
The following parameters can be retrieved with
@@ -45,6 +59,8 @@ EVP_MAC_CTX_get_params():
=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+Gets the MAC size.
+
=back
The "size" parameter can also be retrieved with EVP_MAC_CTX_get_mac_size().
diff --git a/doc/man7/EVP_MAC-HMAC.pod b/doc/man7/EVP_MAC-HMAC.pod
index fe63b329f9..790f01f094 100644
--- a/doc/man7/EVP_MAC-HMAC.pod
+++ b/doc/man7/EVP_MAC-HMAC.pod
@@ -8,6 +8,9 @@ EVP_MAC-HMAC - The HMAC EVP_MAC implementation
Support for computing HMAC MACs through the B<EVP_MAC> API.
+This implementation uses EVP_MD functions to get access to the underlying
+digest.
+
=head2 Identity
This implementation is identified with this name and properties, to be
@@ -30,22 +33,37 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
+Sets the MAC key.
+Setting this parameter is identical to passing a I<key> to L<EVP_MAC_init(3)>.
+
=item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string>
+Sets the name of the underlying digest to be used.
+
+=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
+
+Sets the properties to be queried when trying to fetch the underlying digest.
+This must be given together with the digest naming parameter ("digest", or
+B<OSSL_MAC_PARAM_DIGEST>) to be considered valid.
+
=item "digest-noinit" (B<OSSL_MAC_PARAM_DIGEST_NOINIT>) <integer>
+A flag to set the MAC digest to not initialise the implementation
+specific data.
+The value 0 or 1 is expected.
+
=item "digest-oneshot" (B<OSSL_MAC_PARAM_DIGEST_ONESHOT>) <integer>
-=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
+A flag to set the MAC digest to be a one-shot operation.
+The value 0 or 1 is expected.
=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().
+=for comment The "flags" parameter is passed directly to HMAC_CTX_set_flags().
-The following parameter can be retrieved with
-EVP_MAC_CTX_get_params():
+The following parameter can be retrieved with EVP_MAC_CTX_get_params():
=over 4
diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod
index 46fce76274..504622b7d1 100644
--- a/doc/man7/EVP_MAC-KMAC.pod
+++ b/doc/man7/EVP_MAC-KMAC.pod
@@ -36,10 +36,19 @@ The length of the "size" parameter should not exceed that of a B<size_t>.
=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
+Sets the MAC key.
+Setting this parameter is identical to passing a I<key> to L<EVP_MAC_init(3)>.
+
=item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <octet string>
+Sets the custom value.
+It is an optional value of at most 127 bytes, and is empty by default.
+
=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+Sets the MAC size.
+By default, it is 16 for C<KMAC-128> and 32 for C<KMAC-256>.
+
=item "xof" (B<OSSL_MAC_PARAM_XOF>) <integer>
The "xof" parameter value is expected to be 1 or 0. Use 1 to enable XOF mode.
diff --git a/doc/man7/EVP_MAC-Poly1305.pod b/doc/man7/EVP_MAC-Poly1305.pod
index 8a0989ab71..a7e2f23439 100644
--- a/doc/man7/EVP_MAC-Poly1305.pod
+++ b/doc/man7/EVP_MAC-Poly1305.pod
@@ -30,6 +30,9 @@ The following parameter can be set with EVP_MAC_CTX_set_params():
=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
+Sets the MAC key.
+Setting this parameter is identical to passing a I<key> to L<EVP_MAC_init(3)>.
+
=back
The following parameters can be retrieved with
@@ -39,6 +42,8 @@ EVP_MAC_CTX_get_params():
=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+Gets the MAC size.
+
=back
The "size" parameter can also be retrieved with with EVP_MAC_CTX_get_mac_size().
diff --git a/doc/man7/EVP_MAC-Siphash.pod b/doc/man7/EVP_MAC-Siphash.pod
index 2b6f2ae4e4..01849f7c4a 100644
--- a/doc/man7/EVP_MAC-Siphash.pod
+++ b/doc/man7/EVP_MAC-Siphash.pod
@@ -34,8 +34,13 @@ The length of the "size" parameter should not exceed that of a B<size_t>.
=item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
+Sets the MAC key.
+Setting this parameter is identical to passing a I<key> to L<EVP_MAC_init(3)>.
+
=item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+Sets the MAC size.
+
=item "c-rounds" (B<OSSL_MAC_PARAM_C_ROUNDS>) <unsigned integer>
Specifies the number of rounds per message block. By default this is I<2>.
diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod
index 47f26ca89b..8b4ce93613 100644
--- a/doc/man7/provider-mac.pod
+++ b/doc/man7/provider-mac.pod
@@ -152,9 +152,11 @@ with the provider side context I<mctx> in its current state if it is
not NULL. Otherwise, they return the parameters associated with the
provider side algorithm I<provctx>.
+All MAC implementations are expected to handle the following parameters:
-Parameters currently recognised by built-in macs are as follows. Not all
-parameters are relevant to, or are understood by all macs:
+=over 4
+
+=item with OSSL_FUNC_set_ctx_params():
=over 4
@@ -163,56 +165,21 @@ parameters are relevant to, or are understood by all macs:
Sets the key in the associated MAC ctx. This is identical to passing a I<key>
argument to the OSSL_FUNC_mac_init() function.
-=item "iv" (B<OSSL_MAC_PARAM_IV>) <octet string>
-
-Sets the IV of the underlying cipher, when applicable.
-
-=item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <UTF8 string>
-
-Sets the custom string in the associated MAC ctx.
-
-=item "salt" (B<OSSL_MAC_PARAM_SALT>) <octet string>
-
-Sets the salt of the underlying cipher, when applicable.
-
-=item "xof" (B<OSSL_MAC_PARAM_BLOCK_XOF>) <integer>
-
-Sets XOF mode in the associated MAC ctx.
-0 means no XOF mode, 1 means XOF mode.
-
-=item "digest-noinit" (B<OSSL_MAC_PARAM_DIGEST_NOINIT>) <integer>
-
-A simple flag to set the MAC digest to not initialise the
-implementation specific data. The value 0 or 1 is expected.
-
-=item "digest-oneshot" (B<OSSL_MAC_PARAM_DIGEST_ONESHOT>) <integer>
-
-A simple flag to set the MAC digest to be a oneshot operation.
-The value 0 or 1 is expected.
-
-
-=for comment We need to investigate if this is the right approach
-
-=item "cipher" (B<OSSL_MAC_PARAM_CIPHER>) <UTF8 string>
-
-=item "digest" (B<OSSL_MAC_PARAM_DIGEST>) <UTF8 string>
-
-Sets the name of the underlying cipher or digest to be used.
-It must name a suitable algorithm for the MAC that's being used.
+=back
-=item "properties" (B<OSSL_MAC_PARAM_PROPERTIES>) <UTF8 string>
+=item with OSSL_FUNC_get_params():
-Sets the properties to be queried when trying to fetch the underlying algorithm.
-This must be given together with the algorithm naming parameter to be
-considered valid.
+=over 4
=item "size" (B<OSSL_MAC_PARAM_SIZE>) <integer>
-Can be used to get the resulting MAC size.
+Can be used to get the default MAC size (which might be the only allowable
+MAC size for the implementation).
-With some MAC algorithms, it can also be used to set the size that the
-resulting MAC should have.
-Allowable sizes are decided within each implementation.
+Note that some implementations allow setting the size that the resulting MAC
+should have as well, see the documentation of the implementation.
+
+=back
=back
@@ -231,7 +198,11 @@ array, or NULL if none is offered.
=head1 SEE ALSO
-L<provider(7)>, L<EVP_MAC_init(3)>
+L<provider(7)>,
+L<EVP_MAC-BLAKE2(7)>, L<EVP_MAC-CMAC(7)>, L<EVP_MAC-GMAC(7)>,
+L<EVP_MAC-HMAC(7)>, L<EVP_MAC-KMAC(7)>, L<EVP_MAC-Poly1305(7)>,
+L<EVP_MAC-Siphash(7)>
+
=head1 HISTORY
More information about the openssl-commits
mailing list