xref: /freebsd/share/man/man9/random.9 (revision d6b92ffa) 
1.\"
2.\" Copyright (c) 2015
3.\"	Mark R V Murray
4.\" Copyright (c) 2000
5.\"	The Regents of the University of California.  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 July 16, 2015
30.Dt RANDOM 9
31.Os
32.Sh NAME
33.Nm arc4rand ,
34.Nm arc4random ,
35.Nm random ,
36.Nm read_random ,
37.Nm read_random_uio ,
38.Nm srandom
39.Nd supply pseudo-random numbers
40.Sh SYNOPSIS
41.In sys/libkern.h
42.Ft void
43.Fn srandom "u_long seed"
44.Ft u_long
45.Fn random "void"
46.Ft void
47.Fn arc4rand "void *ptr" "u_int length" "int reseed"
48.Ft uint32_t
49.Fn arc4random "void"
50.Pp
51.In sys/random.h
52.Ft int
53.Fn read_random "void *buffer" "int count"
54.Ft int
55.Fn read_random_uio "struct uio *uio" "bool nonblock"
56.Sh DESCRIPTION
57The
58.Fn random
59function will by default produce
60a sequence of numbers
61that can be duplicated
62by calling
63.Fn srandom
64with some constant
65as the
66.Fa seed .
67The
68.Fn srandom
69function may be called with any arbitrary
70.Fa seed
71value to get slightly more unpredictable numbers.
72It is important to remember that the
73.Fn random
74function is entirely predictable,
75and is therefore not of use where
76knowledge of the sequence of numbers
77may be of benefit to an attacker.
78.Pp
79The
80.Fn arc4rand
81function will return very good quality random numbers,
82better suited
83for security-related purposes.
84The random numbers from
85.Fn arc4rand
86are seeded from the entropy device
87if it is available.
88Automatic reseeds happen
89after a certain timeinterval
90and after a certain number of bytes
91have been delivered.
92A forced reseed
93can be forced
94by passing a non-zero
95value in the
96.Fa reseed
97argument.
98.Pp
99The
100.Fn read_random
101function is used to return entropy directly from the entropy device
102if it has been loaded.
103If the entropy device is not loaded, then
104the
105.Fa buffer
106is ignored
107and zero is returned.
108The
109.Fa buffer
110is filled with no more than
111.Fa count
112bytes.
113It is strongly advised that
114.Fn read_random
115is not used;
116instead use
117.Fn arc4rand
118unless it is
119necessary to know
120that no entropy
121has been returned.
122.Pp
123The
124.Fn read_random_uio
125function behaves identically to
126.Xr read 2
127on
128.Pa /dev/random .
129The
130.Fa uio
131argument points to a buffer where random data should be stored.
132This function only returns data if the random device is seeded.
133It blocks if unseeded,
134except when the
135.Fa nonblock
136argument is true.
137.Pp
138All the bits returned by
139.Fn random ,
140.Fn arc4rand ,
141.Fn read_random ,
142and
143.Fn read_random_uio
144are usable.
145For example,
146.Sq Li random()&01
147will produce a random binary value.
148.Pp
149The
150.Fn arc4random
151is a convenience function which calls
152.Fn arc4rand
153to return a 32 bit pseudo-random integer.
154.Sh RETURN VALUES
155The
156.Fn random
157function uses
158a non-linear additive feedback random number generator
159employing a default table
160of size 31
161containing long integers
162to return successive pseudo-random
163numbers in the range from 0 to
164.if t 2\u\s731\s10\d\(mi1.
165.if n (2**31)\(mi1.
166The period of this random number generator
167is very large,
168approximately
169.if t 16\(mu(2\u\s731\s10\d\(mi1).
170.if n 16*((2**31)\(mi1).
171.Pp
172The
173.Fn arc4rand
174function uses the RC4 algorithm
175to generate successive pseudo-random bytes.
176The
177.Fn arc4random
178function uses
179.Fn arc4rand
180to generate pseudo-random numbers
181in the range from 0 to
182.if t 2\u\s732\s10\d\(mi1.
183.if n (2**32)\(mi1.
184.Pp
185The
186.Fn read_random
187function returns
188the number of bytes placed in
189.Fa buffer .
190.Pp
191.Fn read_random_uio
192returns zero when successful,
193otherwise an error code is returned.
194.Sh ERRORS
195.Fn read_random_uio
196may fail if:
197.Bl -tag -width Er
198.It Bq Er EFAULT
199.Fa uio
200points to an invalid memory region.
201.It Bq Er EWOULDBLOCK
202The random device is unseeded and
203.Fa nonblock
204is true.
205.El
206.Sh AUTHORS
207.An Dan Moschuk
208wrote
209.Fn arc4random .
210.An Mark R V Murray
211wrote
212.Fn read_random .
213