[PATCH] Update the random(4) documentation towards a more accurate view on /dev/urandom

[Nikos Mavrogiannopoulos <nmav-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>]

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 only suitable for applications which can afford
indeterminate delays since very few applications can do so.
Smooth the alarming language about a theoretical attack, and mention that its
security depends on the cryptographic primitives used by the kernel, as well
as the total entropy gathered.

Signed-off-by: Nikos Mavrogiannopoulos <nmav-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---
 man4/random.4 | 32 +++++++++++++++++---------------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/man4/random.4 b/man4/random.4
index b6fdd8c..27a78c6 100644
--- a/man4/random.4
+++ b/man4/random.4
@@ -38,10 +38,10 @@ 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
+only within the estimated number of bits of fresh 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.
+\fI/dev/random\fP is suitable for uses 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
@@ -63,15 +63,20 @@ will be set to
 .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.
+If the estimated fresh entropy is not sufficient, a pseudorandom number generator is
+used to create the requested bytes. This is typically of no concern to applications,
+except for applications that initialize early at boot time, in systems which cannot
+accumulate sufficient entropy at boot.
+
+As a result, in this case the returned values' security depends on
+the cryptographic primitives used by the driver, and the entropy accumulated
+by the system. An attack on the cryptographic primitives is not available in the
+current unclassified literature, but it is theoretically possible that such an attack
+exists.
+
+If these are a concern in your application, use
+.BR getrandom(2)
+or \fI/dev/random\fP instead.
 .B O_NONBLOCK
 has no effect when opening
 .IR /dev/urandom .
@@ -109,9 +114,6 @@ If you are unsure about whether you should use
 or
 .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.
 
 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.5.5







--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html