getrandom(2) - NetBSD Manual Pages

GETRANDOM(2)              NetBSD System Calls Manual              GETRANDOM(2)


NAME

     getrandom -- generate uniform random seeds from system entropy for cryp-
     tography


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 physi-
     cal 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 gen-
     eration 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 sig-
     nals 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.

NetBSD 10.99                    March 17, 2022                    NetBSD 10.99