1.\" $NetBSD: getrandom.2,v 1.3 2023/07/02 13:25:52 riastradh Exp $ 2.\" 3.\" Copyright (c) 2020 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Taylor R. Campbell. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd March 17, 2022 31.Dt GETRANDOM 2 32.Os 33.Sh NAME 34.Nm getrandom 35.Nd generate uniform random seeds from system entropy for cryptography 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In sys/random.h 40.Ft ssize_t 41.Fn getrandom "void *buf" "size_t buflen" "unsigned int flags" 42.Sh DESCRIPTION 43The 44.Nm 45function fills 46.Fa buf 47with up to 48.Fa buflen 49independent uniform random bytes derived from the system's entropy 50pool. 51.Pp 52The output of 53.Nm 54is meant to be unpredictable to an adversary and fit for use in 55cryptography. 56See CAVEATS below. 57.Pp 58.Nm 59is meant for seeding random number generators, not for direct use by 60applications; most applications should use 61.Xr arc4random 3 . 62.Pp 63.Nm 64is a nonstandard extension that was added before POSIX began to 65converge on 66.Xr getentropy 2 . 67Applications should avoid 68.Nm 69and use 70.Xr getentropy 2 71instead; 72.Nm 73may be removed from a later release. 74.Pp 75.Nm 76may block indefinitely unless the 77.Dv GRND_INSECURE 78or 79.Dv GRND_NONBLOCK 80flags are specified. 81.Pp 82The 83.Fa flags 84argument may be: 85.Bl -tag -offset indent -width GRND_INSECURE 86.It Li 0 87May block. 88On success, guaranteed to generate the smaller of 89.Fa buflen 90or 256 bytes. 91.It Dv GRND_INSECURE 92Never blocks. 93On success, guaranteed to generate the smaller of 94.Fa buflen 95or 256 bytes. 96.It Dv GRND_RANDOM 97Will probably block. 98On success, may generate as little as a single byte of data. 99.Pp 100This is provided for source compatibility with Linux; there is no 101reason to ever use it. 102.El 103.Pp 104The flag 105.Dv GNRD_NONBLOCK 106may also be included with bitwise-OR, in which case if 107.Fn getrandom 108would have blocked without 109.Dv GRND_NONBLOCK , 110it returns 111.Er EAGAIN 112instead. 113.Pp 114Adding 115.Dv GRND_NONBLOCK 116to 117.Dv GRND_INSECURE 118has no effect; the combination 119.Dv GRND_INSECURE Ns Li "|" Ns Li GRND_NONBLOCK 120is equivalent to 121.Dv GRND_INSECURE , 122since 123.Dv GRND_INSECURE 124never blocks. 125The combination 126.Dv GRND_INSECURE Ns Li "|" Ns Li GRND_RANDOM 127always fails with 128.Er EINVAL . 129.Sh RETURN VALUES 130If successful, 131.Fn getrandom 132returns the number of bytes stored in 133.Fa buf . 134Otherwise, 135.Fn getrandom 136returns \-1 and sets 137.Va errno . 138.Pp 139Since 140.Li "getrandom(..., 0)" 141and 142.Li "getrandom(..., GRND_INSECURE)" 143are guaranteed to generate 144.Fa buflen 145or 256 bytes, whichever is smaller, if successful, it 146is sufficient to use, e.g., 147.Bd -literal -compact 148 getrandom(buf, 32, 0) == -1 149.Ed 150or 151.Bd -literal -compact 152 getrandom(buf, 32, GRND_INSECURE) == -1 153.Ed 154to detect failure. 155However, with 156.Dv GRND_RANDOM , 157.Fn getrandom 158may generate as little as a single byte if successful. 159.Sh EXAMPLES 160Generate a key for cryptography: 161.Bd -literal 162 uint8_t secretkey[32]; 163 164 if (getrandom(secretkey, sizeof secretkey, 0) == -1) 165 err(EXIT_FAILURE, "getrandom"); 166 crypto_secretbox_xsalsa20poly1305(..., secretkey); 167.Ed 168.Sh ERRORS 169.Bl -tag -width Er 170.It Bq Er EAGAIN 171The 172.Dv GRND_NONBLOCK 173flag was specified, and 174.Nm 175would have blocked waiting for entropy. 176.It Bq Er EINTR 177The 178.Dv GRND_NONBLOCK 179flag was 180.Em not 181specified, 182.Nm 183blocked waiting for entropy, and the process was interrupted by a 184signal. 185.It Bq Er EINVAL 186.Fa flags 187contains an unrecognized flag or a nonsensical combination of flags. 188.It Bq Er EFAULT 189.Fa buf 190points outside the allocated address space. 191.El 192.Sh CAVEATS 193Security can only be guaranteed relative to whatever unpredictable 194physical processes or secret seed material are available to the system; 195see 196.Xr entropy 7 . 197.Pp 198On systems which have no hardware random number generator and which 199have not had secret seed material loaded, 200.Nx 201makes a reasonable effort to incorporate samples from various physical 202processes available to it that might be unpredictable from random 203jitter in timing. 204.Pp 205However, the 206.Nm 207interface alone can make no security guarantees without a physical 208system configuration that includes random number generation hardware or 209secret seed material from such hardware on another machine. 210.Sh SEE ALSO 211.Xr arc4random 3 , 212.Xr getentropy 3 , 213.Xr rnd 4 , 214.Xr entropy 7 215.Sh STANDARDS 216The 217.Nm 218function is a nonstandard Linux extension and will probably never be 219standardized. 220.Sh HISTORY 221The 222.Nm 223system call first appeared in Linux 3.17, and was added to 224.Nx 10.0 . 225.Sh BUGS 226There is no way to multiplex waiting for 227.Fn getrandom 228with other I/O in 229.Xr select 2 , 230.Xr poll 2 , 231or 232.Xr kqueue 2 , 233or to atomically unmask a set of signals while 234.Nm 235blocks. 236Instead, you can wait for a read from 237.Pa /dev/random ; 238see 239.Xr rnd 4 . 240.Pp 241The 242.Nm 243interface has more options than real-world applications need, with 244confusing and unclear semantics inherited from Linux. 245