1.\" 2.\" Copyright (c) 2015 3.\" Mark R V Murray 4.\" Copyright (c) 2000 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" " 27.Dd March 22, 2021 28.Dt RANDOM 9 29.Os 30.Sh NAME 31.Nm arc4rand , 32.Nm arc4random , 33.Nm arc4random_buf , 34.Nm is_random_seeded , 35.Nm random , 36.Nm read_random , 37.Nm read_random_uio 38.Nd supply pseudo-random numbers 39.Sh SYNOPSIS 40.In sys/libkern.h 41.Ft uint32_t 42.Fn arc4random "void" 43.Ft void 44.Fn arc4random_buf "void *ptr" "size_t len" 45.Ft void 46.Fn arc4rand "void *ptr" "u_int length" "int reseed" 47.Pp 48.In sys/random.h 49.Ft bool 50.Fn is_random_seeded "void" 51.Ft void 52.Fn read_random "void *buffer" "int count" 53.Ft int 54.Fn read_random_uio "struct uio *uio" "bool nonblock" 55.Ss LEGACY ROUTINES 56.In sys/libkern.h 57.Ft u_long 58.Fn random "void" 59.Sh DESCRIPTION 60The 61.Fn arc4random 62and 63.Fn arc4random_buf 64functions will return very good quality random numbers, suited for 65security-related purposes. 66Both are wrappers around the underlying 67.Fn arc4rand 68interface. 69.Fn arc4random 70returns a 32-bit random value, while 71.Fn arc4random_buf 72fills 73.Fa ptr 74with 75.Fa len 76bytes of random data. 77.Pp 78The 79.Fn arc4rand 80CSPRNG 81is seeded from the 82.Xr random 4 83kernel abstract entropy device. 84Automatic reseeding happens at unspecified time and bytes (of output) 85intervals. 86A reseed can be forced by passing a non-zero 87.Fa reseed 88value. 89.Pp 90The 91.Fn read_random 92function is used to read entropy directly from the kernel abstract entropy 93device. 94.Fn read_random 95blocks if and until the entropy device is seeded. 96The provided 97.Fa buffer 98is filled with no more than 99.Fa count 100bytes. 101It is strongly advised that 102.Fn read_random 103is not used directly; 104instead, use the 105.Fn arc4rand 106family of functions. 107.Pp 108The 109.Fn is_random_seeded 110function can be used to check in advance if 111.Fn read_random 112will block. 113(If random is seeded, it will not block.) 114.Pp 115The 116.Fn read_random_uio 117function behaves identically to 118.Xr read 2 119on 120.Pa /dev/random . 121The 122.Fa uio 123argument points to a buffer where random data should be stored. 124If 125.Fa nonblock 126is true and the random device is not seeded, this function does not return any 127data. 128Otherwise, this function may block interruptibly until the random device is seeded. 129If the function is interrupted before the random device is seeded, no data is 130returned. 131.Pp 132The deprecated 133.Fn random 134function will return a 31-bit value. 135It is obsolete and scheduled to be removed in 136.Fx 14.0 . 137Consider 138.Xr prng 9 139instead and see 140.Sx SECURITY CONSIDERATIONS . 141.Sh RETURN VALUES 142The 143.Fn arc4rand 144function uses the Chacha20 algorithm to generate a pseudo-random sequence of 145bytes. 146The 147.Fn arc4random 148function uses 149.Fn arc4rand 150to generate pseudo-random numbers 151in the range from 0 to 152.if t 2\u\s732\s10\d\(mi1. 153.if n (2**32)\(mi1. 154.Pp 155The 156.Fn read_random 157function returns 158the number of bytes placed in 159.Fa buffer . 160.Pp 161.Fn read_random_uio 162returns zero when successful, 163otherwise an error code is returned. 164.Pp 165.Fn random 166returns numbers 167in the range from 0 to 168.if t 2\u\s731\s10\d\(mi1. 169.if n (2**31)\(mi1. 170 171.Sh ERRORS 172.Fn read_random_uio 173may fail if: 174.Bl -tag -width Er 175.It Bq Er EFAULT 176.Fa uio 177points to an invalid memory region. 178.It Bq Er EWOULDBLOCK 179The random device is unseeded and 180.Fa nonblock 181is true. 182.El 183.Sh AUTHORS 184.An Dan Moschuk 185wrote 186.Fn arc4random . 187.An Mark R V Murray 188wrote 189.Fn read_random . 190.Sh SECURITY CONSIDERATIONS 191Do not use 192.Fn random 193in new code. 194.Pp 195It is important to remember that the 196.Fn random 197function is entirely predictable. 198It is easy for attackers to predict future output of 199.Fn random 200by recording some generated values. 201We cannot emphasize strongly enough that 202.Fn random 203must not be used to generate values that are intended to be unpredictable. 204