arc4random.3 (6a068746777241722b2b32c5d0bc443a2a64d80b) arc4random.3 (c1e80940f3b4030df0aaed73028053af057e476d)
1.\" $OpenBSD: arc4random.3,v 1.2 1997/04/27 22:40:25 angelos Exp $
1.\" $OpenBSD: arc4random.3,v 1.35 2014/11/25 16:45:24 millert Exp $
2.\"
2.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.

--- 15 unchanged lines hidden (view full) ---

25.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29.\"
30.\" Manual page, using -mandoc macros
31.\" $FreeBSD$
32.\"
3.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.

--- 15 unchanged lines hidden (view full) ---

26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30.\"
31.\" Manual page, using -mandoc macros
32.\" $FreeBSD$
33.\"
33.Dd April 15, 1997
34.Dd July 19, 2014
34.Dt ARC4RANDOM 3
35.Os
36.Sh NAME
37.Nm arc4random ,
38.Nm arc4random_buf ,
35.Dt ARC4RANDOM 3
36.Os
37.Sh NAME
38.Nm arc4random ,
39.Nm arc4random_buf ,
39.Nm arc4random_uniform ,
40.Nm arc4random_stir ,
41.Nm arc4random_addrandom
42.Nd arc4 random number generator
40.Nm arc4random_uniform
41.Nd random number generator
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In stdlib.h
47.Ft uint32_t
48.Fn arc4random "void"
49.Ft void
50.Fn arc4random_buf "void *buf" "size_t nbytes"
51.Ft uint32_t
52.Fn arc4random_uniform "uint32_t upper_bound"
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In stdlib.h
46.Ft uint32_t
47.Fn arc4random "void"
48.Ft void
49.Fn arc4random_buf "void *buf" "size_t nbytes"
50.Ft uint32_t
51.Fn arc4random_uniform "uint32_t upper_bound"
53.Ft void
54.Fn arc4random_stir "void"
55.Ft void
56.Fn arc4random_addrandom "unsigned char *dat" "int datlen"
57.Sh DESCRIPTION
52.Sh DESCRIPTION
53This family of functions provides higher quality data than those
54described in
55.Xr rand 3 ,
56.Xr random 3 ,
57and
58.Xr rand48 3 .
59.Pp
60Use of these functions is encouraged for almost all random number
61consumption because the other interfaces are deficient in either
62quality, portability, standardization, or availability.
63These functions can be called in almost all coding environments,
64including
65.Xr pthreads 3
66and
67.Xr chroot 2 .
68.Pp
69High quality 32-bit pseudo-random numbers are generated very quickly.
70On each call, a cryptographic pseudo-random number generator is used
71to generate a new result.
72One data pool is used for all consumers in a process, so that consumption
73under program flow can act as additional stirring.
74The subsystem is re-seeded from the kernel random number subsystem using
75.Xr getentropy 2
76on a regular basis, and also upon
77.Xr fork 2 .
78.Pp
58The
59.Fn arc4random
79The
80.Fn arc4random
60function uses the key stream generator employed by the
61arc4 cipher, which uses 8*8 8 bit S-Boxes.
62The S-Boxes
63can be in about
64.if t 2\u\s71700\s10\d
65.if n (2**1700)
66states.
81function returns a single 32-bit value.
67The
68.Fn arc4random
69function returns pseudo-random numbers in the range of 0 to
70.if t 2\u\s731\s10\d\(mi1,
71.if n (2**32)\(mi1,
72and therefore has twice the range of
73.Xr rand 3
74and
75.Xr random 3 .
76.Pp
77.Fn arc4random_buf
82The
83.Fn arc4random
84function returns pseudo-random numbers in the range of 0 to
85.if t 2\u\s731\s10\d\(mi1,
86.if n (2**32)\(mi1,
87and therefore has twice the range of
88.Xr rand 3
89and
90.Xr random 3 .
91.Pp
92.Fn arc4random_buf
78function fills the region
93fills the region
79.Fa buf
80of length
81.Fa nbytes
94.Fa buf
95of length
96.Fa nbytes
82with ARC4-derived random data.
97with random data.
83.Pp
84.Fn arc4random_uniform
98.Pp
99.Fn arc4random_uniform
85will return a uniformly distributed random number less than
100will return a single 32-bit value, uniformly distributed but less than
86.Fa upper_bound .
101.Fa upper_bound .
87.Fn arc4random_uniform
88is recommended over constructions like
102This is recommended over constructions like
89.Dq Li arc4random() % upper_bound
90as it avoids "modulo bias" when the upper bound is not a power of two.
103.Dq Li arc4random() % upper_bound
104as it avoids "modulo bias" when the upper bound is not a power of two.
91.Pp
92The
93.Fn arc4random_stir
94function reads data from
95.Pa /dev/urandom
96and uses it to permute the S-Boxes via
97.Fn arc4random_addrandom .
98.Pp
99There is no need to call
100.Fn arc4random_stir
101before using
102.Fn arc4random
103functions family, since
104they automatically initialize themselves.
105In the worst case, this function may consume multiple iterations
106to ensure uniformity; see the source code to understand the problem
107and solution.
108.Sh RETURN VALUES
109These functions are always successful, and no return value is
110reserved to indicate an error.
105.Sh EXAMPLES
106The following produces a drop-in replacement for the traditional
107.Fn rand
108and
109.Fn random
110functions using
111.Fn arc4random :
112.Pp
113.Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))"
114.Sh SEE ALSO
115.Xr rand 3 ,
111.Sh EXAMPLES
112The following produces a drop-in replacement for the traditional
113.Fn rand
114and
115.Fn random
116functions using
117.Fn arc4random :
118.Pp
119.Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))"
120.Sh SEE ALSO
121.Xr rand 3 ,
116.Xr random 3 ,
117.Xr srandomdev 3
122.Xr rand48 3 ,
123.Xr random 3
118.Sh HISTORY
124.Sh HISTORY
119.Pa RC4
120has been designed by RSA Data Security, Inc.
121It was posted anonymously
122to the USENET and was confirmed to be equivalent by several sources who
123had access to the original cipher.
124Since
125.Pa RC4
126used to be a trade secret, the cipher is now referred to as
127.Pa ARC4 .
125These functions first appeared in
126.Ox 2.1 .
127.Pp
128The original version of this random number generator used the
129RC4 (also known as ARC4) algorithm.
130In
131.Ox 5.5
132it was replaced with the ChaCha20 cipher, and it may be replaced
133again in the future as cryptographic techniques advance.
134A good mnemonic is
135.Dq A Replacement Call for Random .
136.Pp
137The
138.Fn arc4random
139random number generator was first introduced in
140.Fx 2.2.6 .
141The ChaCha20 based implementation was introduced in
142.Fx 12.0 ,
143with obsolete stir and addrandom interfaces removed at the same time.