Hello Ted,
I've now merged the branch that contains the getrandom(2) page that
you initially contributed, Heinrich greatly enhanced, and to which I
also added a few pieces. If you have a chance to do a final review, it
would be most appreciated. If you are very short if time, then parts
I'd most like to have reviewed are the DESCRIPTION and the
"Interruption by a signal handler" subsection. I've provided a
rendered version of the page below, for ease of reading.
Cheers,
Michael
=====
NAME
getrandom - obtain a series of random bytes
SYNOPSIS
#include <linux/random.h>
int getrandom(void *buf, size_t buflen, unsigned int flags);
DESCRIPTION
The getrandom() system call fills the buffer pointed to by buf
with up to buflen random bytes. These can be used to seed
user-space random number generators or for cryptographic pur‐
poses.
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 sam‐
pling.
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_RANDOM is speci‐
fied in flags.
The flags argument is a bit mask that can contain zero or more
of the following values ORed together:
GRND_RANDOM
If 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_NONBLOCK
By default, if there are no random bytes available at
all (when reading from /dev/random), or the entropy pool
has not yet been initialized (when reading from
/dev/urandom), getrandom() blocks until data is avail‐
able. If the GRND_NONBLOCK flag is set, then getran‐
dom() instead immediately returns -1 with errno set to
EAGAIN.
RETURN VALUE
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.
ERRORS
EINVAL An invalid flag was specified in flags.
EFAULT The address referred to by buf is outside the accessible
address space.
EAGAIN The requested entropy was not available, and getrandom()
would have blocked if the GRND_NONBLOCK flag was not
set.
EINTR While blocked waiting for entropy, the call was inter‐
rupted 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.
VERSIONS
getrandom() was introduced in version 3.17 of the Linux kernel.
CONFORMING TO
This system call is Linux-specific.
NOTES
Maximum number of bytes returned
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.
Initialization of the entropy pool
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.
Interruption by a signal handler
A call to getrandom() can block only when called without the
GRND_NONBLOCK flag. When reading from /dev/urandom (GRND_RAN‐
DOM is not set), blocking can occur if the entropy pool has not
been initialized yet or if the requested number of bytes is
large. When reading from /dev/random (GRND_RANDOM is set),
blocking occurs if not enough random bytes are available.
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 ini‐
tialized, 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!
Choice of random device
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 con‐
servative, 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.
Emulating OpenBSD's getentropy()
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;
}
BUGS
As of Linux 3.19, the following bug exists:
* Depending on CPU load, getrandom() does not react to inter‐
rupts before reading all bytes requested.
SEE ALSO
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/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
