X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fcrypto%2FRAND_egd.pod;h=80fa734d1865b672288f901d5db797cba7e638fb;hp=a40bd96198861e3259eadefeb229f8de9d44a302;hb=93b83d0626e73bb09559ce85aefa418ac7318d59;hpb=a610374cb256fd2743b8cd956b7b430f916ee41a

diff --git a/doc/crypto/RAND_egd.pod b/doc/crypto/RAND_egd.pod
index a40bd96198..80fa734d18 100644
--- a/doc/crypto/RAND_egd.pod
+++ b/doc/crypto/RAND_egd.pod
@@ -2,37 +2,87 @@
 
 =head1 NAME
 
-RAND_egd - query entropy gathering daemon
+RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon
 
 =head1 SYNOPSIS
 
  #include <openssl/rand.h>
 
  int RAND_egd(const char *path);
+ int RAND_egd_bytes(const char *path, int bytes);
+
+ int RAND_query_egd_bytes(const char *path, unsigned char *buf, int bytes);
 
 =head1 DESCRIPTION
 
 RAND_egd() queries the entropy gathering daemon EGD on socket B<path>.
+It queries 255 bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the
+OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for
+RAND_egd_bytes(path, 255);
+
+RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>.
+It queries B<bytes> bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the
+OpenSSL built-in PRNG.
+This function is more flexible than RAND_egd().
+When only one secret key must
+be generated, it is not necessary to request the full amount 255 bytes from
+the EGD socket. This can be advantageous, since the amount of entropy
+that can be retrieved from EGD over time is limited.
+
+RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket
+B<path>. If B<buf> is given, B<bytes> bytes are queried and written into
+B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the
+OpenSSL built-in PRNG using L<RAND_add(3)|RAND_add(3)>.
+
+=head1 NOTES
+
+On systems without /dev/*random devices providing entropy from the kernel,
+the EGD entropy gathering daemon can be used to collect entropy. It provides
+a socket interface through which entropy can be gathered in chunks up to
+255 bytes. Several chunks can be queried during one connection.
 
 EGD is available from http://www.lothar.com/tech/crypto/ (C<perl
 Makefile.PL; make; make install> to install). It is run as B<egd>
 I<path>, where I<path> is an absolute path designating a socket. When
 RAND_egd() is called with that path as an argument, it tries to read
-random bytes that EGD has collected. The read is performed in
-non-blocking mode.
+random bytes that EGD has collected. RAND_egd() retrieves entropy from the
+daemon using the daemon's "non-blocking read" command which shall
+be answered immediately by the daemon without waiting for additional
+entropy to be collected. The write and read socket operations in the
+communication are blocking.
+
+Alternatively, the EGD-interface compatible daemon PRNGD can be used. It is
+available from
+http://prngd.sourceforge.net/ .
+PRNGD does employ an internal PRNG itself and can therefore never run
+out of entropy.
+
+OpenSSL automatically queries EGD when entropy is requested via RAND_bytes()
+or the status is checked via RAND_status() for the first time, if the socket
+is located at /var/run/egd-pool, /dev/egd-pool or /etc/egd-pool.
 
 =head1 RETURN VALUE
 
-RAND_egd() returns the number of bytes read from the daemon on
-success, and -1 if the connection failed or the daemon did not return
-enough data to fully seed the PRNG.
+RAND_egd() and RAND_egd_bytes() return the number of bytes read from the
+daemon on success, and -1 if the connection failed or the daemon did not
+return enough data to fully seed the PRNG.
+
+RAND_query_egd_bytes() returns the number of bytes read from the daemon on
+success, and -1 if the connection failed. The PRNG state is not considered.
 
 =head1 SEE ALSO
 
-L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)>
+L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>,
+L<RAND_cleanup(3)|RAND_cleanup(3)>
 
 =head1 HISTORY
 
 RAND_egd() is available since OpenSSL 0.9.5.
 
+RAND_egd_bytes() is available since OpenSSL 0.9.6.
+
+RAND_query_egd_bytes() is available since OpenSSL 0.9.7.
+
+The automatic query of /var/run/egd-pool et al was added in OpenSSL 0.9.7.
+
 =cut