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