GETRANDOM(2)

GETRANDOM(2) | System Calls Manual | GETRANDOM(2)

# NAME

`getrandom` —
generate uniform random seeds from system entropy for cryptography

# LIBRARY

Standard C Library (libc, -lc)

# 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.

March 17, 2022 | NetBSD 10.0