]>
Commit | Line | Data |
---|---|---|
60b52453 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c16de9d8 | 5 | RAND_add, RAND_poll, RAND_seed, RAND_status, RAND_event, RAND_screen |
8389ec4b | 6 | - add randomness to the PRNG or get its status |
60b52453 UM |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/rand.h> | |
11 | ||
8389ec4b | 12 | int RAND_status(void); |
75e2c877 | 13 | int RAND_poll(); |
60b52453 | 14 | |
f367ac2b | 15 | void RAND_add(const void *buf, int num, double randomness); |
8389ec4b | 16 | void RAND_seed(const void *buf, int num); |
60b52453 | 17 | |
8389ec4b | 18 | Deprecated: |
4ec2d4d2 | 19 | |
1931a04c | 20 | #if OPENSSL_API_COMPAT < 0x10100000L |
8389ec4b | 21 | int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); |
73241290 | 22 | void RAND_screen(void); |
1931a04c | 23 | #endif |
73241290 | 24 | |
60b52453 UM |
25 | =head1 DESCRIPTION |
26 | ||
8389ec4b RS |
27 | Random numbers are a vital part of cryptography, including key generation, |
28 | creating salts, etc., and software-based | |
29 | generators must be "seeded" with external randomness before they can be | |
30 | used as a cryptographically-secure pseudo-random number generator (CSPRNG). | |
31 | The availability of common hardware with special instructions and | |
32 | modern operating systems, which may use items such as interrupt jitter | |
33 | and network packet timings, can be reasonable sources of seeding material. | |
34 | ||
35 | RAND_status() indicates whether or not the CSPRNG has been sufficiently | |
36 | seeded. If not, functions such as RAND_bytes(3) will fail. | |
37 | ||
c16de9d8 DMSP |
38 | RAND_poll() uses the system's capabilities to seed the CSPRNG using |
39 | random input obtained from polling various trusted entropy sources. | |
40 | The default choice of the entropy source can be modified at build time | |
41 | using the --with-rand-seed configure option, see also the B<NOTES> section. | |
42 | A summary of the configure options can be displayed with the OpenSSL | |
43 | L<version(1)> command. | |
8389ec4b RS |
44 | |
45 | RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. | |
46 | The B<randomness> argument is an estimate of how much randomness is | |
47 | contained in | |
f367ac2b RS |
48 | B<buf>, in bytes, and should be a number between zero and B<num>. |
49 | Details about sources of randomness and how to estimate their randomness | |
8389ec4b RS |
50 | can be found in the literature; for example NIST SP 800-90B. |
51 | The content of B<buf> cannot be recovered from subsequent CSPRNG output. | |
52 | This function will not normally be needed, as RAND_poll() should have been | |
53 | configured to do the appropriate seeding for the local platform. | |
54 | Applications that need to keep random state in an external file should | |
55 | use L<RAND_load_file(3)>. | |
60b52453 | 56 | |
f367ac2b | 57 | RAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>. |
60b52453 | 58 | |
8389ec4b | 59 | RAND_event() and RAND_screen() are equivalent to RAND_poll(). |
1931a04c | 60 | |
60b52453 UM |
61 | =head1 RETURN VALUES |
62 | ||
8389ec4b | 63 | RAND_status() returns 1 if the CSPRNG has been seeded |
513393f8 | 64 | with enough data, 0 otherwise. |
4ec2d4d2 | 65 | |
8389ec4b | 66 | RAND_poll() returns 1 if it generated seed data, 0 otherwise. |
73241290 | 67 | |
8389ec4b | 68 | RAND_event() returns RAND_status(). |
73241290 | 69 | |
4ec2d4d2 | 70 | The other functions do not return values. |
60b52453 | 71 | |
c16de9d8 DMSP |
72 | =head1 NOTES |
73 | ||
74 | The new OpenSSL DRBG has some peculiarities which need to be taken | |
75 | into account when it is selected as the default OpenSSL CSPRNG, i.e., | |
76 | when RAND_get_rand_method() == RAND_OpenSSL(). | |
77 | This applies in particular to the way reseeding is done by the DRBG: | |
78 | ||
79 | =over 2 | |
80 | ||
81 | =item * | |
82 | ||
83 | The DRBG seeds itself automatically, pulling random input from trusted | |
84 | entropy sources. | |
85 | Automatic reseeding occurs after a predefined number of generate requests. | |
86 | The selection of the trusted entropy sources is configured at build | |
87 | time using the --with-rand-seed option. | |
88 | ||
89 | =item * | |
90 | ||
91 | The DRBG distinguishes two different types of random input: | |
92 | 'entropy', which comes from a trusted source, and 'additional input', | |
93 | which can optionally be added by the user and is considered untrusted. | |
94 | ||
95 | =back | |
96 | ||
97 | Automatic seeding can be disabled using the --with-rand-seed=none option. | |
98 | ||
99 | =head2 DRBG with automatic seeding enabled | |
100 | ||
101 | Calling RAND_poll() or RAND_add() is not necessary, because the DRBG | |
102 | polls the entropy source automatically. | |
103 | However, both calls are permitted, and do reseed the RNG. | |
104 | ||
105 | RAND_add() can be used to add both kinds of random input, depending on the | |
106 | value of the B<randomness> argument: | |
107 | ||
108 | =over 4 | |
109 | ||
110 | =item randomness == 0: | |
111 | ||
112 | The random bytes are mixed as additional input into the current state of | |
113 | the DRBG. | |
114 | Mixing in additional input is not considered a full reseeding, hence the | |
115 | reseed counter is not reset. | |
116 | ||
117 | ||
118 | =item randomness > 0: | |
119 | ||
120 | The random bytes are used as entropy input for a full reseeding | |
121 | (resp. reinstantiation) if the DRBG is instantiated | |
122 | (resp. uninstantiated or in an error state). | |
123 | A reseeding requires 16 bytes (128 bits) of randomness. | |
124 | It is possible to provide less randomness than required. | |
125 | In this case the missing randomness will be obtained by pulling random input | |
126 | from the trusted entropy sources. | |
127 | ||
128 | =back | |
129 | ||
130 | =head2 DRBG with automatic seeding disabled (--with-rand-seed=none) | |
131 | ||
132 | Calling RAND_poll() will always fail. | |
133 | ||
134 | RAND_add() needs to be called for initial seeding and periodic reseeding. | |
135 | At least 16 bytes (128 bits) of randomness have to be provided, otherwise | |
136 | the (re-)seeding of the DRBG will fail. | |
137 | ||
1931a04c JY |
138 | =head1 HISTORY |
139 | ||
8389ec4b RS |
140 | RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should |
141 | not be used. | |
1931a04c | 142 | |
60b52453 UM |
143 | =head1 SEE ALSO |
144 | ||
b97fdb57 | 145 | L<RAND_bytes(3)>, L<RAND_egd(3)>, |
04256277 | 146 | L<RAND_load_file(3)> |
60b52453 | 147 | |
e2f92610 RS |
148 | =head1 COPYRIGHT |
149 | ||
04256277 | 150 | Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
151 | |
152 | Licensed under the OpenSSL license (the "License"). You may not use | |
153 | this file except in compliance with the License. You can obtain a copy | |
154 | in the file LICENSE in the source distribution or at | |
155 | L<https://www.openssl.org/source/license.html>. | |
156 | ||
157 | =cut |