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