NAME

getrandom — wait for system entropy to be seeded and randomly fill buffer

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <sys/random.h>

int
getrandom(void *buf, size_t len, int flags);

DESCRIPTION

The getrandom() function blocks until the system has been seeded with entropy, and then fills the buffer starting at buf with len bytes chosen uniformly at random, which are unpredictable secrets fit for use in cryptography.

The following flags may be or'ed together to form the flags argument:

GRND_NONBLOCK

If the buffer cannot be filled immediately, fail with EWOULDBLOCK instead of blocking. The buffer may be partially initialized in this case, but the caller has no way to ascertain how much of it was initialized.

The length len must not exceed 33554431; however, callers should limit their requests to 32 bytes and use a stream cipher to expand 32-byte keys into longer pads, like the increasingly inaccurately named arc4random(3) does with ChaCha.

GRND_RANDOM

Enable compatibility with legacy and Linux applications by blocking more often.

The length len must not exceed 512; however, callers should limit their requests to 32 bytes and use a stream cipher to expand 32-byte keys into longer pads.

SECURITY MODEL

The getrandom() system call assumes the operating system has access to a hardware entropy source, such as a human flipping coins without surveillance or a seed file managed by rndctl(8). After enough coin flips (256 is enough) have been written by root to /dev/random once, or after the seed file has been read once, getrandom() will consider the system to be unpredictable and will never block again.

Once the system is seeded, the output of getrandom() is indistinguishable from uniform random with more than negligible advantage by standards of modern cryptography.

The getrandom() system call does not protect against an adversary who can find a kernel memory disclosure bug in NetBSD and use it to dump the operating system's seed. Absent such an adversary, entropy does not “run out”.

RETURN VALUES

The getrandom() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

EXAMPLES

Generate a key, but abort immediately if the system is not yet seeded:

	uint8_t key[32]; 
 
	if (getrandom(key, sizeof key, GRND_NONBLOCK)) 
		err("getrandom"); 
 
	... do cryptography using key ...

Generate a key, or block until the system has been seeded, if the application can tolerate indefinite blocking:

	uint8_t key[32]; 
 
	printf("if this hangs get out a coin and start flipping\n"); 
	printf("and then do `echo ththhh... >> /dev/random'\n"); 
	fflush(stdout); 
	if (ferror(stdout)) 
		err("printf"); 
 
	if (getrandom(key, sizeof key, 0)) 
		err("getrandom"); 
 
	... do cryptography using key ....

Beware that the blocking code path is unlikely to be exercised, and may need special attention like fault injection to test it. Consider aborting without blocking instead.

ERRORS

getrandom() will fail if:

[EFAULT]

Part of buf points outside the process's allocated address space.

[EINTR]

A signal was delivered before getrandom() could complete.

[EINVAL]

The len argument was too large or the flags argument was invalid.

[EWOULDBLOCK]

The request cannot be served immediately and GRND_NONBLOCK was specified.

SEE ALSO

arc4random(3), rnd(4), boot.cfg(5), cprng(9), rnd(9)

HISTORY

The getrandom() function first appeared in Linux 3.17 and NetBSD 10.0.

CAVEATS

Applications cannot generate secrets before the system has been seeded. If getrandom() fails because the system is not yet seeded, applications can either abort or block until the system has been seeded (or proceed without secrets, e.g. by disabling networking functionality).

Since many systems are seeded automatically by sysinst(8) and rndctl(8), or have hardware entropy sources built-in, the failure is unlikely to happen during what are otherwise extensive tests. Applications should therefore be careful to test getrandom() failure with fault injection simulating failure or blocking.

BUGS

There is no way to do a multiplexed wait for the system to be seeded, like with select(2), kqueue(2), etc. Applications can read a single byte from /dev/random, but like GRND_RANDOM it may block indefinitely even if the system has been seeded.