]>
Commit | Line | Data |
---|---|---|
a73d990e DMSP |
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, | |
65175163 P |
16 | const unsigned char *adin, size_t adinlen, |
17 | int prediction_resistance); | |
a73d990e DMSP |
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. | |
65175163 P |
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. | |
a73d990e DMSP |
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 | ||
a73d990e DMSP |
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 | ||
b5c4bbbe JL |
103 | =head1 HISTORY |
104 | ||
105 | The RAND_DRBG functions were added in OpenSSL 1.1.1. | |
106 | ||
4674aaf4 | 107 | Prediction resistance is supported from OpenSSL 3.0. |
b5c4bbbe | 108 | |
a73d990e DMSP |
109 | =head1 COPYRIGHT |
110 | ||
b5c4bbbe | 111 | Copyright 2017-2019 The OpenSSL Project Authors. All Rights Reserved. |
a73d990e | 112 | |
4746f25a | 113 | Licensed under the Apache License 2.0 (the "License"). You may not use |
a73d990e DMSP |
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 |