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.\" $FreeBSD$ 28.\" " 29.Dd April 16, 2019 30.Dt RANDOM 9 31.Os 32.Sh NAME 33.Nm arc4rand , 34.Nm arc4random , 35.Nm arc4random_buf , 36.Nm is_random_seeded , 37.Nm random , 38.Nm read_random , 39.Nm read_random_uio , 40.Nm srandom 41.Nd supply pseudo-random numbers 42.Sh SYNOPSIS 43.In sys/libkern.h 44.Ft uint32_t 45.Fn arc4random "void" 46.Ft void 47.Fn arc4random_buf "void *ptr" "size_t len" 48.Ft void 49.Fn arc4rand "void *ptr" "u_int length" "int reseed" 50.Pp 51.In sys/random.h 52.Ft bool 53.Fn is_random_seeded "void" 54.Ft void 55.Fn read_random "void *buffer" "int count" 56.Ft int 57.Fn read_random_uio "struct uio *uio" "bool nonblock" 58.Ss LEGACY ROUTINES 59.In sys/libkern.h 60.Ft void 61.Fn srandom "u_long seed" 62.Ft u_long 63.Fn random "void" 64.Sh DESCRIPTION 65The 66.Fn arc4random 67and 68.Fn arc4random_buf 69functions will return very good quality random numbers, suited for 70security-related purposes. 71Both are wrappers around the underlying 72.Fn arc4rand 73interface. 74.Fn arc4random 75returns a 32-bit random value, while 76.Fn arc4random_buf 77fills 78.Fa ptr 79with 80.Fa len 81bytes of random data. 82.Pp 83The 84.Fn arc4rand 85CSPRNG 86is seeded from the 87.Xr random 4 88kernel abstract entropy device. 89Automatic reseeding happens at unspecified time and bytes (of output) 90intervals. 91A reseed can be forced by passing a non-zero 92.Fa reseed 93value. 94.Pp 95The 96.Fn read_random 97function is used to read entropy directly from the kernel abstract entropy 98device. 99.Fn read_random 100blocks if and until the entropy device is seeded. 101The provided 102.Fa buffer 103is filled with no more than 104.Fa count 105bytes. 106It is strongly advised that 107.Fn read_random 108is not used directly; 109instead, use the 110.Fn arc4rand 111family of functions. 112.Pp 113The 114.Fn is_random_seeded 115function can be used to check in advance if 116.Fn read_random 117will block. 118(If random is seeded, it will not block.) 119.Pp 120The 121.Fn read_random_uio 122function behaves identically to 123.Xr read 2 124on 125.Pa /dev/random . 126The 127.Fa uio 128argument points to a buffer where random data should be stored. 129If 130.Fa nonblock 131is true and the random device is not seeded, this function does not return any 132data. 133Otherwise, this function may block interruptibly until the random device is seeded. 134If the function is interrupted before the random device is seeded, no data is 135returned. 136.Pp 137The legacy 138.Fn random 139function will produce a sequence of numbers that can be duplicated by calling 140.Fn srandom 141with some constant as the 142.Fa seed . 143The legacy 144.Fn srandom 145function may be called with any 146.Fa seed 147value. 148It is strongly advised that the 149.Fn random 150function not be used to generate random numbers. 151See 152.Sx SECURITY CONSIDERATIONS . 153.Sh RETURN VALUES 154The 155.Fn arc4rand 156function uses the Chacha20 algorithm to generate a pseudo-random sequence of 157bytes. 158The 159.Fn arc4random 160function uses 161.Fn arc4rand 162to generate pseudo-random numbers 163in the range from 0 to 164.if t 2\u\s732\s10\d\(mi1. 165.if n (2**32)\(mi1. 166.Pp 167The 168.Fn read_random 169function returns 170the number of bytes placed in 171.Fa buffer . 172.Pp 173.Fn read_random_uio 174returns zero when successful, 175otherwise an error code is returned. 176.Pp 177The legacy 178.Fn random 179function uses 180a non-linear additive feedback random number generator 181employing a default table 182of size 31 183containing long integers 184to return successive pseudo-random 185numbers in the range from 0 to 186.if t 2\u\s731\s10\d\(mi1. 187.if n (2**31)\(mi1. 188The period of this random number generator 189is very large, 190approximately 191.if t 16\(mu(2\u\s731\s10\d\(mi1). 192.if n 16*((2**31)\(mi1). 193.Sh ERRORS 194.Fn read_random_uio 195may fail if: 196.Bl -tag -width Er 197.It Bq Er EFAULT 198.Fa uio 199points to an invalid memory region. 200.It Bq Er EWOULDBLOCK 201The random device is unseeded and 202.Fa nonblock 203is true. 204.El 205.Sh AUTHORS 206.An Dan Moschuk 207wrote 208.Fn arc4random . 209.An Mark R V Murray 210wrote 211.Fn read_random . 212.Sh SECURITY CONSIDERATIONS 213Do not use 214.Fn random 215or 216.Fn srandom 217in new code. 218.Pp 219It is important to remember that the 220.Fn random 221function is entirely predictable. 222It is easy for attackers to predict future output of 223.Fn random 224by recording some generated values. 225We cannot emphasize strongly enough that 226.Fn random 227must not be used to generate values that are intended to be unpredictable. 228