-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


   EGD : an Entropy Gathering Daemon
   v0.6

    Brian Warner <warner@lothar.com>
    <http://www.lothar.com/tech/crypto/>

    mainly intended for use with the GNU Privacy Guard
     <http://www.gnupg.org>

This is a standalone daemon that sits around running various statistics
collection programs (ps, vmstat, iostat, etc). It hashes the results into an
"entropy pool". If things happen on your system at relatively random and
unpredictable times, then some of that randomness will become a part of the
entropy pool and can be used to generate random numbers. It is basically a
user-space implementation of the Linux kernel /dev/random device. As such, it
should be runnable on all unix-like systems. It is intended to make up for the
lack of /dev/random on non-Linux systems so that programs like GPG can be used
safely.

This daemon should be allowed to run for a long time. It only gathers a small
amount of entropy at a time, because many system statistics do not change
very frequently and are rather predictable if sampled too quickly. It does not
require any special privileges to run, but it may be reasonable for a sysadmin
to arrange for it to be started at boot time, allowing it to be used by all
users.

The daemon provides a socket interface (either UNIX-style or TCP) from which
the entropy can be read. For the exact protocol, see the notes at the end of
the daemon source. Blocking and non-blocking reads are available, as well as a
call to get the amount of entropy available in the pool. The entropy level is
raised by running gatherer programs (which happens automatically over time)
and adding their output; it is lowered by clients reading entropy. Once the
count goes to zero, no entropy can be read until some more is generated. There
is currently no equivalent to the Linux /dev/urandom device, which provides
exactly this read-when-entropy-is-empty capability (at this point the data
returned is no longer truly random, merely cryptographically strong).

The daemon is written in perl for greatest portability to lots of non-Linux
systems. perl5.004 should be plenty. It uses the SHA extension, currently by
Uwe Hollerbach, available from CPAN. If your system does not already have this
extension installed, version 1.2 will be installed for you (to make it easier
to embed this module in the GnuPG distribution). This embedded version has
been modified slightly to not ask the user about doing SHA-0 versus SHA-1 at
configure time (to allow the GnuPG configure process to remain
non-interactive). The list of entropy gathering programs includes a variety of
stats programs. They are searched for in a number of common directories. Any
that are missing are pruned from the list at startup; any that cause runtime
errors are dropped as well. Most sources remove all but the digits from the
output in an attempt to distill the entropy before counting how many bits are
provided by that source.


HOW TO INSTALL:

 Installation isn't strictly necessary. If you already have the SHA module
 installed, then the egd.pl script can be run directly from any location.
 Using the installation process just puts it into a common place. You install
 EGD just as you would any normal perl module:

  perl Makefile.PL
  make
  make test
  make install

 (there are no self-tests, so don't worry if the "make test" step complains
 about errors). The 'make install' step must generally be executed as root.
 The Makefile.PL will check to see if you have SHA installed already, and will
 build/install an included copy if not. After installation, egd.pl will
 probably be found in /usr/bin/egd.pl or /usr/local/bin/egd.pl, and should
 already be on your $PATH. The example scripts in eg/ are useful for testing,
 and for calculating how much entropy your system can generate (bits per
 second), but are not installed.


HOW TO USE EGD WITH GPG:

 First, you'll need to configure GnuPG to use EGD for it's random number needs.
 If you are compiling GPG, the easiest way to do this is at configure time.
 Add "--enable-static-rnd=egd" to the arguments you give to ./configure . If
 you have a pre-compiled version of GPG that wasn't configured this way, you
 should be able to use a loadable extension module to accomplish the same 
 thing; try adding:
  load-extension rndegd
 to your ~/.gnupg/options file, or use "--load-extension=rndegd" on the
 command line when you run GPG. Since a system that doesn't have /dev/random
 at compile time probably won't have it at runtime, configuring rndegd 
 statically makes a lot more sense.

 Second, you need to have the daemon running. EGD listens on unix-domain
 socket for entropy requests. Unless you modify the path name in the GnuPG
 file "cipher/rndegd.c", GPG will look for this socket in your home directory,
 in ~/.gnupg/entropy (specifically it will look for "entropy" in the same
 directory that has your keyrings, the "--homedir"). So you need to tell EGD
 to listen there. Simply start the daemon as follows:

  egd.pl ~/.gnupg/entropy

 If you've never run GPG before, you'll have to create your ~/.gnupg directory
 yourself (gpg will make it for you the first time it's run). The daemon
 automatically forks itself into the background. Wait a few minutes for it to
 collect some entropy. After that, GPG should run just like usual. If you
 encrypt or sign stuff too frequently, you may get messages telling you to
 wait as more entropy is gathered. Just give the daemon a few minutes to
 gather more entropy, and GPG will continue along.


HOW TO USE EGD FOR THE GPG SELF-TESTS:

 The 'make check' target in GPG performs some extensive self-tests. I highly
 recommend running them after you compile a new version, especially on the
 less-common systems (anything other than linux-i386). The only problem is
 that the self tests require an enormous amount of entropy, 58320 bytes as of
 gnupg-0.9.9 . EGD cannot gather entropy very fast (50 *bits* per second in my
 tests on a solaris box), so using EGD the normal way can result in self tests
 that take several hours to run.

 The simple workaround is the --bottomless option to EGD. That tells the
 daemon to serve up an infinite pool of entropy instead of making the
 requestor wait until more can be collected. Naturally you don't want to use
 this mode for normal encryption: it would be considerably less secure. But
 it's handy for tests. If you use it this way, I recommend also using the
 --quit-after=60 option, which tells the daemon to quit after 60 minutes. That
 way you won't have an insecure --bottomless EGD lying around forever,
 possibly encouraging unsuspecting users to use it.

 In addition, the self-tests run with GPG's --homedir option pointed at the
 source tree's checks/ directory (since they use special test keys and not
 your personal keyrings). That means they expect the entropy socket to live
 there too. Either make a symlink to your ~/.gnupg/entropy socket, or start
 the daemon listening to checks/entropy. (you can have multiple daemons
 running: your normal, real one on ~/.gnupg/entropy, and the test-only,
 --bottomless one in checks/entropy).

 So to run the self tests:

  cd gnupg-0.9.9
  egd.pl --bottomless --quit-after=60 checks/entropy
  (wait a minute or two to let the entropy build up)
  make check


LICENSE:

 EGD is free software and can be used and copied under the terms of the GNU
 General Public License. Please see the file COPYING in this directory for
 the exact terms. Share and Enjoy!

 (please note that the included SHA-1.2 module comes under a slightly
 different license, the same as used by Perl itself, which is a bit more
 liberal than the GPL. I chose to put EGD under GPL because the cryptlib
 library that inspired it was permitted to be distributed in GPG under the GPL
 and I figured I should do the same. If you find this restrictive, please
 write me, and I'd be happy to give you permission to do other stuff with it).


BUGS and LIMITATIONS:

 EGD forks itself into the background automatically. It probably doesn't do
 this as cleanly as it ought to (by following the helpful hints in the perl
 documentation). So there might be ways to make it die by removing the
 environment it was started under (unmounting the filesystem, stuff like
 that).

 The stirring of the pool feels secure to me, and uses SHA which is widely
 considered secure, but there could be some weird interaction that causes
 the entropy to be less random than you would expect. Some rough tests have
 been done, but nothing really extensive. Please consider the output to be
 fairly unpredictable but not necessarily completely random: use the output
 to seed a random number generation algorithm. This is what GPG does with it.


AUTHOR:
 Brian Warner, <warner@lothar.com>. Please send all patches, bug reports,
  and comments to me. I'm especially interested in how well it works on
  systems I don't have access to (I've only got linux, sunos, and solaris to
  test on), as well as new gatherer programs to add to the list.

 EGD was inspired by, and got the initial list of random number sources
  from, the cryptlib entropy gathering code, by Peter Gutmann and others.
  <http://www.cs.auckland.ac.nz/~pgut001/cryptlib/index.html>

 Thanks to Werner Koch for writing GnuPG and for convincing me to go and
 write this thing.

 Visit <http://www.lothar.com/tech/crypto/> for updates and other fun stuff.

Changes:
 v0.6 : fix a typo in egd.pl that caused filehandles to leak when blocking
	reads were blocked. Thanks to Dale Harris for the report.
	While searching @dirs for gatherer executables, stop after finding
	the first instance. This removes spurious duplicate gatherers on
	systems (like solaris) that have, e.g., both /bin/ps and /usr/bin/ps
	Improve argument checking in egc.pl . Thanks to Shane Kerr.
	Improve docs on how to use with GPG. Thanks to Guy Hulbert.

 v0.5 : add get-pid command to protocol (0x04)
	add --kill command to find a daemon on the specified socket and kill
	 it off
	detect if a socket is already in use and don't try to use it
	 (if all sockets are in use, just exit silently)
	fork into background unless --nofork is given
	add --quit-after=NN : terminate after NN minutes

 v0.4 : ignore SIGPIPE.
	use Getopt::Long to switch on debug flags
	don't decay entropy below zero
	add a counter for total bytes consumed. use --debug-client to display
	add eg/sucker.pl to pull out as much entropy as possible. Used to
	 determine the entropy generation rate. With all the weights and timers
	 at the default, my linux box extracts 28 bits per second out of 20
	 sources. My solaris box manages about 105 bps from 56 sources.
	add --bottomless option to not decrement entropy count when clients
	 consume entropy. Use for GPG self-tests since they require about
	 53kbytes of entropy, which would take over an hour to generate
	 on my fastest test box

 v0.3 : finally bundled into a form that could be put into the GPG 
        distribution. Included a copy of SHA-1.2 and created Makefile.PL
        tricks to build it only if necessary.

 v0.2 : add reuse timers (don't run a given gatherer too frequently)
        redirect stderr of gatherers to /dev/null (much quieter now)

 v0.1 : initial release. noisy as all heck but it seems to work.


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v0.9.9 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQE3qTKPkDmgv9E5zEwRAh1DAKCRSXH32t/raYXpNvCU0liSf14LOQCfQLZa
0SP40cKmdX8T/cbL1fdLvak=
=yOXW
-----END PGP SIGNATURE-----
