.\" Copyright (C) 2008, George Spelvin <linux@horizon.com>,

.\" and Copyright (C) 2008, Matt Mackall <mpm@selenic.com>

.\" and Copyright (C) 2016, Laurent Georget <laurent.georget@supelec.fr>

.\" and Copyright (C) 2016, Nikos Mavrogiannopoulos <nmav@redhat.com>

.\"

.\" %%%LICENSE_START(VERBATIM)

.\" Permission is granted to make and distribute verbatim copies of this

.\" manual provided the copyright notice and this permission notice are

.\" preserved on all copies.

.\"

.\" Permission is granted to copy and distribute modified versions of

.\" this manual under the conditions for verbatim copying, provided that

.\" the entire resulting derived work is distributed under the terms of

.\" a permission notice identical to this one.

.\"

.\" Since the Linux kernel and libraries are constantly changing, this

.\" manual page may be incorrect or out-of-date.  The author(s) assume.

.\" no responsibility for errors or omissions, or for damages resulting.

.\" from the use of the information contained herein.  The author(s) may.

.\" not have taken the same level of care in the production of this.

.\" manual, which is licensed free of charge, as they might when working.

.\" professionally.

.\"

.\" Formatted or processed versions of this manual, if unaccompanied by

.\" the source, must acknowledge the copyright and authors of this work.

.\" %%%LICENSE_END

.\"

.\" The following web page is quite informative:

.\" http://www.2uo.de/myths-about-urandom/

.\"

.TH RANDOM 7 2017-03-13 "Linux" "Linux Programmer's Manual"

.SH NAME

random \- overview of interfaces for obtaining randomness

.SH DESCRIPTION

The kernel random-number generator relies on entropy gathered from

device drivers and other sources of environmental noise to seed

a cryptographically secure pseudorandom number generator (CSPRNG).

It is designed for security, rather than speed.

.PP

The following interfaces provide access to output from the kernel CSPRNG:

.IP * 3

The

.I /dev/urandom

and

.I /dev/random

devices, both described in

.BR random (4).

These devices have been present on Linux since early times,

and are also available on many other systems.

.IP *

The Linux-specific

.BR getrandom (2)

system call, available since Linux 3.17.

This system call provides access either to the same source as

.I /dev/urandom

(called the

.I urandom

source in this page)

or to the same source as

.I /dev/random

(called the

.I random

source in this page).

The default is the

.I urandom

source; the

.I random

source is selected by specifying the

.BR GRND_RANDOM

flag to the system call.

(The

.BR getentropy (3)

function provides a slightly more portable interface on top of

.BR getrandom (2).)

.\"

.SS 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.

.SS Choice of random source

Unless you are doing long-term key generation (and most likely not even

then), you probably shouldn't be reading from the

.IR /dev/random

device or employing

.BR getrandom (2)

with the

.BR GRND_RANDOM

flag.

Instead, either read from the

.IR /dev/urandom

device or employ

.BR getrandom (2)

without the

.B GRND_RANDOM

flag.

The cryptographic algorithms used for the

.IR urandom

source are quite conservative, and so should be sufficient for all purposes.

.PP

The disadvantage of

.B GRND_RANDOM

and reads from

.I /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

.B GRND_RANDOM

or when reading from

.I /dev/random

increases code complexity.

.\"

.SS Monte Carlo and other probabilistic sampling applications

Using these interfaces to provide large quantities of data for

Monte Carlo simulations or other programs/algorithms which are

doing probabilistic sampling will be slow.

Furthermore, it is unnecessary, because such applications do not

need cryptographically secure random numbers.

Instead, use the interfaces described in this page to obtain

a small amount of data to seed a user-space pseudorandom

number generator for use by such applications.

.\"

.SS 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.

.B GRND_NONBLOCK

is a flag that can be used to control the blocking behavior of

.BR 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.

.ad l

.TS

allbox;

lbw13 lbw12 lbw14 lbw18

l l l l.

Interface	Pool	T{

Blocking

\%behavior

T}	T{

Behavior when pool is not yet ready

T}

T{

.I /dev/random

T}	T{

Blocking pool

T}	T{

If entropy too low, blocks until there is enough entropy again

T}	T{

Blocks until enough entropy gathered

T}

T{

.I /dev/urandom

T}	T{

CSPRNG output

T}	T{

Never blocks

T}	T{

Returns output from uninitialized CSPRNG (may be low entropy and unsuitable for cryptography)

T}

T{

.BR getrandom ()

T}	T{

Same as

.I /dev/urandom

T}	T{

Does not block once is pool ready

T}	T{

Blocks until pool ready

T}

T{

.BR getrandom ()

.B GRND_RANDOM

T}	T{

Same as

.I /dev/random

T}	T{

If entropy too low, blocks until there is enough entropy again

T}	T{

Blocks until pool ready

T}

T{

.BR getrandom ()

.B GRND_NONBLOCK

T}	T{

Same as

.I /dev/urandom

T}	T{

Does not block once is pool ready

T}	T{

.B EAGAIN

T}

T{

.BR getrandom ()

.B GRND_RANDOM

+

.B GRND_NONBLOCK

T}	T{

Same as

.I /dev/random

T}	T{

.B EAGAIN

if not enough entropy available

T}	T{

.B EAGAIN

T}

.TE

.ad

.\"

.SS 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

.IR /dev/random .

.PP

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

.I not

skillfully implemented.

.\"

.SH SEE ALSO

.BR getrandom (2),

.BR getauxval (3),

.BR getentropy (3),

.BR random (4),

.BR urandom (4),

.BR signal (7)

.SH COLOPHON

This page is part of release 4.15 of the Linux

.I man-pages

project.

A description of the project,

information about reporting bugs,

and the latest version of this page,

can be found at

\%https://www.kernel.org/doc/man\-pages/.