Provided by: rng-tools_2-unofficial-mt.10-2iubuntu1_i386 bug

NAME

       rngd  -  Check  and  feed  random  data  from hardware device to kernel
       entropy pool

SYNOPSIS

       rngd [-b | --background | -f  |  --foreground]  [-o  file  |  --random-
       device=file] [-r file | --rng-device=file] [-s n | --random-step=n] [-W
       n | --fill-watermark=n[%]] [-t n | --feed-interval=n] [--trng=name] [-H
       n.nnn  |  --rng-entropy=n.nnn]  [-B n | --rng-buffers=n] [-T n | --rng-
       timeout=n] [-p file | --pidfile=file] [-?] [--help] [-V] [--version]

DESCRIPTION

       This daemon feeds entropy  from  a  hardware  random  number  generator
       (HRNG)  to the kernel’s entropy pool, after checking the data to ensure
       that it is suitably random.

       Entropy measures the uncertainty (randomness) contained in an  unit  of
       information.   For  the  Linux  kernel, this unit is a binary bit.  The
       kernel keeps all the entropy it gathers from different  sources  in  an
       entropy  pool,  from  which  it  drawns  uncertainty to generate random
       numbers.

       rngd works on blocks of 20000 bits at a  time,  using  the  FIPS  140-2
       tests  to  verify the randomness of the block of data.  If it is deemed
       random, the block is fed back random-step*8  bits  at  a  time  to  the
       kernel, until the kernel’s entropy pool is full.

       When  the  entropy  pool is full, the daemon will force-feed the kernel
       random-step*8 bits of data every feed-interval  seconds,  to  stir  the
       entropy  pool.   If the HRNG used by rngd is of very high quality, this
       will improve the entropy of the pool.

       The -f or --foreground options can  be  used  to  tell  rngd  to  avoid
       forking  on  startup.  This is typically used for debugging.  The -b or
       --background options, which fork  and  put  rngd  into  the  background
       automatically, are the default.

       The  -r  or  --rng-device  options  can  be used to select an alternate
       source of entropy, instead  of  the  default  /dev/hwrng.   The  -o  or
       --random-device  options  can  be  used  to select an alternate entropy
       output device, instead of the  default  /dev/random.   Note  that  this
       device must support the Linux kernel’s /dev/random ioctl API.

       The -H or --rng-entropy options should be used to inform rngd about the
       entropy per bit of data received from the input source.

       The -B or --rng-buffers options can be used to  change  the  number  of
       buffers used by rngd.  Each buffer holds a block of 20000 bits of data,
       which  will  be  either  approved  or  discarded  by  the  FIPS  tests.
       Decreasing   the   number   of  buffers  below  3  can  degrade  rngd’s
       performance.  Increasing it above 3 will only help if you have very big
       bursts of entropy usage that a larger number of buffers can accomodate.

OPTIONS

       -b, --background
              Become a daemon (default)

       -f, --foreground
              Do not fork, nor detach from the controlling terminal

       -o file, --random-device=file (default: /dev/random)
              Kernel device used for entropy output

       -r file, --rng-device=file (default: /dev/hwrng)
              Kernel device used for entropy input

       --trng=name
              Selects known-good defaults for  some  HRNGs.   help  lists  all
              known  HRNGs.   You can override these defaults selectively with
              the other options.

       -H n.n, --rng-entropy=n.n (default: 1.0)
              Entropy per bit of input data.  This is a floating point  number
              between 0 and 1 (inclusive)

       -B n, --rng-buffers=n (default: 3)
              Number of 20000 bit buffers to use

       -s n, --random-step=n (default: 64)
              Number of bytes written to random-device at a time.  This number
              should be even, and between 8 and 2500.   Setting  it  too  high
              will  cause  rngd  to dominate the contents of the entropy pool.
              Values above 256 are unlikely to increase performance.

       -W n, --fill-watermark=n[%] (default: 50%)
              Once we start doing it, feed entropy to random-device  until  at
              least  fill-watermark  bits  of  entropy  are  available  in its
              entropy pool.  Setting this too high will cause rngd to dominate
              the  contents  of the entropy pool.  Low values will hurt system
              performance  during  entropy  starves.   fill-watermark  can  be
              specified  either  as  an  absolute  number  of  bits,  or  as a
              percentage of the total size of the entropy pool.

       -t n, --feed-interval=n (default: 60)
              If feed-interval is not zero, rngd will  force-feed  entropy  to
              the random device even when the entropy pool is full every feed-
              interval seconds.  Setting  this  too  low  may  cause  rngd  to
              dominate the contents of the entropy pool.

       --timeout=n
              Deprecated, use --feed-interval instead.

       -T n, --rng-timeout=n (default: 10)
              Time  to  wait for data to start coming from the entropy source,
              before   giving   up   and   aborting.    Zero   disables   this
              functionality,  and  will  cause  rngd  to  wait forever for the
              entropy source.

       -p file, --pidfile=file (default: /var/run/rngd.pid)
              File to write PID to when running in background mode

       -?, --help
              Give a short summary of all program options.

       -V, --version
              Print program version

WARNING

       Depending on its settings, rngd can dominate the kernel’s entropy pool,
       by feeding it so much data, so often, that other sources of entropy are
       mostly ignored or lost.  Do not to that unless you trust rngd’s  source
       of random data ultimately.

       Also,  there is only so much bandwidth available from a HRNG, and it is
       often not much.  Don’t drain too much with too low a feed-interval,  or
       rngd  may  not have enough data on its buffers when the kernel gets low
       on entropy.

STATISTICS

       rngd will dump some statistics to its output channel  hourly,  or  when
       sent  a  SIGUSR1  signal.   The output channel is either stderr when in
       foreground mode, or syslog when in background mode.

       Bits received from HRNG source is the number of bits received  by  rngd
       from  the  entropy  source.   Bits sent to kernel pool is the number of
       bits sent by rngd to the kernel, and Entropy added to  kernel  pool  is
       the number of bits of entropy in that mass of data that was informed to
       the kernel.

       FIPS 140-2 successes and FIPS  140-2  failures  counts  the  number  of
       20000-bit  blocks  either accepted or rejected by the FIPS 140-2 tests.
       The other statistics show a breakdown of the  FIPS  140-2  failures  by
       FIPS 140-2 test.  See the FIPS 140-2 document for more information.

       HRNG source speed measures the speed of the entropy source, for reading
       a 20000-bit block of data.  FIPS tests speed measures the speed of  the
       FIPS 140-2 tests for a 20000-bit block of data.

       Lowest  ready-buffers  level records the lowest number of ready buffers
       (i.e. that can be fed to the kernel) hit so far.  If it gets  to  zero,
       you may want to increase rng-buffers.  If it is always above 1, you may
       want to decrease rng-buffers.

       Entropy starvations counts the number of times the  kernel  asked  rngd
       for  entropy,  and  rngd  had  none  to  give.  Time spent starving for
       entropy records the time spent by rngd waiting for a buffer  with  good
       entropy to become available, during such an episode.

SIGNALS

       rngd  is  multithreaded.   If  the threading implementation shows up as
       multiple rngd processes, signals should be sent to the  process  listed
       in the pidfile.

       SIGTERM terminates rngd cleanly.

       SIGUSR1  causes  rngd  to  dump  some  statistics to its output channel
       immediately.

EXIT STATUS

       0 if no errors happen.

       1 if rng-source is misbehaving.

       10 if there are problems with the parameters, or if rngd fails to  lock
       the pidfile, or if rng-device cannot be opened.

       11 if an input/output error happens.

       12 if an operating system or resource starvation error happens.

BUGS

       The /dev/random driver in Linux kernels up  to  2.4.28  inclusive  (and
       probably later ones too) has broken entropy accounting, and fails to do
       catrastrophic reseeds correctly.  This has been fixed in Linux 2.6.

       It is a very bad idea to shrink the capacity of the kernel entropy pool
       with  rngd  running, as it may misbehave the next time the pool drains.
       Please restart rngd every time the kernel entropy pool size is changed.

FILES

       /dev/random,               /dev/hwrng,               /var/run/rngd.pid,
       /proc/sys/kernel/random/write_wakeup_threshold

SEE ALSO

       random(4), rngtest(1)

       FIPS PUB 140-2 Security Requirements for Cryptographic Modules, NIST,
              http://csrc.nist.gov/cryptval/140-2.htm

AUTHORS

       Philipp Rumpf
       Jeff Garzik <jgarzik@pobox.com>
       Matt Sottek
       Henrique de Moraes Holschuh <hmh@debian.org>