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.Os 3167297998SMark Murray.Dt RANDOM 9 3267297998SMark Murray.Sh NAME 3367297998SMark Murray.Nm arc4random , 346cfaa4a7SSheldon Hearn.Nm random , 356cfaa4a7SSheldon Hearn.Nm read_random , 366cfaa4a7SSheldon Hearn.Nm srandom 37eb083802SRuslan Ermilov.Nd supply pseudo-random numbers 3867297998SMark Murray.Sh SYNOPSIS 3967297998SMark Murray.Fd #include <sys/libkern.h> 4067297998SMark Murray.Ft void 4167297998SMark Murray.Fn srandom "u_long seed" 4267297998SMark Murray.Ft u_long 4367297998SMark Murray.Fn random "void" 4467297998SMark Murray.Ft u_int32_t 4567297998SMark Murray.Fn arc4random "void" 4667297998SMark Murray.Pp 4767297998SMark Murray.Fd #include <sys/random.h> 4867297998SMark Murray.Ft u_int 4967297998SMark Murray.Fn read_random "void *buffer" "u_int count" 5067297998SMark Murray.Sh DESCRIPTION 5167297998SMark MurrayThe 5267297998SMark Murray.Fn random 5367297998SMark Murrayfunction will by default produce a sequence of numbers that can be duplicated 5467297998SMark Murrayby calling 5567297998SMark Murray.Fn srandom 5667297998SMark Murraywith 5767297998SMark Murray.Ql 1 5867297998SMark Murrayas the 5967297998SMark Murray.Ar seed . 6067297998SMark MurrayThe 6167297998SMark Murray.Fn srandom 6267297998SMark Murrayfunction may be called with any arbitrary 6367297998SMark Murray.Ar seed 6467297998SMark Murrayvalue to get slightly more unpredictable numbers. 6567297998SMark MurrayIt is important to remember that the 6667297998SMark Murray.Fn random 6767297998SMark Murrayfunction is entirely predictable, and is therefore not of use where 6867297998SMark Murrayknowledge of the sequence of numbers may be of benefit to an attacker. 6967297998SMark Murray.Pp 7067297998SMark MurrayThe 7167297998SMark Murray.Fn arc4random 7267297998SMark Murrayfunction will return very good quality random numbers, slightly better 7367297998SMark Murraysuited for security-related purposes. 7467297998SMark MurrayThe random numbers from 7567297998SMark Murray.Fn arc4random 7667297998SMark Murrayare seeded from the entropy device if it is available. 7767297998SMark Murray.Pp 7867297998SMark MurrayThe 7967297998SMark Murray.Fn read_random 8067297998SMark Murrayfunction is used to return entropy directly from the entropy device 8167297998SMark Murrayif it has been loaded. If the entropy device is not loaded, then 8267297998SMark Murraythe 8367297998SMark Murray.Ar buffer 8467297998SMark Murrayis filled with output generated by 8567297998SMark Murray.Fn random . 8667297998SMark MurrayThe 8767297998SMark Murray.Ar buffer 8867297998SMark Murrayis filled with no more than 8967297998SMark Murray.Ar count 9067297998SMark Murraybytes. It is advised that 9167297998SMark Murray.Fn read_random 9267297998SMark Murrayis not used; instead use 9367297998SMark Murray.Fn arc4random . 9467297998SMark Murray.Pp 9567297998SMark MurrayAll the bits generated by 9667297998SMark Murray.Fn random , 9767297998SMark Murray.Fn arc4random 9867297998SMark Murrayand 9967297998SMark Murray.Fn read_random 10067297998SMark Murrayare usable. For example, 10167297998SMark Murray.Sq Li random()&01 10267297998SMark Murraywill produce a random binary value. 10367297998SMark Murray.Sh RETURN VALUES 10467297998SMark MurrayThe 10567297998SMark Murray.Fn random 10667297998SMark Murrayfunction 10767297998SMark Murrayuses a non-linear additive feedback random number generator employing a 10867297998SMark Murraydefault table of size 31 long integers to return successive pseudo-random 10967297998SMark Murraynumbers in the range from 0 to 11067297998SMark Murray.if t 2\u\s731\s10\d\(mi1. 11167297998SMark Murray.if n (2**31)\(mi1. 11267297998SMark MurrayThe period of this random number generator is very large, approximately 11367297998SMark Murray.if t 16\(mu(2\u\s731\s10\d\(mi1). 11467297998SMark Murray.if n 16*((2**31)\(mi1). 11567297998SMark Murray.Pp 11667297998SMark MurrayThe 11767297998SMark Murray.Fn arc4random 11867297998SMark Murrayfunction 11967297998SMark Murrayuses the RC4 algorithm to generate successive pseudo-random 12067297998SMark Murraynumbers in the range from 0 to 12167297998SMark Murray.if t 2\u\s732\s10\d\(mi1. 12267297998SMark Murray.if n (2**32)\(mi1. 12367297998SMark Murray.Pp 12467297998SMark MurrayThe 12567297998SMark Murray.Fn read_random 12667297998SMark Murrayfunction returns the number of bytes placed in 12767297998SMark Murray.Ar buffer . 12867297998SMark Murray.Pp 12967297998SMark Murray.Sh AUTHORS 13067297998SMark Murray.An Dan Moschuk 13167297998SMark Murraywrote 13267297998SMark Murray.Fn arc4random . 13367297998SMark Murray.An Mark R V Murray 13467297998SMark Murraywrote 13567297998SMark Murray.Fn read_random . 136