diff options
Diffstat (limited to 'static/netbsd/man2/getrandom.2')
| -rw-r--r-- | static/netbsd/man2/getrandom.2 | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/static/netbsd/man2/getrandom.2 b/static/netbsd/man2/getrandom.2 new file mode 100644 index 00000000..0543c7be --- /dev/null +++ b/static/netbsd/man2/getrandom.2 @@ -0,0 +1,244 @@ +.\" $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. |