s6-linux-utils: the rngseed program

The `rngseed` program

rngseed manipulates the Linux kernel's entropy pool. It can seed the kernel's random number generator from a file, save a new seed into a file, wait until the entropy pool is full, and so on. Please read the options list carefully in order to use it in a secure way.

rngseed can only be run as root.

Interface

     rngseed [ -r | -R ] [ -N | -n ] [ -w | -W ] [ -d dir ] [ -v verbosity ]

The behaviour of rngseed depends on what options it is given. By default, it just waits until the entropy pool is full, then exits 0.

Options

Configuration options

-v verbosity : be more or less verbose. Default is 1, meaning rngseed will print warning and error messages. 0 will make it only print error messages, not warnings. 2 or more will make it add informational messages.
-d dir : use dir as the directory where the seed file is located (for reading as well as writing). dir must be located on a writable, permanent filesystem. Default is /var/lib/rngseed.

Behaviour options

-r : read from a seed file. rngseed will attempt to read some bits from dir/seed and seed the kernel's RNG with the data. dir must be on a writable filesystem, because the seed file will be unlinked (the same data must not be used to seed the RNG twice). rngseed -r is typically used at boot time, in init scripts, right after mounting the filesystem where the seed has been saved.
-R : read from a seed file, ignoring creditability. Behaves like -r, but will not increase the entropy count of the kernel RNG even if the seed file is marked as creditable.
-w : write to a seed file. rngseed will save some random bits into dir/seed, marking the seed as creditable if the RNG's entropy pool is fully initialized. rngseed -w is typically used at shutdown time, right before unmounting filesystems; the point is to store a seed on disk so it can be reused on next boot by rngseed -r.
-W : write to a seed file, without registering creditability. Behaves like -w, but does not mark the new seed file as creditable.
-N : block. After reading a seed file if required, and before writing a new seed file if required, rngseed will wait until the entropy pool is ready. This ensures that future readings of the kernel RNG will be cryptographically secure, and that new seed files will be creditable. This is the default.
-n : do not block. Immediately proceed even if the entropy pool is not ready. This may make a new seed file non-creditable.

Creditability

A seed is said to be creditable if it has been obtained through a cryptographically secure RNG. This means it is safe from replay attacks, and safe to use to count towards the entropy pool when seeding the kernel RNG. rngseed -w will normally always create a creditable seed file, especially if used at shutdown time: by then, the kernel's entropy pool should have been initialized for a while.

An uncreditable seed can be used to add to the random pool, but should not increment the entropy count, because it is not safe from replay attacks. rngseed -r will do the right thing if the seed it reads is uncreditable.

rngseed uses the seed file's permissions to mark creditability. An uncreditable seed has rights 0600; a creditable seed has rights 0400.

Exit codes

0: success
100: wrong usage
111: system call failure

Notes

rngseed -N replaces the old s6-fillurandompool program, that only waited for the entropy pool to get ready, but did not include any seed file management.
The options are named r and w from the seed file's point of view. rngseed -r reads from the file (and unlinks it) and writes to the kernel RNG. rngseed -w reads from the kernel RNG and writes to the file.
It is a good idea to use rngseed -rw at boot time, rather than rngseed -r. This ensures that a seed file will be present on next boot even if the system doesn't undergo a clean shutdown (e.g. the power fails). Of course, this does not preclude running rngseed -w in the shutdown sequence, so the next boot runs with the freshest possible seed.
rngseed is inspired by Jason Donenfeld's seedrng program. It is, however, an independent implementation of the same concept.

The rngseed program