From: Simo Sorce <simo@redhat.com>
Date: Fri, 7 Feb 2025 19:20:00 +0000 (-0500)
Subject: Add documentation to explain DRBG changes
X-Git-Tag: openssl-3.5.0-alpha1~632
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=0ba139f4b9db144df5c94bce9f6e70bedf182efb;p=thirdparty%2Fopenssl.git

Add documentation to explain DRBG changes

Signed-off-by: Simo Sorce <simo@redhat.com>

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
(Merged from https://github.com/openssl/openssl/pull/26542)
---

diff --git a/CHANGES.md b/CHANGES.md
index 5a16e267c6d..2b0ae31890d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -35,6 +35,14 @@ OpenSSL 3.5
 
    *Matt Caswell*
 
+ * The default DRBG implementations have been changed to prefer to fetch
+   algorithm implementations from the default provider (the provider the
+   DRBG implementation is built in) regardless of the default properties
+   set in the configuration file. The code will still fallback to find
+   an implementation, as done previously, if needed.
+
+   *Simo Sorce*
+
  * For TLSv1.3: Add capability for a client to send multiple key shares. Extend the scope of
    `SSL_OP_CIPHER_SERVER_PREFERENCE` to cover server-side key exchange group selection.
    Extend the server-side key exchange group selection algorithm and related group list syntax
diff --git a/doc/man7/EVP_RAND-CTR-DRBG.pod b/doc/man7/EVP_RAND-CTR-DRBG.pod
index 3e10f189d3b..51c8c0450d7 100644
--- a/doc/man7/EVP_RAND-CTR-DRBG.pod
+++ b/doc/man7/EVP_RAND-CTR-DRBG.pod
@@ -65,6 +65,12 @@ A context for CTR DRBG can be obtained by calling:
  EVP_RAND *rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
  EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand, NULL);
 
+The default CTR-DRBG implementation attempts to fetch the required internal
+algorithms from the provider they are built into (eg the default provider)
+regardless of the properties provided. Should the provider not implement
+the required algorithms then properties will be used to find a different
+implementation.
+
 =head1 EXAMPLES
 
  EVP_RAND *rand;
diff --git a/doc/man7/EVP_RAND-HASH-DRBG.pod b/doc/man7/EVP_RAND-HASH-DRBG.pod
index ff5b1fa608d..2025771da80 100644
--- a/doc/man7/EVP_RAND-HASH-DRBG.pod
+++ b/doc/man7/EVP_RAND-HASH-DRBG.pod
@@ -64,6 +64,12 @@ 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>):
 
+The default HASH-DRBG implementation attempts to fetch the required internal
+algorithms from the provider they are built into (eg the default provider)
+regardless of the properties provided. Should the provider not implement
+the required algorithms then properties will be used to find a different
+implementation.
+
 =over 4
 
 =item SHA-1
diff --git a/doc/man7/EVP_RAND-HMAC-DRBG.pod b/doc/man7/EVP_RAND-HMAC-DRBG.pod
index f7407a734ad..e640586b490 100644
--- a/doc/man7/EVP_RAND-HMAC-DRBG.pod
+++ b/doc/man7/EVP_RAND-HMAC-DRBG.pod
@@ -65,6 +65,12 @@ These parameters work as described in L<provider-rand(7)/PARAMETERS>.
 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>):
 
+The default HMAC-DRBG implementation attempts to fetch the required internal
+algorithms from the provider they are built into (eg the default provider)
+regardless of the properties provided. Should the provider not implement
+the required algorithms then properties will be used to find a different
+implementation.
+
 =over 4
 
 =item SHA-1