File Coverage

blib/lib/Crypt/Random/TESHA2.pm

Criterion	Covered	Total	%
statement	75	77	97.4
branch	11	20	55.0
condition	4	8	50.0
subroutine	15	15	100.0
pod	5	5	100.0
total	110	125	88.0

package Crypt::Random::TESHA2;
use strict;
use warnings;
use Carp qw/croak confess carp/;
use Time::HiRes qw/gettimeofday usleep/;
use Digest::SHA qw/sha256 sha512/;
use Crypt::Random::TESHA2::Config;

BEGIN {
  $Crypt::Random::TESHA2::AUTHORITY = 'cpan:DANAJ';
  $Crypt::Random::TESHA2::VERSION = '0.01';
}

use base qw( Exporter );
our @EXPORT_OK = qw( random_bytes random_values irand rand is_strong );
our %EXPORT_TAGS = (all => [ @EXPORT_OK ]);
our @EXPORT = qw( );  # nothing by default

my $_opt_need_strong = 0;
my $_opt_weak_ok     = 0;

my $_entropy_per_raw_byte = Crypt::Random::TESHA2::Config::entropy();
# Protect against possible abuse / misconfiguration
$_entropy_per_raw_byte = 1 if $_entropy_per_raw_byte < 1;
$_entropy_per_raw_byte = 7 if $_entropy_per_raw_byte > 7;
my $_hashalg = \&sha512;
my $_pool_size = 512;
my $_nehi = 0;            # A 64-bit counter
my $_nelo = 0;
my $_pool;
my $_C;                   # bits of entropy that we think are in the pool

# Make sure SHA512 is supported, back off to 256 if not.
if (!defined sha512("test")) {
  $_pool_size = 256;
  $_hashalg = \&sha256;
}

sub import {
  my @options;

  @options = grep { $_ !~ /^[-:]?weak$/i } @_;
  $_opt_weak_ok = 1 if @options != @_;
  @_ = @options;

  @options = grep { $_ !~ /^[-:]?strong$/i } @_;
  $_opt_need_strong = 1 if @options != @_;
  @_ = @options;

  croak "TESHA2 is not a strong randomness source on this platform"
    if $_opt_need_strong && !is_strong();

  goto &Exporter::import;
}

# Returns 1 if our installtion-time entropy measurements indicated we could
# get enough entropy to make this method work on this platform.
sub is_strong {
  return ($_entropy_per_raw_byte > 1.0) ? 1 : 0;
}

# Return $n random 32-bit values
sub random_values {
  return map { unpack("L", random_bytes(4)) } 1 .. shift;
}
# Note, only 32 bits.
# TODO: Figure out a portable non-64-bit way to make 52-bit doubles.
sub rand {
  return ($_[0]||1) * (unpack("L", random_bytes(4))/4294967296.0);
}
sub irand {
  return unpack("L", random_bytes(4));
}

# This uses an entropy pool (see Encyclopedia of Cryptography and Security,
# volume 2, "Entropy Sources").  We use SHA-512 to handle a 512-bit pool.
# One this this will do is ensure the input from any one byte is nicely
# spread out among the 64 bytes of the pool.

sub random_bytes {
  my $n = shift;
  return '' unless defined $n;
  if (!defined $_pool) {
    # Initialize pool with 64 bits of entropy.
    $_C = 64;
    # Get some extra bytes at the start.
    my $nbytes = 4 + int($_C/$_entropy_per_raw_byte) + 1;
    my $S = join("", map { _get_random_byte() } 1 .. $nbytes);
    $_pool = $_hashalg->($S);

    carp "TESHA2 is not a strong randomness source on this platform"
      if !$_opt_weak_ok && !is_strong();
  }
  my $X = '';
  while (length($X) < $n) {
    my $K = 8 * $n;
    $K = $_pool_size if $K > $_pool_size;
    # Add more entropy to pool if needed.
    while ($_C < $K) {
      my $nbytes = int( ($K - $_C) / $_entropy_per_raw_byte ) + 1;
      #warn "want $K bits, pool has $_C bits.  Adding $nbytes bytes\n";
      my $S = join("", map { _get_random_byte() } 1 .. $nbytes);
      $_pool = $_hashalg->($_pool . $S);
      $_C += $_entropy_per_raw_byte * $nbytes;
      $_C = $_pool_size if $_C > $_pool_size;
    }
    # Extract K bits from the pool.
    $_C -= $K;
    my $V = $_hashalg->( 'te' . pack("LL", $_nehi, $_nelo) . $_pool );
    if ($_nelo < 4294967295) { $_nelo++; } else { $_nehi++; $_nelo = 0; }
    $X .= substr($V, 0, int($K/8));
  }
  return $X;
}

# The heart of the system, where we gather entropy from timer jitter
# (technically this is scheduler jitter).  This is a similar idea to
# timer_entropyd, TrueRand, or the old Math::TrulyRandom module.
#
# *) Cryptographically, there are numerous issues here.  This is, at best,
#    one source to feed to a well designed entropy pool system.
#
# *) The output of this function passes ENT and TestU01 Rabbit on all systems
#    I've run it on.  timer_entropyd does not, even when von Neumann debiased.
#    However, even a counter run through SHA256 will pass these tests, which
#    just indicates the stream data is uncorrelated.
#
# *) The entropy tests mentioned above are only one part.  If a system
#    returned the same sequence every time, it may pass all the tests but
#    still be a horrible generator.  That's especially not what one wants
#    from this module.
#
# *) I discovered Matt Blaze's truerand after I wrote this -- no ideas or
#    code were used.  However, I got the idea from timer_entropyd, which
#    probably in turn got the idea from truerand.  Version 2.1 (1996) of
#    Matt Blaze's truerand is _far_ more conservative than the old design
#    in Math::TrulyRandom.  First he replaces the old-school byte mixing
#    with a SHA (very similar to my solution here).  Next, he does another
#    mixing to generate the actual bytes, while the old code would use the
#    raw results.  I use a different method above, but the end result is
#    somewhat similar -- we take these raw results and stir them further.
#
# *) My tests using the raw timer data are showing 1.5 - 4 bits per xor.
#    The truerand 2.1 documentation indicates 0.67 to 1.33 bits per call,
#    then conservatively halves the number.
#
# *) Expanding on the above, assume the worst and absolutely no entropy is
#    gathered.  Then each byte will be a sha256 related to the current hires
#    time, where each byte is mixed in the pool.  We get a fine PRNG, just
#    not seeded well (from a crypto point of view, this is awful).
#
# *) For each bit, the two microsecond values are xor'd and packed into
#    32-bit words.  Eight of these are concatenated and a SHA-256 hash is
#    performed.  As long as the sum of entropy gathered from all eight xors
#    is at least 8, we're good.  The sha256 takes care of shuffling bits so
#    there aren't biases.  This generates a much better result than using
#    boolean differences like timer_entropyd (even if the differences are
#    sent through von Neumann debiasing).
#
sub _get_random_byte {
  my ($start, $t1, $t2) = gettimeofday();
  # This basically gives us a counter, so every call is unique.  We can
  # assume it adds no entropy.
  my $str = pack("LL", $start, $t1);
  # A hash we will use for a little bit of CPU processing inside the loop.
  my %dummy;
  foreach my $bit (1 .. 8) {
    # Sleep some period of time.  Differ the times so we don't hit a
    # particular beat of the scheduler.
    usleep(2+3*$bit);
    (undef, $t2) = gettimeofday();
    # xor the two.  The entropy is in the variation between what we got
    # (t2 - t1) and what we expected (2+3*bit + c).
    $str .= pack("L", $t1 ^ $t2);
    # A little hash processing to further perturb the times.
    $dummy{$str . $_}++ for 1..8;
    $t1 = $t2;
  }
  # To truly return a byte:  return substr( sha256($str), 0, 1 );
  # Return the entire string -- let the pool figure it out.
  return sha256($str);
}

1;

__END__