1.\" $NetBSD: arc4random.3,v 1.9 2011/02/05 00:24:08 wiz Exp $ 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 February 4, 2011 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.Nd arc4 random number generator 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In stdlib.h 48.Ft uint32_t 49.Fn arc4random "void" 50.Ft void 51.Fn arc4random_buf "void *buffer" "size_t length" 52.Ft uint32_t 53.Fn arc4random_uniform "uint32_t upper_bound" 54.Ft void 55.Fn arc4random_stir "void" 56.Ft void 57.Fn arc4random_addrandom "u_char *dat" "int datlen" 58.Sh DESCRIPTION 59The 60.Fn arc4random 61function provides a high quality 32-bit pseudo-random 62number very quickly. 63.Fn arc4random 64seeds itself on a regular basis from the kernel strong random number 65subsystem described in 66.Xr rnd 4 . 67On each call, an ARC4 generator is used to generate a new result. 68The 69.Fn arc4random 70function uses the ARC4 cipher key stream generator, 71which uses 8*8 8 bit S-Boxes. 72The S-Boxes can be in about (2**1700) states. 73.Pp 74.Fn arc4random 75fits into a middle ground not covered by other subsystems such as 76the strong, slow, and resource expensive random 77devices described in 78.Xr rnd 4 79versus the fast but poor quality interfaces described in 80.Xr rand 3 , 81.Xr random 3 , 82and 83.Xr drand48 3 . 84.Pp 85The 86.Fn arc4random_buf 87function fills the 88.Fa buffer 89with 90.Fa length 91bytes of ARC4-derived random data. 92.Pp 93The 94.Fn arc4random_uniform 95function returns a uniformly distributed random number less than 96.Fa upper_bound 97avoiding modulo bias when the upper bound is not a power of two. 98.Pp 99The 100.Fn arc4random_stir 101function reads data from 102.Pa /dev/urandom 103and uses it to permute the S-Boxes via 104.Fn arc4random_addrandom . 105.Pp 106There is no need to call 107.Fn arc4random_stir 108before using 109.Fn arc4random , 110since 111.Fn arc4random 112automatically initializes itself. 113.Sh SEE ALSO 114.Xr rand 3 , 115.Xr rand48 3 , 116.Xr random 3 117.Sh HISTORY 118An algorithm called 119.Pa RC4 120was designed by RSA Data Security, Inc. 121It was considered a trade secret, but not trademarked. 122Because it was a trade secret, it obviously could not be patented. 123A clone of this was posted anonymously to USENET and confirmed to 124be equivalent by several sources who had access to the original cipher. 125Because of the trade secret situation, RSA Data Security, Inc. can do 126nothing about the release of the ARC4 algorithm. 127Since 128.Pa RC4 129used to be a trade secret, the cipher is now referred to as 130.Pa ARC4 . 131.Pp 132These functions first appeared in 133.Ox 2.1 . 134