[Dropping a couple of other people into CC who may be able / willing to review.] Folks, I'd really appreciate some review help here! Cheers, Michael On 10/20/2016 10:37 AM, Nikos Mavrogiannopoulos wrote: > On Mon, 2016-08-01 at 13:48 +0200, Nikos Mavrogiannopoulos wrote: >> > This is an updated patch reflecting the recent discussion in linux- >> > crypto: >> > http://www.mail-archive.com/linux-crypto@xxxxxxxxxxxxxxx/msg20400.html > Hi, > I'm resending the patch with few typo fixes, and adding Ted in CC for > review. Ted would you like to review this patch for the random(4) > manpage? > > regards, > Nikos > > > 0001-Update-the-random-4-documentation-towards-a-more-acc.patch > > > From 7952cf6bbabf36a4be50a3ba953278077f7b5157 Mon Sep 17 00:00:00 2001 > From: Nikos Mavrogiannopoulos <nmav@xxxxxxxxxx> > Date: Thu, 7 Apr 2016 09:08:14 +0200 > Subject: [PATCH] Update the random(4) documentation towards a more accurate > view on /dev/urandom > > This documents the "property" of /dev/urandom of being able to serve numbers > prior to pool being initialized, and removes any suggested usages of /dev/random > which are disputable (i.e., one-time pad). > Document the fact /dev/random is a legacy interface and only suitable for > applications which can afford indeterminate delays since very few applications > can do so. > > Signed-off-by: Nikos Mavrogiannopoulos <nmav@xxxxxxxxxx> > --- > man4/random.4 | 51 ++++++++++++++++++++++++++------------------------- > 1 file changed, 26 insertions(+), 25 deletions(-) > > diff --git a/man4/random.4 b/man4/random.4 > index b67c46f..c7afaf4 100644 > --- a/man4/random.4 > +++ b/man4/random.4 > @@ -13,8 +13,9 @@ > .\" 2004-04-08, AEB, Improved description of read from /dev/urandom > .\" 2008-06-20, George Spelvin <linux@xxxxxxxxxxx>, > .\" Matt Mackall <mpm@xxxxxxxxxxx> > -.\" Add a Usage subsection that recommends most users to use > -.\" /dev/urandom, and emphasizes parsimonious usage of /dev/random. > +.\" 2016-10-20, Nikos Mavrogiannopoulos <nmav@xxxxxxxxxx> > +.\" Mention that /dev/random is a legacy interface and removed suggested > +.\" uses of /dev/random. > .\" > .TH RANDOM 4 2016-10-08 "Linux" "Linux Programmer's Manual" > .SH NAME > @@ -37,11 +38,22 @@ The generator also keeps an estimate of the > number of bits of noise in the entropy pool. > From this entropy pool random numbers are created. > .LP > -When read, the \fI/dev/random\fP device will return random bytes > -only within the estimated number of bits of noise in the entropy > -pool. > -\fI/dev/random\fP should be suitable for uses that need very > -high quality randomness such as one-time pad or key generation. > +When read, the \fI/dev/urandom\fP device return random bytes using a pseudorandom > +number generator seeded from the entropy pool. That operation is > +non-blocking. When used during early boot time, this device may return > +data prior to the entropy pool being initialized. > +If this is of concern in your application, use > +.BR getrandom(2) > +or \fI/dev/random\fP instead. > + > +.LP > +The \fI/dev/random\fP device is a legacy interface which dates back to > +a time where the cryptographic primitives used in the implementation > +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 very > +high quality randomness, and can afford indeterminate delays. > When the entropy pool is empty, reads from \fI/dev/random\fP will block > until additional environmental noise is gathered. > If > @@ -60,18 +72,8 @@ will return -1 and > .I errno > will be set to > .BR EAGAIN . > -.LP > -A read from the \fI/dev/urandom\fP device will not block > -waiting for more entropy. > -If there is not sufficient entropy, a pseudorandom number generator is used > -to create the requested bytes. > -As a result, in this case the returned values are theoretically vulnerable to a > -cryptographic attack on the algorithms used by the driver. > -Knowledge of how to do this is not available in the current unclassified > -literature, but it is theoretically possible that such an attack may > -exist. > -If this is a concern in your application, use \fI/dev/random\fP > -instead. > + > +The flag > .B O_NONBLOCK > has no effect when opening > .IR /dev/urandom . > @@ -82,6 +84,8 @@ for the device > signals will not be handled until after the requested random bytes > have been generated. > > + > + > Since Linux 3.16, > .\" commit 79a8468747c5f95ed3d5ce8376a3e82e0c5857fc > a > @@ -104,14 +108,11 @@ This means that it will impact the contents > read from both files, but it will not make reads from > \fI/dev/random\fP faster. > .SS Usage > -If you are unsure about whether you should use > +The > .IR /dev/random > -or > +interface is considered a legacy interface, and > .IR /dev/urandom , > -then probably you want to use the latter. > -As a general rule, > -.IR /dev/urandom > -should be used for everything except long-lived GPG/SSL/SSH keys. > +is recommended for general use. > > If a seed file is saved across reboots as recommended below (all major > Linux distributions have done this since 2000 at least), the output is > -- 2.7.4 > -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
