The RAND_DRBG API was added in PR #5462 and modified by PR #5547.
This commit adds the corresponding documention.
Reviewed-by: NKurt Roeckx <kurt@roeckx.be>
Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5461)

Reviewed-by: NDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
GH: #5402

This commit adds a new api RAND_DRBG_set_defaults() which sets the
default type and flags for new DRBG instances. See also #5576.
Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5632)

Fixes #4403

This commit moves the internal header file "internal/rand.h" to
<openssl/rand_drbg.h>, making the RAND_DRBG API public.
The RAND_POOL API remains private, its function prototypes were
moved to "internal/rand_int.h" and converted to lowercase.

Documentation for the new API is work in progress on GitHub #5461.
Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5462)

The introduction of thread local public and private DRBG instances (#5547)
makes it very cumbersome to change the reseeding (time) intervals for
those instances. This commit provides a function to set the default
values for all subsequently created DRBG instances.

 int RAND_DRBG_set_reseed_defaults(
                                   unsigned int master_reseed_interval,
                                   unsigned int slave_reseed_interval,
                                   time_t master_reseed_time_interval,
                                   time_t slave_reseed_time_interval
                                   );

The function is intended only to be used during application initialization,
before any threads are created and before any random bytes are generated.
Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5576)

Reviewed-by: NDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
GH: #5401

In PR #5295 it was decided that the locking api should remain private
and used only inside libcrypto. However, the locking functions were added
back to `libcrypto.num` by `mkdef.pl`, because the function prototypes
were still listed in `internal/rand.h`. (This header contains functions
which are internal, but shared between libcrypto and libssl.)

This commit moves the prototypes to `rand_lcl.h` and changes the names
to lowercase, following the convention therein. It also corrects an
outdated documenting comment.
Reviewed-by: NRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5375)

The NIST standard presents two alternative ways for seeding the
CTR DRBG, depending on whether a derivation function is used or not.
In Section 10.2.1 of NIST SP800-90Ar1 the following is assessed:

  The use of the derivation function is optional if either an
  approved RBG or an entropy source provides full entropy output
  when entropy input is requested by the DRBG mechanism.
  Otherwise, the derivation function shall be used.

Since the OpenSSL DRBG supports being reseeded from low entropy random
sources (using RAND_POOL), the use of a derivation function is mandatory.
For that reason we change the default and replace the opt-in flag
RAND_DRBG_FLAG_CTR_USE_DF with an opt-out flag RAND_DRBG_FLAG_CTR_NO_DF.
This change simplifies the RAND_DRBG_new() calls.
Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5294)

The functions drbg_setup() and drbg_cleanup() used to duplicate a lot of
code from RAND_DRBG_new() and RAND_DRBG_free(). This duplication has been
removed, which simplifies drbg_setup() and makes drbg_cleanup() obsolete.
Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5294)

This commit adds three new accessors to the internal DRBG lock

   int RAND_DRBG_lock(RAND_DRBG *drbg)
   int RAND_DRBG_unlock(RAND_DRBG *drbg)
   int RAND_DRBG_enable_locking(RAND_DRBG *drbg)

The three shared DRBGs are intended to be used concurrently, so they
have locking enabled by default. It is the callers responsibility to
guard access to the shared DRBGs by calls to RAND_DRBG_lock() and
RAND_DRBG_unlock().

All other DRBG instances don't have locking enabled by default, because
they are intendended to be used by a single thread. If it is desired,
locking can be enabled by using RAND_DRBG_enable_locking().
Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5294)

Reviewed-by: NRichard Levitte <levitte@openssl.org>

Reviewed-by: NPaul Dale <paul.dale@oracle.com>
Reviewed-by: NMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/4752)

Every DRBG now supports automatic reseeding not only after a given
number of generate requests, but also after a specified time interval.
Signed-off-by: NDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
Reviewed-by: NKurt Roeckx <kurt@roeckx.be>
(Merged from https://github.com/openssl/openssl/pull/4402)

A third shared DRBG is added, the so called master DRBG. Its sole purpose
is to reseed the two other shared DRBGs, the public and the private DRBG.
The randomness for the master DRBG is either pulled from the os entropy
sources, or added by the application using the RAND_add() call.

The master DRBG reseeds itself automatically after a given number of generate
requests, but can also be reseeded using RAND_seed() or RAND_add().
A reseeding of the master DRBG is automatically propagated to the public
and private DRBG. This construction fixes the problem, that up to now
the randomness provided by RAND_add() was added only to the public and
not to the private DRBG.
Signed-off-by: NDr. Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
Reviewed-by: NKurt Roeckx <kurt@roeckx.be>
(Merged from https://github.com/openssl/openssl/pull/4402)

Reseeding is handled very differently by the classic RAND_METHOD API
and the new RAND_DRBG api. These differences led to some problems when
the new RAND_DRBG was made the default OpenSSL RNG. In particular,
RAND_add() did not work as expected anymore. These issues are discussed
on the thread '[openssl-dev] Plea for a new public OpenSSL RNG API'
and in Pull Request #4328. This commit fixes the mentioned issues,
introducing the following changes:

- Replace the fixed size RAND_BYTES_BUFFER by a new RAND_POOL API which
  facilitates collecting entropy by the get_entropy() callback.
- Don't use RAND_poll()/RAND_add() for collecting entropy from the
  get_entropy() callback anymore. Instead, replace RAND_poll() by
  RAND_POOL_acquire_entropy().
- Add a new function rand_drbg_restart() which tries to get the DRBG
  in an instantiated state by all means, regardless of the current
  state (uninstantiated, error, ...) the DRBG is in. If the caller
  provides entropy or additional input, it will be used for reseeding.
- Restore the original documented behaviour of RAND_add() and RAND_poll()
  (namely to reseed the DRBG immediately) by a new implementation based
  on rand_drbg_restart().
- Add automatic error recovery from temporary failures of the entropy
  source to RAND_DRBG_generate() using the rand_drbg_restart() function.
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
Reviewed-by: NKurt Roeckx <kurt@roeckx.be>
Reviewed-by: NRich Salz <rsalz@openssl.org>
Reviewed-by: NBen Kaduk <kaduk@mit.edu>
(Merged from https://github.com/openssl/openssl/pull/4328)

The one creating the DRBG should instantiate it, it's there that we
know which parameters we should use to instantiate it.

This splits the rand init in two parts to avoid a deadlock
because when the global drbg is created it wands to call
rand_add on the global rand method.
Reviewed-by: NRich Salz <rsalz@openssl.org>
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
GH: #4268

The DRBG callbacks 'get_entropy()' and 'cleanup_entropy()' are designed
in such a way that the randomness buffer does not have to be allocated
by the calling function. It receives the address of a dynamically
allocated buffer from get_entropy() and returns this address to
cleanup_entropy(), where it is freed. If these two calls are properly
paired, the address can be stored in a stack local variable of the
calling function, so there is no need for having a 'randomness' member
(and a 'filled' member) in 'RAND_DRBG'.
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4266)

Give each SSL object it's own DRBG, chained to the parent global
DRBG which is used only as a source of randomness into the per-SSL
DRBG.  This is used for all session, ticket, and pre-master secret keys.
It is NOT used for ECDH key generation which use only the global
DRBG. (Doing that without changing the API is tricky, if not impossible.)
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/4050)

If RAND_add wraps around, XOR with existing. Add test to drbgtest that
does the wrap-around.

Re-order seeding and stop after first success.

Add RAND_poll_ex()

Use the DF and therefore lower RANDOMNESS_NEEDED.  Also, for child DRBG's,
mix in the address as the personalization bits.

Centralize the entropy callbacks, from drbg_lib to rand_lib.
(Conceptually, entropy is part of the enclosing application.)
Thanks to Dr. Matthias St Pierre for the suggestion.

Various code cleanups:
    -Make state an enum; inline RANDerr calls.
    -Add RAND_POLL_RETRIES (thanks Pauli for the idea)
    -Remove most RAND_seed calls from rest of library
    -Rename DRBG_CTX to RAND_DRBG, etc.
    -Move some code from drbg_lib to drbg_rand; drbg_lib is now only the
     implementation of NIST DRBG.
    -Remove blocklength
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/4019)

Reviewed-by: NRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3971)

As suggested by Kurt.
Reviewed-by: NBernd Edlinger <bernd.edlinger@hotmail.de>
(Merged from https://github.com/openssl/openssl/pull/3970)

Ported from the last FIPS release, with DUAL_EC and SHA1 and the
self-tests removed.  Since only AES-CTR is supported, other code
simplifications were done.  Removed the "entropy blocklen" concept.

Moved internal functions to new include/internal/rand.h.
Reviewed-by: NPaul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/3789)