xref: /freebsd/crypto/openssl/doc/man3/RAND_add.pod (revision e71b70530d95c4f34d8bdbd78d1242df1ba4a945)
1*e71b7053SJung-uk Kim=pod
2*e71b7053SJung-uk Kim
3*e71b7053SJung-uk Kim=head1 NAME
4*e71b7053SJung-uk Kim
5*e71b7053SJung-uk KimRAND_add, RAND_poll, RAND_seed, RAND_status, RAND_event, RAND_screen,
6*e71b7053SJung-uk KimRAND_keep_random_devices_open
7*e71b7053SJung-uk Kim- add randomness to the PRNG or get its status
8*e71b7053SJung-uk Kim
9*e71b7053SJung-uk Kim=head1 SYNOPSIS
10*e71b7053SJung-uk Kim
11*e71b7053SJung-uk Kim #include <openssl/rand.h>
12*e71b7053SJung-uk Kim
13*e71b7053SJung-uk Kim int RAND_status(void);
14*e71b7053SJung-uk Kim int RAND_poll();
15*e71b7053SJung-uk Kim
16*e71b7053SJung-uk Kim void RAND_add(const void *buf, int num, double randomness);
17*e71b7053SJung-uk Kim void RAND_seed(const void *buf, int num);
18*e71b7053SJung-uk Kim
19*e71b7053SJung-uk Kim void RAND_keep_random_devices_open(int keep);
20*e71b7053SJung-uk Kim
21*e71b7053SJung-uk KimDeprecated:
22*e71b7053SJung-uk Kim
23*e71b7053SJung-uk Kim #if OPENSSL_API_COMPAT < 0x10100000L
24*e71b7053SJung-uk Kim int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam);
25*e71b7053SJung-uk Kim void RAND_screen(void);
26*e71b7053SJung-uk Kim #endif
27*e71b7053SJung-uk Kim
28*e71b7053SJung-uk Kim=head1 DESCRIPTION
29*e71b7053SJung-uk Kim
30*e71b7053SJung-uk KimThese functions can be used to seed the random generator and to check its
31*e71b7053SJung-uk Kimseeded state.
32*e71b7053SJung-uk KimIn general, manual (re-)seeding of the default OpenSSL random generator
33*e71b7053SJung-uk Kim(L<RAND_OpenSSL(3)>) is not necessary (but allowed), since it does (re-)seed
34*e71b7053SJung-uk Kimitself automatically using trusted system entropy sources.
35*e71b7053SJung-uk KimThis holds unless the default RAND_METHOD has been replaced or OpenSSL was
36*e71b7053SJung-uk Kimbuilt with automatic reseeding disabled, see L<RAND(7)> for more details.
37*e71b7053SJung-uk Kim
38*e71b7053SJung-uk KimRAND_status() indicates whether or not the random generator has been sufficiently
39*e71b7053SJung-uk Kimseeded. If not, functions such as L<RAND_bytes(3)> will fail.
40*e71b7053SJung-uk Kim
41*e71b7053SJung-uk KimRAND_poll() uses the system's capabilities to seed the random generator using
42*e71b7053SJung-uk Kimrandom input obtained from polling various trusted entropy sources.
43*e71b7053SJung-uk KimThe default choice of the entropy source can be modified at build time,
44*e71b7053SJung-uk Kimsee L<RAND(7)> for more details.
45*e71b7053SJung-uk Kim
46*e71b7053SJung-uk KimRAND_add() mixes the B<num> bytes at B<buf> into the internal state
47*e71b7053SJung-uk Kimof the random generator.
48*e71b7053SJung-uk KimThis function will not normally be needed, as mentioned above.
49*e71b7053SJung-uk KimThe B<randomness> argument is an estimate of how much randomness is
50*e71b7053SJung-uk Kimcontained in
51*e71b7053SJung-uk KimB<buf>, in bytes, and should be a number between zero and B<num>.
52*e71b7053SJung-uk KimDetails about sources of randomness and how to estimate their randomness
53*e71b7053SJung-uk Kimcan be found in the literature; for example [NIST SP 800-90B].
54*e71b7053SJung-uk KimThe content of B<buf> cannot be recovered from subsequent random generator output.
55*e71b7053SJung-uk KimApplications that intend to save and restore random state in an external file
56*e71b7053SJung-uk Kimshould consider using L<RAND_load_file(3)> instead.
57*e71b7053SJung-uk Kim
58*e71b7053SJung-uk KimRAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>.
59*e71b7053SJung-uk Kim
60*e71b7053SJung-uk KimRAND_keep_random_devices_open() is used to control file descriptor
61*e71b7053SJung-uk Kimusage by the random seed sources. Some seed sources maintain open file
62*e71b7053SJung-uk Kimdescriptors by default, which allows such sources to operate in a
63*e71b7053SJung-uk Kimchroot(2) jail without the associated device nodes being available. When
64*e71b7053SJung-uk Kimthe B<keep> argument is zero, this call disables the retention of file
65*e71b7053SJung-uk Kimdescriptors. Conversely, a non-zero argument enables the retention of
66*e71b7053SJung-uk Kimfile descriptors. This function is usually called during initialization
67*e71b7053SJung-uk Kimand it takes effect immediately.
68*e71b7053SJung-uk Kim
69*e71b7053SJung-uk KimRAND_event() and RAND_screen() are equivalent to RAND_poll() and exist
70*e71b7053SJung-uk Kimfor compatibility reasons only. See HISTORY section below.
71*e71b7053SJung-uk Kim
72*e71b7053SJung-uk Kim=head1 RETURN VALUES
73*e71b7053SJung-uk Kim
74*e71b7053SJung-uk KimRAND_status() returns 1 if the random generator has been seeded
75*e71b7053SJung-uk Kimwith enough data, 0 otherwise.
76*e71b7053SJung-uk Kim
77*e71b7053SJung-uk KimRAND_poll() returns 1 if it generated seed data, 0 otherwise.
78*e71b7053SJung-uk Kim
79*e71b7053SJung-uk KimRAND_event() returns RAND_status().
80*e71b7053SJung-uk Kim
81*e71b7053SJung-uk KimThe other functions do not return values.
82*e71b7053SJung-uk Kim
83*e71b7053SJung-uk Kim=head1 HISTORY
84*e71b7053SJung-uk Kim
85*e71b7053SJung-uk KimRAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should
86*e71b7053SJung-uk Kimnot be used.
87*e71b7053SJung-uk Kim
88*e71b7053SJung-uk Kim=head1 SEE ALSO
89*e71b7053SJung-uk Kim
90*e71b7053SJung-uk KimL<RAND_bytes(3)>,
91*e71b7053SJung-uk KimL<RAND_egd(3)>,
92*e71b7053SJung-uk KimL<RAND_load_file(3)>,
93*e71b7053SJung-uk KimL<RAND(7)>
94*e71b7053SJung-uk Kim
95*e71b7053SJung-uk Kim=head1 COPYRIGHT
96*e71b7053SJung-uk Kim
97*e71b7053SJung-uk KimCopyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
98*e71b7053SJung-uk Kim
99*e71b7053SJung-uk KimLicensed under the OpenSSL license (the "License").  You may not use
100*e71b7053SJung-uk Kimthis file except in compliance with the License.  You can obtain a copy
101*e71b7053SJung-uk Kimin the file LICENSE in the source distribution or at
102*e71b7053SJung-uk KimL<https://www.openssl.org/source/license.html>.
103*e71b7053SJung-uk Kim
104*e71b7053SJung-uk Kim=cut
105