getrandom(2) - NetBSD Manual Pages

Command: Section: Arch: Collection:  
GETRANDOM(2)              NetBSD System Calls Manual              GETRANDOM(2)


NAME
getrandom -- random number generation from system entropy
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 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: When the system has only partial entropy, the output of getrandom() may be predictable. When the system has full entropy, the output is fit for use as cryp- tographic key material. The flags argument may be: 0 Block until the system entropy pool has full entropy; then generate arbitrarily much data. Recommended. 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 Do not block; instead fill buf with output derived from whatever is in the system entropy pool so far. Equivalent to reading from /dev/urandom; see rnd(4). 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 sys- tems may not. GRND_RANDOM Block until the system entropy pool has full entropy; then generate a small amount of data. Equivalent to reading from /dev/random; see rnd(4). This is pro- vided mainly for source compatibility with Linux; there is essentially 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 is nonsensical and 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 return at least 256 bytes 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 return as little as a single byte if successful.
EXAMPLES
Recommended usage. Generate a key for cryptography: uint8_t secretkey[32]; if (getrandom(secretkey, sizeof secretkey, 0) == -1) err(EXIT_FAILURE, "getrandom"); crypto_secretbox_xsalsa20poly1305(..., secretkey); Other idioms for illustration: Wait for entropy once, and then generate many keys without waiting: 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"); Twiddle thumbs while waiting for entropy: 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.)
ERRORS
[EAGAIN] The GRND_NONBLOCK flag was specified, and the system entropy pool does not have full entropy. [EINTR] The 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] flags contains an unrecognized flag or a nonsensical combination of flags. [EFAULT] buf points outside the allocated address space.
SEE ALSO
rnd(4)
HISTORY
The getrandom system call first appeared in Linux 3.17, and was added to NetBSD 10.0.
AUTHORS
The NetBSD implementation of getrandom and this man page were written by Taylor R Campbell <riastradh@NetBSD.org>.
BUGS
There is no way to multiplex waiting for 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. NetBSD 9.99 January 13, 2020 NetBSD 9.99
Powered by man-cgi (2020-09-24). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.