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