From: Pauli <pauli@openssl.org>
Date: Thu, 16 Mar 2023 03:21:25 +0000 (+1100)
Subject: doc: note the restriction on digests used by DRBGs in FIPS mode.
X-Git-Tag: openssl-3.2.0-alpha1~1085
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e14fc22c90ce5a9e6d66d8658fc6bb37f95019da;p=thirdparty%2Fopenssl.git

doc: note the restriction on digests used by DRBGs in FIPS mode.

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/20521)
---

diff --git a/doc/man1/openssl-fipsinstall.pod.in b/doc/man1/openssl-fipsinstall.pod.in
index 8b066453f92..e3ceeb481c7 100644
--- a/doc/man1/openssl-fipsinstall.pod.in
+++ b/doc/man1/openssl-fipsinstall.pod.in
@@ -22,6 +22,7 @@ B<openssl fipsinstall>
 [B<-no_conditional_errors>]
 [B<-no_security_checks>]
 [B<-ems_check>]
+[B<-no_drbg_truncated_digests>]
 [B<-self_test_onload>]
 [B<-self_test_oninstall>]
 [B<-corrupt_desc> I<selftest_description>]
@@ -175,6 +176,11 @@ Configure the module to enable a run-time Extended Master Secret (EMS) check
 when using the TLS1_PRF KDF algorithm. This check is disabled by default.
 See RFC 7627 for information related to EMS.
 
+=item B<-no_drbg_truncated_digests>
+
+Configure the module to not allow truncated digests to be used with Hash and
+HMAC DRBGs.  See FIPS 140-3 IG D.R for details.
+
 =item B<-self_test_onload>
 
 Do not write the two fields related to the "test status indicator" and
diff --git a/doc/man7/EVP_RAND-HASH-DRBG.pod b/doc/man7/EVP_RAND-HASH-DRBG.pod
index 3361f7d8a57..97a3ecc684f 100644
--- a/doc/man7/EVP_RAND-HASH-DRBG.pod
+++ b/doc/man7/EVP_RAND-HASH-DRBG.pod
@@ -54,6 +54,24 @@ These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
 
 =head1 NOTES
 
+When the FIPS provider is installed using the B<-no_drbg_truncated_digests>
+option to fipsinstall, only these digests are permitted (as per
+L<FIPS 140-3 IG D.R|https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>):
+
+=over 4
+
+=item SHA-1
+
+=item SHA2-256
+
+=item SHA2-512
+
+=item SHA3-256
+
+=item SHA3-512
+
+=back
+
 A context for HASH DRBG can be obtained by calling:
 
  EVP_RAND *rand = EVP_RAND_fetch(NULL, "HASH-DRBG", NULL);
@@ -86,7 +104,15 @@ NIST SP 800-90A and SP 800-90B
 =head1 SEE ALSO
 
 L<EVP_RAND(3)>,
-L<EVP_RAND(3)/PARAMETERS>
+L<EVP_RAND(3)/PARAMETERS>,
+L<openssl-fipsinstall(1)>
+
+=head1 HISTORY
+
+OpenSSL 3.1.1 introduced the B<-no_drbg_truncated_digests> option to
+fipsinstall which restricts the permitted digests when using the FIPS
+provider in a complaint manner.  For details refer to
+L<FIPS 140-3 IG D.R|https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man7/EVP_RAND-HMAC-DRBG.pod b/doc/man7/EVP_RAND-HMAC-DRBG.pod
index ae3a51dbd73..5b188404f9c 100644
--- a/doc/man7/EVP_RAND-HMAC-DRBG.pod
+++ b/doc/man7/EVP_RAND-HMAC-DRBG.pod
@@ -56,6 +56,23 @@ These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
 
 =head1 NOTES
 
+When using the FIPS provider, only these digests are permitted (as per
+L<FIPS 140-3 IG D.R|https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>):
+
+=over 4
+
+=item SHA-1
+
+=item SHA2-256
+
+=item SHA2-512
+
+=item SHA3-256
+
+=item SHA3-512
+
+=back
+
 A context for HMAC DRBG can be obtained by calling:
 
  EVP_RAND *rand = EVP_RAND_fetch(NULL, "HMAC-DRBG", NULL);
@@ -89,7 +106,16 @@ NIST SP 800-90A and SP 800-90B
 =head1 SEE ALSO
 
 L<EVP_RAND(3)>,
-L<EVP_RAND(3)/PARAMETERS>
+L<EVP_RAND(3)/PARAMETERS>,
+L<openssl-fipsinstall(1)>
+
+
+=head1 HISTORY
+
+OpenSSL 3.1.1 introduced the B<-no_drbg_truncated_digests> option to
+fipsinstall which restricts the permitted digests when using the FIPS
+provider in a complaint manner.  For details refer to
+L<FIPS 140-3 IG D.R|https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>).
 
 =head1 COPYRIGHT