167297998SMark Murray.\" 267297998SMark Murray.\" Copyright (c) 2000 367297998SMark Murray.\" The Regents of the University of California. All rights reserved. 467297998SMark Murray.\" 567297998SMark Murray.\" 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.\" " 2967297998SMark Murray.Dd September 25, 2000 3067297998SMark Murray.Dt RANDOM 9 31*aa12cea2SUlrich Spörlein.Os 3267297998SMark Murray.Sh NAME 33d962d52aSRuslan Ermilov.Nm arc4rand , 3467297998SMark Murray.Nm arc4random , 356cfaa4a7SSheldon Hearn.Nm random , 366cfaa4a7SSheldon Hearn.Nm read_random , 376cfaa4a7SSheldon Hearn.Nm srandom 38eb083802SRuslan Ermilov.Nd supply pseudo-random numbers 3967297998SMark Murray.Sh SYNOPSIS 4032eef9aeSRuslan Ermilov.In sys/libkern.h 4167297998SMark Murray.Ft void 4267297998SMark Murray.Fn srandom "u_long seed" 4367297998SMark Murray.Ft u_long 4467297998SMark Murray.Fn random "void" 452c38619bSPoul-Henning Kamp.Ft void 462c38619bSPoul-Henning Kamp.Fn arc4rand "void *ptr" "u_int length" "int reseed" 4767297998SMark Murray.Ft u_int32_t 4867297998SMark Murray.Fn arc4random "void" 4967297998SMark Murray.Pp 5032eef9aeSRuslan Ermilov.In sys/random.h 51234b7100SChad David.Ft int 52234b7100SChad David.Fn read_random "void *buffer" "int count" 5367297998SMark Murray.Sh DESCRIPTION 5467297998SMark MurrayThe 5567297998SMark Murray.Fn random 5667297998SMark Murrayfunction will by default produce a sequence of numbers that can be duplicated 5767297998SMark Murrayby calling 5867297998SMark Murray.Fn srandom 5967297998SMark Murraywith 6067297998SMark Murray.Ql 1 6167297998SMark Murrayas the 62d962d52aSRuslan Ermilov.Fa seed . 6367297998SMark MurrayThe 6467297998SMark Murray.Fn srandom 6567297998SMark Murrayfunction may be called with any arbitrary 66d962d52aSRuslan Ermilov.Fa seed 6767297998SMark Murrayvalue to get slightly more unpredictable numbers. 6867297998SMark MurrayIt is important to remember that the 6967297998SMark Murray.Fn random 7067297998SMark Murrayfunction is entirely predictable, and is therefore not of use where 7167297998SMark Murrayknowledge of the sequence of numbers may be of benefit to an attacker. 7267297998SMark Murray.Pp 7367297998SMark MurrayThe 742c38619bSPoul-Henning Kamp.Fn arc4rand 7567297998SMark Murrayfunction will return very good quality random numbers, slightly better 7667297998SMark Murraysuited for security-related purposes. 7767297998SMark MurrayThe random numbers from 782c38619bSPoul-Henning Kamp.Fn arc4rand 7967297998SMark Murrayare seeded from the entropy device if it is available. 802c38619bSPoul-Henning KampAutomatic reseeds happen after a certain timeinterval and after a 812c38619bSPoul-Henning Kampcertain number of bytes have been delivered. 822c38619bSPoul-Henning KampA forced reseed can be forced by passing a non-zero value in the 83d962d52aSRuslan Ermilov.Fa reseed 842c38619bSPoul-Henning Kampargument. 8567297998SMark Murray.Pp 8667297998SMark MurrayThe 8767297998SMark Murray.Fn read_random 8867297998SMark Murrayfunction is used to return entropy directly from the entropy device 895203edcdSRuslan Ermilovif it has been loaded. 905203edcdSRuslan ErmilovIf the entropy device is not loaded, then 9167297998SMark Murraythe 92d962d52aSRuslan Ermilov.Fa buffer 9367297998SMark Murrayis filled with output generated by 9467297998SMark Murray.Fn random . 9567297998SMark MurrayThe 96d962d52aSRuslan Ermilov.Fa buffer 9767297998SMark Murrayis filled with no more than 98d962d52aSRuslan Ermilov.Fa count 995203edcdSRuslan Ermilovbytes. 1005203edcdSRuslan ErmilovIt is advised that 10167297998SMark Murray.Fn read_random 10267297998SMark Murrayis not used; instead use 1032c38619bSPoul-Henning Kamp.Fn arc4rand 10467297998SMark Murray.Pp 10567297998SMark MurrayAll the bits generated by 10667297998SMark Murray.Fn random , 1072c38619bSPoul-Henning Kamp.Fn arc4rand 10867297998SMark Murrayand 10967297998SMark Murray.Fn read_random 110559eb8d2SHiten Pandyaare usable. 111559eb8d2SHiten PandyaFor example, 11267297998SMark Murray.Sq Li random()&01 11367297998SMark Murraywill produce a random binary value. 1142c38619bSPoul-Henning Kamp.Pp 1152c38619bSPoul-Henning KampThe 1162c38619bSPoul-Henning Kamp.Fn arc4random 1172c38619bSPoul-Henning Kampis a convenience function which calls 1182c38619bSPoul-Henning Kamp.Fn arc4rand 1192c38619bSPoul-Henning Kampto return a 32 bit pseudo-random integer. 12067297998SMark Murray.Sh RETURN VALUES 12167297998SMark MurrayThe 12267297998SMark Murray.Fn random 12367297998SMark Murrayfunction 12467297998SMark Murrayuses a non-linear additive feedback random number generator employing a 12567297998SMark Murraydefault table of size 31 long integers to return successive pseudo-random 12667297998SMark Murraynumbers in the range from 0 to 12767297998SMark Murray.if t 2\u\s731\s10\d\(mi1. 12867297998SMark Murray.if n (2**31)\(mi1. 12967297998SMark MurrayThe period of this random number generator is very large, approximately 13067297998SMark Murray.if t 16\(mu(2\u\s731\s10\d\(mi1). 13167297998SMark Murray.if n 16*((2**31)\(mi1). 13267297998SMark Murray.Pp 13367297998SMark MurrayThe 1342c38619bSPoul-Henning Kamp.Fn arc4rand 1352c38619bSPoul-Henning Kampfunction uses the RC4 algorithm to generate successive pseudo-random 1362c38619bSPoul-Henning Kampbytes. 1372c38619bSPoul-Henning KampThe 13867297998SMark Murray.Fn arc4random 13967297998SMark Murrayfunction 1402c38619bSPoul-Henning Kampuses 1412c38619bSPoul-Henning Kamp.Fn arc4rand 1422c38619bSPoul-Henning Kampto generate pseudo-random numbers in the range from 0 to 14367297998SMark Murray.if t 2\u\s732\s10\d\(mi1. 14467297998SMark Murray.if n (2**32)\(mi1. 14567297998SMark Murray.Pp 14667297998SMark MurrayThe 14767297998SMark Murray.Fn read_random 14867297998SMark Murrayfunction returns the number of bytes placed in 149d962d52aSRuslan Ermilov.Fa buffer . 15067297998SMark Murray.Sh AUTHORS 15167297998SMark Murray.An Dan Moschuk 15267297998SMark Murraywrote 15367297998SMark Murray.Fn arc4random . 15467297998SMark Murray.An Mark R V Murray 15567297998SMark Murraywrote 15667297998SMark Murray.Fn read_random . 157