.\"	$NetBSD: getrandom.2,v 1.3 2023/07/02 13:25:52 riastradh Exp $
.\"
.\" Copyright (c) 2020 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Taylor R. Campbell.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd March 17, 2022
.Dt GETRANDOM 2
.Os
.Sh NAME
.Nm getrandom
.Nd generate uniform random seeds from system entropy for cryptography
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/random.h
.Ft ssize_t
.Fn getrandom "void *buf" "size_t buflen" "unsigned int flags"
.Sh DESCRIPTION
The
.Nm
function fills
.Fa buf
with up to
.Fa buflen
independent uniform random bytes derived from the system's entropy
pool.
.Pp
The output of
.Nm
is meant to be unpredictable to an adversary and fit for use in
cryptography.
See CAVEATS below.
.Pp
.Nm
is meant for seeding random number generators, not for direct use by
applications; most applications should use
.Xr arc4random 3 .
.Pp
.Nm
is a nonstandard extension that was added before POSIX began to
converge on
.Xr getentropy 2 .
Applications should avoid
.Nm
and use
.Xr getentropy 2
instead;
.Nm
may be removed from a later release.
.Pp
.Nm
may block indefinitely unless the
.Dv GRND_INSECURE
or
.Dv GRND_NONBLOCK
flags are specified.
.Pp
The
.Fa flags
argument may be:
.Bl -tag -offset indent -width GRND_INSECURE
.It Li 0
May block.
On success, guaranteed to generate the smaller of
.Fa buflen
or 256 bytes.
.It Dv GRND_INSECURE
Never blocks.
On success, guaranteed to generate the smaller of
.Fa buflen
or 256 bytes.
.It Dv GRND_RANDOM
Will probably block.
On success, may generate as little as a single byte of data.
.Pp
This is provided for source compatibility with Linux; there is no
reason to ever use it.
.El
.Pp
The flag
.Dv GNRD_NONBLOCK
may also be included with bitwise-OR, in which case if
.Fn getrandom
would have blocked without
.Dv GRND_NONBLOCK ,
it returns
.Er EAGAIN
instead.
.Pp
Adding
.Dv GRND_NONBLOCK
to
.Dv GRND_INSECURE
has no effect; the combination
.Dv GRND_INSECURE Ns Li "|" Ns Li GRND_NONBLOCK
is equivalent to
.Dv GRND_INSECURE ,
since
.Dv GRND_INSECURE
never blocks.
The combination
.Dv GRND_INSECURE Ns Li "|" Ns Li GRND_RANDOM
always fails with
.Er EINVAL .
.Sh RETURN VALUES
If successful,
.Fn getrandom
returns the number of bytes stored in
.Fa buf .
Otherwise,
.Fn getrandom
returns \-1 and sets
.Va errno .
.Pp
Since
.Li "getrandom(..., 0)"
and
.Li "getrandom(..., GRND_INSECURE)"
are guaranteed to generate
.Fa buflen
or 256 bytes, whichever is smaller, if successful, it
is sufficient to use, e.g.,
.Bd -literal -compact
	getrandom(buf, 32, 0) == -1
.Ed
or
.Bd -literal -compact
	getrandom(buf, 32, GRND_INSECURE) == -1
.Ed
to detect failure.
However, with
.Dv GRND_RANDOM ,
.Fn getrandom
may generate as little as a single byte if successful.
.Sh EXAMPLES
Generate a key for cryptography:
.Bd -literal
	uint8_t secretkey[32];

	if (getrandom(secretkey, sizeof secretkey, 0) == -1)
		err(EXIT_FAILURE, "getrandom");
	crypto_secretbox_xsalsa20poly1305(..., secretkey);
.Ed
.Sh ERRORS
.Bl -tag -width Er
.It Bq Er EAGAIN
The
.Dv GRND_NONBLOCK
flag was specified, and
.Nm
would have blocked waiting for entropy.
.It Bq Er EINTR
The
.Dv GRND_NONBLOCK
flag was
.Em not
specified,
.Nm
blocked waiting for entropy, and the process was interrupted by a
signal.
.It Bq Er EINVAL
.Fa flags
contains an unrecognized flag or a nonsensical combination of flags.
.It Bq Er EFAULT
.Fa buf
points outside the allocated address space.
.El
.Sh CAVEATS
Security can only be guaranteed relative to whatever unpredictable
physical processes or secret seed material are available to the system;
see
.Xr entropy 7 .
.Pp
On systems which have no hardware random number generator and which
have not had secret seed material loaded,
.Nx
makes a reasonable effort to incorporate samples from various physical
processes available to it that might be unpredictable from random
jitter in timing.
.Pp
However, the
.Nm
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.
.Sh SEE ALSO
.Xr arc4random 3 ,
.Xr getentropy 3 ,
.Xr rnd 4 ,
.Xr entropy 7
.Sh STANDARDS
The
.Nm
function is a nonstandard Linux extension and will probably never be
standardized.
.Sh HISTORY
The
.Nm
system call first appeared in Linux 3.17, and was added to
.Nx 10.0 .
.Sh BUGS
There is no way to multiplex waiting for
.Fn getrandom
with other I/O in
.Xr select 2 ,
.Xr poll 2 ,
or
.Xr kqueue 2 ,
or to atomically unmask a set of signals while
.Nm
blocks.
Instead, you can wait for a read from
.Pa /dev/random ;
see
.Xr rnd 4 .
.Pp
The
.Nm
interface has more options than real-world applications need, with
confusing and unclear semantics inherited from Linux.