getrandom — obtain a series of random bytes
#include <linux/random.h>
int
getrandom( |
void *buf, |
| size_t buflen, | |
unsigned int flags); |
The getrandom() system call
fills the buffer pointed to by buf with up to buflen random bytes. These
bytes can be used to seed user-space random number generators
or for cryptographic purposes.
getrandom() relies on
entropy gathered from device drivers and other sources of
environmental noise. Unnecessarily reading large quantities
of data will have a negative impact on other users of the
/dev/random and /dev/urandom devices. Therefore,
getrandom() should not be used
for Monte Carlo simulations or other programs/algorithms
which are doing probabilistic sampling.
By default, getrandom()
draws entropy from the /dev/urandom pool. This behavior can be
changed via the flags
argument. If the /dev/urandom
pool has been initialized, reads of up to 256 bytes will
always return as many bytes as requested and will not be
interrupted by signals. No such guarantees apply for larger
buffer sizes. For example, if the call is interrupted by a
signal handler, it may return a partially filled buffer, or
fail with the error EINTR. If
the pool has not yet been initialized, then the call blocks,
unless GRND_NONBLOCK is
specified in flags.
The flags argument
is a bit mask that can contain zero or more of the following
values ORed together:
GRND_RANDOMIf this bit is set, then random bytes are drawn from
the /dev/random pool
instead of the /dev/urandom pool. The /dev/random pool is limited based on
the entropy that can be obtained from environmental
noise. If the number of available bytes in /dev/random is less than requested in
buflen, the
call returns just the available random bytes. If no
random bytes are available, the behavior depends on the
presence of GRND_NONBLOCK
in the flags
argument.
GRND_NONBLOCKBy default, when reading from /dev/random, getrandom() blocks if no random bytes
are available, and when reading from /dev/urandom, it blocks if the
entropy pool has not yet been initialized. If the
GRND_NONBLOCK flag is
set, then getrandom()
does not block in these cases, but instead immediately
returns −1 with errno set to EAGAIN.
On success, getrandom()
returns the number of bytes that were copied to the buffer
buf. This may be less
than the number of bytes requested via buflen if GRND_RANDOM was specified in flags and insufficient entropy
was present in the /dev/random
pool, or if the system call was interrupted by a signal.
On error, −1 is returned, and errno is set appropriately.
An invalid flag was specified in flags.
The address referred to by buf is outside the
accessible address space.
The requested entropy was not available, and
getrandom() would have
blocked if the GRND_NONBLOCK flag was not set.
The call was interrupted by a signal handler; see
the description of how interrupted read(2) calls on
"slow" devices are handled with and without the
SA_RESTART flag in the
signal(7) man
page.
As of Linux 3.19 the following limits apply:
When reading from /dev/urandom, a maximum of 33554431
bytes is returned by a single call to getrandom() on a system where
int has a size of 32
bits.
When reading from /dev/random, a maximum of 512 bytes
is returned.
The kernel collects bits of entropy from environment.
When a sufficient number of random bits has been collected,
the /dev/urandom entropy pool
is considered to be initialized. This state is normally
reached early in the system bootstrap phase.
When reading from /dev/urandom (GRND_RANDOM is not set), getrandom() will block until the entropy
pool has been initialized (unless the GRND_NONBLOCK flag was specified). If a
request is made to read a large number (more than 256) of
bytes, getrandom() will block
until those bytes have been generated and transferred from
kernel memory to buf. When reading from
/dev/random (GRND_RANDOM is set), getrandom() will block until some random
bytes become available (unless the GRND_NONBLOCK flag was specified).
The behavior when a call to getrandom() that is blocked while reading
from /dev/urandom is
interrupted by a signal handler depends on the
initialization state of the entropy buffer and on the
request size, buflen. If the entropy is not
yet initialized, then the call will fail with the
EINTR error. If the entropy
pool has been initialized and the request size is large
(buflen > 256),
the call either succeeds, returning a partially filled
buffer, or fails with the error EINTR. If the entropy pool
has been initialized and the request size is small
(buflen <= 256),
then getrandom() will not
fail with EINTR. Instead, it
will return all of the bytes that have been requested.
When reading from /dev/random, blocking requests of any
size can be interrupted by a signal (the call fails with
the error EINTR).
Calling getrandom() to
read /dev/urandom for small
values (<= 256) of buflen is the preferred mode
of usage.
The special treatment of small values of buflen was designed for
compatibility with OpenBSD's getentropy() system call.
The user of getrandom()
must always check
the return value, to determine whether either an error
occurred or fewer bytes than requested were returned. In
the case where GRND_RANDOM is
not specified and buflen is less than or equal
to 256, a return of fewer bytes than requested should never
happen, but the careful programmer will check for this
anyway!
Unless you are doing long-term key generation (and
perhaps not even then), you probably shouldn't be using
GRND_RANDOM. The
cryptographic algorithms used for /dev/urandom are quite conservative, and
so should be sufficient for all purposes. The disadvantage
of GRND_RANDOM is that it can
block. Furthermore, dealing with the partially fulfilled
getrandom() requests that can
occur when using GRND_RANDOM
increases code complexity.
The getentropy() system
call in OpenBSD can be emulated using the following
function:
int getentropy(void *buf, size_t buflen) { int ret; if (buflen > 256) goto failure; ret = getrandom(buf, buflen, 0); if (ret < 0) return ret; if (ret == buflen) return 0; failure: errno = EIO; return −1; }
As of Linux 3.19, the following bug exists:
Depending on CPU load, getrandom() does not react to
interrupts before reading all bytes requested.
This page is part of release 4.07 of the Linux 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/.
|
Copyright (C) 2014, Theodore Ts'o <tytsomit.edu> Copyright (C) 2014,2015 Heinrich Schuchardt <xypron.glpkgmx.de> Copyright (C) 2015, Michael Kerrisk <mtk.manpagesgmail.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 |