NAME

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

DEPENDENCIES

   This module needs the GMP C library - available from:
   http://gmplib.org

   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::GMP->new($s1);
   my $prime2    = Math::GMP->new($s2);
   my $seed      = Math::GMP->new(time + int(rand(10000)));
   my $bitstream = Math::GMP->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);

   # See the test script that ships with the Math::Random::BlumBlumShub
   # module source for other working demos (using both the Math::GMP and
   # Math::GMPz modules).

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.

   $bool = autocorrelation_20000($op, $offset);
    $op is a sequence (Math::GMPz/Math::GMP object) of 20000 + $offset bits.
    Returns true ("success") if the no. of bits in $op not equal to their
    $offset-leftshifts lies in the range [9655 .. 10345] (inclusive).
    Else returns 0 ("failure").

  ($count, $x5val) = autocorrelation($op, $offset);
    $op is a sequence (Math::GMPz/Math::GMP object) of 20000 bits.
    Returns (resp.) the no. of bits in $op not equal to their
    $offset-leftshifts, and the X5 value as specified in section 5.4.4
    of "Handbook of Applied Cryptography" (Menezes at al).

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.
   Copyright 2006-2008, 2009, 2010, 2014, Sisyphus

AUTHOR

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