← Back to branch summary

~ubuntu-branches/ubuntu/trusty/libbsd/trusty

« back to all changes in this revision

Viewing changes to src/arc4random.3

  • Committer: Package Import Robot
  • Author(s): Guillem Jover
  • Date: 2012-05-29 08:11:13 UTC
  • mfrom: (1.2.6)
  • Revision ID: package-import@ubuntu.com-20120529081113-ymoqb4ohrvldiuoj
Tags: 0.4.0-1
http://bugs.debian.org/668705
http://bugs.debian.org/665997
http://bugs.debian.org/635377
http://bugs.debian.org/635379
http://bugs.debian.org/634955
http://bugs.debian.org/657772
http://bugs.debian.org/640895
http://bugs.debian.org/630907
http://bugs.debian.org/580372
* New upstream release. (Closes: #668705)
  - Autoconfiscated, supports cross-building natively. (Closes: #665997)
  - Provide endian encoding/decoding inline functions. (Closes: #635377)
  - Provide expand_number(). (Closes: #635379)
  - Ship <nlist.h> under /usr/include/bsd/. (Closes: #634955, #657772)
  - Ship <libutil.h> under /usr/include/bsd/. (Closes: #640895)
  - Fix header protections when using the overlay. (Closes: #630907)
  - Fix .so symlinks to be relative even when the .so.N shared library
    is on a different directory. (Closes: #580372)
  - Remove all deprecated headers and inclusions.
* Avoid leaving the system w/o an <nlist.h> previously owned by either
  libelfg0-dev or libelf-dev when upgrading from old libsd-dev versions
  which used to Replace them, by restoring <nlist.h> from <bsd/nlist.h>.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/arc4random.3
1
 
.\" $OpenBSD: arc4random.3,v 1.2 1997/04/27 22:40:25 angelos Exp $
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.
10
 
.\" 2. Redistributions in binary form must reproduce the above copyright
11
 
.\"    notice, this list of conditions and the following disclaimer in the
12
 
.\"    documentation and/or other materials provided with the distribution.
13
 
.\" 3. All advertising materials mentioning features or use of this software
14
 
.\"    must display the following acknowledgement:
15
 
.\"      This product includes software developed by Niels Provos.
16
 
.\" 4. The name of the author may not be used to endorse or promote products
17
 
.\"    derived from this software without specific prior written permission.
18
 
.\"
19
 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20
 
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21
 
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22
 
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23
 
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24
 
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
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
 
.\"
33
 
.Dd April 15, 1997
34
 
.Dt ARC4RANDOM 3
35
 
.Os
36
 
.Sh NAME
37
 
.Nm arc4random ,
38
 
.Nm arc4random_buf ,
39
 
.Nm arc4random_uniform ,
40
 
.Nm arc4random_stir ,
41
 
.Nm arc4random_addrandom
42
 
.Nd arc4 random number generator
43
 
.Sh LIBRARY
44
 
.ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
45
 
.Lb libbsd
46
 
.Sh SYNOPSIS
47
 
.In bsd/stdlib.h
48
 
.Ft u_int32_t
49
 
.Fn arc4random "void"
50
 
.Ft void
51
 
.Fn arc4random_buf "void *buf" "size_t nbytes"
52
 
.Ft u_int32_t
53
 
.Fn arc4random_uniform "u_int32_t upper_bound"
54
 
.Ft void
55
 
.Fn arc4random_stir "void"
56
 
.Ft void
57
 
.Fn arc4random_addrandom "unsigned char *dat" "int datlen"
58
 
.Sh DESCRIPTION
59
 
The
60
 
.Fn arc4random
61
 
function uses the key stream generator employed by the
62
 
arc4 cipher, which uses 8*8 8 bit S-Boxes.
63
 
The S-Boxes
64
 
can be in about
65
 
.if t 2\u\s71700\s10\d
66
 
.if n (2**1700)
67
 
states.
68
 
The
69
 
.Fn arc4random
70
 
function returns pseudo-random numbers in the range of 0 to
71
 
.if t 2\u\s731\s10\d\(mi1,
72
 
.if n (2**32)\(mi1,
73
 
and therefore has twice the range of
74
 
.Xr rand 3
75
 
and
76
 
.Xr random 3 .
77
 
.Pp
78
 
.Fn arc4random_buf
79
 
function fills the region
80
 
.Fa buf
81
 
of length
82
 
.Fa nbytes
83
 
with ARC4-derived random data.
84
 
.Pp
85
 
.Fn arc4random_uniform
86
 
will return a uniformly distributed random number less than
87
 
.Fa upper_bound .
88
 
.Fn arc4random_uniform
89
 
is recommended over constructions like
90
 
.Dq Li arc4random() % upper_bound
91
 
as it avoids "modulo bias" when the upper bound is not a power of two.
92
 
.Pp
93
 
The
94
 
.Fn arc4random_stir
95
 
function reads data from
96
 
.Pa /dev/urandom
97
 
and uses it to permute the S-Boxes via
98
 
.Fn arc4random_addrandom .
99
 
.Pp
100
 
There is no need to call
101
 
.Fn arc4random_stir
102
 
before using
103
 
.Fn arc4random
104
 
functions family, since
105
 
they automatically initialize themselves.
106
 
.Sh EXAMPLES
107
 
The following produces a drop-in replacement for the traditional
108
 
.Fn rand
109
 
and
110
 
.Fn random
111
 
functions using
112
 
.Fn arc4random :
113
 
.Pp
114
 
.Dl "#define foo4random() (arc4random() % ((unsigned)RAND_MAX + 1))"
115
 
.Sh SEE ALSO
116
 
.Xr rand 3 ,
117
 
.Xr random 3 ,
118
 
.Xr srandomdev 3
119
 
.Sh HISTORY
120
 
.Pa RC4
121
 
has been designed by RSA Data Security, Inc.
122
 
It was posted anonymously
123
 
to the USENET and was confirmed to be equivalent by several sources who
124
 
had access to the original cipher.
125
 
Since
126
 
.Pa RC4
127
 
used to be a trade secret, the cipher is now referred to as
128
 
.Pa ARC4 .