rand: add a provider side seed source.

This allows the operating system sources that OpenSSL supports to be
used directly as RNGs.  It also allows DRBG seeding to be explicitly
specified rather than being left to a fall back case.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13455)

2 files changed, 97 insertions, 0 deletions

diff --git a/doc/man5/config.pod b/doc/man5/config.pod
index 0a28f4ea4b..45165f20ec 100644
--- a/doc/man5/config.pod
+++ b/doc/man5/config.pod
@@ -438,6 +438,16 @@ generators will use.  Other random bit generators ignore this name.
 This sets the property query used when fetching the random bit generator and
 any underlying algorithms.
 
+=item B<seed>
+
+This sets the randomness source that should be used.  By default B<SEED-SRC>
+will be used outside of the FIPS provider.  The FIPS provider uses call backs
+to access the same randomness sources from outside the validated boundary.
+
+=item B<seed_properties>
+
+This sets the property query used when fetching the randomness source.
+
 =back
 
 =head1 EXAMPLES
diff --git a/doc/man7/EVP_RAND-SEED-SRC.pod b/doc/man7/EVP_RAND-SEED-SRC.pod
new file mode 100644
index 0000000000..f301ed25f9
--- /dev/null
+++ b/doc/man7/EVP_RAND-SEED-SRC.pod
@@ -0,0 +1,87 @@
+=pod
+
+=head1 NAME
+
+EVP_RAND-SEED-SRC - The randomness seed source EVP_RAND implementation
+
+=head1 DESCRIPTION
+
+Support for deterministic random number generator seeding through the
+B<EVP_RAND> API.
+
+The seed sources used are specified at the time OpenSSL is configured for
+building using the B<--with-rand-seed=> option.  By default, operating system
+randomness sources are used.
+
+=head2 Identity
+
+"SEED-SRC" is the name for this implementation; it can be used with the
+EVP_RAND_fetch() function.
+
+=head2 Supported parameters
+
+The supported parameters are:
+
+=over 4
+
+=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
+
+=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
+
+=item "max_request" (B<OSSL_RAND_PARAM_MAX_REQUEST>) <unsigned integer>
+
+These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
+
+=back
+
+=head1 NOTES
+
+A context for the seed source can be obtained by calling:
+
+ EVP_RAND *rand = EVP_RAND_fetch(NULL, "SEED-SRC", NULL);
+ EVP_RAND_CTX *rctx = EVP_RAND_CTX_new(rand);
+
+=head1 EXAMPLES
+
+ EVP_RAND *rand;
+ EVP_RAND_CTX *seed, *rctx;
+ unsigned char bytes[100];
+ OSSL_PARAM params[2], *p = params;
+ unsigned int strength = 128;
+
+ /* Create a seed source */
+ rand = EVP_RAND_fetch(NULL, "SEED-SRC", NULL);
+ seed = EVP_RAND_CTX_new(rand, NULL);
+ EVP_RAND_free(rand);
+
+ /* Feed this into a DRBG */
+ rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
+ rctx = EVP_RAND_CTX_new(rand, seed);
+ EVP_RAND_free(rand);
+
+ /* Configure the DRBG */
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_DRBG_PARAM_CIPHER,
+                                         SN_aes_256_ctr, 0);
+ *p = OSSL_PARAM_construct_end();
+ EVP_RAND_set_ctx_params(rctx, params);
+
+ EVP_RAND_generate(rctx, bytes, sizeof(bytes), strength, 0, NULL, 0);
+
+ EVP_RAND_CTX_free(rctx);
+ EVP_RAND_CTX_free(seed);
+
+=head1 SEE ALSO
+
+L<EVP_RAND(3)>,
+L<EVP_RAND(3)/PARAMETERS>
+
+=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