GETRANDOM(2) | System Calls Manual | GETRANDOM(2) |
getrandom
—
#include <sys/random.h>
ssize_t
getrandom
(void
*buf, size_t
buflen, unsigned int
flags);
getrandom
function fills buf
with up to buflen independent uniform random bytes
derived from the system's entropy pool.
The function may block until the system has full entropy, meaning that the system has observed enough noise from physical processes that an adversary cannot predict what state it is in:
getrandom
() may be predictable.The flags argument may be:
0
If interrupted by a signal, may fail with
EINTR
or return a short read. If successful,
guaranteed to return at least 256 bytes even if interrupted.
GRND_INSECURE
If interrupted by a signal, may fail with
EINTR
or return a short read. If successful,
guaranteed to return at least 256 bytes even if interrupted.
Despite the name, this is secure as long as you only do it
after at least one successful call without
GRND_INSECURE
, such as
getrandom(..., 0)
or
getrandom(..., GRND_RANDOM)
, or after reading at
least one byte from /dev/random.
WARNING: If you use
GRND_INSECURE
before the
system has full entropy. the output may enable an adversary to search
the possible states of the entropy pool by brute force, and thereby
reduce its entropy to zero. Thus, incautious use of
GRND_INSECURE
can ruin the security of the whole
system.
NetBSD attempts to defend against this
threat model by resetting the system's entropy estimate to zero in this
event, requiring gathering full entropy again before
/dev/random or
getrandom
() without
GRND_INSECURE
will unblock, but other operating
systems may not.
GRND_RANDOM
The flag GNRD_NONBLOCK
may also be
included with bitwise-OR, in which case if
getrandom
() would have blocked without
GRND_NONBLOCK
, it returns
EAGAIN
instead.
Adding GRND_NONBLOCK
to
GRND_INSECURE
has no effect; the combination
GRND_INSECURE
|GRND_NONBLOCK
is equivalent to GRND_INSECURE
, since
GRND_INSECURE
never blocks. The combination
GRND_INSECURE
|GRND_RANDOM
is
nonsensical and fails with EINVAL
.
getrandom
() returns the number of bytes
stored in buf. Otherwise,
getrandom
() returns -1 and sets
errno.
Since getrandom(..., 0)
and
getrandom(..., GRND_INSECURE)
are guaranteed to
return at least 256 bytes if successful, it is sufficient to use, e.g.,
getrandom(buf, 32, 0) == -1
getrandom(buf, 32, GRND_INSECURE) == -1
GRND_RANDOM
,
getrandom
() may return as little as a single byte if
successful.
uint8_t secretkey[32]; if (getrandom(secretkey, sizeof secretkey, 0) == -1) err(EXIT_FAILURE, "getrandom"); crypto_secretbox_xsalsa20poly1305(..., secretkey);
Other idioms for illustration:
struct { uint8_t key[32]; } user[100]; if (getrandom(NULL, 0, 0) == -1) err(EXIT_FAILURE, "getrandom"); for (i = 0; i < 100; i++) if (getrandom(user[i].key, sizeof user[i].key, GRND_INSECURE) == -1) err(EXIT_FAILURE, "getrandom");
uint8_t secretkey[32]; while (getrandom(secretkey, sizeof secretkey, GRND_NONBLOCK) == -1) { if (errno != EAGAIN) err(EXIT_FAILURE, "getrandom"); twiddle_thumbs(); } crypto_secretbox_xsalsa20poly1305(..., secretkey);
(No examples of GRND_RANDOM
because it is
not useful.)
EAGAIN
]GRND_NONBLOCK
flag was specified, and the
system entropy pool does not have full entropy.EINTR
]GRND_NONBLOCK
flag was not
specified, the system entropy pool does not have full entropy, and the
process was interrupted by a signal while waiting.EINVAL
]EFAULT
]getrandom
system call first appeared in Linux 3.17,
and was added to NetBSD 10.0.
getrandom
and this man page were written by
Taylor R Campbell
<riastradh@NetBSD.org>.
getrandom
()
with other I/O in select(2),
poll(2), or
kqueue(2). Instead, you can wait
for a read from /dev/random; see
rnd(4).
GRND_RANDOM
is a little silly.
January 13, 2020 | NetBSD 10.0 |