245 lines
6.0 KiB
Groff
245 lines
6.0 KiB
Groff
.\" $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.
|