From ad5973028c42d947440cdae5e4f106152c3dda28 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 8 Jun 2022 17:53:50 +0000 Subject: Prepare for 2.6.0.0; delete s6-fillurandompool; add rngseed Signed-off-by: Laurent Bercot --- doc/index.html | 4 +- doc/rngseed.html | 134 ++++++++++++++++++++++++++++++++++++++++++++ doc/s6-fillurandompool.html | 74 ------------------------ doc/upgrade.html | 4 +- 4 files changed, 139 insertions(+), 77 deletions(-) create mode 100644 doc/rngseed.html delete mode 100644 doc/s6-fillurandompool.html (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index 733a1c7..d8077c2 100644 --- a/doc/index.html +++ b/doc/index.html @@ -63,7 +63,7 @@ library.

The current released version of s6-linux-utils is -2.5.1.8.

Alternatively, you can checkout a copy of the s6-linux-utils git repository: @@ -100,8 +100,8 @@ the previous versions of s6-linux-utils and the current one.

The rngseed program
The s6-chroot program
The s6-fillurandompool program
The s6-freeramdisk program
The s6-hostname program
The s6-logwatch program

s6-linux-utils: the rngseed program

+s6-linux-utils
+Software
+skarnet.org +

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.
rngseed is inspired by Jason Donenfeld's +seedrng program. It is, +however, an independent implementation of the same concept.

s6-linux-utils: the s6-fillurandompool program

-s6-linux-utils
-Software
-skarnet.org -

The `s6-fillurandompool` program

-s6-fillurandompool blocks until the machine's -/dev/urandom entropy pool is filled up. Then it exits. -

Interface

-     s6-fillurandompool
-

Rationale

- For some reason, Linux has two separate entropy pools: one for -/dev/random and one for /dev/urandom. -

- Reading from /dev/random blocks when its entropy pool is -not full enough, so it will never return weak random data. (Reading -from /dev/random is overkill anyway, and -you -should not be doing it.) -

- However, reading from /dev/urandom (which -you should be doing) -will not block, even though the entropy pool may not have been -initialized yet. That's the only insecure thing about it: at boot time, -/dev/urandom may return weak random data, until its entropy -pool has filled up. -

- s6-fillurandompool is meant to address this issue. Call it once -early on in your boot scripts, before you need any serious random data; -when it exits, the /dev/urandom pool has been properly initialized, -and it is now safe to read from /dev/urandom every time you need -random data, until the machine shuts down. -

Notes

s6-fillurandompool will only work on a Linux kernel version -3.17 or later: this is when the -getrandom() -system call, which it internally uses, has been implemented.

The `rngseed` program

Interface

Options

Configuration options

Behaviour options

Creditability

Exit codes

Notes

The `s6-fillurandompool` program

Interface

Rationale

Notes

What has changed in s6-linux-utils

in 2.5.1.8

in 2.6.0.0

in 2.5.1.7

The rngseed program

Interface

Options

Configuration options

Behaviour options

Creditability

Exit codes

Notes

The s6-fillurandompool program

Interface

Rationale

Notes

What has changed in s6-linux-utils

in 2.5.1.8

in 2.6.0.0

in 2.5.1.7

The `rngseed` program

The `s6-fillurandompool` program