Update page a little, in particular try to describe the underlying mechanisms

in simple terms (mostly as a yardstick for others to be measured against):
     Entropy data stored previously is provided to the kernel during the boot
     sequence and used as inner-state of a stream cipher.  High quality data
     is available immediately upon kernel startup.  System activity (such as
     disk, network, and clock device interrupts), and hardware random
     generator output is collected, whitened with a crc and hash, then
     periodically folded together with stream cipher inner-state and outer-
     state to create a new inner state.  Reads from all consumers (including
     the kernel itself, which makes many requests per second) are sliced from
     the same output stream, which carves the stream cipher output
     unpredictably and helps improve forward and backtracking protection
     beyond the strength of the stream cipher.
some discussion with djm.  There may be more updates.

1 files changed, 22 insertions, 13 deletions

diff --git a/share/man/man4/random.4 b/share/man/man4/random.4
index 6c0cb7347dd..dffd054145d 100644
--- a/share/man/man4/random.4
+++ b/share/man/man4/random.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: random.4,v 1.33 2017/11/10 23:29:09 naddy Exp $
+.\"	$OpenBSD: random.4,v 1.34 2019/09/28 14:57:36 deraadt Exp $
 .\"
 .\" Copyright (c) 1996, 1997 Michael Shalayeff
 .\"
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 10 2017 $
+.Dd $Mdocdate: September 28 2019 $
 .Dt RANDOM 4
 .Os
 .Sh NAME
@@ -37,10 +37,19 @@
 The
 .Nm urandom
 device produces high quality pseudo-random output data without ever
-blocking, even immediately after booting.
-Entropy data is collected from system activity (such as disk, network,
-and clock device interrupts), and then used to key a stream cipher
-to generate the output.
+blocking.
+.Pp
+Entropy data stored previously is provided to the kernel during the
+boot sequence and used as inner-state of a stream cipher.
+High quality data is available immediately upon kernel startup.
+System activity (such as disk, network, and clock device interrupts),
+and hardware random generator output is collected, whitened with a crc
+and hash, then periodically folded together with stream cipher
+inner-state and outer-state to create a new inner state.
+Reads from all consumers (including the kernel itself, which makes many
+requests per second) are sliced from the same output stream, which carves
+the stream cipher output unpredictably and helps improve forward and
+backtracking protection beyond the strength of the stream cipher.
 .Pp
 The
 .Nm urandom
@@ -51,19 +60,19 @@ family of functions instead, which can be called in almost all
 coding environments, including
 .Xr pthreads 3 ,
 .Xr chroot 2 ,
-and
 .Xr pledge 2 ,
-and which avoids accessing a device every time.
+and
+.Xr unveil 2 ,
+and which avoids accessing a filesystem device every time.
 .Pp
-Never use
+For portability reasons, never use
 .Pa /dev/random .
 On
 .Ox ,
-it does the same as
+it is an alias for
 .Pa /dev/urandom ,
-but on many other systems, it misbehaves.
-For example, it may block, directly return entropy instead of using
-a stream cipher, or only return data from hardware random generators.
+but on many other systems misbehaves by blocking because their
+random number generators lack a robust boot-time initialization sequence.
 .Sh FILES
 .Bl -tag -width /dev/urandom -compact
 .It Pa /dev/urandom