xref: /freebsd/share/man/man9/random.9 (revision f3bae413e9d0ee6dd48cab41fc353039d49bbde7)
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*f3bae413SConrad Meyer.Dd December 26, 2019
3067297998SMark Murray.Dt RANDOM 9
31aa12cea2SUlrich Spörlein.Os
3267297998SMark Murray.Sh NAME
33d962d52aSRuslan Ermilov.Nm arc4rand ,
3467297998SMark Murray.Nm arc4random ,
3513774e82SConrad Meyer.Nm arc4random_buf ,
36f3d2512dSConrad Meyer.Nm is_random_seeded ,
376cfaa4a7SSheldon Hearn.Nm random ,
386cfaa4a7SSheldon Hearn.Nm read_random ,
39*f3bae413SConrad Meyer.Nm read_random_uio
40eb083802SRuslan Ermilov.Nd supply pseudo-random numbers
4167297998SMark Murray.Sh SYNOPSIS
4232eef9aeSRuslan Ermilov.In sys/libkern.h
4313774e82SConrad Meyer.Ft uint32_t
4413774e82SConrad Meyer.Fn arc4random "void"
4513774e82SConrad Meyer.Ft void
4613774e82SConrad Meyer.Fn arc4random_buf "void *ptr" "size_t len"
4713774e82SConrad Meyer.Ft void
4813774e82SConrad Meyer.Fn arc4rand "void *ptr" "u_int length" "int reseed"
4913774e82SConrad Meyer.Pp
5013774e82SConrad Meyer.In sys/random.h
51f3d2512dSConrad Meyer.Ft bool
52f3d2512dSConrad Meyer.Fn is_random_seeded "void"
5313774e82SConrad Meyer.Ft void
5413774e82SConrad Meyer.Fn read_random "void *buffer" "int count"
5513774e82SConrad Meyer.Ft int
5613774e82SConrad Meyer.Fn read_random_uio "struct uio *uio" "bool nonblock"
5713774e82SConrad Meyer.Ss LEGACY ROUTINES
5813774e82SConrad Meyer.In sys/libkern.h
5967297998SMark Murray.Ft u_long
6067297998SMark Murray.Fn random "void"
6167297998SMark Murray.Sh DESCRIPTION
6267297998SMark MurrayThe
6313774e82SConrad Meyer.Fn arc4random
6413774e82SConrad Meyerand
6513774e82SConrad Meyer.Fn arc4random_buf
6613774e82SConrad Meyerfunctions will return very good quality random numbers, suited for
6713774e82SConrad Meyersecurity-related purposes.
6813774e82SConrad MeyerBoth are wrappers around the underlying
6913774e82SConrad Meyer.Fn arc4rand
7013774e82SConrad Meyerinterface.
7113774e82SConrad Meyer.Fn arc4random
7213774e82SConrad Meyerreturns a 32-bit random value, while
7313774e82SConrad Meyer.Fn arc4random_buf
7413774e82SConrad Meyerfills
7513774e82SConrad Meyer.Fa ptr
7613774e82SConrad Meyerwith
7713774e82SConrad Meyer.Fa len
7813774e82SConrad Meyerbytes of random data.
7967297998SMark Murray.Pp
8067297998SMark MurrayThe
812c38619bSPoul-Henning Kamp.Fn arc4rand
8213774e82SConrad MeyerCSPRNG
8313774e82SConrad Meyeris seeded from the
8413774e82SConrad Meyer.Xr random 4
8513774e82SConrad Meyerkernel abstract entropy device.
8613774e82SConrad MeyerAutomatic reseeding happens at unspecified time and bytes (of output)
8713774e82SConrad Meyerintervals.
8813774e82SConrad MeyerA reseed can be forced by passing a non-zero
89d962d52aSRuslan Ermilov.Fa reseed
9013774e82SConrad Meyervalue.
9167297998SMark Murray.Pp
9267297998SMark MurrayThe
9367297998SMark Murray.Fn read_random
9413774e82SConrad Meyerfunction is used to read entropy directly from the kernel abstract entropy
9513774e82SConrad Meyerdevice.
9613774e82SConrad Meyer.Fn read_random
9713774e82SConrad Meyerblocks if and until the entropy device is seeded.
9813774e82SConrad MeyerThe provided
99d962d52aSRuslan Ermilov.Fa buffer
10067297998SMark Murrayis filled with no more than
101d962d52aSRuslan Ermilov.Fa count
1025203edcdSRuslan Ermilovbytes.
103d1b06863SMark MurrayIt is strongly advised that
10467297998SMark Murray.Fn read_random
10513774e82SConrad Meyeris not used directly;
10613774e82SConrad Meyerinstead, use the
1072c38619bSPoul-Henning Kamp.Fn arc4rand
10813774e82SConrad Meyerfamily of functions.
10967297998SMark Murray.Pp
110707d98feSEd SchoutenThe
111f3d2512dSConrad Meyer.Fn is_random_seeded
112f3d2512dSConrad Meyerfunction can be used to check in advance if
113f3d2512dSConrad Meyer.Fn read_random
114f3d2512dSConrad Meyerwill block.
115f3d2512dSConrad Meyer(If random is seeded, it will not block.)
116f3d2512dSConrad Meyer.Pp
117f3d2512dSConrad MeyerThe
118707d98feSEd Schouten.Fn read_random_uio
119707d98feSEd Schoutenfunction behaves identically to
120707d98feSEd Schouten.Xr read 2
121707d98feSEd Schoutenon
122707d98feSEd Schouten.Pa /dev/random .
123707d98feSEd SchoutenThe
124707d98feSEd Schouten.Fa uio
125707d98feSEd Schoutenargument points to a buffer where random data should be stored.
12613774e82SConrad MeyerIf
127707d98feSEd Schouten.Fa nonblock
12813774e82SConrad Meyeris true and the random device is not seeded, this function does not return any
12913774e82SConrad Meyerdata.
13013774e82SConrad MeyerOtherwise, this function may block interruptibly until the random device is seeded.
13113774e82SConrad MeyerIf the function is interrupted before the random device is seeded, no data is
13213774e82SConrad Meyerreturned.
133707d98feSEd Schouten.Pp
134*f3bae413SConrad MeyerThe deprecated
135*f3bae413SConrad Meyer.Xr random 9
136*f3bae413SConrad Meyerfunction will produce a sequence of pseudorandom numbers using a similar weak
137*f3bae413SConrad Meyerlinear congruential generator as
138*f3bae413SConrad Meyer.Xr rand 3
139*f3bae413SConrad Meyer(the 1988 Park-Miller LCG).
140*f3bae413SConrad MeyerIt is obsolete and scheduled to be removed in
141*f3bae413SConrad Meyer.Fx 13.0 .
14213774e82SConrad MeyerIt is strongly advised that the
143*f3bae413SConrad Meyer.Xr random 9
14413774e82SConrad Meyerfunction not be used to generate random numbers.
14513774e82SConrad MeyerSee
14613774e82SConrad Meyer.Sx SECURITY CONSIDERATIONS .
14767297998SMark Murray.Sh RETURN VALUES
14867297998SMark MurrayThe
1492c38619bSPoul-Henning Kamp.Fn arc4rand
15013774e82SConrad Meyerfunction uses the Chacha20 algorithm to generate a pseudo-random sequence of
15113774e82SConrad Meyerbytes.
1522c38619bSPoul-Henning KampThe
15367297998SMark Murray.Fn arc4random
154d1b06863SMark Murrayfunction uses
1552c38619bSPoul-Henning Kamp.Fn arc4rand
156d1b06863SMark Murrayto generate pseudo-random numbers
157d1b06863SMark Murrayin the range from 0 to
15867297998SMark Murray.if t 2\u\s732\s10\d\(mi1.
15967297998SMark Murray.if n (2**32)\(mi1.
16067297998SMark Murray.Pp
16167297998SMark MurrayThe
16267297998SMark Murray.Fn read_random
163d1b06863SMark Murrayfunction returns
164d1b06863SMark Murraythe number of bytes placed in
165d962d52aSRuslan Ermilov.Fa buffer .
166707d98feSEd Schouten.Pp
167707d98feSEd Schouten.Fn read_random_uio
168707d98feSEd Schoutenreturns zero when successful,
169707d98feSEd Schoutenotherwise an error code is returned.
170707d98feSEd Schouten.Sh ERRORS
171707d98feSEd Schouten.Fn read_random_uio
172707d98feSEd Schoutenmay fail if:
173707d98feSEd Schouten.Bl -tag -width Er
174707d98feSEd Schouten.It Bq Er EFAULT
175707d98feSEd Schouten.Fa uio
176707d98feSEd Schoutenpoints to an invalid memory region.
177707d98feSEd Schouten.It Bq Er EWOULDBLOCK
178707d98feSEd SchoutenThe random device is unseeded and
179707d98feSEd Schouten.Fa nonblock
180707d98feSEd Schoutenis true.
181707d98feSEd Schouten.El
18267297998SMark Murray.Sh AUTHORS
18367297998SMark Murray.An Dan Moschuk
18467297998SMark Murraywrote
18567297998SMark Murray.Fn arc4random .
18667297998SMark Murray.An Mark R V Murray
18767297998SMark Murraywrote
18867297998SMark Murray.Fn read_random .
18913774e82SConrad Meyer.Sh SECURITY CONSIDERATIONS
19013774e82SConrad MeyerDo not use
19113774e82SConrad Meyer.Fn random
19213774e82SConrad Meyerin new code.
19313774e82SConrad Meyer.Pp
19413774e82SConrad MeyerIt is important to remember that the
19513774e82SConrad Meyer.Fn random
19613774e82SConrad Meyerfunction is entirely predictable.
19713774e82SConrad MeyerIt is easy for attackers to predict future output of
19813774e82SConrad Meyer.Fn random
19913774e82SConrad Meyerby recording some generated values.
20013774e82SConrad MeyerWe cannot emphasize strongly enough that
20113774e82SConrad Meyer.Fn random
20213774e82SConrad Meyermust not be used to generate values that are intended to be unpredictable.
203