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

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]

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.

-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

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.

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.

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.

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.

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.

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

random(4), rngtest(1)

FIPS PUB 140-2 Security Requirements for Cryptographic Modules, NIST,

http://csrc.nist.gov/cryptval/140-2.htm

Philipp Rumpf

Jeff Garzik <jgarzik@pobox.com>

Matt Sottek

Henrique de Moraes Holschuh <hmh@debian.org>