diff options
author | Richard Levitte <levitte@openssl.org> | 2021-03-01 18:46:20 +0100 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2021-03-03 14:08:00 +0100 |
commit | 8593ff00cc66e330228164ae5422f80ef93ed35d (patch) | |
tree | 933aa54bfa42767070606d99a845ebf0d2cc5524 | |
parent | cb54d1b9d7f0d386aa22550d8b12ecd43e248a3f (diff) |
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@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/14380)
-rw-r--r-- | doc/man7/EVP_MAC-BLAKE2.pod | 23 | ||||
-rw-r--r-- | doc/man7/EVP_MAC-CMAC.pod | 12 | ||||
-rw-r--r-- | doc/man7/EVP_MAC-GMAC.pod | 16 | ||||
-rw-r--r-- | doc/man7/EVP_MAC-HMAC.pod | 26 | ||||
-rw-r--r-- | doc/man7/EVP_MAC-KMAC.pod | 9 | ||||
-rw-r--r-- | doc/man7/EVP_MAC-Poly1305.pod | 5 | ||||
-rw-r--r-- | doc/man7/EVP_MAC-Siphash.pod | 5 | ||||
-rw-r--r-- | 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 |