Annotation of src/lib/libc/gen/arc4random.3, Revision 1.7
1.7 ! perry 1: .\" $NetBSD: arc4random.3,v 1.6 2003/04/16 13:34:35 wiz Exp $
1.1 itojun 2: .\" $OpenBSD: arc4random.3,v 1.17 2000/12/21 14:07:41 aaron Exp $
3: .\"
4: .\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
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: .\" 3. All advertising materials mentioning features or use of this software
16: .\" must display the following acknowledgement:
17: .\" This product includes software developed by Niels Provos.
18: .\" 4. The name of the author may not be used to endorse or promote products
19: .\" derived from this software without specific prior written permission.
20: .\"
21: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31: .\"
32: .\" Manual page, using -mandoc macros
33: .\"
34: .Dd April 15, 1997
35: .Dt ARC4RANDOM 3
36: .Os
37: .Sh NAME
38: .Nm arc4random ,
39: .Nm arc4random_stir ,
40: .Nm arc4random_addrandom
41: .Nd arc4 random number generator
1.5 itojun 42: .Sh LIBRARY
43: .Lb libc
1.1 itojun 44: .Sh SYNOPSIS
1.6 wiz 45: .In stdlib.h
1.7 ! perry 46: .Ft uint32_t
1.1 itojun 47: .Fn arc4random "void"
48: .Ft void
49: .Fn arc4random_stir "void"
50: .Ft void
51: .Fn arc4random_addrandom "u_char *dat" "int datlen"
52: .Sh DESCRIPTION
53: The
54: .Fn arc4random
55: function provides a high quality 32-bit pseudo-random
56: number very quickly.
57: .Fn arc4random
58: seeds itself on a regular basis from the kernel strong random number
59: subsystem described in
1.4 itojun 60: .Xr rnd 4 .
1.1 itojun 61: On each call, an ARC4 generator is used to generate a new result.
62: The
63: .Fn arc4random
64: function uses the ARC4 cipher key stream generator,
65: which uses 8*8 8 bit S-Boxes.
66: The S-Boxes can be in about (2**1700) states.
67: .Pp
68: .Fn arc4random
69: fits into a middle ground not covered by other subsystems such as
70: the strong, slow, and resource expensive random
71: devices described in
1.4 itojun 72: .Xr rnd 4
1.1 itojun 73: versus the fast but poor quality interfaces described in
74: .Xr rand 3 ,
75: .Xr random 3 ,
76: and
77: .Xr drand48 3 .
78: .Pp
79: The
80: .Fn arc4random_stir
81: function reads data from
1.2 itojun 82: .Pa /dev/urandom
1.1 itojun 83: and uses it to permute the S-Boxes via
84: .Fn arc4random_addrandom .
85: .Pp
86: There is no need to call
87: .Fn arc4random_stir
88: before using
89: .Fn arc4random ,
90: since
91: .Fn arc4random
92: automatically initializes itself.
93: .Sh SEE ALSO
94: .Xr rand 3 ,
95: .Xr rand48 3 ,
96: .Xr random 3
97: .Sh HISTORY
98: An algorithm called
99: .Pa RC4
100: was designed by RSA Data Security, Inc.
101: It was considered a trade secret, but not trademarked.
102: Because it was a trade secret, it obviously could not be patented.
103: A clone of this was posted anonymously to USENET and confirmed to
104: be equivalent by several sources who had access to the original cipher.
105: Because of the trade secret situation, RSA Data Security, Inc. can do
106: nothing about the release of the ARC4 algorithm.
107: Since
108: .Pa RC4
109: used to be a trade secret, the cipher is now referred to as
110: .Pa ARC4 .
111: .Pp
112: These functions first appeared in
113: .Ox 2.1 .
CVSweb <webmaster@jp.NetBSD.org>