From: James Muir Date: Fri, 17 Nov 2023 22:58:24 +0000 (-0500) Subject: doc: fix description of mac "block-size" parameter X-Git-Tag: openssl-3.1.5~142 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=eef9951e72ca2d55325493a500c286be524a2d02;p=thirdparty%2Fopenssl.git 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 Reviewed-by: Tomas Mraz Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/22763) (cherry picked from commit 1750689767cc922bdbe73358f7256475f0838c67) --- diff --git a/doc/man7/EVP_MAC-BLAKE2.pod b/doc/man7/EVP_MAC-BLAKE2.pod index 5557e153536..f1106ef5a2d 100644 --- 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. -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. @@ -45,7 +46,7 @@ Setting this parameter is identical to passing a I to L. =item "custom" (B) -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) +=item "block-size" (B) 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 43eb315c407..3db8a136664 100644 --- 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. =over 4 -=item "block-size" (B) +=item "block-size" (B) 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 ea2eda9ec81..0e401710fc9 100644 --- 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. =over 4 -=item "block-size" (B) +=item "block-size" (B) 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 bdadb0ff604..526ef4480a1 100644 --- 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. -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. @@ -45,18 +46,19 @@ The length of the key (in bytes) must be in the range 4...512. =item "custom" (B) -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) Sets the MAC size. By default, it is 32 for C and 64 for C. -=item "block-size" (B) +=item "block-size" (B) Gets the MAC block size. -By default, it is 168 for C and 136 for C. +It is 168 for C and 136 for C. =item "xof" (B)