1.\" $MirOS: src/lib/libc/crypt/arc4random.3,v 1.16 2010/09/21 21:27:46 tg Exp $
2.\" $OpenBSD: arc4random.3,v 1.27 2008/12/23 18:31:02 deraadt Exp $
3.\"
4.\" Copyright (c) 2010
5.\"	Thorsten Glaser <tg@mirbsd.de>
6.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
7.\" All rights reserved.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"      This product includes software developed by Niels Provos.
20.\" 4. The name of the author may not be used to endorse or promote products
21.\"    derived from this software without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
24.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
25.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
26.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
27.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
28.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
32.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33.\"
34.Dd $Mdocdate: September 21 2010 $
35.Dt ARC4RANDOM 3
36.Os
37.Sh NAME
38.Nm arc4random ,
39.Nm arc4random_buf ,
40.Nm arc4random_uniform ,
41.Nm arc4random_stir ,
42.Nm arc4random_addrandom ,
43.Nm arc4random_push ,
44.Nm arc4random_pushb ,
45.Nm arc4random_pushb_fast ,
46.Nm arc4random_pushk
47.Nd arcfour based stretching random number generator
48.Sh SYNOPSIS
49.Fd #include <stdlib.h>
50.Ft u_int32_t
51.Fn arc4random "void"
52.Ft void
53.Fn arc4random_buf "void *buf" "size_t nbytes"
54.Ft u_int32_t
55.Fn arc4random_uniform "u_int32_t upper_bound"
56.Ft void
57.Fn arc4random_stir "void"
58.Ft void
59.Fn arc4random_addrandom "u_char *dat" "int datlen"
60.Ft void
61.Pq deprecated
62.Fn arc4random_push "int value"
63.Ft uint32_t
64.Pq deprecated
65.Fn arc4random_pushb "const void *buf" "size_t len"
66.Ft uint32_t
67.Pq deprecated
68.Fn arc4random_pushk "const void *buf" "size_t len"
69.Ft void
70.Fn arc4random_pushb_fast "const void *buf" "size_t len"
71.Sh DESCRIPTION
72The
73.Fn arc4random
74function provides a high quality 32-bit pseudo-random
75number very quickly.
76.Fn arc4random
77seeds itself on a regular basis from the kernel strong random number
78subsystem described in
79.Xr random 4 .
80On each call, an ARC4 generator is used to generate a new result.
81The
82.Fn arc4random
83function uses the ARC4 cipher key stream generator,
84which uses 8*8 8-bit S-Boxes.
85The S-Boxes can be in about (2**1700) states.
86.Pp
87.Fn arc4random
88fits into a middle ground not covered by other subsystems such as
89the strong, slow, and resource expensive random
90devices described in
91.Xr random 4
92versus the fast but poor quality interfaces described in
93.Xr rand 3 ,
94.Xr random 3 ,
95and
96.Xr drand48 3 .
97.Pp
98.Fn arc4random_buf
99fills the region
100.Fa buf
101of length
102.Fa nbytes
103with ARC4-derived random data.
104.Pp
105.Fn arc4random_uniform
106will return a uniformly distributed random number less than
107.Fa upper_bound .
108.Fn arc4random_uniform
109is recommended over constructions like
110.Dq Li arc4random() % upper_bound
111as it avoids "modulo bias" when the upper bound is not a power of two.
112.Pp
113The
114.Fn arc4random_stir
115function collects data from the user-space SRNG and queued for upload,
116sends it to the kernel and receives new entropic data using
117.Xr sysctl 3
118from
119.Va kern.arandom
120and uses it to permute the S-Boxes.
121There is no need to call
122.Fn arc4random_stir
123before using
124.Fn arc4random ,
125since
126.Fn arc4random
127automatically initialises itself.
128Explicit calls will, however, trigger kernel pushing after
129.Fn arc4random_pushb_fast
130has been used to queue some data for doing so.
131.Pp
132The
133.Fn arc4random_pushb_fast
134function will queue the data passed for upload on the
135next stir using a (non-cryptographic) hash algorithm, which is only
136used for collapsing/compressing the data into the queue buffer.
137The deprecated
138.Fn arc4random_push
139function behaves the same, except instead of being passed a buffer
140and its size for pushing, it takes a direct numeric argument.
141The deprecated
142.Fn arc4random_pushk
143and
144.Fn arc4random_pushb
145functions do exactly the same, namely call
146.Fn arc4random_pushb_fast
147and then call
148.Fn arc4random
149and return its return value.
150.Pp
151The
152.Fn arc4random_addrandom
153function implements an old, discouraged, API with which the S-Boxes
154can be permuted directly from user-specified data.
155If merely desiring to add entropy to the pool, use
156.Nm arc4random_pushb_fast
157instead, which is much faster, unless you really want to do a KSA.
158.Sh RETURN VALUES
159These functions are always successful, and no return value is
160reserved to indicate an error.
161.Sh SEE ALSO
162.Xr rand 3 ,
163.Xr rand48 3 ,
164.Xr random 3 ,
165.Xr random 9
166.Sh HISTORY
167An algorithm called
168.Pa RC4
169was designed by RSA Data Security, Inc.
170It was considered a trade secret.
171Because it was a trade secret, it obviously could not be patented.
172A clone of this was posted anonymously to USENET and confirmed to
173be equivalent by several sources who had access to the original cipher.
174Because of the trade secret situation, RSA Data Security, Inc. could
175do nothing about the release of the
176.Ql Alleged RC4
177algorithm.
178Since
179.Pa RC4
180was trademarked, the cipher is now referred to as
181.Pa ARC4 .
182.Pp
183These functions first appeared in
184.Ox 2.1 .
185.Fn arc4random_push
186first appeared in
187.Mx 8 .
188.Fn arc4random_pushb
189first appeared in
190.Mx 10 .
191.Fn arc4random_pushk
192and
193.Fn arc4random_pushb_fast
194first appeared in
195.Mx 11 .
196All these functions were rewritten for
197.Mx 11
198and macros for every function are now defined for easy existence checks.
199