1=pod 2 3=head1 NAME 4 5RAND_add, RAND_seed, RAND_status, RAND_event, RAND_screen - add 6entropy to the PRNG 7 8=head1 SYNOPSIS 9 10 #include <openssl/rand.h> 11 12 void RAND_seed(const void *buf, int num); 13 14 void RAND_add(const void *buf, int num, double entropy); 15 16 int RAND_status(void); 17 18 int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); 19 void RAND_screen(void); 20 21=head1 DESCRIPTION 22 23RAND_add() mixes the B<num> bytes at B<buf> into the PRNG state. Thus, 24if the data at B<buf> are unpredictable to an adversary, this 25increases the uncertainty about the state and makes the PRNG output 26less predictable. Suitable input comes from user interaction (random 27key presses, mouse movements) and certain hardware events. The 28B<entropy> argument is (the lower bound of) an estimate of how much 29randomness is contained in B<buf>, measured in bytes. Details about 30sources of randomness and how to estimate their entropy can be found 31in the literature, e.g. RFC 1750. 32 33RAND_add() may be called with sensitive data such as user entered 34passwords. The seed values cannot be recovered from the PRNG output. 35 36OpenSSL makes sure that the PRNG state is unique for each thread. On 37systems that provide C</dev/urandom>, the randomness device is used 38to seed the PRNG transparently. However, on all other systems, the 39application is responsible for seeding the PRNG by calling RAND_add(), 40L<RAND_egd(3)|RAND_egd(3)> 41or L<RAND_load_file(3)|RAND_load_file(3)>. 42 43RAND_seed() is equivalent to RAND_add() when B<num == entropy>. 44 45RAND_event() collects the entropy from Windows events such as mouse 46movements and other user interaction. It should be called with the 47B<iMsg>, B<wParam> and B<lParam> arguments of I<all> messages sent to 48the window procedure. It will estimate the entropy contained in the 49event message (if any), and add it to the PRNG. The program can then 50process the messages as usual. 51 52The RAND_screen() function is available for the convenience of Windows 53programmers. It adds the current contents of the screen to the PRNG. 54For applications that can catch Windows events, seeding the PRNG by 55calling RAND_event() is a significantly better source of 56randomness. It should be noted that both methods cannot be used on 57servers that run without user interaction. 58 59=head1 RETURN VALUES 60 61RAND_status() and RAND_event() return 1 if the PRNG has been seeded 62with enough data, 0 otherwise. 63 64The other functions do not return values. 65 66=head1 SEE ALSO 67 68L<rand(3)|rand(3)>, L<RAND_egd(3)|RAND_egd(3)>, 69L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> 70 71=head1 HISTORY 72 73RAND_seed() and RAND_screen() are available in all versions of SSLeay 74and OpenSSL. RAND_add() and RAND_status() have been added in OpenSSL 750.9.5, RAND_event() in OpenSSL 0.9.5a. 76 77=cut 78