xref: /freebsd/share/man/man9/random.9 (revision 707d98fe2fd59bb3b6e975a0dce2ef297341d0bd)
167297998SMark Murray.\"
2d1b06863SMark Murray.\" Copyright (c) 2015
3d1b06863SMark Murray.\"	Mark R V Murray
467297998SMark Murray.\" Copyright (c) 2000
567297998SMark Murray.\"	The Regents of the University of California.  All rights reserved.
667297998SMark Murray.\"
767297998SMark Murray.\" Redistribution and use in source and binary forms, with or without
867297998SMark Murray.\" modification, are permitted provided that the following conditions
967297998SMark Murray.\" are met:
1067297998SMark Murray.\" 1. Redistributions of source code must retain the above copyright
1167297998SMark Murray.\"    notice, this list of conditions and the following disclaimer.
1267297998SMark Murray.\" 2. Redistributions in binary form must reproduce the above copyright
1367297998SMark Murray.\"    notice, this list of conditions and the following disclaimer in the
1467297998SMark Murray.\"    documentation and/or other materials provided with the distribution.
1567297998SMark Murray.\"
1667297998SMark Murray.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
1767297998SMark Murray.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
1867297998SMark Murray.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1967297998SMark Murray.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
2067297998SMark Murray.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
2167297998SMark Murray.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
2267297998SMark Murray.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
2367297998SMark Murray.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
2467297998SMark Murray.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
2567297998SMark Murray.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
2667297998SMark Murray.\"
2767297998SMark Murray.\" $FreeBSD$
2867297998SMark Murray.\" "
29*707d98feSEd Schouten.Dd July 14, 2015
3067297998SMark Murray.Dt RANDOM 9
31aa12cea2SUlrich Spörlein.Os
3267297998SMark Murray.Sh NAME
33d962d52aSRuslan Ermilov.Nm arc4rand ,
3467297998SMark Murray.Nm arc4random ,
356cfaa4a7SSheldon Hearn.Nm random ,
366cfaa4a7SSheldon Hearn.Nm read_random ,
37*707d98feSEd Schouten.Nm read_random_uio ,
386cfaa4a7SSheldon Hearn.Nm srandom
39eb083802SRuslan Ermilov.Nd supply pseudo-random numbers
4067297998SMark Murray.Sh SYNOPSIS
4132eef9aeSRuslan Ermilov.In sys/libkern.h
4267297998SMark Murray.Ft void
4367297998SMark Murray.Fn srandom "u_long seed"
4467297998SMark Murray.Ft u_long
4567297998SMark Murray.Fn random "void"
462c38619bSPoul-Henning Kamp.Ft void
472c38619bSPoul-Henning Kamp.Fn arc4rand "void *ptr" "u_int length" "int reseed"
486b99842aSEd Schouten.Ft uint32_t
4967297998SMark Murray.Fn arc4random "void"
5067297998SMark Murray.Pp
5132eef9aeSRuslan Ermilov.In sys/random.h
52234b7100SChad David.Ft int
53234b7100SChad David.Fn read_random "void *buffer" "int count"
54*707d98feSEd Schouten.Ft int
55*707d98feSEd Schouten.Fn read_random_uio "struct uio *uio" "bool nonblock"
5667297998SMark Murray.Sh DESCRIPTION
5767297998SMark MurrayThe
5867297998SMark Murray.Fn random
59d1b06863SMark Murrayfunction will by default produce
60d1b06863SMark Murraya sequence of numbers
61d1b06863SMark Murraythat can be duplicated
6267297998SMark Murrayby calling
6367297998SMark Murray.Fn srandom
64d1b06863SMark Murraywith some constant
6567297998SMark Murrayas the
66d962d52aSRuslan Ermilov.Fa seed .
6767297998SMark MurrayThe
6867297998SMark Murray.Fn srandom
6967297998SMark Murrayfunction may be called with any arbitrary
70d962d52aSRuslan Ermilov.Fa seed
7167297998SMark Murrayvalue to get slightly more unpredictable numbers.
7267297998SMark MurrayIt is important to remember that the
7367297998SMark Murray.Fn random
74d1b06863SMark Murrayfunction is entirely predictable,
75d1b06863SMark Murrayand is therefore not of use where
76d1b06863SMark Murrayknowledge of the sequence of numbers
77d1b06863SMark Murraymay be of benefit to an attacker.
7867297998SMark Murray.Pp
7967297998SMark MurrayThe
802c38619bSPoul-Henning Kamp.Fn arc4rand
81d1b06863SMark Murrayfunction will return very good quality random numbers,
82d1b06863SMark Murraybetter suited
83d1b06863SMark Murrayfor security-related purposes.
8467297998SMark MurrayThe random numbers from
852c38619bSPoul-Henning Kamp.Fn arc4rand
86d1b06863SMark Murrayare seeded from the entropy device
87d1b06863SMark Murrayif it is available.
88d1b06863SMark MurrayAutomatic reseeds happen
89d1b06863SMark Murrayafter a certain timeinterval
90d1b06863SMark Murrayand after a certain number of bytes
91d1b06863SMark Murrayhave been delivered.
92d1b06863SMark MurrayA forced reseed
93d1b06863SMark Murraycan be forced
94d1b06863SMark Murrayby passing a non-zero
95d1b06863SMark Murrayvalue in the
96d962d52aSRuslan Ermilov.Fa reseed
972c38619bSPoul-Henning Kampargument.
9867297998SMark Murray.Pp
9967297998SMark MurrayThe
10067297998SMark Murray.Fn read_random
10167297998SMark Murrayfunction is used to return entropy directly from the entropy device
1025203edcdSRuslan Ermilovif it has been loaded.
1035203edcdSRuslan ErmilovIf the entropy device is not loaded, then
10467297998SMark Murraythe
105d962d52aSRuslan Ermilov.Fa buffer
106d1b06863SMark Murrayis ignored
107d1b06863SMark Murrayand zero is returned.
10867297998SMark MurrayThe
109d962d52aSRuslan Ermilov.Fa buffer
11067297998SMark Murrayis filled with no more than
111d962d52aSRuslan Ermilov.Fa count
1125203edcdSRuslan Ermilovbytes.
113d1b06863SMark MurrayIt is strongly advised that
11467297998SMark Murray.Fn read_random
115d1b06863SMark Murrayis not used;
116d1b06863SMark Murrayinstead use
1172c38619bSPoul-Henning Kamp.Fn arc4rand
118d1b06863SMark Murrayunless it is
119d1b06863SMark Murraynecessary to know
120d1b06863SMark Murraythat no entropy
121d1b06863SMark Murrayhas been returned.
12267297998SMark Murray.Pp
123*707d98feSEd SchoutenThe
124*707d98feSEd Schouten.Fn read_random_uio
125*707d98feSEd Schoutenfunction behaves identically to
126*707d98feSEd Schouten.Xr read 2
127*707d98feSEd Schoutenon
128*707d98feSEd Schouten.Pa /dev/random .
129*707d98feSEd SchoutenThe
130*707d98feSEd Schouten.Fa uio
131*707d98feSEd Schoutenargument points to a buffer where random data should be stored.
132*707d98feSEd SchoutenThis function only returns data if the the random device is seeded.
133*707d98feSEd SchoutenIt blocks if unseeded,
134*707d98feSEd Schoutenexcept when the
135*707d98feSEd Schouten.Fa nonblock
136*707d98feSEd Schoutenargument is true.
137*707d98feSEd Schouten.Pp
138d1b06863SMark MurrayAll the bits returned by
13967297998SMark Murray.Fn random ,
140*707d98feSEd Schouten.Fn arc4rand ,
141*707d98feSEd Schouten.Fn read_random ,
14267297998SMark Murrayand
143*707d98feSEd Schouten.Fn read_random_uio
144559eb8d2SHiten Pandyaare usable.
145559eb8d2SHiten PandyaFor example,
14667297998SMark Murray.Sq Li random()&01
14767297998SMark Murraywill produce a random binary value.
1482c38619bSPoul-Henning Kamp.Pp
1492c38619bSPoul-Henning KampThe
1502c38619bSPoul-Henning Kamp.Fn arc4random
1512c38619bSPoul-Henning Kampis a convenience function which calls
1522c38619bSPoul-Henning Kamp.Fn arc4rand
1532c38619bSPoul-Henning Kampto return a 32 bit pseudo-random integer.
15467297998SMark Murray.Sh RETURN VALUES
15567297998SMark MurrayThe
15667297998SMark Murray.Fn random
157d1b06863SMark Murrayfunction uses
158d1b06863SMark Murraya non-linear additive feedback random number generator
159d1b06863SMark Murrayemploying a default table
160d1b06863SMark Murrayof size 31
161d1b06863SMark Murraycontaining long integers
162d1b06863SMark Murrayto return successive pseudo-random
16367297998SMark Murraynumbers in the range from 0 to
16467297998SMark Murray.if t 2\u\s731\s10\d\(mi1.
16567297998SMark Murray.if n (2**31)\(mi1.
166d1b06863SMark MurrayThe period of this random number generator
167d1b06863SMark Murrayis very large,
168d1b06863SMark Murrayapproximately
16967297998SMark Murray.if t 16\(mu(2\u\s731\s10\d\(mi1).
17067297998SMark Murray.if n 16*((2**31)\(mi1).
17167297998SMark Murray.Pp
17267297998SMark MurrayThe
1732c38619bSPoul-Henning Kamp.Fn arc4rand
174d1b06863SMark Murrayfunction uses the RC4 algorithm
175d1b06863SMark Murrayto generate successive pseudo-random bytes.
1762c38619bSPoul-Henning KampThe
17767297998SMark Murray.Fn arc4random
178d1b06863SMark Murrayfunction uses
1792c38619bSPoul-Henning Kamp.Fn arc4rand
180d1b06863SMark Murrayto generate pseudo-random numbers
181d1b06863SMark Murrayin the range from 0 to
18267297998SMark Murray.if t 2\u\s732\s10\d\(mi1.
18367297998SMark Murray.if n (2**32)\(mi1.
18467297998SMark Murray.Pp
18567297998SMark MurrayThe
18667297998SMark Murray.Fn read_random
187d1b06863SMark Murrayfunction returns
188d1b06863SMark Murraythe number of bytes placed in
189d962d52aSRuslan Ermilov.Fa buffer .
190*707d98feSEd Schouten.Pp
191*707d98feSEd Schouten.Fn read_random_uio
192*707d98feSEd Schoutenreturns zero when successful,
193*707d98feSEd Schoutenotherwise an error code is returned.
194*707d98feSEd Schouten.Sh ERRORS
195*707d98feSEd Schouten.Fn read_random_uio
196*707d98feSEd Schoutenmay fail if:
197*707d98feSEd Schouten.Bl -tag -width Er
198*707d98feSEd Schouten.It Bq Er EFAULT
199*707d98feSEd Schouten.Fa uio
200*707d98feSEd Schoutenpoints to an invalid memory region.
201*707d98feSEd Schouten.It Bq Er EWOULDBLOCK
202*707d98feSEd SchoutenThe random device is unseeded and
203*707d98feSEd Schouten.Fa nonblock
204*707d98feSEd Schoutenis true.
205*707d98feSEd Schouten.El
20667297998SMark Murray.Sh AUTHORS
20767297998SMark Murray.An Dan Moschuk
20867297998SMark Murraywrote
20967297998SMark Murray.Fn arc4random .
21067297998SMark Murray.An Mark R V Murray
21167297998SMark Murraywrote
21267297998SMark Murray.Fn read_random .
213