BSD::arc4random version 1.50
============================

This module provides a Perl API for the BSDs' arc4random(3) suite
of functions and adds a few high-level functions, such as the new
arc4random_uniform(3). The Perl functions are ithreads-safe (only
if threads::shared is required). Scalars can be tied to this pak-
kage, yielding uniformly distributed random numbers with an arbi-
trary upper bound on read access, contributing to the RC4 entropy
pool on write access. An exported global $RANDOM variable returns
15-bit unsigned random numbers, from [0; 32767], similar to mksh.
Furthermore, Perl's internal PRNG is seeded with entropy obtained
from the arc4random generator once on module load time.

INSTALLATION

Makefile.PL tries to auto-detect existence of arc4random_pushb by
looking at the operating system used; see below if this fails:

If your system does not have arc4random_pushb(3), edit the DEFINE
line in Makefile.PL to define HAVE_ARC4RANDOM_PUSHB to 0 and make
sure at least arc4random_addrandom(3) exists. *HOWEVER* note that
then, entropy pushed into the system will end up in the process's
own pool instead of in the kernel. You can fix this by regularily
calling arc4random() or arc4random_bytes() and writing the output
to /dev/urandom or similar (after obtaining permissions) FROM THE
SAME PROCESS/SCRIPT (other ithread is okay) or, better, providing
at compile time an arc4random_pushb(3)* implementation collecting
entropy, sending it to a sensible place, e.g. a gathering daemon.

Using a seed file, similar to the randex.pl Irssi plugin, is also
a viable option. Future versions of this module will have support
for seed files and entropy daemons included.

*) http://www.mirbsd.org/man3/arc4random

If your system's arc4random(3) function suite is not in libc, edit
the LIBS line in Makefile.PL to include the appropriate library,
e.g. -lbsd on Debian or -lcrypt on Interix, and possibly the INC
line to use the appropriate header, e.g. something like this for
Debian libbsd: '-include /usr/include/bsd/bsd.h'

NOTE: This version of BSD::arc4random comes with an experimental
implementation tested on BSD, Cygwin, Debian and Solaris; this is
a kludge and will most likely go away. It is only used automati-
cally on Debian GNU/HURD, GNU/kFreeBSD, GNU/Linux, as well as
Cygwin and Solaris. It can be used on some BSDs as well; support
for pushing back entropy is available on Cygwin/WIN32 and MirBSD.

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

This module requires arc4random(3), arc4random_addrandom(3) and
arc4random_stir(3) in libc. There are configuration options in
Makefile.PL, to change for example, if a different library like
libcrypt on Interix or libbsd on Debian is required to pull in
these functions.

COPYRIGHT AND LICENCE

Copyright (c) 2008, 2009, 2010, 2011
	Thorsten "mirabilos" Glaser, MirOS Project
Copyright (c) 2009
	Benny Siegert, MirOS Project
Uploaded to CPAN by: Sebastian "Vutral" Schwarz (PAUSE ID: SJSZ)
Credits to him for input, ideas and a lot of help.
The arc4random(9) PRNG has been invented by the OpenBSD Project.
The arc4random_uniform algorithm is derived from the code in the
OpenBSD kernel, published by Damien Miller under the ISC licence
(although no code was copied, acknowledgement is granted).

This module is covered by the MirOS Licence: http://mirbsd.de/MirOS-Licence

________________________________________________________________________________________
$MirOS: contrib/hosted/tg/code/BSD::arc4random/README,v 1.6 2011/06/05 23:19:03 tg Exp $