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