1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948RAND_egd - query entropy gathering daemon 6*2175Sjp161948 7*2175Sjp161948=head1 SYNOPSIS 8*2175Sjp161948 9*2175Sjp161948 #include <openssl/rand.h> 10*2175Sjp161948 11*2175Sjp161948 int RAND_egd(const char *path); 12*2175Sjp161948 int RAND_egd_bytes(const char *path, int bytes); 13*2175Sjp161948 14*2175Sjp161948 int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes); 15*2175Sjp161948 16*2175Sjp161948=head1 DESCRIPTION 17*2175Sjp161948 18*2175Sjp161948RAND_egd() queries the entropy gathering daemon EGD on socket B<path>. 19*2175Sjp161948It queries 255 bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the 20*2175Sjp161948OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for 21*2175Sjp161948RAND_egd_bytes(path, 255); 22*2175Sjp161948 23*2175Sjp161948RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>. 24*2175Sjp161948It queries B<bytes> bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the 25*2175Sjp161948OpenSSL built-in PRNG. 26*2175Sjp161948This function is more flexible than RAND_egd(). 27*2175Sjp161948When only one secret key must 28*2175Sjp161948be generated, it is not necessary to request the full amount 255 bytes from 29*2175Sjp161948the EGD socket. This can be advantageous, since the amount of entropy 30*2175Sjp161948that can be retrieved from EGD over time is limited. 31*2175Sjp161948 32*2175Sjp161948RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket 33*2175Sjp161948B<path>. If B<buf> is given, B<bytes> bytes are queried and written into 34*2175Sjp161948B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the 35*2175Sjp161948OpenSSL built-in PRNG using L<RAND_add(3)|RAND_add(3)>. 36*2175Sjp161948 37*2175Sjp161948=head1 NOTES 38*2175Sjp161948 39*2175Sjp161948On systems without /dev/*random devices providing entropy from the kernel, 40*2175Sjp161948the EGD entropy gathering daemon can be used to collect entropy. It provides 41*2175Sjp161948a socket interface through which entropy can be gathered in chunks up to 42*2175Sjp161948255 bytes. Several chunks can be queried during one connection. 43*2175Sjp161948 44*2175Sjp161948EGD is available from http://www.lothar.com/tech/crypto/ (C<perl 45*2175Sjp161948Makefile.PL; make; make install> to install). It is run as B<egd> 46*2175Sjp161948I<path>, where I<path> is an absolute path designating a socket. When 47*2175Sjp161948RAND_egd() is called with that path as an argument, it tries to read 48*2175Sjp161948random bytes that EGD has collected. The read is performed in 49*2175Sjp161948non-blocking mode. 50*2175Sjp161948 51*2175Sjp161948Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is 52*2175Sjp161948available from 53*2175Sjp161948http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html . 54*2175Sjp161948PRNGD does employ an internal PRNG itself and can therefore never run 55*2175Sjp161948out of entropy. 56*2175Sjp161948 57*2175Sjp161948OpenSSL automatically queries EGD when entropy is requested via RAND_bytes() 58*2175Sjp161948or the status is checked via RAND_status() for the first time, if the socket 59*2175Sjp161948is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool. 60*2175Sjp161948 61*2175Sjp161948=head1 RETURN VALUE 62*2175Sjp161948 63*2175Sjp161948RAND_egd() and RAND_egd_bytes() return the number of bytes read from the 64*2175Sjp161948daemon on success, and -1 if the connection failed or the daemon did not 65*2175Sjp161948return enough data to fully seed the PRNG. 66*2175Sjp161948 67*2175Sjp161948RAND_query_egd_bytes() returns the number of bytes read from the daemon on 68*2175Sjp161948success, and -1 if the connection failed. The PRNG state is not considered. 69*2175Sjp161948 70*2175Sjp161948=head1 SEE ALSO 71*2175Sjp161948 72*2175Sjp161948L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, 73*2175Sjp161948L<RAND_cleanup(3)|RAND_cleanup(3)> 74*2175Sjp161948 75*2175Sjp161948=head1 HISTORY 76*2175Sjp161948 77*2175Sjp161948RAND_egd() is available since OpenSSL 0.9.5. 78*2175Sjp161948 79*2175Sjp161948RAND_egd_bytes() is available since OpenSSL 0.9.6. 80*2175Sjp161948 81*2175Sjp161948RAND_query_egd_bytes() is available since OpenSSL 0.9.7. 82*2175Sjp161948 83*2175Sjp161948The automatic query of /var/run/egd-pool et al was added in OpenSSL 0.9.7. 84*2175Sjp161948 85*2175Sjp161948=cut 86