xref: /freebsd/share/man/man9/random.9 (revision aa12cea2ccc6e686d6d31cf67d6bc69cbc1ba744)
167297998SMark Murray.\"
267297998SMark Murray.\" Copyright (c) 2000
367297998SMark Murray.\"	The Regents of the University of California.  All rights reserved.
467297998SMark Murray.\"
567297998SMark Murray.\" 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.\" "
2967297998SMark Murray.Dd September 25, 2000
3067297998SMark Murray.Dt RANDOM 9
31*aa12cea2SUlrich Spörlein.Os
3267297998SMark Murray.Sh NAME
33d962d52aSRuslan Ermilov.Nm arc4rand ,
3467297998SMark Murray.Nm arc4random ,
356cfaa4a7SSheldon Hearn.Nm random ,
366cfaa4a7SSheldon Hearn.Nm read_random ,
376cfaa4a7SSheldon Hearn.Nm srandom
38eb083802SRuslan Ermilov.Nd supply pseudo-random numbers
3967297998SMark Murray.Sh SYNOPSIS
4032eef9aeSRuslan Ermilov.In sys/libkern.h
4167297998SMark Murray.Ft void
4267297998SMark Murray.Fn srandom "u_long seed"
4367297998SMark Murray.Ft u_long
4467297998SMark Murray.Fn random "void"
452c38619bSPoul-Henning Kamp.Ft void
462c38619bSPoul-Henning Kamp.Fn arc4rand "void *ptr" "u_int length" "int reseed"
4767297998SMark Murray.Ft u_int32_t
4867297998SMark Murray.Fn arc4random "void"
4967297998SMark Murray.Pp
5032eef9aeSRuslan Ermilov.In sys/random.h
51234b7100SChad David.Ft int
52234b7100SChad David.Fn read_random "void *buffer" "int count"
5367297998SMark Murray.Sh DESCRIPTION
5467297998SMark MurrayThe
5567297998SMark Murray.Fn random
5667297998SMark Murrayfunction will by default produce a sequence of numbers that can be duplicated
5767297998SMark Murrayby calling
5867297998SMark Murray.Fn srandom
5967297998SMark Murraywith
6067297998SMark Murray.Ql 1
6167297998SMark Murrayas the
62d962d52aSRuslan Ermilov.Fa seed .
6367297998SMark MurrayThe
6467297998SMark Murray.Fn srandom
6567297998SMark Murrayfunction may be called with any arbitrary
66d962d52aSRuslan Ermilov.Fa seed
6767297998SMark Murrayvalue to get slightly more unpredictable numbers.
6867297998SMark MurrayIt is important to remember that the
6967297998SMark Murray.Fn random
7067297998SMark Murrayfunction is entirely predictable, and is therefore not of use where
7167297998SMark Murrayknowledge of the sequence of numbers may be of benefit to an attacker.
7267297998SMark Murray.Pp
7367297998SMark MurrayThe
742c38619bSPoul-Henning Kamp.Fn arc4rand
7567297998SMark Murrayfunction will return very good quality random numbers, slightly better
7667297998SMark Murraysuited for security-related purposes.
7767297998SMark MurrayThe random numbers from
782c38619bSPoul-Henning Kamp.Fn arc4rand
7967297998SMark Murrayare seeded from the entropy device if it is available.
802c38619bSPoul-Henning KampAutomatic reseeds happen after a certain timeinterval and after a
812c38619bSPoul-Henning Kampcertain number of bytes have been delivered.
822c38619bSPoul-Henning KampA forced reseed can be forced by passing a non-zero value in the
83d962d52aSRuslan Ermilov.Fa reseed
842c38619bSPoul-Henning Kampargument.
8567297998SMark Murray.Pp
8667297998SMark MurrayThe
8767297998SMark Murray.Fn read_random
8867297998SMark Murrayfunction is used to return entropy directly from the entropy device
895203edcdSRuslan Ermilovif it has been loaded.
905203edcdSRuslan ErmilovIf the entropy device is not loaded, then
9167297998SMark Murraythe
92d962d52aSRuslan Ermilov.Fa buffer
9367297998SMark Murrayis filled with output generated by
9467297998SMark Murray.Fn random .
9567297998SMark MurrayThe
96d962d52aSRuslan Ermilov.Fa buffer
9767297998SMark Murrayis filled with no more than
98d962d52aSRuslan Ermilov.Fa count
995203edcdSRuslan Ermilovbytes.
1005203edcdSRuslan ErmilovIt is advised that
10167297998SMark Murray.Fn read_random
10267297998SMark Murrayis not used; instead use
1032c38619bSPoul-Henning Kamp.Fn arc4rand
10467297998SMark Murray.Pp
10567297998SMark MurrayAll the bits generated by
10667297998SMark Murray.Fn random ,
1072c38619bSPoul-Henning Kamp.Fn arc4rand
10867297998SMark Murrayand
10967297998SMark Murray.Fn read_random
110559eb8d2SHiten Pandyaare usable.
111559eb8d2SHiten PandyaFor example,
11267297998SMark Murray.Sq Li random()&01
11367297998SMark Murraywill produce a random binary value.
1142c38619bSPoul-Henning Kamp.Pp
1152c38619bSPoul-Henning KampThe
1162c38619bSPoul-Henning Kamp.Fn arc4random
1172c38619bSPoul-Henning Kampis a convenience function which calls
1182c38619bSPoul-Henning Kamp.Fn arc4rand
1192c38619bSPoul-Henning Kampto return a 32 bit pseudo-random integer.
12067297998SMark Murray.Sh RETURN VALUES
12167297998SMark MurrayThe
12267297998SMark Murray.Fn random
12367297998SMark Murrayfunction
12467297998SMark Murrayuses a non-linear additive feedback random number generator employing a
12567297998SMark Murraydefault table of size 31 long integers to return successive pseudo-random
12667297998SMark Murraynumbers in the range from 0 to
12767297998SMark Murray.if t 2\u\s731\s10\d\(mi1.
12867297998SMark Murray.if n (2**31)\(mi1.
12967297998SMark MurrayThe period of this random number generator is very large, approximately
13067297998SMark Murray.if t 16\(mu(2\u\s731\s10\d\(mi1).
13167297998SMark Murray.if n 16*((2**31)\(mi1).
13267297998SMark Murray.Pp
13367297998SMark MurrayThe
1342c38619bSPoul-Henning Kamp.Fn arc4rand
1352c38619bSPoul-Henning Kampfunction uses the RC4 algorithm to generate successive pseudo-random
1362c38619bSPoul-Henning Kampbytes.
1372c38619bSPoul-Henning KampThe
13867297998SMark Murray.Fn arc4random
13967297998SMark Murrayfunction
1402c38619bSPoul-Henning Kampuses
1412c38619bSPoul-Henning Kamp.Fn arc4rand
1422c38619bSPoul-Henning Kampto generate pseudo-random numbers in the range from 0 to
14367297998SMark Murray.if t 2\u\s732\s10\d\(mi1.
14467297998SMark Murray.if n (2**32)\(mi1.
14567297998SMark Murray.Pp
14667297998SMark MurrayThe
14767297998SMark Murray.Fn read_random
14867297998SMark Murrayfunction returns the number of bytes placed in
149d962d52aSRuslan Ermilov.Fa buffer .
15067297998SMark Murray.Sh AUTHORS
15167297998SMark Murray.An Dan Moschuk
15267297998SMark Murraywrote
15367297998SMark Murray.Fn arc4random .
15467297998SMark Murray.An Mark R V Murray
15567297998SMark Murraywrote
15667297998SMark Murray.Fn read_random .
157