.\" $NetBSD: getrandom.2,v 1.1.6.1 2023/08/11 14:35:24 martin 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.