From 5647960dd5126a7fa25f9bb518ed8d7e031c4827 Mon Sep 17 00:00:00 2001 From: James Muir Date: Fri, 17 Nov 2023 17:58:24 -0500 Subject: 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) --- doc/man7/EVP_MAC-BLAKE2.pod | 9 +++++---- doc/man7/EVP_MAC-CMAC.pod | 2 +- doc/man7/EVP_MAC-HMAC.pod | 2 +- doc/man7/EVP_MAC-KMAC.pod | 12 +++++++----- 4 files changed, 14 insertions(+), 11 deletions(-) diff --git a/doc/man7/EVP_MAC-BLAKE2.pod b/doc/man7/EVP_MAC-BLAKE2.pod index 5557e15353..f1106ef5a2 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 3fb530c4cf..44c5fc7c44 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 ea2eda9ec8..0e401710fc 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 dc67c66336..9c4fbc0b2a 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) -- cgit v1.2.3