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>