NAME¶
BSD::arc4random - Perl interface to the arc4 random number generator
SYNOPSIS¶
use BSD::arc4random qw(:all);
$v = arc4random();
$v = arc4random_uniform($hz);
if (!BSD::arc4random::have_kintf()) {
$v = arc4random_addrandom("entropy to pass to the system");
} else {
$v = arc4random_pushb("entropy to pass to the system");
$v = arc4random_pushk("entropy to pass to the kernel");
}
$s = arc4random_bytes(16, "entropy to pass to libc");
arc4random_stir();
$s = arc4random_bytes(16);
print $RANDOM;
DESCRIPTION¶
This set of functions maps the
arc4random(3) family of libc functions
into Perl code. All functions listed below are ithreads-safe. The internal XS
functions are not, but you are not supposed to call them, either.
On module load, perl's internal PRNG is re-seeded, as a bonus, using
srand with an argument calculated from using
arc4random_pushb on
some entropy returned from
rand's previous state.
LOW-LEVEL FUNCTIONS¶
- arc4random()
- This function returns an unsigned 32-bit integer random value.
- arc4random_addrandom(pbuf)
- This function adds the entropy from pbuf into the libc pool and
returns an unsigned 32-bit integer random value from it.
- arc4random_pushb(pbuf)
- This function first pushes the pbuf argument to the kernel if
possible, then the entropy returned by the kernel into the libc pool, then
returns an unsigned 32-bit integer random value from it.
- arc4random_pushk(pbuf)
- This function first pushes the pbuf argument to the kernel if
possible, then returns an unsigned 32-bit integer random value from the
kernel.
This function is deprecated. Use arc4random_pushb instead.
- arc4random_stir()
- This procedure attempts to retrieve new entropy from the kernel and add it
to the libc pool. Usually, this means you must have access to the
urandom(4) device; create it inside chroot(2) jails first if
you use them.
- have_kintf()
- This constant function returns 1 if arc4random_pushb and/or
arc4random_pushk actually call the kernel interfaces, 0 if they
merely map to arc4random_addrandom instead.
HIGH-LEVEL FUNCTIONS¶
- arc4random_bytes(num[, pbuf])
- This function returns a string containing as many random bytes as
requested by the integral argument num. An optional pbuf
argument is passed to the system first.
- arc4random_uniform(upper_bound)
- Calculate a uniformly distributed random number less than upper_bound
avoiding "modulo bias".
PACKAGE VARIABLES¶
- $RANDOM
- The $RANDOM returns a random value in the range
[0; 32767] on each read attempt and pushes any value it is assigned
to the kernel. It is tied at module load time.
- tie variable, 'BSD::arc4random'[, max]
- You can tie any scalar variable to this package; the max argument
is the maximum number returned; if undefined, 0 or
>= 0xFFFFFFFF, no bound is used, and values in the range
[0; 2**32-1] are returned. They will behave like
$RANDOM .
AUTHOR¶
Thorsten Glaser <tg@mirbsd.de>
SEE ALSO¶
The
arc4random(3) manual page, available online at:
<
https://www.mirbsd.org/man/arc4random.3>
Perl's rand and srand functions via perlfunc and perlfaq4.
The
randex.pl plugin for Irssi, implementing the MirOS RANDEX protocol
(entropy exchange over IRC), with CVSweb at:
<
http://cvs.mirbsd.de/ports/net/irssi/files/randex.pl>
<
https://www.mirbsd.org/a4rp5bsd.htm> when it's done being written.
COPYRIGHT AND LICENSE¶
Copyright (c) 2008, 2009, 2010, 2011 Thorsten "mirabilos" Glaser
Copyright (c) 2009 Benny Siegert Credits to Sebastian "Vutral"
Schwarz
This module is covered by the MirOS Licence:
<
http://mirbsd.de/MirOS-Licence>
The original C implementation of arc4random_uniform was contributed by Damien
Miller from OpenBSD, with simplifications by Jinmei Tatuya.