Add documentation for the RAND_DRBG API

The RAND_DRBG API was added in PR #5462 and modified by PR #5547.
This commit adds the corresponding documention.

Reviewed-by: Kurt Roeckx <kurt@roeckx.be>
Reviewed-by: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5461)

15 files changed, 1062 insertions, 115 deletions

diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod
index 1a4ad52de0..4d5a2b93a0 100644
--- a/doc/man3/CRYPTO_get_ex_new_index.pod
+++ b/doc/man3/CRYPTO_get_ex_new_index.pod
@@ -40,20 +40,22 @@ Several OpenSSL structures can have application-specific data attached to them,
 known as "exdata."
 The specific structures are:
 
-    SSL
-    SSL_CTX
-    SSL_SESSION
-    X509
-    X509_STORE
-    X509_STORE_CTX
+    APP
+    BIO
     DH
+    DRBG
     DSA
     EC_KEY
-    RSA
     ENGINE
+    RSA
+    SSL
+    SSL_CTX
+    SSL_SESSION
     UI
     UI_METHOD
-    BIO
+    X509
+    X509_STORE
+    X509_STORE_CTX
 
 Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h>
 header file.  In addition, B<CRYPTO_EX_INDEX_APP> is reserved for
@@ -155,7 +157,7 @@ dup_func() should return 0 for failure and 1 for success.
 
 =head1 COPYRIGHT
 
-Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/RAND_DRBG_generate.pod b/doc/man3/RAND_DRBG_generate.pod
new file mode 100644
index 0000000000..b39ee93f51
--- /dev/null
+++ b/doc/man3/RAND_DRBG_generate.pod
@@ -0,0 +1,88 @@
+=pod
+
+=head1 NAME
+
+RAND_DRBG_generate,
+RAND_DRBG_bytes
+- generate random bytes using the given drbg instance
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand_drbg.h>
+
+ int RAND_DRBG_generate(RAND_DRBG *drbg,
+                        unsigned char *out, size_t outlen,
+                        int prediction_resistance,
+                        const unsigned char *adin, size_t adinlen);
+
+ int RAND_DRBG_bytes(RAND_DRBG *drbg,
+                     unsigned char *out, size_t outlen);
+
+
+=head1 DESCRIPTION
+
+RAND_DRBG_generate() generates B<outlen> random bytes using the given
+DRBG instance B<drbg> and stores them in the buffer at B<out>.
+
+Before generating the output, the DRBG instance checks whether the maximum
+number of generate requests (I<reseed interval>) or the maximum timespan
+(I<reseed time interval>) since its last seeding have been reached.
+If this is the case, the DRBG reseeds automatically.
+Additionally, an immediate reseeding can be requested by setting the
+B<prediction_resistance> flag to 1. See NOTES section for more details.
+
+The caller can optionally provide additional data to be used for reseeding
+by passing a pointer B<adin> to a buffer of length B<adinlen>.
+This additional data is mixed into the internal state of the random
+generator but does not contribute to the entropy count.
+The additional data can be omitted by setting B<adin> to NULL and
+B<adinlen> to 0;
+
+RAND_DRBG_bytes() generates B<outlen> random bytes using the given
+DRBG instance B<drbg> and stores them in the buffer at B<out>.
+This function is a wrapper around the RAND_DRBG_generate() call,
+which collects some additional data from low entropy sources
+(e.g., a high resolution timer) and calls
+RAND_DRBG_generate(drbg, out, outlen, 0, adin, adinlen).
+
+
+=head1 RETURN VALUES
+
+RAND_DRBG_generate() and RAND_DRBG_bytes() return 1 on success,
+and 0 on failure.
+
+=head1 NOTES
+
+The I<reseed interval> and I<reseed time interval> of the B<drbg> are set to
+reasonable default values, which in general do not have to be adjusted.
+If necessary, they can be changed using L<RAND_DRBG_set_reseed_interval(3)>
+and L<RAND_DRBG_set_reseed_time_interval(3)>, respectively.
+
+A request for prediction resistance can only be satisfied by pulling fresh
+entropy from one of the approved entropy sources listed in section 5.5.2 of
+[NIST SP 800-90C].
+Since the default DRBG implementation does not have access to such an approved
+entropy source, a request for prediction resistance will always fail.
+In other words, prediction resistance is currently not supported yet by the DRBG.
+
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
+=head1 SEE ALSO
+
+L<RAND_bytes(3)>,
+L<RAND_DRBG_set_reseed_interval(3)>,
+L<RAND_DRBG_set_reseed_time_interval(3)>,
+L<RAND_DRBG(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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/RAND_DRBG_get0_master.pod b/doc/man3/RAND_DRBG_get0_master.pod
new file mode 100644
index 0000000000..c958bf20ec
--- /dev/null
+++ b/doc/man3/RAND_DRBG_get0_master.pod
@@ -0,0 +1,80 @@
+=pod
+
+=head1 NAME
+
+RAND_DRBG_get0_master,
+RAND_DRBG_get0_public,
+RAND_DRBG_get0_private
+- get access to the global RAND_DRBG instances
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand_drbg.h>
+
+ RAND_DRBG *RAND_DRBG_get0_master(void);
+ RAND_DRBG *RAND_DRBG_get0_public(void);
+ RAND_DRBG *RAND_DRBG_get0_private(void);
+
+
+=head1 DESCRIPTION
+
+The default RAND API implementation (RAND_OpenSSL()) utilizes three
+shared DRBG instances which are accessed via the RAND API:
+
+The <public> and <private> DRBG are thread-local instances, which are used
+by RAND_bytes() and RAND_priv_bytes(), respectively.
+The <master> DRBG is a global instance, which is not intended to be used
+directly, but is used internally to reseed the other two instances.
+
+These functions here provide access to the shared DRBG instances.
+
+=head1 RETURN VALUES
+
+RAND_DRBG_get0_master() returns a pointer to the <master> DRBG instance.
+
+RAND_DRBG_get0_public() returns a pointer to the <public> DRBG instance.
+
+RAND_DRBG_get0_private() returns a pointer to the <private> DRBG instance.
+
+
+=head1 NOTES
+
+It is not thread-safe to access the <master> DRBG instance.
+The <public> and <private> DRBG instance can be accessed safely, because
+they are thread-local. Note however, that changes to these two instances
+apply only to the current thread.
+
+For that reason it is recommended not to change the settings of these
+three instances directly.
+Instead, an application should change the default settings for new DRBG instances
+at initialization time, before creating additional threads.
+
+During initialization, it is possible to change the reseed interval
+and reseed time interval.
+It is also possible to exchange the reseeding callbacks entirely.
+
+
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
+=head1 SEE ALSO
+
+L<RAND_DRBG_set_callbacks(3)>,
+L<RAND_DRBG_set_reseed_defaults(3)>,
+L<RAND_DRBG_set_reseed_interval(3)>,
+L<RAND_DRBG_set_reseed_time_interval(3)>,
+L<RAND_DRBG_set_callbacks(3)>,
+L<RAND_DRBG_generate(3)>,
+L<RAND_DRBG(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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/RAND_DRBG_new.pod b/doc/man3/RAND_DRBG_new.pod
new file mode 100644
index 0000000000..dcd7a94419
--- /dev/null
+++ b/doc/man3/RAND_DRBG_new.pod
@@ -0,0 +1,127 @@
+=pod
+
+=head1 NAME
+
+RAND_DRBG_new,
+RAND_DRBG_secure_new,
+RAND_DRBG_set,
+RAND_DRBG_set_defaults,
+RAND_DRBG_instantiate,
+RAND_DRBG_uninstantiate,
+RAND_DRBG_free
+- initialize and cleanup a RAND_DRBG instance
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand_drbg.h>
+
+
+ RAND_DRBG *RAND_DRBG_new(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(RAND_DRBG *drbg,
+                   int type, unsigned int flags);
+
+ int RAND_DRBG_set_defaults(int type, unsigned int flags);
+
+ int RAND_DRBG_instantiate(RAND_DRBG *drbg,
+                           const unsigned char *pers, size_t perslen);
+
+ int RAND_DRBG_uninstantiate(RAND_DRBG *drbg);
+
+ void RAND_DRBG_free(RAND_DRBG *drbg);
+
+
+=head1 DESCRIPTION
+
+RAND_DRBG_new() and RAND_DRBG_secure_new()
+create a new DRBG instance of the given B<type>, allocated from the heap resp.
+the secure heap
+(using OPENSSL_zalloc() resp. OPENSSL_secure_zalloc()).
+
+RAND_DRBG_set() initializes the B<drbg> with the given B<type> and B<flags>.
+
+RAND_DRBG_set_defaults() sets the default B<type> and B<flags> for new DRBG
+instances.
+
+Currently, all DRBG types are based on AES-CTR, so B<type> can be one of the
+following values: NID_aes_128_ctr, NID_aes_192_ctr, NID_aes_256_ctr.
+Before the DRBG can be used to generate random bits, it is necessary to set
+its type and to instantiate it.
+
+The optional B<flags> argument specifies a set of bit flags which can be
+joined using the | operator. Currently, the only flag is
+RAND_DRBG_FLAG_CTR_NO_DF, which disables the use of a the derivation function
+ctr_df. For an explanation, see [NIST SP 800-90A Rev. 1].
+
+If a B<parent> instance is specified then this will be used instead of
+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
+specified.
+To omit the personalization string, set B<pers>=NULL and B<perslen>=0;
+
+RAND_DRBG_uninstantiate()
+clears the internal state of the B<drbg> and puts it back in the
+uninstantiated state.
+
+=head1 RETURN VALUES
+
+
+RAND_DRBG_new() and RAND_DRBG_secure_new() return a pointer to a DRBG
+instance allocated on the heap, resp. secure heap.
+
+RAND_DRBG_set(),
+RAND_DRBG_instantiate(), and
+RAND_DRBG_uninstantiate()
+return 1 on success, and 0 on failure.
+
+RAND_DRBG_free() does not return a value.
+
+=head1 NOTES
+
+The DRBG design supports I<chaining>, which means that a DRBG instance can
+use another B<parent> DRBG instance instead of the default entropy source
+to obtain fresh random input for reseeding, provided that B<parent> DRBG
+instance was properly instantiated, either from a trusted entropy source,
+or from yet another parent DRBG instance.
+For a detailed description of the reseeding process, see L<RAND_DRBG(7)>.
+
+The default DRBG type and flags are applied only during creation of a DRBG
+instance.
+To ensure that they are applied to the global and thread-local DRBG instances
+(<master>, resp. <public> and <private>), it is necessary to call
+RAND_DRBG_set_defaults() before creating any thread and before calling any
+cryptographic routines that obtain random data directly or indirectly.
+
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
+=head1 SEE ALSO
+
+L<OPENSSL_zalloc(3)>,
+L<OPENSSL_secure_zalloc(3)>,
+L<RAND_DRBG_generate(3)>,
+L<RAND_DRBG(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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/RAND_DRBG_reseed.pod b/doc/man3/RAND_DRBG_reseed.pod
new file mode 100644
index 0000000000..da3a40be44
--- /dev/null
+++ b/doc/man3/RAND_DRBG_reseed.pod
@@ -0,0 +1,111 @@
+=pod
+
+=head1 NAME
+
+RAND_DRBG_reseed,
+RAND_DRBG_set_reseed_interval,
+RAND_DRBG_set_reseed_time_interval,
+RAND_DRBG_set_reseed_defaults
+- reseed a RAND_DRBG instance
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand_drbg.h>
+
+ int RAND_DRBG_reseed(RAND_DRBG *drbg,
+                      const unsigned char *adin, size_t adinlen);
+
+ int RAND_DRBG_set_reseed_interval(RAND_DRBG *drbg,
+                                   unsigned int interval);
+
+ int RAND_DRBG_set_reseed_time_interval(RAND_DRBG *drbg,
+                                        time_t interval);
+
+ 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
+                                   );
+
+
+=head1 DESCRIPTION
+
+RAND_DRBG_reseed()
+reseeds the given B<drbg>, obtaining entropy input from its entropy source
+and mixing in the specified additional data provided in the buffer B<adin>
+of length B<adinlen>.
+The additional data can be omitted by setting B<adin> to NULL and B<adinlen>
+to 0.
+
+RAND_DRBG_set_reseed_interval()
+sets the reseed interval of the B<drbg>, which is the maximum allowed number
+of generate requests between consecutive reseedings.
+If B<interval> > 0, then the B<drbg> will reseed automatically whenever the
+number of generate requests since its last seeding exceeds the given reseed
+interval.
+If B<interval> == 0, then this feature is disabled.
+
+
+RAND_DRBG_set_reseed_time_interval()
+sets the reseed time interval of the B<drbg>, which is the maximum allowed
+number of seconds between consecutive reseedings.
+If B<interval> > 0, then the B<drbg> will reseed automatically whenever the
+elapsed time since its last reseeding exceeds the given reseed time interval.
+If B<interval> == 0, then this feature is disabled.
+
+RAND_DRBG_set_reseed_defaults() sets the default values for the reseed interval
+(B<master_reseed_interval> and B<slave_reseed_interval>)
+and the reseed time interval
+(B<master_reseed_time_interval> and B<slave_reseed_tme_interval>)
+of DRBG instances.
+The default values are set independently for master DRBG instances (which don't
+have a parent) and slave DRBG instances (which are chained to a parent DRBG).
+
+=head1 RETURN VALUES
+
+RAND_DRBG_reseed(),
+RAND_DRBG_set_reseed_interval(), and
+RAND_DRBG_set_reseed_time_interval(),
+return 1 on success, 0 on failure.
+
+
+=head1 NOTES
+
+The default OpenSSL random generator is already set up for automatic reseeding,
+so in general it is not necessary to reseed it explicitly, or to modify
+its reseeding thresholds.
+
+Normally, the entropy input for seeding a DRBG is either obtained from a
+trusted os entropy source or from a parent DRBG instance, which was seeded
+(directly or indirectly) from a trusted os entropy source.
+In exceptional cases it is possible to replace the reseeding mechanism entirely
+by providing application defined callbacks using RAND_DRBG_set_callbacks().
+
+The reseeding default values are applied only during creation of a DRBG instance.
+To ensure that they are applied to the global and thread-local DRBG instances
+(<master>, resp. <public> and <private>), it is necessary to call
+RAND_DRBG_set_reseed_defaults() before creating any thread and before calling any
+ cryptographic routines that obtain random data directly or indirectly.
+
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
+=head1 SEE ALSO
+
+L<RAND_DRBG_generate(3)>,
+L<RAND_DRBG_bytes(3)>,
+L<RAND_DRBG_set_callbacks(3)>.
+L<RAND_DRBG(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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/RAND_DRBG_set_callbacks.pod b/doc/man3/RAND_DRBG_set_callbacks.pod
new file mode 100644
index 0000000000..3e9a98585e
--- /dev/null
+++ b/doc/man3/RAND_DRBG_set_callbacks.pod
@@ -0,0 +1,147 @@
+=pod
+
+=head1 NAME
+
+RAND_DRBG_set_callbacks,
+RAND_DRBG_get_entropy_fn,
+RAND_DRBG_cleanup_entropy_fn,
+RAND_DRBG_get_nonce_fn,
+RAND_DRBG_cleanup_nonce_fn
+- set callbacks for reseeding
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand_drbg.h>
+
+
+ int RAND_DRBG_set_callbacks(RAND_DRBG *drbg,
+                             RAND_DRBG_get_entropy_fn get_entropy,
+                             RAND_DRBG_cleanup_entropy_fn cleanup_entropy,
+                             RAND_DRBG_get_nonce_fn get_nonce,
+                             RAND_DRBG_cleanup_nonce_fn cleanup_nonce);
+
+
+=head2 Callback Functions
+
+ typedef size_t (*RAND_DRBG_get_entropy_fn)(
+                       RAND_DRBG *drbg,
+                       unsigned char **pout,
+                       int entropy,
+                       size_t min_len, size_t max_len,
+                       int prediction_resistance);
+
+ typedef void (*RAND_DRBG_cleanup_entropy_fn)(
+                     RAND_DRBG *drbg,
+                     unsigned char *out, size_t outlen);
+
+ typedef size_t (*RAND_DRBG_get_nonce_fn)(
+                       RAND_DRBG *drbg,
+                       unsigned char **pout,
+                       int entropy,
+                       size_t min_len, size_t max_len);
+
+ typedef void (*RAND_DRBG_cleanup_nonce_fn)(
+                     RAND_DRBG *drbg,
+                     unsigned char *out, size_t outlen);
+
+
+
+=head1 DESCRIPTION
+
+RAND_DRBG_set_callbacks() sets the callbacks for obtaining fresh entropy and
+the nonce when reseeding the given B<drbg>.
+The callback functions are implemented and provided by the caller.
+Their parameter lists need to match the function prototypes above.
+
+Setting the callbacks is allowed only if the DRBG has not been initialized yet.
+Otherwise, the operation will fail.
+To change the settings for one of the three shared DRBGs it is necessary to call
+RAND_DRBG_uninstantiate() first.
+
+The B<get_entropy>() callback is called by the B<drbg> when it requests fresh
+random input.
+It is expected that the callback allocates and fills a random buffer of size
+B<min_len> <= size <= B<max_len> (in bytes) which contains at least B<entropy>
+bits of randomness.
+The B<prediction_resistance> flag indicates whether the reseeding was
+triggered by a prediction resistance request.
+
+The buffer's address is to be returned in *B<pout> and the number of collected
+randomness bytes as return value.
+
+If the callback fails to acquire at least B<entropy> bits of randomness,
+it must indicate an error by returning a buffer length of 0.
+
+If B<prediction_resistance> was requested and the random source of the DRBG
+does not satisfy the conditions requested by [NIST SP 800-90C], then
+it must also indicate an error by returning a buffer length of 0.
+See NOTES section for more details.
+
+The B<cleanup_entropy>() callback is called from the B<drbg> to to clear and
+free the buffer allocated previously by get_entropy().
+The values B<out> and B<outlen> are the random buffer's  address and length,
+as returned by the get_entropy() callback.
+
+The B<get_nonce>() and B<cleanup_nonce>() callbacks are used to obtain a nonce
+and free it again. A nonce is only required for instantiation (not for reseeding)
+and only in the case where the DRBG uses a derivation function.
+The callbacks are analogous to get_entropy() and cleanup_entropy(),
+except for the missing prediction_resistance flag.
+
+If the derivation function is disabled, then no nonce is used for instantiation,
+and the B<get_nonce>() and B<cleanup_nonce>() callbacks can be omitted by
+setting them to NULL.
+
+
+=head1 RETURN VALUES
+
+RAND_DRBG_set_callbacks() return 1 on success, and 0 on failure
+
+=head1 NOTES
+
+It is important that B<cleanup_entropy>() and B<cleanup_nonce>() clear the buffer
+contents safely before freeing it, in order not to leave sensitive information
+about the DRBG's state in memory.
+
+A request for prediction resistance can only be satisfied by pulling fresh
+entropy from one of the approved entropy sources listed in section 5.5.2 of
+[NIST SP 800-90C].
+Since the default implementation of the get_entropy callback does not have access
+to such an approved entropy source, a request for prediction resistance will
+always fail.
+In other words, prediction resistance is currently not supported yet by the DRBG.
+
+The derivation function is disabled during initialization by calling the
+RAND_DRBG_set() 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 speeking it can be omitted if the random
+source has "full entropy", i.e., contains 8 bits of entropy per byte.
+
+Even if a nonce is required, the B<get_nonce>() and B<cleanup_nonce>()
+callbacks can be omitted by setting them to NULL.
+In this case the DRBG will automatically request an extra amount of entropy
+(using the B<get_entropy>() and B<cleanup_entropy>() callbacks) which it will
+utilize for the nonce, following the recommendations of [NIST SP 800-90A Rev. 1],
+section 8.6.7.
+
+
+=head1 HISTORY
+
+The RAND_DRBG functions were added in OpenSSL 1.1.1.
+
+=head1 SEE ALSO
+
+L<RAND_DRBG_new(3)>,
+L<RAND_DRBG_reseed(3)>,
+L<RAND_DRBG(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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/RAND_DRBG_set_ex_data.pod b/doc/man3/RAND_DRBG_set_ex_data.pod
new file mode 100644
index 0000000000..22b7332571
--- /dev/null
+++ b/doc/man3/RAND_DRBG_set_ex_data.pod
@@ -0,0 +1,68 @@
+=pod
+
+=head1 NAME
+
+RAND_DRBG_set_ex_data,
+RAND_DRBG_get_ex_data,
+RAND_DRBG_get_ex_new_index
+- store and retrieve extra data from the DRBG instance
+
+=head1 SYNOPSIS
+
+ #include <openssl/rand_drbg.h>
+
+ int RAND_DRBG_set_ex_data(RAND_DRBG *drbg, int idx, void *data);
+
+ void *RAND_DRBG_get_ex_data(const RAND_DRBG *drbg, int idx);
+
+ int RAND_DRBG_get_ex_new_index(long argl, void *argp,
+                                CRYPTO_EX_new *new_func,
+                                CRYPTO_EX_dup *dup_func,
+                                CRYPTO_EX_free *free_func);
+
+
+
+=head1 DESCRIPTION
+
+RAND_DRBG_set_ex_data() enables an application to store arbitrary application
+specific data B<data> in a RAND_DRBG instance B<drbg>. The index B<idx> should
+be a value previously returned from a call to RAND_DRBG_get_ex_new_index().
+
+RAND_DRBG_get_ex_data() retrieves application specific data previously stored
+in an RAND_DRBG instance B<drbg>. The B<idx> value should be the same as that
+used when originally storing the data.
+
+For more detailed information see L<CRYPTO_get_ex_data(3)> and
+L<CRYPTO_set_ex_data(3)> which implement these functions and
+L<CRYPTO_get_ex_new_index(3)> for generating a unique index.
+
+=head1 RETURN VALUES
+
+RAND_DRBG_set_ex_data() returns 1 for success or 0 for failure.
+
+RAND_DRBG_get_ex_data() returns the previously stored value or NULL on
+failure. NULL may also be a valid value.
+
+
+=head1 NOTES
+
+RAND_DRBG_get_ex_new_index(...) is implemented as a macro and equivalent to
+CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_DRBG,...).
+
+=head1 SEE ALSO
+
+L<CRYPTO_get_ex_data(3)>,
+L<CRYPTO_set_ex_data(3)>,
+L<CRYPTO_get_ex_new_index(3)>,
+L<RAND_DRBG(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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/RAND_add.pod b/doc/man3/RAND_add.pod
index 62048e6792..1b06d1be87 100644
--- a/doc/man3/RAND_add.pod
+++ b/doc/man3/RAND_add.pod
@@ -24,43 +24,42 @@ Deprecated:
 
 =head1 DESCRIPTION
 
-Random numbers are a vital part of cryptography, including key generation,
-creating salts, etc., and software-based
-generators must be "seeded" with external randomness before they can be
-used as a cryptographically-secure pseudo-random number generator (CSPRNG).
-The availability of common hardware with special instructions and
-modern operating systems, which may use items such as interrupt jitter
-and network packet timings, can be reasonable sources of seeding material.
-
-RAND_status() indicates whether or not the CSPRNG has been sufficiently
-seeded. If not, functions such as RAND_bytes(3) will fail.
-
-RAND_poll() uses the system's capabilities to seed the CSPRNG using
+These functions can be used to seed the random generator and to check its
+seeded state.
+In general, manual (re-)seeding of the default OpenSSL random generator
+(L<RAND_OpenSSL(3)>) is not necessary (but allowed), since it does (re-)seed
+itself automatically using trusted system entropy sources.
+This holds unless the default RAND_METHOD has been replaced or OpenSSL was
+built with automatic reseeding disabled, see L<RAND(7)> for more details.
+
+RAND_status() indicates whether or not the random generator has been sufficiently
+seeded. If not, functions such as L<RAND_bytes(3)> will fail.
+
+RAND_poll() uses the system's capabilities to seed the random generator using
 random input obtained from polling various trusted entropy sources.
-The default choice of the entropy source can be modified at build time
-using the --with-rand-seed configure option, see also the B<NOTES> section.
-A summary of the configure options can be displayed with the OpenSSL
-L<version(1)> command.
+The default choice of the entropy source can be modified at build time,
+see L<RAND(7)> for more details.
 
-RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state.
+RAND_add() mixes the B<num> bytes at B<buf> into the internal state
+of the random generator.
+This function will not normally be needed, as mentioned above.
 The B<randomness> argument is an estimate of how much randomness is
 contained in
 B<buf>, in bytes, and should be a number between zero and B<num>.
 Details about sources of randomness and how to estimate their randomness
-can be found in the literature; for example NIST SP 800-90B.
-The content of B<buf> cannot be recovered from subsequent CSPRNG output.
-This function will not normally be needed, as RAND_poll() should have been
-configured to do the appropriate seeding for the local platform.
-Applications that need to keep random state in an external file should
-use L<RAND_load_file(3)>.
+can be found in the literature; for example [NIST SP 800-90B].
+The content of B<buf> cannot be recovered from subsequent random generator output.
+Applications that intend to save and restore random state in an external file
+should consider using L<RAND_load_file(3)> instead.
 
 RAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>.
 
-RAND_event() and RAND_screen() are equivalent to RAND_poll().
+RAND_event() and RAND_screen() are equivalent to RAND_poll() and exist
+for compatibility reasons only. See HISTORY section below.
 
 =head1 RETURN VALUES
 
-RAND_status() returns 1 if the CSPRNG has been seeded
+RAND_status() returns 1 if the random generator has been seeded
 with enough data, 0 otherwise.
 
 RAND_poll() returns 1 if it generated seed data, 0 otherwise.
@@ -69,72 +68,6 @@ RAND_event() returns RAND_status().
 
 The other functions do not return values.
 
-=head1 NOTES
-
-The new OpenSSL DRBG has some peculiarities which need to be taken
-into account when it is selected as the default OpenSSL CSPRNG, i.e.,
-when RAND_get_rand_method() == RAND_OpenSSL().
-This applies in particular to the way reseeding is done by the DRBG:
-
-=over 2
-
-=item *
-
-The DRBG seeds itself automatically, pulling random input from trusted
-entropy sources.
-Automatic reseeding occurs after a predefined number of generate requests.
-The selection of the trusted entropy sources is configured at build
-time using the --with-rand-seed option.
-
-=item *
-
-The DRBG distinguishes two different types of random input:
-'entropy', which comes from a trusted source, and 'additional input',
-which can optionally be added by the user and is considered untrusted.
-
-=back
-
-Automatic seeding can be disabled using the --with-rand-seed=none option.
-
-=head2 DRBG with automatic seeding enabled
-
-Calling RAND_poll() or RAND_add() is not necessary, because the DRBG
-polls the entropy source automatically.
-However, both calls are permitted, and do reseed the RNG.
-
-RAND_add() can be used to add both kinds of random input, depending on the
-value of the B<randomness> argument:
-
-=over 4
-
-=item randomness == 0:
-
-The random bytes are mixed as additional input into the current state of
-the DRBG.
-Mixing in additional input is not considered a full reseeding, hence the
-reseed counter is not reset.
-
-
-=item randomness > 0:
-
-The random bytes are used as entropy input for a full reseeding
-(resp. reinstantiation) if the DRBG is instantiated
-(resp. uninstantiated or in an error state).
-A reseeding requires 16 bytes (128 bits) of randomness.
-It is possible to provide less randomness than required.
-In this case the missing randomness will be obtained by pulling random input
-from the trusted entropy sources.
-
-=back
-
-=head2 DRBG with automatic seeding disabled (--with-rand-seed=none)
-
-Calling RAND_poll() will always fail.
-
-RAND_add() needs to be called for initial seeding and periodic reseeding.
-At least 16 bytes (128 bits) of randomness have to be provided, otherwise
-the (re-)seeding of the DRBG will fail.
-
 =head1 HISTORY
 
 RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should
@@ -142,12 +75,14 @@ not be used.
 
 =head1 SEE ALSO
 
-L<RAND_bytes(3)>, L<RAND_egd(3)>,
-L<RAND_load_file(3)>
+L<RAND_bytes(3)>,
+L<RAND_egd(3)>,
+L<RAND_load_file(3)>,
+L<RAND(7)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2018 The OpenSSL Project Authors. A