From: Alejandro Colomar <alx@kernel.org>
To: Mingye Wang <arthur200126@gmail.com>
Cc: linux-man <linux-man@vger.kernel.org>
Subject: Re: [PATCH] random.{4,7}, getrandom.2: Adapt to Linux 5.6 changes
Date: Sat, 8 Jul 2023 21:06:59 +0200 [thread overview]
Message-ID: <62c56706-4879-3f68-745f-84f214498bf1@kernel.org> (raw)
In-Reply-To: <CAD66C+bLeRstDB++5LHEBrXNbXJxbBkupKdkReaCrKSaxkBL-g@mail.gmail.com>
[-- Attachment #1.1: Type: text/plain, Size: 10113 bytes --]
On 6/5/23 05:13, Mingye Wang wrote:
> Hi Alex,
>
> attached are two patches split and revised as requested.
>
> Regards,
> Mingye
Hi! Here go some comments for one of the patches:
> Author: Mingye Wang <arthur200126@gmail.com>
> Date: Mon Jun 5 11:10:12 2023 +0800
>
> random.{4,7}, getrandom.2: Adapt to Linux 5.6 changes In-Reply-To: <bug-214885-11311-M5kG7tptAp@https.bugzilla.kernel.org/>
>
> Linux kernel 5.6 no longer has a blocking random pool. This commit
> updates all relevant references to reflect this change.
>
> * random.7: Remove references to the blocking pool in the table. Add a
> note about the blocking pool.
> * random.7: Revise "choice of random source" to remove any recommen-
Don't hyphenate words here.
> dationof the blocking pool. Stop suggesting that the blocking pool is
> safer (it's not after initialization).
> * random.7: Add table entry for GRND_INSECURE.
> * getrandom.2: Add flag entry for GRND_INSECURE.
> * getrandom.2: Add removal note to GRND_RANDOM.
> * random.4: Split DESCRIPTION paragraph on /dev/random into two, one
> for the new behavior and the other for the old.
> * random.4: Adjust size limits and /proc list for 5.6.
> * random.4: Mention blocking resolution by high-precision timer entropy.
>
> Closes: https://bugzilla.kernel.org/show_bug.cgi?id=214885
> Signed-Off-By: Mingye Wang <arthur200126@gmail.com>
>
> diff --git a/man2/getrandom.2 b/man2/getrandom.2
> index dbd23a0a6..fb2e948be 100644
> --- a/man2/getrandom.2
> +++ b/man2/getrandom.2
> @@ -64,6 +64,8 @@ .SH DESCRIPTION
> ORed together:
> .TP
> .B GRND_RANDOM
> +.\" commit 48446f198f9adcb499b30332488dfd5bc3f176f6
> +Ignored since Linux 5.6.
> If this bit is set, then random bytes are drawn from the
> .I random
> source
> @@ -105,6 +107,13 @@ .SH DESCRIPTION
> .I errno
> set to
> .BR EAGAIN .
> +.TP GRND_INSECURE
> +.\" commit 75551dbf112c992bc6c99a972990b3f272247e23
> +Added in Linux 5.6.
> +Request best-effort, non-cryptographic-quality random bytes.
> +If this bit is set, then
> +.BR getrandom ()
> +will never block or fail due to a lack of entropy.
> .SH RETURN VALUE
> On success,
> .BR getrandom ()
> diff --git a/man4/random.4 b/man4/random.4
> index edd047b77..8e5b7152b 100644
> --- a/man4/random.4
> +++ b/man4/random.4
> @@ -58,16 +58,21 @@ .SH DESCRIPTION
> .BR getrandom (2)
> or \fI/dev/random\fP instead.
> .PP
> -The \fI/dev/random\fP device is a legacy interface which dates back to
> -a time where the cryptographic primitives used in the implementation
> -of \fI/dev/urandom\fP were not widely trusted.
> -It will return random bytes only within the estimated number of
> -bits of fresh noise in the entropy pool, blocking if necessary.
> -\fI/dev/random\fP is suitable for applications that need
> +.\" commit 30c08efec8884fb106b8e57094baa51bb4c44e32
> +As of Linux 5.6, \fI/dev/random\fP is identical to \fI/dev/urandom\fP,
> +except that it blocks during early boot.
> +A jitter-based seeding technique added in Linux 5.4 should help reduce
> +block time.
Please use semantic newlines. See man-pages(7):
Use semantic newlines
In the source of a manual page, new sentences should be
started on new lines, long sentences should be split into
lines at clause breaks (commas, semicolons, colons, and
so on), and long clauses should be split at phrase bound‐
aries. This convention, sometimes known as "semantic
newlines", makes it easier to see the effect of patches,
which often operate at the level of individual sentences,
clauses, or phrases.
> +.\" commit 50ee7529ec4500c88f8664560770a7a1b65db72b
> +.PP
> +The pre-5.6 \fI/dev/random\fP device is a legacy interface which dates
> +back to a time where the cryptographic primitives used in the implementation
> +of \fI/dev/urandom\fP were not widely trusted. It would return random bytes
> +only within the estimated number of bits of fresh noise in the entropy pool,
> +blocking until additional environmental noise is gathered.
> +This old \fI/dev/random\fP is suitable for applications that need
> high quality randomness, and can afford indeterminate delays.
> .PP
> -When the entropy pool is empty, reads from \fI/dev/random\fP will block
> -until additional environmental noise is gathered.
> Since Linux 5.6, the
> .B O_NONBLOCK
> flag is ignored as
> @@ -116,15 +121,15 @@ .SH DESCRIPTION
> .BR read (2)
> from
> .I /dev/random
> -will return at most 512 bytes
> +has the same maximum size since Linux 5.6. Between Linux 3.16 and 5.5,
> +the maximum size was 512 bytes. (340 bytes before Linux 2.6.12)
> .\" SEC_XFER_SIZE in drivers/char/random.c
> -(340 bytes before Linux 2.6.12).
> .PP
> Writing to \fI/dev/random\fP or \fI/dev/urandom\fP will update the
> entropy pool with the data written, but this will not result in a
> higher entropy count.
> This means that it will impact the contents
> -read from both files, but it will not make reads from
> +read from both files, but it will not make reads from a pre-5.6
To make it easier to grep, prefix verions with the software name (this
is done consistently in the pages). So something like 'pre-Linux 5.6'
would work.
Thanks,
Alex
> \fI/dev/random\fP faster.
> .SS Usage
> The
> @@ -145,7 +150,7 @@ .SS Usage
> network encryption session keys.
> (All major Linux distributions have saved the seed file across reboots
> since 2000 at least.)
> -Since reads from
> +Since reads from a pre-5.6
> .I /dev/random
> may block, users will usually want to open it in nonblocking mode
> (or perform a read with timeout),
> @@ -246,6 +251,7 @@ .SS /proc interfaces
> .RE
> .TP
> .I read_wakeup_threshold
> +Removed in Linux 5.6.
> This file
> contains the number of bits of entropy required for waking up processes
> that sleep waiting for entropy from
> diff --git a/man7/random.7 b/man7/random.7
> index 69e6c2403..23aecf2a2 100644
> --- a/man7/random.7
> +++ b/man7/random.7
> @@ -59,17 +59,16 @@ .SS Initialization of the entropy pool
> When a sufficient number of random bits has been collected, the
> entropy pool is considered to be initialized.
> .SS Choice of random source
> -Unless you are doing long-term key generation (and most likely not even
> -then), you probably shouldn't be reading from the
> +Unless your program may run at early-boot, before the entropy pool
> +is initialized, there is no longer any palpable difference between
> .I /dev/random
> -device or employing
> -.BR getrandom (2)
> -with the
> -.B GRND_RANDOM
> -flag.
> -Instead, either read from the
> +and
> .I /dev/urandom
> -device or employ
> +since Linux 5.6. (See the table below.)
> +.PP.
> +On older kernels, either read from the
> +.I /dev/urandom
> +device or (especially if you are concerned with early boot) employ
> .BR getrandom (2)
> without the
> .B GRND_RANDOM
> @@ -77,18 +76,6 @@ .SS Choice of random source
> The cryptographic algorithms used for the
> .I urandom
> source are quite conservative, and so should be sufficient for all purposes.
> -.PP
> -The disadvantage of
> -.B GRND_RANDOM
> -and reads from
> -.I /dev/random
> -is that the operation can block for an indefinite period of time.
> -Furthermore, dealing with the partially fulfilled
> -requests that can occur when using
> -.B GRND_RANDOM
> -or when reading from
> -.I /dev/random
> -increases code complexity.
> .\"
> .SS Monte Carlo and other probabilistic sampling applications
> Using these interfaces to provide large quantities of data for
> @@ -122,9 +109,9 @@ .SS Comparison between getrandom, /dev/urandom, and /dev/random
> T{
> .I /dev/random
> T} T{
> -Blocking pool
> +CSPRNG output
> T} T{
> -If entropy too low, blocks until there is enough entropy again
> +Never blocks
> T} T{
> Blocks until enough entropy gathered
> T}
> @@ -149,17 +136,6 @@ .SS Comparison between getrandom, /dev/urandom, and /dev/random
> T}
> T{
> .BR getrandom ()
> -.B GRND_RANDOM
> -T} T{
> -Same as
> -.I /dev/random
> -T} T{
> -If entropy too low, blocks until there is enough entropy again
> -T} T{
> -Blocks until pool ready
> -T}
> -T{
> -.BR getrandom ()
> .B GRND_NONBLOCK
> T} T{
> Same as
> @@ -171,21 +147,45 @@ .SS Comparison between getrandom, /dev/urandom, and /dev/random
> T}
> T{
> .BR getrandom ()
> -.B GRND_RANDOM
> -+
> -.B GRND_NONBLOCK
> +.B GRND_INSECURE
> T} T{
> Same as
> -.I /dev/random
> +.I /dev/urandom
> T} T{
> -.B EAGAIN
> -if not enough entropy available
> +Never blocks
> T} T{
> -.B EAGAIN
> +Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography)
> T}
> .TE
> .ad
> .\"
> +.SS The old blocking pool
> +The above table describes the behavior of the interfaces since
> +Linux 5.6. In older kernels, the
> +.I /dev/random
> +used a separate blocking pool, and
> +.BR getrandom ()
> +had a
> +.B GRND_RANDOM
> +flag for reading from the blocking pool.
> +.\"
> +.PP
> +The older blocking pool was a vestige of a time when the CSPRNG
> +was not trusted.
> +It assumed that entropy can run out by reading the CSPRNG.
> +This has never been the case.
> +Instead, programs using
> +.B GRND_RANDOM
> +and
> +.I /dev/random
> +had to deal with operations blocking indefinitely.
> +Furthermore, dealing with the partially fulfilled
> +requests that can occur when using
> +.B GRND_RANDOM
> +or when reading from
> +.I /dev/random
> +increases code complexity.
> +.\"
> .SS Generating cryptographic keys
> The amount of seed material required to generate a cryptographic key
> equals the effective key size of the key.
--
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2023-07-08 19:07 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-10-30 16:42 [Bug 214885] New: random.{4,7} [man-pages 5.13] do not reflect changes to /dev/random semantics since kernel 5.6 bugzilla-daemon
2021-10-30 17:01 ` [Bug 214885] " bugzilla-daemon
2023-05-25 11:34 ` bugzilla-daemon
2023-05-25 12:36 ` bugzilla-daemon
2023-05-29 8:50 ` [PATCH] random.{4,7}, getrandom.2: Adapt to Linux 5.6 changes Mingye Wang
2023-05-31 22:20 ` Alejandro Colomar
2023-06-02 11:35 ` Mingye Wang
2023-06-05 3:13 ` Mingye Wang
2023-07-08 19:06 ` Alejandro Colomar [this message]
2024-03-25 12:44 ` [Bug 214885] random.{4,7} [man-pages 5.13] do not reflect changes to /dev/random semantics since kernel 5.6 bugzilla-daemon
2024-03-25 13:26 ` bugzilla-daemon
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=62c56706-4879-3f68-745f-84f214498bf1@kernel.org \
--to=alx@kernel.org \
--cc=arthur200126@gmail.com \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.