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