doc: fix description of mac "block-size" parameter

The macro for "block-size" is OSSL_MAC_PARAM_BLOCK_SIZE, and this
parameter is not settable.  Refer to the "customization string" rather
than the "custom value" (in the Blake2 spec, this is called the
personalization string).

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/22763)

diff --git a/doc/man7/EVP_MAC-BLAKE2.pod b/doc/man7/EVP_MAC-BLAKE2.pod
index 5557e153536a08d1ac8008950be319b144979c5f..f1106ef5a2d1956b692285c4db70791c74b093dd 100644 (file)
--- a/doc/man7/EVP_MAC-BLAKE2.pod
+++ b/doc/man7/EVP_MAC-BLAKE2.pod
@@ -27,7 +27,8 @@ properties, to be used with EVP_MAC_fetch():
 The general description of these parameters can be found in
 L<EVP_MAC(3)/PARAMETERS>.
 
-All these parameters can be set with EVP_MAC_CTX_set_params().
+All these parameters (except for "block-size") can be set with
+EVP_MAC_CTX_set_params().
 Furthermore, the "size" parameter can be retrieved with
 EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_mac_size().
 The length of the "size" parameter should not exceed that of a B<size_t>.
@@ -45,7 +46,7 @@ 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.
+Sets the customization/personalization string.
 It is an optional value of at most 16 bytes for BLAKE2BMAC or 8 for
 BLAKE2SMAC, and is empty by default.
 
@@ -62,10 +63,10 @@ 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.
 
-=item "block-size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+=item "block-size" (B<OSSL_MAC_PARAM_BLOCK_SIZE>) <unsigned integer>
 
 Gets the MAC block size.
-By default, it is 64 for EVP_MAC_BLAKE2S and 128 for EVP_MAC_BLAKE2B.
+It is 64 for EVP_MAC_BLAKE2S and 128 for EVP_MAC_BLAKE2B.
 
 =back
 

diff --git a/doc/man7/EVP_MAC-CMAC.pod b/doc/man7/EVP_MAC-CMAC.pod
index 3fb530c4cfe166b2ac975293a68f3149a05c4c85..44c5fc7c44e18f45f3731bbc910fa9aa5a3a5269 100644 (file)
--- a/doc/man7/EVP_MAC-CMAC.pod
+++ b/doc/man7/EVP_MAC-CMAC.pod
@@ -63,7 +63,7 @@ The length of the "size" parameter is equal to that of an B<unsigned int>.
 
 =over 4
 
-=item "block-size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+=item "block-size" (B<OSSL_MAC_PARAM_BLOCK_SIZE>) <unsigned integer>
 
 Gets the MAC block size.  The "block-size" parameter can also be retrieved with
 EVP_MAC_CTX_get_block_size().

diff --git a/doc/man7/EVP_MAC-HMAC.pod b/doc/man7/EVP_MAC-HMAC.pod
index ea2eda9ec81902c298b561362a03ac7c9d7a368e..0e401710fc92300732d7a7a4fa5eb55f7d8f3880 100644 (file)
--- a/doc/man7/EVP_MAC-HMAC.pod
+++ b/doc/man7/EVP_MAC-HMAC.pod
@@ -76,7 +76,7 @@ The length of the "size" parameter is equal to that of an B<unsigned int>.
 
 =over 4
 
-=item "block-size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+=item "block-size" (B<OSSL_MAC_PARAM_BLOCK_SIZE>) <unsigned integer>
 
 Gets the MAC block size.  The "block-size" parameter can also be retrieved with
 EVP_MAC_CTX_get_block_size().

diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod
index dc67c66336df45dba520e8b6757adccf479cd027..9c4fbc0b2ad9c9116f8f005d2500f84e89d0d5ec 100644 (file)
--- a/doc/man7/EVP_MAC-KMAC.pod
+++ b/doc/man7/EVP_MAC-KMAC.pod
@@ -27,7 +27,8 @@ properties, to be used with EVP_MAC_fetch():
 The general description of these parameters can be found in
 L<EVP_MAC(3)/PARAMETERS>.
 
-All these parameters can be set with EVP_MAC_CTX_set_params().
+All these parameters (except for "block-size") can be set with
+EVP_MAC_CTX_set_params().
 Furthermore, the "size" parameter can be retrieved with
 EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_mac_size().
 The length of the "size" parameter should not exceed that of a B<size_t>.
@@ -45,18 +46,19 @@ The length of the key (in bytes) must be in the range 4...512.
 
 =item "custom" (B<OSSL_MAC_PARAM_CUSTOM>) <octet string>
 
-Sets the custom value.
-It is an optional value with a length of at most 512 bytes, and is empty by default.
+Sets the customization string.
+It is an optional value with a length of at most 512 bytes, and is
+empty by default.
 
 =item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
 
 Sets the MAC size.
 By default, it is 32 for C<KMAC-128> and 64 for C<KMAC-256>.
 
-=item "block-size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+=item "block-size" (B<OSSL_MAC_PARAM_BLOCK_SIZE>) <unsigned integer>
 
 Gets the MAC block size.
-By default, it is 168 for C<KMAC-128> and 136 for C<KMAC-256>.
+It is 168 for C<KMAC-128> and 136 for C<KMAC-256>.
 
 =item "xof" (B<OSSL_MAC_PARAM_XOF>) <integer>