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)

diff --git a/doc/man3/EVP_MAC.pod b/doc/man3/EVP_MAC.pod
index d053375dcf2fd5211d0173433ff4acd35ccd266d..0fc34009ecc5b17649bb2e397f3cda2ebbd3b585 100644 (file)
--- 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 809a29a0fe759d2b08b86040a81b8ee555e32172..5557e153536a08d1ac8008950be319b144979c5f 100644 (file)
--- 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 4beac89d9c1758f7f32e7f4ce5a080e414621d8f..cf80586f0244ff4984e905f226281812a372c4d5 100644 (file)
--- 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 790f01f094c909051e801a68fc442b6b5c6c4160..ea2eda9ec81902c298b561362a03ac7c9d7a368e 100644 (file)
--- 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 85986d5449fa7b64e4de293a26c0f15d7f2f44fd..0197a4b3c12a0ef4cc9b3f0ec0e4da12e0b292a4 100644 (file)
--- 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 3d49e4f41226e9aad972c367a93b159137fd4175..7ebe72f07dc74554ec2f08bad73a6e07ae4e830e 100644 (file)
--- 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