113d40330Schristos=pod 213d40330Schristos 313d40330Schristos=head1 NAME 413d40330Schristos 513d40330SchristosRAND_add, RAND_poll, RAND_seed, RAND_status, RAND_event, RAND_screen, 613d40330SchristosRAND_keep_random_devices_open 713d40330Schristos- add randomness to the PRNG or get its status 813d40330Schristos 913d40330Schristos=head1 SYNOPSIS 1013d40330Schristos 1113d40330Schristos #include <openssl/rand.h> 1213d40330Schristos 1313d40330Schristos int RAND_status(void); 1413d40330Schristos int RAND_poll(); 1513d40330Schristos 1613d40330Schristos void RAND_add(const void *buf, int num, double randomness); 1713d40330Schristos void RAND_seed(const void *buf, int num); 1813d40330Schristos 1913d40330Schristos void RAND_keep_random_devices_open(int keep); 2013d40330Schristos 21*b0d17251SchristosThe following functions have been deprecated since OpenSSL 1.1.0, and can be 22*b0d17251Schristoshidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value, 23*b0d17251Schristossee L<openssl_user_macros(7)>: 2413d40330Schristos 2513d40330Schristos int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); 2613d40330Schristos void RAND_screen(void); 2713d40330Schristos 2813d40330Schristos=head1 DESCRIPTION 2913d40330Schristos 3013d40330SchristosThese functions can be used to seed the random generator and to check its 3113d40330Schristosseeded state. 3213d40330SchristosIn general, manual (re-)seeding of the default OpenSSL random generator 3313d40330Schristos(L<RAND_OpenSSL(3)>) is not necessary (but allowed), since it does (re-)seed 3413d40330Schristositself automatically using trusted system entropy sources. 3513d40330SchristosThis holds unless the default RAND_METHOD has been replaced or OpenSSL was 3613d40330Schristosbuilt with automatic reseeding disabled, see L<RAND(7)> for more details. 3713d40330Schristos 3813d40330SchristosRAND_status() indicates whether or not the random generator has been sufficiently 3913d40330Schristosseeded. If not, functions such as L<RAND_bytes(3)> will fail. 4013d40330Schristos 4113d40330SchristosRAND_poll() uses the system's capabilities to seed the random generator using 4213d40330Schristosrandom input obtained from polling various trusted entropy sources. 4313d40330SchristosThe default choice of the entropy source can be modified at build time, 4413d40330Schristossee L<RAND(7)> for more details. 4513d40330Schristos 4613d40330SchristosRAND_add() mixes the B<num> bytes at B<buf> into the internal state 4713d40330Schristosof the random generator. 4813d40330SchristosThis function will not normally be needed, as mentioned above. 4913d40330SchristosThe B<randomness> argument is an estimate of how much randomness is 5013d40330Schristoscontained in 5113d40330SchristosB<buf>, in bytes, and should be a number between zero and B<num>. 5213d40330SchristosDetails about sources of randomness and how to estimate their randomness 5313d40330Schristoscan be found in the literature; for example [NIST SP 800-90B]. 5413d40330SchristosThe content of B<buf> cannot be recovered from subsequent random generator output. 5513d40330SchristosApplications that intend to save and restore random state in an external file 5613d40330Schristosshould consider using L<RAND_load_file(3)> instead. 5713d40330Schristos 58*b0d17251SchristosNOTE: In FIPS mode, random data provided by the application is not considered to 59*b0d17251Schristosbe a trusted entropy source. It is mixed into the internal state of the RNG as 60*b0d17251Schristosadditional data only and this does not count as a full reseed. 61*b0d17251SchristosFor more details, see L<EVP_RAND(7)>. 62*b0d17251Schristos 6313d40330SchristosRAND_seed() is equivalent to RAND_add() with B<randomness> set to B<num>. 6413d40330Schristos 6513d40330SchristosRAND_keep_random_devices_open() is used to control file descriptor 6613d40330Schristosusage by the random seed sources. Some seed sources maintain open file 6713d40330Schristosdescriptors by default, which allows such sources to operate in a 6813d40330Schristoschroot(2) jail without the associated device nodes being available. When 6913d40330Schristosthe B<keep> argument is zero, this call disables the retention of file 70f30e0929Schristosdescriptors. Conversely, a nonzero argument enables the retention of 7113d40330Schristosfile descriptors. This function is usually called during initialization 72*b0d17251Schristosand it takes effect immediately. This capability only applies to the default 73*b0d17251Schristosprovider. 7413d40330Schristos 7513d40330SchristosRAND_event() and RAND_screen() are equivalent to RAND_poll() and exist 7613d40330Schristosfor compatibility reasons only. See HISTORY section below. 7713d40330Schristos 7813d40330Schristos=head1 RETURN VALUES 7913d40330Schristos 8013d40330SchristosRAND_status() returns 1 if the random generator has been seeded 8113d40330Schristoswith enough data, 0 otherwise. 8213d40330Schristos 8313d40330SchristosRAND_poll() returns 1 if it generated seed data, 0 otherwise. 8413d40330Schristos 8513d40330SchristosRAND_event() returns RAND_status(). 8613d40330Schristos 8713d40330SchristosThe other functions do not return values. 8813d40330Schristos 8913d40330Schristos=head1 SEE ALSO 9013d40330Schristos 9113d40330SchristosL<RAND_bytes(3)>, 9213d40330SchristosL<RAND_egd(3)>, 9313d40330SchristosL<RAND_load_file(3)>, 9413d40330SchristosL<RAND(7)> 95*b0d17251SchristosL<EVP_RAND(7)> 9613d40330Schristos 97a3b08d93Schristos=head1 HISTORY 98a3b08d93Schristos 99a3b08d93SchristosRAND_event() and RAND_screen() were deprecated in OpenSSL 1.1.0 and should 100a3b08d93Schristosnot be used. 101a3b08d93Schristos 10213d40330Schristos=head1 COPYRIGHT 10313d40330Schristos 104*b0d17251SchristosCopyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. 10513d40330Schristos 106*b0d17251SchristosLicensed under the Apache License 2.0 (the "License"). You may not use 10713d40330Schristosthis file except in compliance with the License. You can obtain a copy 10813d40330Schristosin the file LICENSE in the source distribution or at 10913d40330SchristosL<https://www.openssl.org/source/license.html>. 11013d40330Schristos 11113d40330Schristos=cut 112