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