167297998SMark Murray.\" 2d1b06863SMark Murray.\" Copyright (c) 2015 3d1b06863SMark Murray.\" Mark R V Murray 467297998SMark Murray.\" Copyright (c) 2000 567297998SMark Murray.\" The Regents of the University of California. All rights reserved. 667297998SMark Murray.\" 767297998SMark Murray.\" Redistribution and use in source and binary forms, with or without 867297998SMark Murray.\" modification, are permitted provided that the following conditions 967297998SMark Murray.\" are met: 1067297998SMark Murray.\" 1. Redistributions of source code must retain the above copyright 1167297998SMark Murray.\" notice, this list of conditions and the following disclaimer. 1267297998SMark Murray.\" 2. Redistributions in binary form must reproduce the above copyright 1367297998SMark Murray.\" notice, this list of conditions and the following disclaimer in the 1467297998SMark Murray.\" documentation and/or other materials provided with the distribution. 1567297998SMark Murray.\" 1667297998SMark Murray.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 1767297998SMark Murray.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 1867297998SMark Murray.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 1967297998SMark Murray.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 2067297998SMark Murray.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 2167297998SMark Murray.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 2267297998SMark Murray.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 2367297998SMark Murray.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 2467297998SMark Murray.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 2567297998SMark Murray.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 2667297998SMark Murray.\" 2767297998SMark Murray.\" $FreeBSD$ 2867297998SMark Murray.\" " 29*f3bae413SConrad Meyer.Dd December 26, 2019 3067297998SMark Murray.Dt RANDOM 9 31aa12cea2SUlrich Spörlein.Os 3267297998SMark Murray.Sh NAME 33d962d52aSRuslan Ermilov.Nm arc4rand , 3467297998SMark Murray.Nm arc4random , 3513774e82SConrad Meyer.Nm arc4random_buf , 36f3d2512dSConrad Meyer.Nm is_random_seeded , 376cfaa4a7SSheldon Hearn.Nm random , 386cfaa4a7SSheldon Hearn.Nm read_random , 39*f3bae413SConrad Meyer.Nm read_random_uio 40eb083802SRuslan Ermilov.Nd supply pseudo-random numbers 4167297998SMark Murray.Sh SYNOPSIS 4232eef9aeSRuslan Ermilov.In sys/libkern.h 4313774e82SConrad Meyer.Ft uint32_t 4413774e82SConrad Meyer.Fn arc4random "void" 4513774e82SConrad Meyer.Ft void 4613774e82SConrad Meyer.Fn arc4random_buf "void *ptr" "size_t len" 4713774e82SConrad Meyer.Ft void 4813774e82SConrad Meyer.Fn arc4rand "void *ptr" "u_int length" "int reseed" 4913774e82SConrad Meyer.Pp 5013774e82SConrad Meyer.In sys/random.h 51f3d2512dSConrad Meyer.Ft bool 52f3d2512dSConrad Meyer.Fn is_random_seeded "void" 5313774e82SConrad Meyer.Ft void 5413774e82SConrad Meyer.Fn read_random "void *buffer" "int count" 5513774e82SConrad Meyer.Ft int 5613774e82SConrad Meyer.Fn read_random_uio "struct uio *uio" "bool nonblock" 5713774e82SConrad Meyer.Ss LEGACY ROUTINES 5813774e82SConrad Meyer.In sys/libkern.h 5967297998SMark Murray.Ft u_long 6067297998SMark Murray.Fn random "void" 6167297998SMark Murray.Sh DESCRIPTION 6267297998SMark MurrayThe 6313774e82SConrad Meyer.Fn arc4random 6413774e82SConrad Meyerand 6513774e82SConrad Meyer.Fn arc4random_buf 6613774e82SConrad Meyerfunctions will return very good quality random numbers, suited for 6713774e82SConrad Meyersecurity-related purposes. 6813774e82SConrad MeyerBoth are wrappers around the underlying 6913774e82SConrad Meyer.Fn arc4rand 7013774e82SConrad Meyerinterface. 7113774e82SConrad Meyer.Fn arc4random 7213774e82SConrad Meyerreturns a 32-bit random value, while 7313774e82SConrad Meyer.Fn arc4random_buf 7413774e82SConrad Meyerfills 7513774e82SConrad Meyer.Fa ptr 7613774e82SConrad Meyerwith 7713774e82SConrad Meyer.Fa len 7813774e82SConrad Meyerbytes of random data. 7967297998SMark Murray.Pp 8067297998SMark MurrayThe 812c38619bSPoul-Henning Kamp.Fn arc4rand 8213774e82SConrad MeyerCSPRNG 8313774e82SConrad Meyeris seeded from the 8413774e82SConrad Meyer.Xr random 4 8513774e82SConrad Meyerkernel abstract entropy device. 8613774e82SConrad MeyerAutomatic reseeding happens at unspecified time and bytes (of output) 8713774e82SConrad Meyerintervals. 8813774e82SConrad MeyerA reseed can be forced by passing a non-zero 89d962d52aSRuslan Ermilov.Fa reseed 9013774e82SConrad Meyervalue. 9167297998SMark Murray.Pp 9267297998SMark MurrayThe 9367297998SMark Murray.Fn read_random 9413774e82SConrad Meyerfunction is used to read entropy directly from the kernel abstract entropy 9513774e82SConrad Meyerdevice. 9613774e82SConrad Meyer.Fn read_random 9713774e82SConrad Meyerblocks if and until the entropy device is seeded. 9813774e82SConrad MeyerThe provided 99d962d52aSRuslan Ermilov.Fa buffer 10067297998SMark Murrayis filled with no more than 101d962d52aSRuslan Ermilov.Fa count 1025203edcdSRuslan Ermilovbytes. 103d1b06863SMark MurrayIt is strongly advised that 10467297998SMark Murray.Fn read_random 10513774e82SConrad Meyeris not used directly; 10613774e82SConrad Meyerinstead, use the 1072c38619bSPoul-Henning Kamp.Fn arc4rand 10813774e82SConrad Meyerfamily of functions. 10967297998SMark Murray.Pp 110707d98feSEd SchoutenThe 111f3d2512dSConrad Meyer.Fn is_random_seeded 112f3d2512dSConrad Meyerfunction can be used to check in advance if 113f3d2512dSConrad Meyer.Fn read_random 114f3d2512dSConrad Meyerwill block. 115f3d2512dSConrad Meyer(If random is seeded, it will not block.) 116f3d2512dSConrad Meyer.Pp 117f3d2512dSConrad MeyerThe 118707d98feSEd Schouten.Fn read_random_uio 119707d98feSEd Schoutenfunction behaves identically to 120707d98feSEd Schouten.Xr read 2 121707d98feSEd Schoutenon 122707d98feSEd Schouten.Pa /dev/random . 123707d98feSEd SchoutenThe 124707d98feSEd Schouten.Fa uio 125707d98feSEd Schoutenargument points to a buffer where random data should be stored. 12613774e82SConrad MeyerIf 127707d98feSEd Schouten.Fa nonblock 12813774e82SConrad Meyeris true and the random device is not seeded, this function does not return any 12913774e82SConrad Meyerdata. 13013774e82SConrad MeyerOtherwise, this function may block interruptibly until the random device is seeded. 13113774e82SConrad MeyerIf the function is interrupted before the random device is seeded, no data is 13213774e82SConrad Meyerreturned. 133707d98feSEd Schouten.Pp 134*f3bae413SConrad MeyerThe deprecated 135*f3bae413SConrad Meyer.Xr random 9 136*f3bae413SConrad Meyerfunction will produce a sequence of pseudorandom numbers using a similar weak 137*f3bae413SConrad Meyerlinear congruential generator as 138*f3bae413SConrad Meyer.Xr rand 3 139*f3bae413SConrad Meyer(the 1988 Park-Miller LCG). 140*f3bae413SConrad MeyerIt is obsolete and scheduled to be removed in 141*f3bae413SConrad Meyer.Fx 13.0 . 14213774e82SConrad MeyerIt is strongly advised that the 143*f3bae413SConrad Meyer.Xr random 9 14413774e82SConrad Meyerfunction not be used to generate random numbers. 14513774e82SConrad MeyerSee 14613774e82SConrad Meyer.Sx SECURITY CONSIDERATIONS . 14767297998SMark Murray.Sh RETURN VALUES 14867297998SMark MurrayThe 1492c38619bSPoul-Henning Kamp.Fn arc4rand 15013774e82SConrad Meyerfunction uses the Chacha20 algorithm to generate a pseudo-random sequence of 15113774e82SConrad Meyerbytes. 1522c38619bSPoul-Henning KampThe 15367297998SMark Murray.Fn arc4random 154d1b06863SMark Murrayfunction uses 1552c38619bSPoul-Henning Kamp.Fn arc4rand 156d1b06863SMark Murrayto generate pseudo-random numbers 157d1b06863SMark Murrayin the range from 0 to 15867297998SMark Murray.if t 2\u\s732\s10\d\(mi1. 15967297998SMark Murray.if n (2**32)\(mi1. 16067297998SMark Murray.Pp 16167297998SMark MurrayThe 16267297998SMark Murray.Fn read_random 163d1b06863SMark Murrayfunction returns 164d1b06863SMark Murraythe number of bytes placed in 165d962d52aSRuslan Ermilov.Fa buffer . 166707d98feSEd Schouten.Pp 167707d98feSEd Schouten.Fn read_random_uio 168707d98feSEd Schoutenreturns zero when successful, 169707d98feSEd Schoutenotherwise an error code is returned. 170707d98feSEd Schouten.Sh ERRORS 171707d98feSEd Schouten.Fn read_random_uio 172707d98feSEd Schoutenmay fail if: 173707d98feSEd Schouten.Bl -tag -width Er 174707d98feSEd Schouten.It Bq Er EFAULT 175707d98feSEd Schouten.Fa uio 176707d98feSEd Schoutenpoints to an invalid memory region. 177707d98feSEd Schouten.It Bq Er EWOULDBLOCK 178707d98feSEd SchoutenThe random device is unseeded and 179707d98feSEd Schouten.Fa nonblock 180707d98feSEd Schoutenis true. 181707d98feSEd Schouten.El 18267297998SMark Murray.Sh AUTHORS 18367297998SMark Murray.An Dan Moschuk 18467297998SMark Murraywrote 18567297998SMark Murray.Fn arc4random . 18667297998SMark Murray.An Mark R V Murray 18767297998SMark Murraywrote 18867297998SMark Murray.Fn read_random . 18913774e82SConrad Meyer.Sh SECURITY CONSIDERATIONS 19013774e82SConrad MeyerDo not use 19113774e82SConrad Meyer.Fn random 19213774e82SConrad Meyerin new code. 19313774e82SConrad Meyer.Pp 19413774e82SConrad MeyerIt is important to remember that the 19513774e82SConrad Meyer.Fn random 19613774e82SConrad Meyerfunction is entirely predictable. 19713774e82SConrad MeyerIt is easy for attackers to predict future output of 19813774e82SConrad Meyer.Fn random 19913774e82SConrad Meyerby recording some generated values. 20013774e82SConrad MeyerWe cannot emphasize strongly enough that 20113774e82SConrad Meyer.Fn random 20213774e82SConrad Meyermust not be used to generate values that are intended to be unpredictable. 203