xref: /freebsd/share/man/man9/random.9 (revision 6990ffd8a95caaba6858ad44ff1b3157d1efba8f)
1.\"
2.\" Copyright (c) 2000
3.\"	The Regents of the University of California.  All rights reserved.
4.\"
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26.\"
27.\" $FreeBSD$
28.\" "
29.Dd September 25, 2000
30.Os
31.Dt RANDOM 9
32.Sh NAME
33.Nm arc4random ,
34.Nm random ,
35.Nm read_random ,
36.Nm srandom
37.Nd supply pseudo-random numbers
38.Sh SYNOPSIS
39.Fd #include <sys/libkern.h>
40.Ft void
41.Fn srandom "u_long seed"
42.Ft u_long
43.Fn random "void"
44.Ft u_int32_t
45.Fn arc4random "void"
46.Pp
47.Fd #include <sys/random.h>
48.Ft u_int
49.Fn read_random "void *buffer" "u_int count"
50.Sh DESCRIPTION
51The
52.Fn random
53function will by default produce a sequence of numbers that can be duplicated
54by calling
55.Fn srandom
56with
57.Ql 1
58as the
59.Ar seed .
60The
61.Fn srandom
62function may be called with any arbitrary
63.Ar seed
64value to get slightly more unpredictable numbers.
65It is important to remember that the
66.Fn random
67function is entirely predictable, and is therefore not of use where
68knowledge of the sequence of numbers may be of benefit to an attacker.
69.Pp
70The
71.Fn arc4random
72function will return very good quality random numbers, slightly better
73suited for security-related purposes.
74The random numbers from
75.Fn arc4random
76are seeded from the entropy device if it is available.
77.Pp
78The
79.Fn read_random
80function is used to return entropy directly from the entropy device
81if it has been loaded. If the entropy device is not loaded, then
82the
83.Ar buffer
84is filled with output generated by
85.Fn random .
86The
87.Ar buffer
88is filled with no more than
89.Ar count
90bytes. It is advised that
91.Fn read_random
92is not used; instead use
93.Fn arc4random .
94.Pp
95All the bits generated by
96.Fn random ,
97.Fn arc4random
98and
99.Fn read_random
100are usable.  For example,
101.Sq Li random()&01
102will produce a random binary value.
103.Sh RETURN VALUES
104The
105.Fn random
106function
107uses a non-linear additive feedback random number generator employing a
108default table of size 31 long integers to return successive pseudo-random
109numbers in the range from 0 to
110.if t 2\u\s731\s10\d\(mi1.
111.if n (2**31)\(mi1.
112The period of this random number generator is very large, approximately
113.if t 16\(mu(2\u\s731\s10\d\(mi1).
114.if n 16*((2**31)\(mi1).
115.Pp
116The
117.Fn arc4random
118function
119uses the RC4 algorithm to generate successive pseudo-random
120numbers in the range from 0 to
121.if t 2\u\s732\s10\d\(mi1.
122.if n (2**32)\(mi1.
123.Pp
124The
125.Fn read_random
126function returns the number of bytes placed in
127.Ar buffer .
128.Sh AUTHORS
129.An Dan Moschuk
130wrote
131.Fn arc4random .
132.An Mark R V Murray
133wrote
134.Fn read_random .
135