Revised draft of random(7) man page for review

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 11639 bytes --]

Hello all,

Here's one more draft of the random(7) man page for review. I wanted to 
recirculate this one more time, because I came up with  couple of
questions (shown in FIXMEs below). 

Ted, I'd be especially happy if you could take a look at those questions, 
but I also welcome any input from others, as well as any further comments
on the remainder of the page.

Rendered version of the page is below; source is attached.

Cheers,

Michael


RANDOM(7)              Linux Programmer's Manual             RANDOM(7)

NAME
       random - overview of interfaces for obtaining randomness

DESCRIPTION
       The  kernel  provides  the following interfaces to the kernel's
       cryptographically   secure   pseudorandom   number    generator
       (CSPRNG):

       *  The  /dev/urandom and /dev/random devices, both described in
          random(4).  These devices have been present on  Linux  since
          early times, and are also available on many other systems.

       *  The Linux-specific getrandom(2) system call, available since
          Linux 3.17.  This system call provides access either to  the
          same  source  as  /dev/urandom (called the urandom source in
          this page) or to the same source as /dev/random (called  the
          random  source  in  this  page).  The default is the urandom
          source; the random source  is  selected  by  specifying  the
          GRND_RANDOM flag to the system call.

   Initialization of the entropy pool
       The kernel collects bits of entropy from the environment.  When
       a sufficient number of random  bits  has  been  collected,  the
       entropy pool is considered to be initialized.

   Choice of random device
       Unless  you are doing long-term key generation (and most likely
       not even then), you probably shouldn't be using the /dev/random
       device or getrandom(2) with the GRND_RANDOM flag.

       Instead,  use  either  the  /dev/urandom device or getrandom(2)
       without the GRND_RANDOM  flag.   The  cryptographic  algorithms
       used  for  the  urandom  source  are quite conservative, and so
       should be sufficient for all purposes.

       The disadvantage of GRND_RANDOM and reads from  /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 GRND_RANDOM or when reading from /dev/ran‐
       dom increases code complexity.

   Usage recommendations
       The kernel random-number generator relies on  entropy  gathered
       from  device  drivers and other sources of environmental noise.
       It is designed to produce a small amount of  high-quality  seed
       material to seed a cryptographically secure pseudorandom number
       generator (CSPRNG).  It is designed for  security,  not  speed,
       and  is  poorly  suited  to generating large amounts of crypto‐
       graphic random data.  Users should be economical in the  amount
       of seed material that they consume via getrandom(2), /dev/uran‐
       dom, and /dev/random.


       ┌─────────────────────────────────────────────────────┐
       │FIXME                                                │
       ├─────────────────────────────────────────────────────┤
       │Is it really  necessary  to  avoid  consuming  large │
       │amounts from /dev/urandom? Various sources linked to │
       │by https://bugzilla.kernel.org/show_bug.cgi?id=71211 │
       │suggest it is not.                                   │
       │                                                     │
       │And: has the answer to the previous question changed │
       │across kernel versions?                              │
       └─────────────────────────────────────────────────────┘
       Consuming unnecessarily large  quantities  of  data  via  these
       interfaces  will  have  a negative impact on other consumers of
       randomness.


       ┌─────────────────────────────────────────────────────┐
       │FIXME                                                │
       ├─────────────────────────────────────────────────────┤
       │Above: we need to define "negative impact".  Is  the │
       │only  negative  impact  that  we may slow readers of │
       │/dev/random, since it will  block  until  sufficient │
       │entropy has once more accumulated?                   │
       │                                                     │
       │And: has the answer to the previous question changed │
       │across kernel versions?                              │
       └─────────────────────────────────────────────────────┘

       These interfaces should not be used to provide large quantities
       of  data  for  Monte  Carlo simulations or other programs/algo‐
       rithms which are doing probabilistic  sampling.   Indeed,  such
       usage  will  be slow, and is unnecessary, because such applica‐
       tions do  not  need  crytographically  secure  random  numbers.
       Instead, use these interfaces to provide a small amount of data
       used to seed a user-space pseudorandom number generator for use
       by such applications.

   Comparison between getrandom, /dev/urandom, and /dev/random
       The  following  table  summarizes  the  behavior of the various
       interfaces that can be used to  obtain  randomness.   GRND_NON‐
       BLOCK is a flag that can be used to control the blocking behav‐
       ior of getrandom(2).  The final column of the  table  considers
       the  case  that  can  occur in early boot time when the entropy
       pool is not yet initialized.

       ┌──────────────┬──────────────┬────────────────┬────────────────────┐
       │Interface     │ Pool         │ Blocking       │ Behavior when pool │
       │              │              │ behavior       │ is not yet ready   │
       ├──────────────┼──────────────┼────────────────┼────────────────────┤
       │/dev/random   │ Blocking     │ If entropy too │ Blocks until       │
       │              │ pool         │ low, blocks    │ enough entropy     │
       │              │              │ until there is │ gathered           │
       │              │              │ enough entropy │                    │
       │              │              │ again          │                    │
       ├──────────────┼──────────────┼────────────────┼────────────────────┤
       │/dev/urandom  │ CSPRNG out‐  │ Never blocks   │ Returns output     │
       │              │ put          │                │ from uninitialized │
       │              │              │                │ CSPRNG (may be low │
       │              │              │                │ entropy and        │
       │              │              │                │ unsuitable for     │
       │              │              │                │ cryptography)      │
       ├──────────────┼──────────────┼────────────────┼────────────────────┤
       │getrandom()   │ Same as      │ Does not block │ Blocks until pool  │
       │              │ /dev/urandom │ once is pool   │ ready              │
       │              │              │ ready          │                    │
       ├──────────────┼──────────────┼────────────────┼────────────────────┤
       │getrandom()   │ Same as      │ If entropy too │ Blocks until pool  │
       │GRND_RANDOM   │ /dev/random  │ low, blocks    │ ready              │
       │              │              │ until there is │                    │
       │              │              │ enough entropy │                    │
       │              │              │ again          │                    │
       ├──────────────┼──────────────┼────────────────┼────────────────────┤
       │getrandom()   │ Same as      │ Does not block │ EAGAIN             │
       │GRND_NONBLOCK │ /dev/urandom │ once is pool   │                    │
       │              │              │ ready          │                    │
       ├──────────────┼──────────────┼────────────────┼────────────────────┤
       │getrandom()   │ Same as      │ EAGAIN if not  │ EAGAIN             │
       │GRND_RANDOM + │ /dev/random  │ enough entropy │                    │
       │GRND_NONBLOCK │              │ available      │                    │
       └──────────────┴──────────────┴────────────────┴────────────────────┘
   Generating cryptographic keys
       The  amount  of  seed  material  required to generate a crypto‐
       graphic key equals the effective key  size  of  the  key.   For
       example,  a  3072-bit  RSA or Diffie-Hellman private key has an
       effective key size of 128 bits (it requires about 2^128  opera‐
       tions  to  break)  so  a  key generator needs only 128 bits (16
       bytes) of seed material from /dev/random.

       While some safety margin above that minimum is reasonable, as a
       guard  against  flaws in the CSPRNG algorithm, no cryptographic
       primitive available today can hope to  promise  more  than  256
       bits  of  security,  so if any program reads more than 256 bits
       (32 bytes) from the kernel random pool per invocation,  or  per
       reasonable  reseed  interval  (not  less than one minute), that
       should be taken as a sign that its cryptography is  not  skill‐
       fully implemented.

SEE ALSO
       getrandom(2), random(4), urandom(4), signal(7)

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[-- Attachment #2: random.7 --]
[-- Type: application/x-troff-man, Size: 7381 bytes --]