doc/man3/RAND_DRBG_reseed.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 RAND_DRBG_reseed,
   6 RAND_DRBG_set_reseed_interval,
   7 RAND_DRBG_set_reseed_time_interval,
   8 RAND_DRBG_set_reseed_defaults
   9 - reseed a RAND_DRBG instance
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/rand_drbg.h>
  14
  15  int RAND_DRBG_reseed(RAND_DRBG *drbg,
  16                       const unsigned char *adin, size_t adinlen,
  17                       int prediction_resistance);
  18
  19  int RAND_DRBG_set_reseed_interval(RAND_DRBG *drbg,
  20                                    unsigned int interval);
  21
  22  int RAND_DRBG_set_reseed_time_interval(RAND_DRBG *drbg,
  23                                         time_t interval);
  24
  25  int RAND_DRBG_set_reseed_defaults(
  26                                    unsigned int master_reseed_interval,
  27                                    unsigned int slave_reseed_interval,
  28                                    time_t master_reseed_time_interval,
  29                                    time_t slave_reseed_time_interval
  30                                    );
  31
  32
  33 =head1 DESCRIPTION
  34
  35 RAND_DRBG_reseed()
  36 reseeds the given B<drbg>, obtaining entropy input from its entropy source
  37 and mixing in the specified additional data provided in the buffer B<adin>
  38 of length B<adinlen>.
  39 The additional data can be omitted by setting B<adin> to NULL and B<adinlen>
  40 to 0.
  41 An immediate reseeding can be requested by setting the
  42 B<prediction_resistance> flag to 1.
  43 Requesting prediction resistance is a relative expensive operation.
  44 See NOTES section for more details.
  45
  46 RAND_DRBG_set_reseed_interval()
  47 sets the reseed interval of the B<drbg>, which is the maximum allowed number
  48 of generate requests between consecutive reseedings.
  49 If B<interval> > 0, then the B<drbg> will reseed automatically whenever the
  50 number of generate requests since its last seeding exceeds the given reseed
  51 interval.
  52 If B<interval> == 0, then this feature is disabled.
  53
  54
  55 RAND_DRBG_set_reseed_time_interval()
  56 sets the reseed time interval of the B<drbg>, which is the maximum allowed
  57 number of seconds between consecutive reseedings.
  58 If B<interval> > 0, then the B<drbg> will reseed automatically whenever the
  59 elapsed time since its last reseeding exceeds the given reseed time interval.
  60 If B<interval> == 0, then this feature is disabled.
  61
  62 RAND_DRBG_set_reseed_defaults() sets the default values for the reseed interval
  63 (B<master_reseed_interval> and B<slave_reseed_interval>)
  64 and the reseed time interval
  65 (B<master_reseed_time_interval> and B<slave_reseed_tme_interval>)
  66 of DRBG instances.
  67 The default values are set independently for master DRBG instances (which don't
  68 have a parent) and slave DRBG instances (which are chained to a parent DRBG).
  69
  70 =head1 RETURN VALUES
  71
  72 RAND_DRBG_reseed(),
  73 RAND_DRBG_set_reseed_interval(), and
  74 RAND_DRBG_set_reseed_time_interval(),
  75 return 1 on success, 0 on failure.
  76
  77
  78 =head1 NOTES
  79
  80 The default OpenSSL random generator is already set up for automatic reseeding,
  81 so in general it is not necessary to reseed it explicitly, or to modify
  82 its reseeding thresholds.
  83
  84 Normally, the entropy input for seeding a DRBG is either obtained from a
  85 trusted os entropy source or from a parent DRBG instance, which was seeded
  86 (directly or indirectly) from a trusted os entropy source.
  87 In exceptional cases it is possible to replace the reseeding mechanism entirely
  88 by providing application defined callbacks using RAND_DRBG_set_callbacks().
  89
  90 The reseeding default values are applied only during creation of a DRBG instance.
  91 To ensure that they are applied to the global and thread-local DRBG instances
  92 (<master>, resp. <public> and <private>), it is necessary to call
  93 RAND_DRBG_set_reseed_defaults() before creating any thread and before calling any
  94  cryptographic routines that obtain random data directly or indirectly.
  95
  96 =head1 SEE ALSO
  97
  98 L<RAND_DRBG_generate(3)>,
  99 L<RAND_DRBG_bytes(3)>,
 100 L<RAND_DRBG_set_callbacks(3)>.
 101 L<RAND_DRBG(7)>
 102
 103 =head1 HISTORY
 104
 105 The RAND_DRBG functions were added in OpenSSL 1.1.1.
 106
 107 Prediction resistance is supported from OpenSSL 3.0.
 108
 109 =head1 COPYRIGHT
 110
 111 Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
 112
 113 Licensed under the Apache License 2.0 (the "License").  You may not use
 114 this file except in compliance with the License.  You can obtain a copy
 115 in the file LICENSE in the source distribution or at
 116 L<https://www.openssl.org/source/license.html>.
 117
 118 =cut