BSD::arc4random

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 <[email protected]>

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.