From 3440a9a0e263b4d9a0d328bc79d0f50912e970f0 Mon Sep 17 00:00:00 2001
From: Pauli <ppzgs1@gmail.com>
Date: Wed, 17 Jul 2024 11:09:34 +1000
Subject: [PATCH] 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)
---
 doc/man7/EVP_MAC-KMAC.pod | 17 ++++++++++++++---
 doc/man7/provider-mac.pod | 23 +++++++++++++++++++++++
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/doc/man7/EVP_MAC-KMAC.pod b/doc/man7/EVP_MAC-KMAC.pod
index 9c4fbc0b2ad..0b3e96b0056 100644
--- 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 6d7bd46d299..13be4a7fc08 100644
--- 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
-- 
2.47.2