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 output of getrandom
is meant to be
unpredictable to an adversary and fit for use in cryptography. See CAVEATS
below.
getrandom
is meant for seeding random
number generators, not for direct use by applications; most applications
should use
arc4random(3).
getrandom
is a nonstandard extension that
was added before POSIX began to converge on
getentropy(2).
Applications should avoid getrandom
and use
getentropy(2) instead;
getrandom
may be removed from a later release.
getrandom
may block indefinitely unless
the GRND_INSECURE
or
GRND_NONBLOCK
flags are specified.
The flags argument may be:
0
GRND_INSECURE
GRND_RANDOM
This is provided for source compatibility with Linux; there is no reason to ever use it.
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
always 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
generate buflen or 256 bytes, whichever is smaller, if
successful, it is sufficient to use, e.g.,
getrandom(buf, 32, 0) == -1
getrandom(buf, 32, GRND_INSECURE) == -1
GRND_RANDOM
,
getrandom
() may generate 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);
EAGAIN
]GRND_NONBLOCK
flag was specified, and
getrandom
would have blocked waiting for
entropy.EINTR
]GRND_NONBLOCK
flag was not
specified, getrandom
blocked waiting for entropy,
and the process was interrupted by a signal.EINVAL
]EFAULT
]On systems which have no hardware random number generator and which have not had secret seed material loaded, NetBSD makes a reasonable effort to incorporate samples from various physical processes available to it that might be unpredictable from random jitter in timing.
However, the getrandom
interface alone can
make no security guarantees without a physical system configuration that
includes random number generation hardware or secret seed material from such
hardware on another machine.
getrandom
function is a nonstandard Linux extension
and will probably never be standardized.
getrandom
system call first appeared in Linux 3.17,
and was added to NetBSD 10.0.
getrandom
()
with other I/O in select(2),
poll(2), or
kqueue(2), or to atomically
unmask a set of signals while getrandom
blocks.
Instead, you can wait for a read from /dev/random; see
rnd(4).
The getrandom
interface has more options
than real-world applications need, with confusing and unclear semantics
inherited from Linux.
March 17, 2022 | NetBSD 10.1 |