NAME

Math::Random::BlumBlumShub - the Blum-Blum-Shub pseudorandom bit generator.

DEPENDENCIES

This module needs the GMP C library - available from:
http://swox.com/gmp

The functions in this module take either Math::GMP or Math::GMPz objects
as their arguments - so you'll need either Math::GMP or Math::GMPz as
well. (Actually, *any* perl scalar that's a reference to a GMP mpz
structure will suffice - it doesn't *have* to be a Math::GMP or
Math::GMPz object.)

DESCRIPTION

An implementation of the Blum-Blum-Shub pseudorandom bit generator.

SYNOPSIS

use warnings;
use Math::Random::BlumBlumShub qw(bbs bbs_seedgen);

use Math::GMP;
# and/or:
use Math::GMPz;
my $s1 = '615389388455725613122981570401989286707';
my $s2 = '8936277569639798554773638405675965349567';
my $prime1    = Math::GMPz->new($s1);
my $prime2    = Math::GMPz->new($s2);
my $seed      = Math::GMPz->new(time + int(rand(10000)));
my $bitstream = Math::GMPz->new();
my $bits_out  = 500;

# Generate the seed value
bbs_seedgen($seed, $prime1, $prime2);   

# Fill $bitstream with 500 random bits using $seed, $prime1 and $prime2
bbs($bitstream, $prime1, $prime2, $seed, $bits_out);

FUNCTIONS

bbs($o, $p, $q, $seed, $bits);
 "$o", "$p", "$q", and "$seed" are all Math::GMP or Math::GMPz objects.
 $p and $q must be large primes congruent to 3 modulus 4. (The bbs
 function checks $p and $q for congruence to 3 modulus 4, but does not 
 verify that $p and $q are, in fact, prime.)
 Output a $bits-bit random bitstream to $o - calculated using the 
 Blum-Blum-Shub algorithm, based on the inputs $p, $q, and $seed. See
 the bbs_seedgen documentation below for the requirements that $seed
 needs to meet.

bbs_seedgen($seed, $p, $q);
 "$seed", "$p", and "$q" are all Math::GMP or Math::GMPz objects.
 $p and $q are the 2 large primes being used by the BlumBlumShub PRBG.
 The seed needs to be less than N = $p * $q, and gcd(seed, N) must be 1.
 This routine uses the mpz_urandomm() function to pseudorandomly 
 generate a seed less than N. (The supplied value of $seed is used to
 seed mpz_urandomm.) If gcd(seed, N) != 1, then the seed is decremented
 until gcd(seed, N) == 1. $seed is then set to that seed value.
 You can, of course, write your own routine to create the seed.     

$bool = monobit($op);
$bool = longrun($op);
$bool = runs($op);
$bool = poker($op);

 These are the 4 standard FIPS-140 statistical tests for testing
 prbg's. They return '1' for success and '0' for failure.
 They test 20000-bit pseudorandom sequences, stored in the
 Math::GMPz/Math::GMP object $op.

BUGS

You can get segfaults if you pass the wrong type of argument to the
functions - so if you get a segfault, the first thing to do is to check
that the argument types you have supplied are appropriate.

LICENSE

This program is free software; you may redistribute it and/or 
modify it under the same terms as Perl itself.

AUTHOR

Copyright Sisyhpus <sisyphus at(@) cpan dot (.) org>