]>
Commit | Line | Data |
---|---|---|
60b52453 UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c7504aeb P |
5 | RAND_add, RAND_poll, RAND_seed, RAND_status, RAND_event, RAND_screen, |
6 | RAND_keep_random_devices_open | |
8389ec4b | 7 | - add randomness to the PRNG or get its status |
60b52453 UM |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/rand.h> | |
12 | ||
8389ec4b | 13 | int RAND_status(void); |
75e2c877 | 14 | int RAND_poll(); |
60b52453 | 15 | |
f367ac2b | 16 | void RAND_add(const void *buf, int num, double randomness); |
8389ec4b | 17 | void RAND_seed(const void *buf, int num); |
60b52453 | 18 | |
c7504aeb P |
19 | void RAND_keep_random_devices_open(int keep); |
20 | ||
be80b21d RL |
21 | Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining |
22 | B<OPENSSL_API_COMPAT> with a suitable version value, see | |
23 | L<openssl_user_macros(7)>: | |
4ec2d4d2 | 24 | |
8389ec4b | 25 | int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); |
73241290 JY |
26 | void RAND_screen(void); |
27 | ||
60b52453 UM |
28 | =head1 DESCRIPTION |
29 | ||
a73d990e DMSP |
30 | These functions can be used to seed the random generator and to check its |
31 | seeded state. | |
32 | In general, manual (re-)seeding of the default OpenSSL random generator | |
33 | (L<RAND_OpenSSL(3)>) is not necessary (but allowed), since it does (re-)seed | |
34 | itself automatically using trusted system entropy sources. | |
35 | This holds unless the default RAND_METHOD has been replaced or OpenSSL was | |
36 | built with automatic reseeding disabled, see L<RAND(7)> for more details. | |
37 | ||
38 | RAND_status() indicates whether or not the random generator has been sufficiently | |
39 | seeded. If not, functions such as L<RAND_bytes(3)> will fail. | |
40 | ||
41 | RAND_poll() uses the system's capabilities to seed the random generator using | |
c16de9d8 | 42 | random input obtained from polling various trusted entropy sources. |
a73d990e DMSP |
43 | The default choice of the entropy source can be modified at build time, |
44 | see L<RAND(7)> for more details. | |
8389ec4b | 45 | |
a73d990e DMSP |
46 | RAND_add() mixes the B<num> bytes at B<buf> into the internal state |
47 | of the random generator. | |
48 | This function will not normally be needed, as mentioned above. | |
8389ec4b RS |
49 | The B<randomness> argument is an estimate of how much randomness is |
50 | contained in | |
f367ac2b RS |
51 | B<buf>, in bytes, and should be a number between zero and B<num>. |
52 | Details about sources of randomness and how to estimate their randomness | |
a73d990e DMSP |
53 | can be found in the literature; for example [NIST SP 800-90B]. |
54 | The content of B<buf> cannot be recovered from subsequent random generator output. | |
55 | Applications that intend to save and restore random state in an external file | |
56 | should consider using L<RAND_load_file(3)> instead. | |
60b52453 | 57 | |
3a50a8a9 DMSP |
58 | NOTE: In FIPS mode, random data provided by the application is not considered to |
59 | be a trusted entropy source. It is mixed into the internal state of the RNG as | |
60 | additional data only and this does not count as a full reseed. | |
7d615e21 | 61 | For more details, see L<EVP_RAND(7)>. |
3a50a8a9 | 62 | |
f367ac2b | 63 | RAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>. |
60b52453 | 64 | |
c7504aeb P |
65 | RAND_keep_random_devices_open() is used to control file descriptor |
66 | usage by the random seed sources. Some seed sources maintain open file | |
67 | descriptors by default, which allows such sources to operate in a | |
68 | chroot(2) jail without the associated device nodes being available. When | |
69 | the B<keep> argument is zero, this call disables the retention of file | |
9c0586d5 | 70 | descriptors. Conversely, a nonzero argument enables the retention of |
c7504aeb | 71 | file descriptors. This function is usually called during initialization |
dc4e74ef P |
72 | and it takes effect immediately. This capability only applies to the default |
73 | provider. | |
c7504aeb | 74 | |
a73d990e DMSP |
75 | RAND_event() and RAND_screen() are equivalent to RAND_poll() and exist |
76 | for compatibility reasons only. See HISTORY section below. | |
1931a04c | 77 | |
60b52453 UM |
78 | =head1 RETURN VALUES |
79 | ||
a73d990e | 80 | RAND_status() returns 1 if the random generator has been seeded |
513393f8 | 81 | with enough data, 0 otherwise. |
4ec2d4d2 | 82 | |
8389ec4b | 83 | RAND_poll() returns 1 if it generated seed data, 0 otherwise. |
73241290 | 84 | |
8389ec4b | 85 | RAND_event() returns RAND_status(). |
73241290 | 86 | |
4ec2d4d2 | 87 | The other functions do not return values. |
60b52453 UM |
88 | |
89 | =head1 SEE ALSO | |
90 | ||
a73d990e DMSP |
91 | L<RAND_bytes(3)>, |
92 | L<RAND_egd(3)>, | |
93 | L<RAND_load_file(3)>, | |
94 | L<RAND(7)> | |
7d615e21 | 95 | L<EVP_RAND(7)> |
60b52453 | 96 | |
b5c4bbbe JL |
97 | =head1 HISTORY |
98 | ||
99 | RAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should | |
100 | not be used. | |
101 | ||
e2f92610 RS |
102 | =head1 COPYRIGHT |
103 | ||
fbd2ece1 | 104 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 105 | |
4746f25a | 106 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |