GETRANDOM(2)

NAME
getrandom - generate uniform random seeds from system entropy for cryptography

LIBRARY
libc

SYNOPSIS
#include <sys/random.h>
ssize_t
getrandom(void *buf, size_t buflen, unsigned int flags);

DESCRIPTION
The 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   May block. On success, guaranteed to generate the smaller of buflen or 256 bytes.

GRND_INSECURE
    Never blocks. On success, guaranteed to generate the smaller of buflen or 256 bytes.

GRND_RANDOM
    Will probably block. On success, may generate as little as a single byte of data.

    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.

RETURN VALUES
If successful, 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

or
    	getrandom(buf, 32, GRND_INSECURE) == -1

to detect failure. However, with GRND_RANDOM, getrandom() may generate as little as a single byte if successful.

EXAMPLES
Generate a key for cryptography:

    	uint8_t secretkey[32];
    	if (getrandom(secretkey, sizeof secretkey, 0) == -1)
    		err(EXIT_FAILURE, "getrandom");
    	crypto_secretbox_xsalsa20poly1305(..., secretkey);

ERRORS

[EAGAIN]
    The GRND_NONBLOCK flag was specified, and getrandom would have blocked waiting for entropy.

[EINTR]
    The GRND_NONBLOCK flag was not specified, getrandom blocked waiting for entropy, and the process was interrupted by a signal.

[EINVAL]
    flags contains an unrecognized flag or a nonsensical combination of flags.

[EFAULT]
    buf points outside the allocated address space.

CAVEATS
Security can only be guaranteed relative to whatever unpredictable physical processes or secret seed material are available to the system; see entropy(7).

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.

SEE ALSO
arc4random(3), getentropy(3), rnd(4), entropy(7)

STANDARDS
The getrandom function is a nonstandard Linux extension and will probably never be standardized.

HISTORY
The getrandom system call first appeared in Linux 3.17, and was added to NetBSD 10.0.

BUGS
There is no way to multiplex waiting for 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.