diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2022-06-08 17:53:50 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska@appnovation.com> | 2022-06-08 17:53:50 +0000 |
| commit | ad5973028c42d947440cdae5e4f106152c3dda28 (patch) | |
| tree | e3fc1cb6767c5436ee269fedd80d0d063ea98bc5 /doc | |
| parent | 8add2dbec0842d5b051b4dba5536fba9d82ce6bc (diff) | |
| download | s6-linux-utils-ad5973028c42d947440cdae5e4f106152c3dda28.tar.gz s6-linux-utils-ad5973028c42d947440cdae5e4f106152c3dda28.tar.xz s6-linux-utils-ad5973028c42d947440cdae5e4f106152c3dda28.zip | |
Prepare for 2.6.0.0; delete s6-fillurandompool; add rngseed
Signed-off-by: Laurent Bercot <ska@appnovation.com>
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 4 | ||||
| -rw-r--r-- | doc/rngseed.html | 134 | ||||
| -rw-r--r-- | doc/s6-fillurandompool.html | 74 | ||||
| -rw-r--r-- | doc/upgrade.html | 4 |
4 files changed, 139 insertions, 77 deletions
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. </li> <ul> <li> The current released version of s6-linux-utils is -<a href="s6-linux-utils-2.5.1.8.tar.gz">2.5.1.8</a>. </li> +<a href="s6-linux-utils-2.6.0.0.tar.gz">2.6.0.0</a>. </li> <li> Alternatively, you can checkout a copy of the <a href="//git.skarnet.org/cgi-bin/cgit.cgi/s6-linux-utils/">s6-linux-utils git repository</a>: @@ -100,8 +100,8 @@ the previous versions of s6-linux-utils and the current one. </li> </p> <ul> +<li><a href="rngseed.html">The <tt>rngseed</tt> program</a></li> <li><a href="s6-chroot.html">The <tt>s6-chroot</tt> program</a></li> -<li><a href="s6-fillurandompool.html">The <tt>s6-fillurandompool</tt> program</a></li> <li><a href="s6-freeramdisk.html">The <tt>s6-freeramdisk</tt> program</a></li> <li><a href="s6-hostname.html">The <tt>s6-hostname</tt> program</a></li> <li><a href="s6-logwatch.html">The <tt>s6-logwatch</tt> program</a></li> diff --git a/doc/rngseed.html b/doc/rngseed.html new file mode 100644 index 0000000..d08f56c --- /dev/null +++ b/doc/rngseed.html @@ -0,0 +1,134 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-linux-utils: the rngseed program</title> + <meta name="Description" content="s6-linux-utils: the rngseed program" /> + <meta name="Keywords" content="s6 linux administration root utilities rngseed random pool entropy getrandom seedrng secure random number generator" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-linux-utils</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>rngseed</tt> program </h1> + +<p> + <tt>rngseed</tt> 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. +</p> + +<p> + <tt>rngseed</tt> can only be run as root. +</p> + +<h2> Interface </h2> + +<pre> + rngseed [ -r | -R ] [ -N | -n ] [ -w | -W ] [ -d <em>dir</em> ] [ -v <em>verbosity</em> ] +</pre> + +<p> + 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. +</p> + +<h2> Options </h2> + +<h3> Configuration options </h3> + +<ul> + <li> <tt>-v <em>verbosity</em></tt> : be more or less verbose. +Default is <tt>1</tt>, meaning rngseed will print warning and error +messages. <tt>0</tt> will make it only print error messages, not warnings. +<tt>2</tt> or more will make it add informational messages. </li> + <li> <tt>-d <em>dir</em></tt> : use <em>dir</em> as the +directory where the seed file is located (for reading as well as writing). +<em>dir</em> must be located on a writable, permanent filesystem. +Default is <tt>/var/lib/rngseed</tt>. </li> +</ul> + +<h3> Behaviour options </h3> + +<ul> + <li> <tt>-r</tt> : read from a seed file. rngseed will attempt to read +some bits from <tt><em>dir</em>/seed</tt> and seed the kernel's RNG with the data. +<em>dir</em> 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). <tt>rngseed -r</tt> is +typically used at boot time, in init scripts, right after mounting the +filesystem where the seed has been saved. </li> + <li> <tt>-R</tt> : read from a seed file, ignoring creditability. +Behaves like <tt>-r</tt>, but will not increase the entropy count of the +kernel RNG even if the seed file is marked as creditable. </li> + <li> <tt>-w</tt> : write to a seed file. rngseed will save some +random bits into <tt><em>dir</em>/seed</tt>, marking the seed as creditable if the +RNG's entropy pool is fully initialized. <tt>rngseed -w</tt> 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 <tt>rngseed -r</tt>. </li> + <li> <tt>-W</tt> : write to a seed file, without registering +creditability. Behaves like <tt>-w</tt>, but does not mark the new seed +file as creditable. </li> + <li> <tt>-N</tt> : 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. </li> + <li> <tt>-n</tt> : do not block. Immediately proceed even if the entropy +pool is not ready. This may make a new seed file non-creditable. </li> +</ul> + +<h2> Creditability </h2> + +<p> + A seed is said to be <em>creditable</em> 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. +<tt>rngseed -w</tt> 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. +</p> + +<p> + An <em>uncreditable</em> 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. <tt>rngseed -r</tt> will do the right thing if the seed +it reads is uncreditable. +</p> + +<p> + <tt>rngseed</tt> uses the seed file's permissions to mark creditability. +An uncreditable seed has rights 0600; a creditable seed has rights 0400. +</p> + +<h2> Exit codes </h2> + +<ul> + <li> 0: success </li> + <li> 100: wrong usage </li> + <li> 111: system call failure </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> <tt>rngseed -N</tt> replaces the old <tt>s6-fillurandompool</tt> program, +that only waited for the entropy pool to get ready, but did not include any +seed file management. </li> + <li> The options are named <tt>r</tt> and <tt>w</tt> from the <em>seed file</em>'s +point of view. +<tt>rngseed -r</tt> reads from the file (and unlinks it) and writes to the kernel +RNG. <tt>rngseed -w</tt> reads from the kernel RNG and writes to the file. </li> + <li> <tt>rngseed</tt> is inspired by Jason Donenfeld's +<a href="https://git.zx2c4.com/seedrng/about/">seedrng</a> program. It is, +however, an independent implementation of the same concept. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-fillurandompool.html b/doc/s6-fillurandompool.html deleted file mode 100644 index c07b0f4..0000000 --- a/doc/s6-fillurandompool.html +++ /dev/null @@ -1,74 +0,0 @@ -<html> - <head> - <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6-linux-utils: the s6-fillurandompool program</title> - <meta name="Description" content="s6-linux-utils: the s6-fillurandompool program" /> - <meta name="Keywords" content="s6 linux administration root utilities random urandom /dev/urandom entropy pool getrandom getentropy" /> - <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">s6-linux-utils</a><br /> -<a href="//skarnet.org/software/">Software</a><br /> -<a href="//skarnet.org/">skarnet.org</a> -</p> - -<h1> The <tt>s6-fillurandompool</tt> program </h1> - -<p> -<tt>s6-fillurandompool</tt> blocks until the machine's -<tt>/dev/urandom</tt> entropy pool is filled up. Then it exits. -</p> - -<h2> Interface </h2> - -<pre> - s6-fillurandompool -</pre> - -<h2> Rationale </h2> - -<p> - For some reason, Linux has <em>two</em> separate entropy pools: one for -<tt>/dev/random</tt> and one for <tt>/dev/urandom</tt>. -</p> - -<p> - Reading from <tt>/dev/random</tt> blocks when its entropy pool is -not full enough, so it will never return weak random data. (Reading -from <tt>/dev/random</tt> is overkill anyway, and -<a href="https://sockpuppet.org/blog/2014/02/25/safely-generate-random-numbers/">you -should not be doing it.</a>) -</p> - -<p> - However, reading from <tt>/dev/urandom</tt> (which -<a href="https://www.2uo.de/myths-about-urandom/">you should be doing</a>) -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, -<tt>/dev/urandom</tt> may return weak random data, until its entropy -pool has filled up. -</p> - -<p> - <tt>s6-fillurandompool</tt> 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 <tt>/dev/urandom</tt> pool has been properly initialized, -and it is now safe to read from <tt>/dev/urandom</tt> every time you need -random data, until the machine shuts down. -</p> - -<h2> Notes </h2> - -<ul> - <li> <tt>s6-fillurandompool</tt> will only work on a Linux kernel version -3.17 or later: this is when the -<a href="https://man7.org/linux/man-pages/man2/getrandom.2.html"><tt>getrandom()</tt></a> -system call, which it internally uses, has been implemented. </li> -</ul> - -</body> -</html> diff --git a/doc/upgrade.html b/doc/upgrade.html index e8e658e..bc39329 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -18,11 +18,13 @@ <h1> What has changed in s6-linux-utils </h1> -<h2> in 2.5.1.8 </h2> +<h2> in 2.6.0.0 </h2> <ul> <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> dependency bumped to 2.12.0.0. </li> + <li> <tt>s6-fillurandompool</tt> has been replaced with the new +<a href="rngseed.html">rngseed</a> program. </li> </ul> <h2> in 2.5.1.7 </h2> |