Fix some self references in our manual pages.
[dragonfly.git] / share / man / man4 / random.4
CommitLineData
984263bc
MD
1.\"
2.\" random.c -- A strong random number generator
3.\"
4.\" Version 0.92, last modified 21-Sep-95
1bf4b486 5.\"
984263bc
MD
6.\" Copyright Theodore Ts'o, 1994, 1995. All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, and the entire permission notice in its entirety,
13.\" including the disclaimer of warranties.
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. The name of the author may not be used to endorse or promote
18.\" products derived from this software without specific prior
19.\" written permission.
1bf4b486 20.\"
984263bc
MD
21.\" ALTERNATIVELY, this product may be distributed under the terms of
22.\" the GNU Public License, in which case the provisions of the GPL are
23.\" required INSTEAD OF the above restrictions. (This clause is
24.\" necessary due to a potential bad interaction between the GPL and
25.\" the restrictions contained in a BSD-style copyright.)
1bf4b486 26.\"
984263bc
MD
27.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
28.\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
29.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
30.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
31.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
32.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
33.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
34.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
35.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
36.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
37.\" OF THE POSSIBILITY OF SUCH DAMAGE.
38.\"
39.\" $FreeBSD: src/usr.sbin/rndcontrol/random.4,v 1.9.2.2 2001/11/24 16:14:18 dd Exp $
40.\"
6700dd34 41.Dd July 14, 2014
f98e2cd5 42.Dt RANDOM 4
984263bc
MD
43.Os
44.Sh NAME
45.Nm random ,
46.Nm urandom
47.Nd random number devices
48.Sh DESCRIPTION
49This device gathers environmental noise from device drivers, etc.,
50and returns good random numbers, suitable for cryptographic use.
51Besides the obvious cryptographic uses, these numbers are also good
52for seeding TCP sequence numbers, and other places where it is
53desirable to have numbers which are not only random, but hard to
54predict by an attacker.
55.Ss Theory of operation
56Computers are very predictable devices. Hence it is extremely hard
57to produce truly random numbers on a computer \(em as opposed to
61e97042 58pseudo-random numbers, which can easily be generated by using an
984263bc
MD
59algorithm. Unfortunately, it is very easy for attackers to guess
60the sequence of pseudo-random number generators, and for some
61applications this is not acceptable. So instead, we must try to
62gather "environmental noise" from the computer's environment, which
63must be hard for outside attackers to observe, and use that to
64generate random numbers. In a Unix environment, this is best done
65from inside the kernel.
66.Pp
b149d2d1 67Previous and contemporary
265a1428 68.Nm
b149d2d1
MD
69implementations typically used
70an "entropy" pool which was processed with a cryptographic hash
71function such as MD5. However, at the time of this writing security
72issues have been discovered in some of these functions
73(MD4, MD5, SHA0, SHA1).
984263bc 74.Pp
72d155ad 75This implementation uses a CSPRNG (Cryptographically Secure Pseudo
b149d2d1 76Random Number Generator) which is continuously reseeded as described above.
984263bc 77.Pp
b149d2d1 78The user interface consists of two character devices
984263bc
MD
79.Pa /dev/random
80and
81.Pa /dev/urandom .
82The
83.Pa /dev/random
84device is suitable for use when very high quality randomness is desired
6910d61c 85(e.g. for key generation). Previous implementations of this device
b149d2d1
MD
86attempted to limit the number of returned bytes based on a guess as to
87the secureness of the pool. However, this resulted in the interface being
88so undependable that most programs just started using /dev/urandom
6910d61c 89instead of /dev/random.
b149d2d1
MD
90The current
91.Dx
92implementation will return all requested bytes but the system reserves the
93right in the future to limit the transfer rate to maintain the high quality
94of randomness requested.
984263bc
MD
95.Pp
96The
97.Pa /dev/urandom
b149d2d1
MD
98device uses a different and much faster algorithm, but one which is not
99considered to be as secure (though for all practical purposes it probably
100is good enough).
984263bc 101.Pp
b149d2d1
MD
102Root may write entropy to
103.Pa /dev/random
f79ec571 104to seed the random number generator only if the securelevel is less than
e9c76aaf
SW
105or equal to zero and the
106.Va kern.seedenable
107sysctl is non-zero. A certain
b149d2d1 108degree of entropy is added by RC scripts during the boot sequence.
3a290b5c
SW
109.Sh FILES
110.Bl -tag -width Pa -compact
111.It Pa /dev/random
112.It Pa /dev/urandom
113.El
ec9265c3 114.Sh SEE ALSO
3a290b5c
SW
115.Xr arc4random 3 ,
116.Xr drand48 3 ,
117.Xr rand 3 ,
118.Xr RAND_add 3 ,
119.Xr RAND_bytes 3 ,
120.Xr random 3 ,
121.Xr rndcontrol 8
122.Sh HISTORY
123The
124.Pa random ,
125.Pa urandom
126files appeared in
127.Fx 2.1.5 .
128.Sh AUTHORS
129.An -nosplit
3a290b5c 130.An Mark Murray
b149d2d1
MD
131wrote the
132.Xr rndcontrol 8
133utility for
134.Fx .
984263bc 135.Pp
b149d2d1
MD
136The
137.Em IBAA
138CSPRNG was developed by
139.An Bob Jenkins
140and is used by
b149d2d1 141.Pa /dev/urandom .
f98e2cd5
AH
142The
143.Dx
144implementation was ported by
145.An Matthew Dillon
146from initial work done by
147.An Robin Carey .
148The
149.Pa /dev/random
150generator uses a choice of
151.Em IBAA
152and a
153.Em Fortuna
154-based CSPRNG implemented by
155.An Alex Hornung .