doc: Documentation changes for moving the entropy source out of the fips provider

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/13226)

5 files changed, 108 insertions, 6 deletions

diff --git a/doc/internal/man3/ossl_rand_get_entropy.pod b/doc/internal/man3/ossl_rand_get_entropy.pod
new file mode 100644
index 0000000000..4da3f1f4d9
--- /dev/null
+++ b/doc/internal/man3/ossl_rand_get_entropy.pod
@@ -0,0 +1,66 @@
+=pod
+
+=head1 NAME
+
+ossl_rand_get_entropy, ossl_rand_cleanup_entropy,
+ossl_rand_get_nonce, ossl_rand_cleanup_nonce
+- get seed material from the operating system
+
+=head1 SYNOPSIS
+
+ #include "crypto/rand.h"
+
+ size_t ossl_rand_get_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);
+ void ossl_rand_cleanup_nonce(OSSL_CORE_HANDLE *handle,
+                              unsigned char *buf, size_t len);
+
+=head1 DESCRIPTION
+
+ossl_rand_get_entropy() retrieves seeding material from the operating system.
+The seeding material will have at least I<entropy> bytes of randomness and 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 is
+returned to the caller.
+
+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_nonce() retrieves a nonce using the passed I<salt> parameter
+of length I<salt_len> and operating system specific information.
+The I<salt> should contain uniquely identifying information and this is
+included, in an unspecified manner, as part of the output.
+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_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.
+
+=head1 RETURN VALUES
+
+ossl_rand_get_entropy() and ossl_rand_get_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.
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_RAND-CTR-DRBG.pod b/doc/man7/EVP_RAND-CTR-DRBG.pod
index d8e2d4f2aa..a31b22390a 100644
--- a/doc/man7/EVP_RAND-CTR-DRBG.pod
+++ b/doc/man7/EVP_RAND-CTR-DRBG.pod
@@ -24,12 +24,12 @@ The supported parameters are:
 
 =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
 
+=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer>
+
 =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
 
 =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
 
-=item "max_request" (B<OSSL_DRBG_PARAM_MAX_REQUEST>) <unsigned integer>
-
 =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
 
 =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
diff --git a/doc/man7/EVP_RAND-HASH-DRBG.pod b/doc/man7/EVP_RAND-HASH-DRBG.pod
index b85010dd41..631383c74a 100644
--- a/doc/man7/EVP_RAND-HASH-DRBG.pod
+++ b/doc/man7/EVP_RAND-HASH-DRBG.pod
@@ -24,12 +24,12 @@ The supported parameters are:
 
 =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
 
+=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer>
+
 =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
 
 =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
 
-=item "max_request" (B<OSSL_DRBG_PARAM_MAX_REQUEST>) <unsigned integer>
-
 =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
 
 =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
diff --git a/doc/man7/EVP_RAND-HMAC-DRBG.pod b/doc/man7/EVP_RAND-HMAC-DRBG.pod
index e9620783b0..f04ae336fc 100644
--- a/doc/man7/EVP_RAND-HMAC-DRBG.pod
+++ b/doc/man7/EVP_RAND-HMAC-DRBG.pod
@@ -24,12 +24,12 @@ The supported parameters are:
 
 =item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
 
+=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer>
+
 =item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
 
 =item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
 
-=item "max_request" (B<OSSL_DRBG_PARAM_MAX_REQUEST>) <unsigned integer>
-
 =item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
 
 =item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
index 536c5ed430..7e8f5188a5 100644
--- a/doc/man7/provider-base.pod
+++ b/doc/man7/provider-base.pod
@@ -65,6 +65,16 @@ provider-base
 
  void self_test_cb(OPENSSL_CORE_CTX *ctx, OSSL_CALLBACK **cb, void **cbarg)
 
+ size_t get_entropy(const OSSL_CORE_HANDLE *handle,
+                    unsigned char **pout, int entropy,
+                    size_t min_len, size_t max_len)
+ void cleanup_entropy(const OSSL_CORE_HANDLE *handle,
+                      unsigned char *buf, size_t len)
+ size_t get_nonce(const OSSL_CORE_HANDLE *handle,
+                  unsigned char **pout, size_t min_len, size_t max_len,
+                  const void *salt, size_t salt_len)
+ void cleanup_nonce(const OSSL_CORE_HANDLE *handle,
+                    unsigned char *buf, size_t len)
 
  /* Functions offered by the provider to libcrypto */
  void provider_teardown(void *provctx);
@@ -129,6 +139,10 @@ provider):
  BIO_vprintf                    OSSL_FUNC_BIO_VPRINTF
  OPENSSL_cleanse                OSSL_FUNC_OPENSSL_CLEANSE
  OSSL_SELF_TEST_set_callback    OSSL_FUNC_SELF_TEST_CB
+ ossl_rand_get_entropy          OSSL_FUNC_GET_ENTROPY
+ ossl_rand_cleanup_entropy      OSSL_FUNC_CLEANUP_ENTROPY
+ ossl_rand_get_nonce            OSSL_FUNC_GET_NONCE
+ ossl_rand_cleanup_nonce        OSSL_FUNC_CLEANUP_NONCE
 
 For I<*out> (the B<OSSL_DISPATCH> array passed from the provider to
 F<libcrypto>):
@@ -210,6 +224,28 @@ side (the two are not compatible).
 OSSL_SELF_TEST_set_callback() is used to set an optional callback that can be
 passed into a provider. This may be ignored by a provider.
 
+get_entropy() retrieves seeding material from the operating system.
+The seeding material will have at least I<entropy> bytes of randomness and the
+output will have 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.  On error, zero is returned.
+
+cleanup_entropy() is used to clean up and free the buffer returned by
+get_entropy().  The entropy pointer returned by get_entropy() is passed in
+B<buf> and its length in B<len>.
+
+get_nonce() retrieves a nonce using the passed I<salt> parameter
+of length I<salt_len> and operating system specific information.
+The I<salt> should contain uniquely identifying information and this is
+included, in an unspecified manner, as part of the output.
+The output is stored in a buffer which contrains 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.  On error, zero is returned.
+
+cleanup_nonce() is used to clean up and free the buffer returned by
+get_nonce().  The nonce pointer returned by get_nonce() is passed in
+B<buf> and its length in B<len>.
+
 =head2 Provider functions
 
 provider_teardown() is called when a provider is shut down and removed