evp_rand: documentation

EVP_RAND, the RNGs and provider-rand.

Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/11682)

15 files changed, 1174 insertions, 56 deletions

diff --git a/crypto/rand/build.info b/crypto/rand/build.info
index b7a4d598f1..7776ca8820 100644
--- a/crypto/rand/build.info
+++ b/crypto/rand/build.info
@@ -1,7 +1,7 @@
 LIBS=../../libcrypto
 
 $COMMON=drbg_lib.c rand_lib.c
-$CRYPTO=randfile.c rand_err.c
+$CRYPTO=randfile.c rand_err.c rand_deprecated.c
 
 IF[{- !$disabled{'egd'} -}]
   $CRYPTO=$CRYPTO rand_egd.c
diff --git a/crypto/rand/rand_deprecated.c b/crypto/rand/rand_deprecated.c
new file mode 100644
index 0000000000..dd69f1beb7
--- /dev/null
+++ b/crypto/rand/rand_deprecated.c
@@ -0,0 +1,35 @@
+/*
+ * Copyright 1995-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
+ * https://www.openssl.org/source/license.html
+ */
+
+#include <e_os.h>
+#include <openssl/macros.h>
+#include <openssl/rand.h>
+
+#if defined(OPENSSL_SYS_WINDOWS) || defined(OPENSSL_SYS_WIN32)
+# include <windows.h>
+# if OPENSSL_API_COMPAT < 0x10100000L
+
+# define DEPRECATED_RAND_FUNCTIONS_DEFINED
+
+int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam)
+{
+    RAND_poll();
+    return RAND_status();
+}
+
+void RAND_screen(void)
+{
+    RAND_poll();
+}
+# endif
+#endif
+
+#ifndef DEPRECATED_RAND_FUNCTIONS_DEFINED
+NON_EMPTY_TRANSLATION_UNIT
+#endif
diff --git a/doc/man1/openssl-list.pod.in b/doc/man1/openssl-list.pod.in
index d7e062bf01..1eb62d3feb 100644
--- a/doc/man1/openssl-list.pod.in
+++ b/doc/man1/openssl-list.pod.in
@@ -16,6 +16,7 @@ B<openssl list>
 [B<-digest-algorithms>]
 [B<-kdf-algorithms>]
 [B<-mac-algorithms>]
+[B<-random-generators>]
 [B<-cipher-commands>]
 [B<-cipher-algorithms>]
 [B<-public-key-algorithms>]
@@ -73,6 +74,16 @@ displayed.
 In verbose mode, the algorithms provided by a provider will get additional
 information on what parameters each implementation supports.
 
+=item B<-random-generators>
+
+Display a list of random number generators.
+
+See L</Display of algorithm names> for a description of how names are
+displayed.
+
+In verbose mode, the algorithms provided by a provider will get additional
+information on what parameters each implementation supports.
+
 =item B<-public-key-algorithms>
 
 Display a list of public key algorithms, with each algorithm as
diff --git a/doc/man3/EVP_RAND.pod b/doc/man3/EVP_RAND.pod
new file mode 100644
index 0000000000..c32217543e
--- /dev/null
+++ b/doc/man3/EVP_RAND.pod
@@ -0,0 +1,379 @@
+=pod
+
+=head1 NAME
+
+EVP_RAND, EVP_RAND_fetch, EVP_RAND_free, EVP_RAND_up_ref, EVP_RAND_CTX,
+EVP_RAND_CTX_new, EVP_RAND_CTX_free, EVP_RAND_instantiate,
+EVP_RAND_uninstantiate, EVP_RAND_generate, EVP_RAND_reseed,
+EVP_RAND_nonce, EVP_RAND_enable_locking, EVP_RAND_set_callbacks,
+EVP_RAND_verify_zeroization, EVP_RAND_strength, EVP_RAND_state,
+EVP_RAND_provider, EVP_RAND_CTX_rand, EVP_RAND_is_a, EVP_RAND_number,
+EVP_RAND_name, EVP_RAND_names_do_all, EVP_RAND_get_ctx_params,
+EVP_RAND_set_ctx_params, EVP_RAND_do_all_provided, EVP_RAND_get_params,
+EVP_RAND_gettable_ctx_params, EVP_RAND_settable_ctx_params,
+EVP_RAND_gettable_params, EVP_RAND_STATE_UNINITIALISED, EVP_RAND_STATE_READY,
+EVP_RAND_STATE_ERROR - EVP RAND routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/evp.h>
+
+ typedef struct evp_rand_st EVP_RAND;
+ typedef struct evp_rand_ctx_st EVP_RAND_CTX;
+
+ EVP_RAND *EVP_RAND_fetch(OPENSSL_CTX *libctx, const char *algorithm,
+                        const char *properties);
+ int EVP_RAND_up_ref(EVP_RAND *rand);
+ void EVP_RAND_free(EVP_RAND *rand);
+ EVP_RAND_CTX *EVP_RAND_CTX_new(EVP_RAND *rand, EVP_RAND_CTX *parent);
+ void EVP_RAND_CTX_free(EVP_RAND_CTX *ctx);
+ EVP_RAND *EVP_RAND_CTX_rand(EVP_RAND_CTX *ctx);
+ int EVP_RAND_get_params(EVP_RAND *rand, OSSL_PARAM params[]);
+ int EVP_RAND_get_ctx_params(EVP_RAND_CTX *ctx, OSSL_PARAM params[]);
+ int EVP_RAND_set_ctx_params(EVP_RAND_CTX *ctx, const OSSL_PARAM params[]);
+ const OSSL_PARAM *EVP_RAND_gettable_params(const EVP_RAND *rand);
+ const OSSL_PARAM *EVP_RAND_gettable_ctx_params(const EVP_RAND *rand);
+ const OSSL_PARAM *EVP_RAND_settable_ctx_params(const EVP_RAND *rand);
+ int EVP_RAND_number(const EVP_RAND *rand);
+ const char *EVP_RAND_name(const EVP_RAND *rand);
+ int EVP_RAND_is_a(const EVP_RAND *rand, const char *name);
+ const OSSL_PROVIDER *EVP_RAND_provider(const EVP_RAND *rand);
+ void EVP_RAND_do_all_provided(OPENSSL_CTX *libctx,
+                               void (*fn)(EVP_RAND *rand, void *arg),
+                               void *arg);
+ void EVP_RAND_names_do_all(const EVP_RAND *rand,
+                            void (*fn)(const char *name, void *data),
+                            void *data);
+
+ int EVP_RAND_instantiate(EVP_RAND_CTX *ctx, unsigned int strength,
+                          int prediction_resistance,
+                          const unsigned char *pstr, size_t pstr_len);
+ int EVP_RAND_uninstantiate(EVP_RAND_CTX *ctx);
+ int EVP_RAND_generate(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen,
+                       unsigned int strength, int prediction_resistance,
+                       const unsigned char *addin, size_t addin_len);
+ int EVP_RAND_reseed(EVP_RAND_CTX *ctx, int prediction_resistance,
+                     const unsigned char *ent, size_t ent_len,
+                     const unsigned char *addin, size_t addin_len);
+ int EVP_RAND_nonce(EVP_RAND_CTX *ctx, unsigned char *out, size_t outlen);
+ int EVP_RAND_enable_locking(EVP_RAND_CTX *ctx);
+ int EVP_RAND_set_callbacks(EVP_RAND_CTX *ctx, OSSL_CALLBACK *get_entropy,
+                            OSSL_CALLBACK *cleanup_entropy,
+                            OSSL_CALLBACK *get_nonce,
+                            OSSL_CALLBACK *cleanup_nonce, void *arg);
+ int EVP_RAND_verify_zeroization(EVP_RAND_CTX *ctx);
+ unsigned int EVP_RAND_strength(EVP_RAND_CTX *ctx);
+ int EVP_RAND_state(EVP_RAND_CTX *ctx);
+
+ #define EVP_RAND_STATE_UNINITIALISED    0
+ #define EVP_RAND_STATE_READY            1
+ #define EVP_RAND_STATE_ERROR            2
+
+=head1 DESCRIPTION
+
+The EVP RAND routines are a high level interface to random number generators
+both deterministic and not.
+If you just want to generate random bytes then you don't need to use
+these functions: just call RAND_bytes() or RAND_priv_bytes().
+If you want to do more, these calls should be used instead of the older
+RAND and RAND_DRBG functions.
+
+After creating a B<EVP_RAND_CTX> for the required algorithm using
+EVP_RAND_CTX_new(), inputs to the algorithm are supplied
+using calls to EVP_RAND_set_ctx_params() before
+calling EVP_RAND_instantiate() and then EVP_RAND_generate() to produce
+cryptographically secure random bytes.
+
+=head2 Types
+
+B<EVP_RAND> is a type that holds the implementation of a RAND.
+
+B<EVP_RAND_CTX> is a context type that holds the algorithm inputs.
+
+=head2 Algorithm implementation fetching
+
+EVP_RAND_fetch() fetches an implementation of a RAND I<algorithm>, given
+a library context I<libctx> and a set of I<properties>.
+See L<provider(7)/Fetching algorithms> for further information.
+
+The returned value must eventually be freed with
+L<EVP_RAND_free(3)>.
+
+EVP_RAND_up_ref() increments the reference count of an already fetched
+RAND.
+
+EVP_RAND_free() frees a fetched algorithm.
+NULL is a valid parameter, for which this function is a no-op.
+
+=head2 Context manipulation functions
+
+EVP_RAND_CTX_new() creates a new context for the RAND implementation I<rand>.
+If not NULL, I<parent> specifies the seed source for this implementation.
+Not all random number generators need to have a seed source specified.
+If a parent is required, a NULL I<parent> will utilise the operating
+system entropy sources.
+It is recommended to minimise the number of random number generators that
+rely on the operating system for their randomness because this is often scarce.
+
+EVP_RAND_CTX_free() frees up the context I<ctx>.  If I<ctx> is NULL, nothing
+is done.
+
+EVP_RAND_CTX_rand() returns the B<EVP_RAND> associated with the context
+I<ctx>.
+
+=head2 Random Number Generator Functions
+
+EVP_RAND_instantiate() instantiates the RAND I<ctx> with a minimum security
+strength of <strength> and personalisation string I<pstr> of length <pstr_len>.
+If I<prediction_resistance> is specified, fresh entropy from a live source
+will be sought.  This call operates as per NIST SP 800-90A and SP 800-90C.
+
+EVP_RAND_uninstantiate() uninstantiates the RAND I<ctx> as per
+NIST SP 800-90A and SP 800-90C.  Subsequent to this call, the RAND cannot
+be used to generate bytes.  It can only be freed or instantiated again.
+
+EVP_RAND_generate() produces random bytes from the RAND I<ctx> with the
+additional input I<addin> of length I<addin_len>.  The bytes
+produced will meet the security I<strength>.
+If I<prediction_resistance> is specified, fresh entropy from a live source
+will be sought.  This call operates as per NIST SP 800-90A and SP 800-90C.
+
+EVP_RAND_reseed() reseeds the RAND with new entropy.
+Entropy I<ent> of length I<ent_len> bytes can be supplied as can additional
+input I<addin> of length I<addin_len> bytes.  In the FIPS provider, both are
+treated as additional input as per NIST SP-800-90Ar1, Sections 9.1 and 9.2.
+Additional seed material is also drawn from the RAND's parent or the
+operating system.  If I<prediction_resistance> is specified, fresh entropy
+from a live source will be sought.  This call operates as per NIST SP 800-90A
+and SP 800-90C.
+
+EVP_RAND_nonce() creates a nonce in I<out> of maximum length I<outlen>
+bytes from the RAND I<ctx>. The function returns the length of the generated
+nonce. If I<out> is NULL, the length is still returned but no generation
+takes place. This allows a caller to dynamically allocate a buffer of the
+appropriate size.
+
+EVP_RAND_enable_locking() enables locking for the RAND I<ctx> and all of
+its parents.  After this I<ctx> will operate in a thread safe manner, albeit
+more slowly.
+
+EVP_RAND_set_callbacks() sets callbacks on the RAND I<ctx> to accept
+external entropy and nonce input.  The callback I<get_entropy> fills a buffer
+with new randomness and the callback I<cleanup_entropy> clears and frees the
+buffer.  Likewise for I<get_nonce> and I<cleanup_nonce>.  In all cases the
+callbacks are passed I<arg> in addition to an OSSL_PARAM array.
+
+EVP_RAND_get_params() retrieves details about the implementation
+I<rand>.
+The set of parameters given with I<params> determine exactly what
+parameters should be retrieved.
+Note that a parameter that is unknown in the underlying context is
+simply ignored.
+
+EVP_RAND_get_ctx_params() retrieves chosen parameters, given the
+context I<ctx> and its underlying context.
+The set of parameters given with I<params> determine exactly what
+parameters should be retrieved.
+Note that a parameter that is unknown in the underlying context is
+simply ignored.
+
+EVP_RAND_set_ctx_params() passes chosen parameters to the underlying
+context, given a context I<ctx>.
+The set of parameters given with I<params> determine exactly what
+parameters are passed down.
+Note that a parameter that is unknown in the underlying context is
+simply ignored.
+Also, what happens when a needed parameter isn't passed down is
+defined by the implementation.
+
+EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
+EVP_RAND_settable_ctx_params() get a constant B<OSSL_PARAM> array that
+describes the retrievable and settable parameters, i.e. parameters that
+can be used with EVP_RAND_get_params(), EVP_RAND_get_ctx_params()
+and EVP_RAND_set_ctx_params(), respectively.
+See L<OSSL_PARAM(3)> for the use of B<OSSL_PARAM> as parameter descriptor.
+
+=head2 Information functions
+
+EVP_RAND_strength() returns the security strength of the RAND I<ctx>.
+
+EVP_RAND_state() returns the current state of the RAND I<ctx>.
+States defined by the OpenSSL DRBGs are:
+
+=over 4
+
+=item *
+
+EVP_RAND_STATE_UNINITIALISED: this DRBG is currently uninitalised.
+The instantiate call will change this to the ready state.
+
+=item *
+
+EVP_RAND_STATE_READY: this DRBG is currently ready to generate output.
+
+=item *
+
+EVP_RAND_STATE_ERROR: this DRBG is in an error state.
+
+=back
+
+EVP_RAND_is_a() returns 1 if I<rand> is an implementation of an
+algorithm that's identifiable with I<name>, otherwise 0.
+
+EVP_RAND_provider() returns the provider that holds the implementation
+of the given I<rand>.
+
+EVP_RAND_do_all_provided() traverses all RAND implemented by all activated
+providers in the given library context I<libctx>, and for each of the
+implementations, calls the given function I<fn> with the implementation method
+and the given I<arg> as argument.
+
+EVP_RAND_number() returns the internal dynamic number assigned to
+I<rand>.
+
+EVP_RAND_name() returns the canonical name of I<rand>.
+
+EVP_RAND_names_do_all() traverses all names for I<rand>, and calls
+I<fn> with each name and I<data>.
+
+EVP_RAND_verify_zeroization() confirms if the internal DRBG state is
+currently zeroed.  This is used by the FIPS provider to support the mandatory
+self tests.
+
+=head1 PARAMETERS
+
+The standard parameter names are:
+
+=over 4
+
+=item "state" (B<OSSL_RAND_PARAM_STATE>) <integer>
+
+Returns the state of the random number generator.
+
+=item "strength" (B<OSSL_RAND_PARAM_STRENGTH>) <unsigned integer>
+
+Returns the bit strength of the random number generator.
+
+=back
+
+For rands that are also deterministic random bit generators (DRBGs), these
+additional parameters are recognised. Not all
+parameters are relevant to, or are understood by all DRBG rands:
+
+=over 4
+
+=item "reseed_requests" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
+
+Reads or set the number of generate requests before reseeding the
+associated RAND ctx.
+
+=item "reseed_time_interval" (B<OSSL_DRBG_PARAM_RESEED_TIME_INTERVAL>) <integer>
+
+Reads or set the number of elapsed seconds before reseeding the
+associated RAND ctx.
+
+=item "max_request" (B<OSSL_DRBG_PARAM_RESEED_REQUESTS>) <unsigned integer>
+
+Specifies the maximum number of bytes that can be generated in a single
+call to OP_rand_generate.
+
+=item "min_entropylen" (B<OSSL_DRBG_PARAM_MIN_ENTROPYLEN>) <unsigned integer>
+
+=item "max_entropylen" (B<OSSL_DRBG_PARAM_MAX_ENTROPYLEN>) <unsigned integer>
+
+Specify the minimum and maximum number of bytes of random material that
+can be used to seed the DRBG.
+
+=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
+
+=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
+
+Specify the minimum and maximum number of bytes of nonce that can be used to
+seed the DRBG.
+
+=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
+
+=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
+
+Specify the minimum and maximum number of bytes of personalisation string
+that can be used with the DRBG.
+
+=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
+
+Specifies the number of times the DRBG has been seeded or reseeded.
+
+=item "properties" (B<OSSL_RAND_PARAM_PROPERTIES>) <UTF8 string>
+
+=item "mac" (B<OSSL_RAND_PARAM_MAC>) <UTF8 string>
+
+=item "digest" (B<OSSL_RAND_PARAM_DIGEST>) <UTF8 string>
+
+=item "cipher" (B<OSSL_RAND_PARAM_CIPHER>) <UTF8 string>
+
+For RAND implementations that use an underlying computation MAC, digest or
+cipher, these parameters set what the algorithm should be.
+
+The value is always the name of the intended algorithm,
+or the properties in the case of B<OSSL_RAND_PARAM_PROPERTIES>.
+
+=back
+
+=head1 RETURN VALUES
+
+EVP_RAND_fetch() returns a pointer to a newly fetched B<EVP_RAND>, or
+NULL if allocation failed.
+
+EVP_RAND_provider() returns a pointer to the provider for the RAND, or
+NULL on error.
+
+EVP_RAND_CTX_rand() returns a pointer to the B<EVP_RAND> associated with the
+context.
+
+EVP_RAND_name() returns the name of the random number generation algorithm.
+
+EVP_RAND_number() returns the provider specific identification number
+for the specified algorithm.
+
+EVP_RAND_up_ref() returns 1 on success, 0 on error.
+
+EVP_RAND_CTX_new() returns either the newly allocated
+B<EVP_RAND_CTX> structure or NULL if an error occurred.
+
+EVP_RAND_CTX_free() does not return a value.
+
+EVP_RAND_nonce() returns the length of the nonce.
+
+EVP_RAND_strength() returns the strenght of the random number generator in bits.
+
+EVP_RAND_gettable_params(), EVP_RAND_gettable_ctx_params() and
+EVP_RAND_settable_ctx_params() return an array of OSSL_PARAMs.
+
+EVP_RAND_verify_zeroization() returns 1 if the internal DRBG state is
+currently zeroed, and 0 if not.
+
+The remaining functions return 1 for success and 0 or a negative value for
+failure.
+
+=head1 SEE ALSO
+
+L<RAND_bytes(3)>,
+L<EVP_RAND-CTR-DRBG(7)>,
+L<EVP_RAND-HASH-DRBG(7)>,
+L<EVP_RAND-HMAC-DRBG(7)>,
+L<EVP_RAND-TEST-RAND(7)>,
+L<provider-rand(7)>
+
+=head1 HISTORY
+
+This functionality was added to 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/man3/OSSL_PARAM_BLD.pod b/doc/man3/OSSL_PARAM_BLD.pod
index ed82e32073..844b715820 100644
--- a/doc/man3/OSSL_PARAM_BLD.pod
+++ b/doc/man3/OSSL_PARAM_BLD.pod
@@ -8,10 +8,10 @@ OSSL_PARAM_BLD_push_uint, OSSL_PARAM_BLD_push_long,
 OSSL_PARAM_BLD_push_ulong, OSSL_PARAM_BLD_push_int32,
 OSSL_PARAM_BLD_push_uint32, OSSL_PARAM_BLD_push_int64,
 OSSL_PARAM_BLD_push_uint64, OSSL_PARAM_BLD_push_size_t,
-OSSL_PARAM_BLD_push_double, OSSL_PARAM_BLD_push_BN,
-OSSL_PARAM_BLD_push_BN_pad, OSSL_PARAM_BLD_push_utf8_string,
-OSSL_PARAM_BLD_push_utf8_ptr, OSSL_PARAM_BLD_push_octet_string,
-OSSL_PARAM_BLD_push_octet_ptr
+OSSL_PARAM_BLD_push_time_t, OSSL_PARAM_BLD_push_double,
+OSSL_PARAM_BLD_push_BN, OSSL_PARAM_BLD_push_BN_pad,
+OSSL_PARAM_BLD_push_utf8_string, OSSL_PARAM_BLD_push_utf8_ptr,
+OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
 - functions to assist in the creation of OSSL_PARAM arrays
 
 =head1 SYNOPSIS
diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod
index ca4e9d066e..7aa6b9377f 100644
--- a/doc/man3/OSSL_PARAM_int.pod
+++ b/doc/man3/OSSL_PARAM_int.pod
@@ -3,31 +3,33 @@
 =head1 NAME
 
 OSSL_PARAM_double, OSSL_PARAM_int, OSSL_PARAM_int32, OSSL_PARAM_int64,
-OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint, OSSL_PARAM_uint32,
-OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN, OSSL_PARAM_utf8_string,
-OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr, OSSL_PARAM_octet_ptr,
+OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint,
+OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN,
+OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr,
+OSSL_PARAM_octet_ptr,
 OSSL_PARAM_END,
 OSSL_PARAM_construct_double, OSSL_PARAM_construct_int,
 OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64,
-OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t, OSSL_PARAM_construct_time_t,
-OSSL_PARAM_construct_uint, OSSL_PARAM_construct_uint32,
-OSSL_PARAM_construct_uint64, OSSL_PARAM_construct_ulong,
-OSSL_PARAM_construct_BN, OSSL_PARAM_construct_utf8_string,
-OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_octet_string,
-OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_construct_end,
+OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t,
+OSSL_PARAM_construct_time_t, OSSL_PARAM_construct_uint,
+OSSL_PARAM_construct_uint32, OSSL_PARAM_construct_uint64,
+OSSL_PARAM_construct_ulong, OSSL_PARAM_construct_BN,
+OSSL_PARAM_construct_utf8_string, OSSL_PARAM_construct_utf8_ptr,
+OSSL_PARAM_construct_octet_string, OSSL_PARAM_construct_octet_ptr,
+OSSL_PARAM_construct_end,
 OSSL_PARAM_locate, OSSL_PARAM_locate_const,
 OSSL_PARAM_get_double, OSSL_PARAM_get_int, OSSL_PARAM_get_int32,
-OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t, OSSL_PARAM_get_time_t,
-OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32, OSSL_PARAM_get_uint64,
-OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN, OSSL_PARAM_get_utf8_string,
-OSSL_PARAM_get_octet_string, OSSL_PARAM_get_utf8_ptr,
-OSSL_PARAM_get_octet_ptr,
+OSSL_PARAM_get_int64, OSSL_PARAM_get_long, OSSL_PARAM_get_size_t,
+OSSL_PARAM_get_time_t, OSSL_PARAM_get_uint, OSSL_PARAM_get_uint32,
+OSSL_PARAM_get_uint64, OSSL_PARAM_get_ulong, OSSL_PARAM_get_BN,
+OSSL_PARAM_get_utf8_string, OSSL_PARAM_get_octet_string,
+OSSL_PARAM_get_utf8_ptr, OSSL_PARAM_get_octet_ptr,
 OSSL_PARAM_set_double, OSSL_PARAM_set_int, OSSL_PARAM_set_int32,
-OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t, OSSL_PARAM_set_time_t,
-OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32, OSSL_PARAM_set_uint64,
-OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN, OSSL_PARAM_set_utf8_string,
-OSSL_PARAM_set_octet_string, OSSL_PARAM_set_utf8_ptr,
-OSSL_PARAM_set_octet_ptr,
+OSSL_PARAM_set_int64, OSSL_PARAM_set_long, OSSL_PARAM_set_size_t,
+OSSL_PARAM_set_time_t, OSSL_PARAM_set_uint, OSSL_PARAM_set_uint32,
+OSSL_PARAM_set_uint64, OSSL_PARAM_set_ulong, OSSL_PARAM_set_BN,
+OSSL_PARAM_set_utf8_string, OSSL_PARAM_set_octet_string,
+OSSL_PARAM_set_utf8_ptr, OSSL_PARAM_set_octet_ptr,
 OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified
 - OSSL_PARAM helpers
 
diff --git a/doc/man3/RAND_DRBG_new.pod b/doc/man3/RAND_DRBG_new.pod
index cd770fd673..7d7cdbad44 100644
--- a/doc/man3/RAND_DRBG_new.pod
+++ b/doc/man3/RAND_DRBG_new.pod
@@ -4,13 +4,12 @@
 
 RAND_DRBG_new_ex,
 RAND_DRBG_new,
-RAND_DRBG_secure_new_ex,
-RAND_DRBG_secure_new,
 RAND_DRBG_set,
 RAND_DRBG_set_defaults,
 RAND_DRBG_instantiate,
 RAND_DRBG_uninstantiate,
-RAND_DRBG_free
+RAND_DRBG_free,
+RAND_DRBG_verify_zeroization
 - initialize and cleanup a RAND_DRBG instance
 
 =head1 SYNOPSIS
@@ -26,15 +25,6 @@ RAND_DRBG_free
                           unsigned int flags,
                           RAND_DRBG *parent);
 
- RAND_DRBG *RAND_DRBG_secure_new_ex(OPENSSL_CTX *ctx,
-                                    int type,
-                                    unsigned int flags,
-                                    RAND_DRBG *parent);
-
- RAND_DRBG *RAND_DRBG_secure_new(int type,
-                                 unsigned int flags,
-                                 RAND_DRBG *parent);
-
  int RAND_DRBG_set_defaults(int type, unsigned int flags);
 
  int RAND_DRBG_instantiate(RAND_DRBG *drbg,
@@ -43,6 +33,7 @@ RAND_DRBG_free
  int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
 
  void RAND_DRBG_free(RAND_DRBG *drbg);
+ int RAND_DRBG_verify_zeroization(RAND_DRBG *drbg);
 
 Deprecated since OpenSSL 3.0, can be hidden entirely by defining
 B<OPENSSL_API_COMPAT> with a suitable version value, see
@@ -53,14 +44,11 @@ L<openssl_user_macros(7)>:
 
 =head1 DESCRIPTION
 
-RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex() create a new DRBG instance
-of the given B<type> for the given OPENSSL_CTX <ctx>.
+RAND_DRBG_new_ex() creates a new DRBG instance of the given B<type> for the
+given OPENSSL_CTX <ctx>.
 The <ctx> parameter can be NULL in which case the default OPENSSL_CTX is used.
-RAND_DRBG_new() and RAND_DRBG_secure_new() are the same as RAND_DRBG_new_ex()
-and RAND_DRBG_secure_new_ex() except that the default OPENSSL_CTX is always
-used.
-As of OpenSSL 3.0, there is no different between the new and secure_new
-functions.
+RAND_DRBG_new() is the same as RAND_DRBG_new_ex() except that the default
+OPENSSL_CTX is always used.
 
 RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
 This function is deprecated.  Applications should instead use
@@ -114,7 +102,6 @@ the default entropy source for reseeding the B<drbg>. It is said that the
 B<drbg> is I<chained> to its B<parent>.
 For more information, see the NOTES section.
 
-
 RAND_DRBG_instantiate()
 seeds the B<drbg> instance using random input from trusted entropy sources.
 Optionally, a personalization string B<pers> of length B<perslen> can be
@@ -125,18 +112,23 @@ RAND_DRBG_uninstantiate()
 clears the internal state of the B<drbg> and puts it back in the
 uninstantiated state.
 
+RAND_DRBG_verify_zeroization() confirms if the internal DRBG state is
+currently zeroed.
+
 =head1 RETURN VALUES
 
 
-RAND_DRBG_new_ex(), RAND_DRBG_new(), RAND_DRBG_secure_new_ex() and
-RAND_DRBG_secure_new() return a pointer to a DRBG instance allocated on the
-heap.
+RAND_DRBG_new_ex() and RAND_DRBG_new() return a pointer to a DRBG instance
+allocated on the heap.
 
 RAND_DRBG_set(),
 RAND_DRBG_instantiate(), and
 RAND_DRBG_uninstantiate()
 return 1 on success, and 0 on failure.
 
+RAND_DRBG_verify_zeroization() returns 1 if the DRBG state is current zeroed,
+and 0 if not.
+
 RAND_DRBG_free() does not return a value.
 
 =head1 NOTES
@@ -155,15 +147,8 @@ To ensure that they are applied to the global and thread-local DRBG instances
 RAND_DRBG_set_defaults() before creating any thread and before calling any
 cryptographic routines that obtain random data directly or indirectly.
 
-As of OpenSSL 3.0, RAND_DRBG_new() and RAND_DRBG_secure_new() are
-functionally identical.  The DRBG is allocated on the normal heap and its
-sensitive state is allocated on the secure heap.  Likewise for,
-RAND_DRBG_new_ex() and RAND_DRBG_secure_new_ex().
-
 =head1 SEE ALSO
 
-L<OPENSSL_zalloc(3)>,
-L<OPENSSL_secure_zalloc(3)>,
 L<RAND_DRBG_generate(3)>,
 L<RAND_DRBG(7)>
 
diff --git a/doc/man3/RAND_DRBG_set_callbacks.pod b/doc/man3/RAND_DRBG_set_callbacks.pod
index 0ae3028a5a..543b3cc911 100644
--- a/doc/man3/RAND_DRBG_set_callbacks.pod
+++ b/doc/man3/RAND_DRBG_set_callbacks.pod
@@ -131,7 +131,7 @@ The derivation function is disabled by calling the RAND_DRBG_new_ex()
 function with the RAND_DRBG_FLAG_CTR_NO_DF flag.  For more information on
 the derivation function and when it can be omitted, see [NIST SP 800-90A
 Rev. 1]. Roughly speaking it can be omitted if the random source has "full
-entropy", i.e., contains 8 bits of entropy per byte. In a FIPS context,
+entropy", that is, it contains 8 bits of entropy per byte. In a FIPS context,
 the derivation function can never be omitted.
 
 Even if a nonce is required, the B<get_nonce>() and B<cleanup_nonce>()
diff --git a/doc/man3/RAND_add.pod b/doc/man3/RAND_add.pod
index b4151164c2..7eafe7bb53 100644
--- a/doc/man3/RAND_add.pod
+++ b/doc/man3/RAND_add.pod
@@ -69,7 +69,8 @@ chroot(2) jail without the associated device nodes being available. When
 the B<keep> argument is zero, this call disables the retention of file
 descriptors. Conversely, a nonzero argument enables the retention of
 file descriptors. This function is usually called during initialization
-and it takes effect immediately.
+and it takes effect immediately. This capability only applies to the default
+provider.
 
 RAND_event() and RAND_screen() are equivalent to RAND_poll() and exist
 for compatibility reasons only. See HISTORY section below.
diff --git a/doc/man7/EVP_RAND-CTR-DRBG.pod b/doc/man7/EVP_RAND-CTR-DRBG.pod
new file mode 100644
index 0000000000..e35703670f
--- /dev/null
+++ b/doc/man7/EVP_RAND-CTR-DRBG.pod
@@ -0,0 +1,108 @@
+=pod
+
+=head1 NAME
+
+EVP_RAND-CTR-DRBG - The CTR DRBG EVP_RAND implementation
+
+=head1 DESCRIPTION
+
+Support for the counter deterministic random bit generator through the
+B<EVP_RAND> API.
+
+=head2 Identity
+
+"CTR-DRBG" 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 "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>
+
+=item "min_noncelen" (B<OSSL_DRBG_PARAM_MIN_NONCELEN>) <unsigned integer>
+
+=item "max_noncelen" (B<OSSL_DRBG_PARAM_MAX_NONCELEN>) <unsigned integer>
+
+=item "max_perslen" (B<OSSL_DRBG_PARAM_MAX_PERSLEN>) <unsigned integer>
+
+=item "max_adinlen" (B<OSSL_DRBG_PARAM_MAX_ADINLEN>) <unsigned integer>
+
+=item "reseed_counter" (B<OSSL_DRBG_PARAM_RESEED_CTR>) <unsigned integer>
+
+=item "properties" (B<OSSL_DRBG_PARAM_PROPERTIES>) <UTF8 string>
+
+=item "cipher" (B<OSSL_DRBG_PARAM_CIPHER>) <UTF8 string>
+
+These parameters work as described in L<EVP_RAND(3)/PARAMETERS>.
+
+=item "use_derivation_function" (B<OSSL_DRBG_PARAM_USE_DF>) <int>
+
+This Boolean indicates if a derivation function should be used or not.
+A nonzero value (the default) uses the derivation function.  A zero value
+does not.  The FIPS provider always uses the derivation function and attempts
+to set this value result in an error.
+
+=back
+
+=head1 NOTES
+
+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);
+
+=head1 EXAMPLES
+
+ EVP_RAND *rand;
+ EVP_RAND_CTX *rctx;
+ unsigned char bytes[100];
+ OSSL_PARAM params[2], *p = params;
+ unsigned int strength = 128;
+
+ rand = EVP_RAND_fetch(NULL, "CTR-DRBG", NULL);
+ rctx = EVP_RAND_CTX_new(rand, NULL);
+ EVP_RAND_free(rand);
+
+ *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);
+
+=head1 CONFORMING TO
+
+NIST SP 800-90A and SP 800-90B
+
+=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
diff --git a/doc/man7/EVP_RAND-HASH-DRBG.pod b/doc/man7/EVP_RAND-HASH-DRBG.pod
new file mode 100644
index 0000000000..879384993e
--- /dev/null
+++ b/doc/man7/EVP_RAND-HASH-DRBG.pod
@@ -0,0 +1,100 @@
+=pod
+
+=head1 NAME
+
+EVP_RAND-HASH-DRBG - The HASH DRBG EVP_RAND implementation
+
+=head1 DESCRIPTION
+
+Support for the hash determinist