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*707d98feSEd Schouten.Dd July 14, 2015 3067297998SMark Murray.Dt RANDOM 9 31aa12cea2SUlrich Spörlein.Os 3267297998SMark Murray.Sh NAME 33d962d52aSRuslan Ermilov.Nm arc4rand , 3467297998SMark Murray.Nm arc4random , 356cfaa4a7SSheldon Hearn.Nm random , 366cfaa4a7SSheldon Hearn.Nm read_random , 37*707d98feSEd Schouten.Nm read_random_uio , 386cfaa4a7SSheldon Hearn.Nm srandom 39eb083802SRuslan Ermilov.Nd supply pseudo-random numbers 4067297998SMark Murray.Sh SYNOPSIS 4132eef9aeSRuslan Ermilov.In sys/libkern.h 4267297998SMark Murray.Ft void 4367297998SMark Murray.Fn srandom "u_long seed" 4467297998SMark Murray.Ft u_long 4567297998SMark Murray.Fn random "void" 462c38619bSPoul-Henning Kamp.Ft void 472c38619bSPoul-Henning Kamp.Fn arc4rand "void *ptr" "u_int length" "int reseed" 486b99842aSEd Schouten.Ft uint32_t 4967297998SMark Murray.Fn arc4random "void" 5067297998SMark Murray.Pp 5132eef9aeSRuslan Ermilov.In sys/random.h 52234b7100SChad David.Ft int 53234b7100SChad David.Fn read_random "void *buffer" "int count" 54*707d98feSEd Schouten.Ft int 55*707d98feSEd Schouten.Fn read_random_uio "struct uio *uio" "bool nonblock" 5667297998SMark Murray.Sh DESCRIPTION 5767297998SMark MurrayThe 5867297998SMark Murray.Fn random 59d1b06863SMark Murrayfunction will by default produce 60d1b06863SMark Murraya sequence of numbers 61d1b06863SMark Murraythat can be duplicated 6267297998SMark Murrayby calling 6367297998SMark Murray.Fn srandom 64d1b06863SMark Murraywith some constant 6567297998SMark Murrayas the 66d962d52aSRuslan Ermilov.Fa seed . 6767297998SMark MurrayThe 6867297998SMark Murray.Fn srandom 6967297998SMark Murrayfunction may be called with any arbitrary 70d962d52aSRuslan Ermilov.Fa seed 7167297998SMark Murrayvalue to get slightly more unpredictable numbers. 7267297998SMark MurrayIt is important to remember that the 7367297998SMark Murray.Fn random 74d1b06863SMark Murrayfunction is entirely predictable, 75d1b06863SMark Murrayand is therefore not of use where 76d1b06863SMark Murrayknowledge of the sequence of numbers 77d1b06863SMark Murraymay be of benefit to an attacker. 7867297998SMark Murray.Pp 7967297998SMark MurrayThe 802c38619bSPoul-Henning Kamp.Fn arc4rand 81d1b06863SMark Murrayfunction will return very good quality random numbers, 82d1b06863SMark Murraybetter suited 83d1b06863SMark Murrayfor security-related purposes. 8467297998SMark MurrayThe random numbers from 852c38619bSPoul-Henning Kamp.Fn arc4rand 86d1b06863SMark Murrayare seeded from the entropy device 87d1b06863SMark Murrayif it is available. 88d1b06863SMark MurrayAutomatic reseeds happen 89d1b06863SMark Murrayafter a certain timeinterval 90d1b06863SMark Murrayand after a certain number of bytes 91d1b06863SMark Murrayhave been delivered. 92d1b06863SMark MurrayA forced reseed 93d1b06863SMark Murraycan be forced 94d1b06863SMark Murrayby passing a non-zero 95d1b06863SMark Murrayvalue in the 96d962d52aSRuslan Ermilov.Fa reseed 972c38619bSPoul-Henning Kampargument. 9867297998SMark Murray.Pp 9967297998SMark MurrayThe 10067297998SMark Murray.Fn read_random 10167297998SMark Murrayfunction is used to return entropy directly from the entropy device 1025203edcdSRuslan Ermilovif it has been loaded. 1035203edcdSRuslan ErmilovIf the entropy device is not loaded, then 10467297998SMark Murraythe 105d962d52aSRuslan Ermilov.Fa buffer 106d1b06863SMark Murrayis ignored 107d1b06863SMark Murrayand zero is returned. 10867297998SMark MurrayThe 109d962d52aSRuslan Ermilov.Fa buffer 11067297998SMark Murrayis filled with no more than 111d962d52aSRuslan Ermilov.Fa count 1125203edcdSRuslan Ermilovbytes. 113d1b06863SMark MurrayIt is strongly advised that 11467297998SMark Murray.Fn read_random 115d1b06863SMark Murrayis not used; 116d1b06863SMark Murrayinstead use 1172c38619bSPoul-Henning Kamp.Fn arc4rand 118d1b06863SMark Murrayunless it is 119d1b06863SMark Murraynecessary to know 120d1b06863SMark Murraythat no entropy 121d1b06863SMark Murrayhas been returned. 12267297998SMark Murray.Pp 123*707d98feSEd SchoutenThe 124*707d98feSEd Schouten.Fn read_random_uio 125*707d98feSEd Schoutenfunction behaves identically to 126*707d98feSEd Schouten.Xr read 2 127*707d98feSEd Schoutenon 128*707d98feSEd Schouten.Pa /dev/random . 129*707d98feSEd SchoutenThe 130*707d98feSEd Schouten.Fa uio 131*707d98feSEd Schoutenargument points to a buffer where random data should be stored. 132*707d98feSEd SchoutenThis function only returns data if the the random device is seeded. 133*707d98feSEd SchoutenIt blocks if unseeded, 134*707d98feSEd Schoutenexcept when the 135*707d98feSEd Schouten.Fa nonblock 136*707d98feSEd Schoutenargument is true. 137*707d98feSEd Schouten.Pp 138d1b06863SMark MurrayAll the bits returned by 13967297998SMark Murray.Fn random , 140*707d98feSEd Schouten.Fn arc4rand , 141*707d98feSEd Schouten.Fn read_random , 14267297998SMark Murrayand 143*707d98feSEd Schouten.Fn read_random_uio 144559eb8d2SHiten Pandyaare usable. 145559eb8d2SHiten PandyaFor example, 14667297998SMark Murray.Sq Li random()&01 14767297998SMark Murraywill produce a random binary value. 1482c38619bSPoul-Henning Kamp.Pp 1492c38619bSPoul-Henning KampThe 1502c38619bSPoul-Henning Kamp.Fn arc4random 1512c38619bSPoul-Henning Kampis a convenience function which calls 1522c38619bSPoul-Henning Kamp.Fn arc4rand 1532c38619bSPoul-Henning Kampto return a 32 bit pseudo-random integer. 15467297998SMark Murray.Sh RETURN VALUES 15567297998SMark MurrayThe 15667297998SMark Murray.Fn random 157d1b06863SMark Murrayfunction uses 158d1b06863SMark Murraya non-linear additive feedback random number generator 159d1b06863SMark Murrayemploying a default table 160d1b06863SMark Murrayof size 31 161d1b06863SMark Murraycontaining long integers 162d1b06863SMark Murrayto return successive pseudo-random 16367297998SMark Murraynumbers in the range from 0 to 16467297998SMark Murray.if t 2\u\s731\s10\d\(mi1. 16567297998SMark Murray.if n (2**31)\(mi1. 166d1b06863SMark MurrayThe period of this random number generator 167d1b06863SMark Murrayis very large, 168d1b06863SMark Murrayapproximately 16967297998SMark Murray.if t 16\(mu(2\u\s731\s10\d\(mi1). 17067297998SMark Murray.if n 16*((2**31)\(mi1). 17167297998SMark Murray.Pp 17267297998SMark MurrayThe 1732c38619bSPoul-Henning Kamp.Fn arc4rand 174d1b06863SMark Murrayfunction uses the RC4 algorithm 175d1b06863SMark Murrayto generate successive pseudo-random bytes. 1762c38619bSPoul-Henning KampThe 17767297998SMark Murray.Fn arc4random 178d1b06863SMark Murrayfunction uses 1792c38619bSPoul-Henning Kamp.Fn arc4rand 180d1b06863SMark Murrayto generate pseudo-random numbers 181d1b06863SMark Murrayin the range from 0 to 18267297998SMark Murray.if t 2\u\s732\s10\d\(mi1. 18367297998SMark Murray.if n (2**32)\(mi1. 18467297998SMark Murray.Pp 18567297998SMark MurrayThe 18667297998SMark Murray.Fn read_random 187d1b06863SMark Murrayfunction returns 188d1b06863SMark Murraythe number of bytes placed in 189d962d52aSRuslan Ermilov.Fa buffer . 190*707d98feSEd Schouten.Pp 191*707d98feSEd Schouten.Fn read_random_uio 192*707d98feSEd Schoutenreturns zero when successful, 193*707d98feSEd Schoutenotherwise an error code is returned. 194*707d98feSEd Schouten.Sh ERRORS 195*707d98feSEd Schouten.Fn read_random_uio 196*707d98feSEd Schoutenmay fail if: 197*707d98feSEd Schouten.Bl -tag -width Er 198*707d98feSEd Schouten.It Bq Er EFAULT 199*707d98feSEd Schouten.Fa uio 200*707d98feSEd Schoutenpoints to an invalid memory region. 201*707d98feSEd Schouten.It Bq Er EWOULDBLOCK 202*707d98feSEd SchoutenThe random device is unseeded and 203*707d98feSEd Schouten.Fa nonblock 204*707d98feSEd Schoutenis true. 205*707d98feSEd Schouten.El 20667297998SMark Murray.Sh AUTHORS 20767297998SMark Murray.An Dan Moschuk 20867297998SMark Murraywrote 20967297998SMark Murray.Fn arc4random . 21067297998SMark Murray.An Mark R V Murray 21167297998SMark Murraywrote 21267297998SMark Murray.Fn read_random . 213