From 4cde7585ce8eb53682256ba79e6af1949498fbfe Mon Sep 17 00:00:00 2001
From: Pauli <pauli@openssl.org>
Date: Tue, 5 Sep 2023 12:51:05 +1000
Subject: fips: use seed source requested

Fixes #21909

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21964)
---
 doc/internal/man3/ossl_rand_get_entropy.pod | 45 +++++++++++++++++++++++------
 1 file changed, 36 insertions(+), 9 deletions(-)

(limited to 'doc/internal')

diff --git a/doc/internal/man3/ossl_rand_get_entropy.pod b/doc/internal/man3/ossl_rand_get_entropy.pod
index 4da3f1f4d9..48343b6fe0 100644
--- a/doc/internal/man3/ossl_rand_get_entropy.pod
+++ b/doc/internal/man3/ossl_rand_get_entropy.pod
@@ -2,8 +2,8 @@
 
 =head1 NAME
 
-ossl_rand_get_entropy, ossl_rand_cleanup_entropy,
-ossl_rand_get_nonce, ossl_rand_cleanup_nonce
+ossl_rand_get_entropy, ossl_rand_get_user_entropy, ossl_rand_cleanup_entropy,
+ossl_rand_get_nonce, ossl_rand_get_user_nonce, ossl_rand_cleanup_nonce
 - get seed material from the operating system
 
 =head1 SYNOPSIS
@@ -13,11 +13,17 @@ ossl_rand_get_nonce, ossl_rand_cleanup_nonce
  size_t ossl_rand_get_entropy(OSSL_CORE_HANDLE *handle,
                               unsigned char **pout, int entropy,
                               size_t min_len, size_t max_len);
+ size_t ossl_rand_get_user_entropy(OSSL_CORE_HANDLE *handle,
+                                   unsigned char **pout, int entropy,
+                                   size_t min_len, size_t max_len);
  void ossl_rand_cleanup_entropy(OSSL_CORE_HANDLE *handle,
                                 unsigned char *buf, size_t len);
  size_t ossl_rand_get_nonce(OSSL_CORE_HANDLE *handle,
                             unsigned char **pout, size_t min_len,
                             size_t max_len, const void *salt, size_t salt_len);
+ size_t ossl_rand_get_user_nonce(OSSL_CORE_HANDLE *handle, unsigned char **pout,
+                                 size_t min_len, size_t max_len,
+                                 const void *salt, size_t salt_len);
  void ossl_rand_cleanup_nonce(OSSL_CORE_HANDLE *handle,
                               unsigned char *buf, size_t len);
 
@@ -29,9 +35,14 @@ stored in a buffer which contains at least I<min_len> and at most I<max_len>
 bytes.  The buffer address is stored in I<*pout> and the buffer length is
 returned to the caller.
 
+ossl_rand_get_user_entropy() is the same as ossl_rand_get_entropy()
+except that it retrieves the seeding material from the library context's
+DRBG seed source.  By default this is the operating system but it can
+be changed by calling L<RAND_set_seed_source_type(3)>.
+
 ossl_rand_cleanup_entropy() cleanses and frees any storage allocated by
-ossl_rand_get_entropy().  The seeding buffer is pointed to by I<buf> and is
-of length I<len> bytes.
+ossl_rand_get_entropy() or ossl_rand_get_user_entropy().  The entropy
+buffer is pointed to by I<buf> and is of length I<len> bytes.
 
 ossl_rand_get_nonce() retrieves a nonce using the passed I<salt> parameter
 of length I<salt_len> and operating system specific information.
@@ -41,18 +52,34 @@ The output is stored in a buffer which contains at least I<min_len> and at
 most I<max_len> bytes.  The buffer address is stored in I<*pout> and the
 buffer length returned to the caller.
 
+ossl_rand_get_user_nonce() is the same as ossl_rand_get_nonce() except
+that it retrieves the seeding material from the library context's DRBG
+seed source.  By default this is the operating system but it can be
+changed by calling L<RAND_set_seed_source_type(3)>.
+
 ossl_rand_cleanup_nonce() cleanses and frees any storage allocated by
-ossl_rand_get_nonce().  The nonce buffer is pointed to by I<buf> and is
-of length I<len> bytes.
+ossl_rand_get_nonce() or ossl_rand_get_user_nonce().  The nonce buffer
+is pointed to by I<buf> and is of length I<len> bytes.
+
+=head1 NOTES
+
+FIPS providers 3.0.0, 3.0.8 and 3.0.9 incorrectly pass a provider
+internal pointer to ossl_rand_get_entropy(), ossl_rand_cleanup_entropy(),
+ossl_rand_get_nonce() and ossl_rand_cleanup_nonce().  This pointer cannot
+be safely dereferenced.
 
 =head1 RETURN VALUES
 
-ossl_rand_get_entropy() and ossl_rand_get_nonce() return the number of bytes
-in I<*pout> or 0 on error.
+ossl_rand_get_entropy(), ossl_rand_get_user_entropy(),
+ossl_rand_get_nonce() and ossl_rand_get_user_nonce() return the number
+of bytes in I<*pout> or 0 on error.
 
 =head1 HISTORY
 
-The functions described here were all added in OpenSSL 3.0.
+The functions ossl_rand_get_user_entropy() and ossl_rand_get_user_nonce()
+were added in OpenSSL 3.0.12, 3.1.4 and 3.2.0.
+
+The remaining functions described here were all added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-- 
cgit v1.2.3