Add prediction resistance capability to the DRBG reseeding process.
[openssl.git] / doc / man3 / RAND_DRBG_reseed.pod
index ca08a39..c4d2671 100644 (file)
@@ -13,7 +13,8 @@ RAND_DRBG_set_reseed_defaults
  #include <openssl/rand_drbg.h>
 
  int RAND_DRBG_reseed(RAND_DRBG *drbg,
-                      const unsigned char *adin, size_t adinlen);
+                      const unsigned char *adin, size_t adinlen,
+                      int prediction_resistance);
 
  int RAND_DRBG_set_reseed_interval(RAND_DRBG *drbg,
                                    unsigned int interval);
@@ -37,6 +38,10 @@ 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.
+An immediate reseeding can be requested by setting the
+B<prediction_resistance> flag to 1.
+Requesting prediction resistance is a relative expensive operation.
+See NOTES section for more details.
 
 RAND_DRBG_set_reseed_interval()
 sets the reseed interval of the B<drbg>, which is the maximum allowed number
@@ -88,10 +93,17 @@ To ensure that they are applied to the global and thread-local DRBG instances
 RAND_DRBG_set_reseed_defaults() before creating any thread and before calling any
  cryptographic routines that obtain random data directly or indirectly.
 
+A request for prediction resistance can only be satisfied by pulling fresh
+entropy from a live entropy source (section 5.5.2 of [NIST SP 800-90C]).
+It is up to the user to ensure that a live entropy source is configured
+and is being used.
+
 =head1 HISTORY
 
 The RAND_DRBG functions were added in OpenSSL 1.1.1.
 
+Prediction resistance is supported from OpenSSL 3.0.0.
+
 =head1 SEE ALSO
 
 L<RAND_DRBG_generate(3)>,