doc: document the MAC block size getter

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

6 files changed, 55 insertions, 7 deletions

diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index d053375dcf..0fc34009ec 100644
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -7,7 +7,7 @@ EVP_MAC_number, EVP_MAC_name, EVP_MAC_names_do_all, EVP_MAC_description,
 EVP_MAC_provider, EVP_MAC_get_params, EVP_MAC_gettable_params,
 EVP_MAC_CTX, EVP_MAC_CTX_new, EVP_MAC_CTX_free, EVP_MAC_CTX_dup,
 EVP_MAC_CTX_mac, EVP_MAC_CTX_get_params, EVP_MAC_CTX_set_params,
-EVP_MAC_CTX_get_mac_size, EVP_Q_mac,
+EVP_MAC_CTX_get_mac_size, EVP_MAC_CTX_get_block_size, EVP_Q_mac,
 EVP_MAC_init, EVP_MAC_update, EVP_MAC_final, EVP_MAC_finalXOF,
 EVP_MAC_gettable_ctx_params, EVP_MAC_settable_ctx_params,
 EVP_MAC_CTX_gettable_params, EVP_MAC_CTX_settable_params,
@@ -42,6 +42,7 @@ EVP_MAC_do_all_provided - EVP MAC routines
  int EVP_MAC_CTX_set_params(EVP_MAC_CTX *ctx, const OSSL_PARAM params[]);
 
  size_t EVP_MAC_CTX_get_mac_size(EVP_MAC_CTX *ctx);
+ size_t EVP_MAC_CTX_get_block_size(EVP_MAC_CTX *ctx);
  unsigned char *EVP_Q_mac(OSSL_LIB_CTX *libctx, const char *name, const char *propq,
                           const char *subalg, const OSSL_PARAM *params,
                           const void *key, size_t keylen,
@@ -212,6 +213,9 @@ for the use of B<OSSL_PARAM> as a parameter descriptor.
 
 EVP_MAC_CTX_get_mac_size() returns the MAC output size for the given context.
 
+EVP_MAC_CTX_get_block_size() returns the MAC block size for the given context.
+Not all MAC algorithms support this.
+
 EVP_MAC_is_a() checks if the given I<mac> is an implementation of an
 algorithm that's identifiable with I<name>.
 
@@ -378,8 +382,11 @@ EVP_Q_mac() returns a pointer to the computed MAC value, or NULL on error.
 EVP_MAC_init(), EVP_MAC_update(), EVP_MAC_final(), and EVP_MAC_finalXOF()
 return 1 on success, 0 on error.
 
-EVP_MAC_CTX_get_mac_size() returns the expected output size, or 0 if it isn't set.
-If it isn't set, a call to EVP_MAC_init() should get it set.
+EVP_MAC_CTX_get_mac_size() returns the expected output size, or 0 if it isn't
+set.  If it isn't set, a call to EVP_MAC_init() will set it.
+
+EVP_MAC_CTX_get_block_size() returns the block size, or 0 if it isn't set.
+If it isn't set, a call to EVP_MAC_init() will set it.
 
 EVP_MAC_do_all_provided() returns nothing at all.
 
diff --git a/doc/man7/EVP_MAC-BLAKE2.pod b/doc/man7/EVP_MAC-BLAKE2.pod
index 809a29a0fe..5557e15353 100644
--- a/doc/man7/EVP_MAC-BLAKE2.pod
+++ b/doc/man7/EVP_MAC-BLAKE2.pod
@@ -31,6 +31,8 @@ All these parameters 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>.
+Likewise, the "block-size" parameter can be retrieved with
+EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_block_size().
 
 =over 4
 
@@ -60,6 +62,11 @@ 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>
+
+Gets the MAC block size.
+By default, it is 64 for EVP_MAC_BLAKE2S and 128 for EVP_MAC_BLAKE2B.
+
 =back
 
 =head1 SEE ALSO
diff --git a/doc/man7/EVP_MAC-CMAC.pod b/doc/man7/EVP_MAC-CMAC.pod
index 4beac89d9c..cf80586f02 100644
--- a/doc/man7/EVP_MAC-CMAC.pod
+++ b/doc/man7/EVP_MAC-CMAC.pod
@@ -55,11 +55,20 @@ EVP_MAC_CTX_get_params():
 
 =item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
 
-=back
-
 The "size" parameter can also be retrieved with with EVP_MAC_CTX_get_mac_size().
 The length of the "size" parameter is equal to that of an B<unsigned int>.
 
+=back
+
+=over 4
+
+=item "block-size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+
+Gets the MAC block size.  The "block-size" parameter can also be retrieved with
+EVP_MAC_CTX_get_block_size().
+
+=back
+
 =head1 SEE ALSO
 
 L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
diff --git a/doc/man7/EVP_MAC-HMAC.pod b/doc/man7/EVP_MAC-HMAC.pod
index 790f01f094..ea2eda9ec8 100644
--- a/doc/man7/EVP_MAC-HMAC.pod
+++ b/doc/man7/EVP_MAC-HMAC.pod
@@ -69,11 +69,20 @@ The following parameter can be retrieved with EVP_MAC_CTX_get_params():
 
 =item "size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
 
-=back
-
 The "size" parameter can also be retrieved with EVP_MAC_CTX_get_mac_size().
 The length of the "size" parameter is equal to that of an B<unsigned int>.
 
+=back
+
+=over 4
+
+=item "block-size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+
+Gets the MAC block size.  The "block-size" parameter can also be retrieved with
+EVP_MAC_CTX_get_block_size().
+
+=back
+
 =head1 SEE ALSO
 
 L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod
index 85986d5449..0197a4b3c1 100644
--- a/doc/man7/EVP_MAC-KMAC.pod
+++ b/doc/man7/EVP_MAC-KMAC.pod
@@ -31,6 +31,9 @@ All these parameters 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>.
+Likewise, the "block-size" parameter can be retrieved with
+EVP_MAC_CTX_get_params(), or with EVP_MAC_CTX_get_block_size().
+
 
 =over 4
 
@@ -49,6 +52,11 @@ It is an optional value of at most 256 bytes, and is empty by default.
 Sets the MAC size.
 By default, it is 16 for C<KMAC-128> and 32 for C<KMAC-256>.
 
+=item "block-size" (B<OSSL_MAC_PARAM_SIZE>) <unsigned integer>
+
+Gets the MAC block size.
+By default, it is 168 for C<KMAC-128> and 136 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/provider-mac.pod b/doc/man7/provider-mac.pod
index 3d49e4f412..7ebe72f07d 100644
--- a/doc/man7/provider-mac.pod
+++ b/doc/man7/provider-mac.pod
@@ -183,6 +183,14 @@ should have as well, see the documentation of the implementation.
 
 =back
 
+=over 4
+
+=item "size" (B<OSSL_MAC_PARAM_BLOCK_SIZE>) <integer>
+
+Can be used to get the MAC block size (if supported by the algorithm).
+
+=back
+
 =back
 
 =head1 NOTES