xref: /freebsd/share/man/man9/random.9 (revision 67297998c85fb277917b924283c86d715989d0b5)
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 srandom,
3467297998SMark Murray.Nm random,
3567297998SMark Murray.Nm arc4random,
3667297998SMark Murray.Nm read_random
3767297998SMark Murray.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