New random(7) page for review

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

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

Hello all,

Following on from our discussions about the random(4)
page, and a suggestion from Laurent, I've created
a random(7) page that provides a short overview of
the APIs for obtaining randomness, and some comparisons
and recommendations for using those APIs. A good part of
the text is relocated from the existing getrandom(2) and
random(4) pages. I also incorporated a table that was
proposed by Laurent that compares the APIs on a number
of points.

The rendered version of the page is below. The source is
attached (and already pushed to Git.) 

Does anyone see any further tweaks that might be required?

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 cryp‐
    tographically 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.

    *  The 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  urandom
    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 getrandom(2) with  the
    GRND_RANDOM flag or the /dev/random device.

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

    The disadvantage of GRND_RANDOM and reads from /dev/random is that
    the  operation can block.  Furthermore, dealing with the partially
    fulfilled requests that can occur when using GRND_RANDOM  or  when
    reading from /dev/random 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 cryptographic  random  data.
    Users  should  be  economical  in the amount of seed material that
    they consume  via  getrandom(2),  /dev/urandom,  and  /dev/random.
    Consuming  unnecessarily large quantities of data via these inter‐
    faces will have a negative impact on other  consumers  of  random‐
    ness.

    These interfaces should not be used to provide large quantities of
    data for Monte  Carlo  simulations  or  other  programs/algorithms
    which  are  doing  probabilistic  sampling.  Indeed, such usage is
    unnecessary (and will be slow).  Instead, use these interfaces  to
    provide  a  small amount of data used to seed a user-space pseudo‐
    random number generator for use by such applications.

Comparison between getrandom, /dev/urandom, and /dev/random
    The following table summarizes the behavior of the various  inter‐
    faces  that  can be used to obtain randomness.  GRND_NONBLOCK is a
    flag that can be used to control the blocking behavior of  getran‐
    dom(2).

    ┌──────────────┬──────────────┬──────────────────┬────────────────────┐
    │Interface     │ Pool         │ Blocking         │ Behavior in early  │
    │              │              │ behavior         │ boot time          │
    ├──────────────┼──────────────┼──────────────────┼────────────────────┤
    │/dev/random   │ Blocking     │ If entropy too   │ Blocks until       │
    │              │ pool         │ low, block until │ enough entropy     │
    │              │              │ there is enough  │ gathered           │
    │              │              │ 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 pool ready  │ ready              │
    ├──────────────┼──────────────┼──────────────────┼────────────────────┤
    │getrandom()   │ Same as      │ If entropy too   │ Blocks until pool  │
    │GRND_RANDOM   │ /dev/random  │ low, block until │ ready              │
    │              │              │ there is enough  │                    │
    │              │              │ entropy again    │                    │
    ├──────────────┼──────────────┼──────────────────┼────────────────────┤
    │getrandom()   │ Same as      │ Does not block   │ EAGAIN if pool not │
    │GRND_NONBLOCK │ /dev/urandom │                  │ ready              │
    ├──────────────┼──────────────┼──────────────────┼────────────────────┤
    │getrandom()   │ Same as      │ EAGAIN if not    │ EAGAIN if pool not │
    │GRND_RANDOM + │ /dev/random  │ enough entropy   │ ready              │
    │GRND_NONBLOCK │              │ available        │                    │
    └──────────────┴──────────────┴──────────────────┴────────────────────┘
Generating cryptographic keys
    The  amount  of seed material required to generate a cryptographic
    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 operations 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 skillfully 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: 6524 bytes --]