1=pod
2
3=head1 NAME
4
5RAND_DRBG_reseed,
6RAND_DRBG_set_reseed_interval,
7RAND_DRBG_set_reseed_time_interval,
8RAND_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
35RAND_DRBG_reseed()
36reseeds the given B<drbg>, obtaining entropy input from its entropy source
37and mixing in the specified additional data provided in the buffer B<adin>
38of length B<adinlen>.
39The additional data can be omitted by setting B<adin> to NULL and B<adinlen>
40to 0.
41An immediate reseeding from a live entropy source can be requested by setting
42the B<prediction_resistance> flag to 1.
43This feature is not implemented yet, so reseeding with prediction resistance
44requested will always fail.
45
46RAND_DRBG_set_reseed_interval()
47sets the reseed interval of the B<drbg>, which is the maximum allowed number
48of generate requests between consecutive reseedings.
49If B<interval> > 0, then the B<drbg> will reseed automatically whenever the
50number of generate requests since its last seeding exceeds the given reseed
51interval.
52If B<interval> == 0, then this feature is disabled.
53
54
55RAND_DRBG_set_reseed_time_interval()
56sets the reseed time interval of the B<drbg>, which is the maximum allowed
57number of seconds between consecutive reseedings.
58If B<interval> > 0, then the B<drbg> will reseed automatically whenever the
59elapsed time since its last reseeding exceeds the given reseed time interval.
60If B<interval> == 0, then this feature is disabled.
61
62RAND_DRBG_set_reseed_defaults() sets the default values for the reseed interval
63(B<master_reseed_interval> and B<slave_reseed_interval>)
64and the reseed time interval
65(B<master_reseed_time_interval> and B<slave_reseed_tme_interval>)
66of DRBG instances.
67The default values are set independently for master DRBG instances (which don't
68have a parent) and slave DRBG instances (which are chained to a parent DRBG).
69
70=head1 RETURN VALUES
71
72RAND_DRBG_reseed(),
73RAND_DRBG_set_reseed_interval(), and
74RAND_DRBG_set_reseed_time_interval(),
75return 1 on success, 0 on failure.
76
77
78=head1 NOTES
79
80The default OpenSSL random generator is already set up for automatic reseeding,
81so in general it is not necessary to reseed it explicitly, or to modify
82its reseeding thresholds.
83
84Normally, the entropy input for seeding a DRBG is either obtained from a
85trusted os entropy source or from a parent DRBG instance, which was seeded
86(directly or indirectly) from a trusted os entropy source.
87In exceptional cases it is possible to replace the reseeding mechanism entirely
88by providing application defined callbacks using RAND_DRBG_set_callbacks().
89
90The reseeding default values are applied only during creation of a DRBG instance.
91To ensure that they are applied to the global and thread-local DRBG instances
92(<master>, resp. <public> and <private>), it is necessary to call
93RAND_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
98L<RAND_DRBG_generate(3)>,
99L<RAND_DRBG_bytes(3)>,
100L<RAND_DRBG_set_callbacks(3)>.
101L<RAND_DRBG(7)>
102
103=head1 HISTORY
104
105The RAND_DRBG functions were added in OpenSSL 1.1.1.
106
107=head1 COPYRIGHT
108
109Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved.
110
111Licensed under the OpenSSL license (the "License").  You may not use
112this file except in compliance with the License.  You can obtain a copy
113in the file LICENSE in the source distribution or at
114L<https://www.openssl.org/source/license.html>.
115
116=cut
117