doc: document no-short-mac param

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tom Cosgrove <tom.cosgrove@arm.com>
(Merged from https://github.com/openssl/openssl/pull/24917)

diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod
index 9c4fbc0b2ad9c9116f8f005d2500f84e89d0d5ec..0b3e96b00566d2eb5ec038bfa3a36a00ef5d4b21 100644 (file)
--- a/doc/man7/EVP_MAC-KMAC.pod
+++ b/doc/man7/EVP_MAC-KMAC.pod
@@ -35,7 +35,6 @@ 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
 
 =item "key" (B<OSSL_MAC_PARAM_KEY>) <octet string>
@@ -65,9 +64,20 @@ It is 168 for C<KMAC-128> and 136 for C<KMAC-256>.
 The "xof" parameter value is expected to be 1 or 0. Use 1 to enable XOF mode.
 The default value is 0.
 
+=item "fips-indicator" (B<OSSL_MAC_PARAM_FIPS_APPROVED_INDICATOR>) <int>
+
+This settable parameter is described in L<provider-mac(7)>.
+
+=item "no-short-mac" (B<OSSL_PROV_FIPS_PARAM_NO_SHORT_MAC>) <integer>
+
+This settable parameter is described in L<provider-mac(7)>.  It is used by
+the OpenSSL FIPS provider and the minimum length output for KMAC
+is defined by NIST's SP 800-185 8.4.2.
+
 =back
 
-The "custom" parameter must be set as part of or before the EVP_MAC_init() call.
+The "custom" and "no-short-mac" parameters must be set as part of or before
+the EVP_MAC_init() call.
 The "xof" and "size" parameters can be set at any time before EVP_MAC_final().
 The "key" parameter is set as part of the EVP_MAC_init() call, but can be
 set before it instead.
@@ -140,7 +150,8 @@ set before it instead.
 =head1 SEE ALSO
 
 L<EVP_MAC_CTX_get_params(3)>, L<EVP_MAC_CTX_set_params(3)>,
-L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>
+L<EVP_MAC(3)/PARAMETERS>, L<OSSL_PARAM(3)>,
+L<SP 800-185 8.4.2|https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf>
 
 =head1 COPYRIGHT
 

diff --git a/doc/man7/provider-mac.pod b/doc/man7/provider-mac.pod
index 6d7bd46d299e9d06fafe3fe78f8bfbe10557d2ac..13be4a7fc0889ad987a09478a12f6ee3a63107b5 100644 (file)
--- a/doc/man7/provider-mac.pod
+++ b/doc/man7/provider-mac.pod
@@ -191,6 +191,29 @@ Can be used to get the MAC block size (if supported by the algorithm).
 
 =back
 
+=over 4
+
+=item "fips-indicator" (B<OSSL_MAC_PARAM_FIPS_APPROVED_INDICATOR>) <int>
+
+A getter that returns 1 if the operation is FIPS approved, or 0 otherwise.
+This may be used after calling the final function.  It may return 0 if
+"no-short-mac" are set to 0.  This option is used by the OpenSSL FIPS
+provider.
+
+=back
+
+=over 4
+
+=item "no-short-mac" (B<OSSL_PROV_FIPS_PARAM_NO_SHORT_MAC>) <integer>
+
+If required this parameter should be set early via an init function.
+The default value of 1 causes an error when too short MAC output is
+asked for.  Setting this to 0 will ignore the error and set the approved
+"fips-indicator" to 0.  This option is used by the OpenSSL FIPS provider,
+and breaks FIPS compliance if set to 0.
+
+=back
+
 =back
 
 =head1 NOTES