KevinSchoenmayer/GseTDDUebungKCLR
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial Commit

Browse Source
This commit is contained in:
Riley Schneider
2025-12-03 16:38:10 +01:00
parent c5e26bf594
commit b732d8d4b5
17680 changed files with 5977495 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

704
database/perl/vendor/lib/Crypt/Random/Seed.pm vendored Normal file
View File

@@ -0,0 +1,704 @@
package Crypt::Random::Seed;
use strict;
use warnings;
use Fcntl;
use Carp qw/carp croak/;
# cert insists on using constant, but regular critic doesn't like it.
## no critic (constant)
BEGIN {
$Crypt::Random::Seed::AUTHORITY = 'cpan:DANAJ';
$Crypt::Random::Seed::VERSION = '0.03';
}
use base qw( Exporter );
our @EXPORT_OK = qw( );
our %EXPORT_TAGS = (all => [ @EXPORT_OK ]);
# Export nothing by default
use constant UINT32_SIZE => 4;
# These are the pre-defined names. We don't let user methods use these.
my %defined_methods = map { $_ => 1 }
(qw(CryptGenRandom RtlGenRand EGD /dev/random /dev/urandom
TESHA2-strong TESHA2-weak));
# If given one of these names as whitelist/blacklist, we add these also.
my %name_aliases = (
'Win32' => [qw(RtlGenRand CryptGenRandom)],
'TESHA2' => [qw(TESHA2-strong TESHA2-weak)],
);
sub new {
my ($class, %params) = @_;
my $self = {};
# Trying to handle strong vs. weak is fraught with complication, so just
# remove the idea entirely.
if (defined $params{Weak}) {
# In this release, just silently don't use it.
delete $params{Weak};
}
if (defined $params{Source}) {
if (ref($params{Source}) eq 'CODE') {
$self->{Name} = 'User';
$self->{SourceSub} = $params{Source};
# We don't know if it is blocking or strong, assume neither
$self->{Blocking} = 0;
$self->{Strong} = 0;
} elsif (ref($params{Source}) eq 'ARRAY') {
($self->{Name}, $self->{SourceSub}, $self->{Blocking}, $self->{Strong})
= @{$params{Source}};
# For sanity, don't let them redefine the standard names.
croak "Invalid name: $self->{Name}. Name reserved."
if defined $defined_methods{$self->{Name}};
} else {
croak "Invalid 'Source'. Should be code or array reference.";
}
} else {
# This is a sorted list -- the first one that returns true gets used.
my @methodlist = (
\&_try_win32,
\&_try_egd,
\&_try_dev_random,
\&_try_dev_urandom,
\&_try_tesha2,
);
my %whitelist;
my $have_whitelist = 0;
if (defined $params{Only}) {
croak "Parameter 'Only' must be an array ref" unless ref($params{Only}) eq 'ARRAY';
$have_whitelist = 1;
$whitelist{$_} = 1 for @{$params{Only}};
while ( my($name, $list) = each %name_aliases) {
@whitelist{@$list} = (1) x scalar @$list if $whitelist{$name};
}
}
my %blacklist;
if (defined $params{Never}) {
croak "Parameter 'Never' must be an array ref" unless ref($params{Never}) eq 'ARRAY';
$blacklist{$_} = 1 for @{$params{Never}};
while ( my($name, $list) = each %name_aliases) {
@blacklist{@$list} = (1) x scalar @$list if $blacklist{$name};
}
}
foreach my $m (@methodlist) {
my ($name, $rsub, $isblocking, $isstrong) = $m->();
next unless defined $name;
next if $isblocking && ($params{NonBlocking} || $params{Nonblocking} || $params{nonblocking});
#next if !$isstrong && !$params{Weak};
next if $blacklist{$name};
next if $have_whitelist && !$whitelist{$name};
$self->{Name} = $name;
$self->{SourceSub} = $rsub;
$self->{Blocking} = $isblocking;
$self->{Strong} = $isstrong;
last;
}
}
# Couldn't find anything appropriate
return unless defined $self->{SourceSub};
bless $self, $class;
return $self;
}
# Nothing special to do on destroy
#sub DESTROY {
# my $self = shift;
# delete $self->{$_} for keys $self;
# return;
#}
sub name {
my $self = shift;
return $self->{Name};
}
sub is_blocking {
my $self = shift;
return $self->{Blocking};
}
sub is_strong {
my $self = shift;
return $self->{Strong};
}
sub random_bytes {
my ($self, $nbytes) = @_;
return '' unless defined $nbytes && int($nbytes) > 0;
my $rsub = $self->{SourceSub};
return unless defined $rsub;
return $rsub->(int($nbytes));
}
sub random_values {
my ($self, $nvalues) = @_;
return unless defined $nvalues && int($nvalues) > 0;
my $rsub = $self->{SourceSub};
return unless defined $rsub;
return unpack( 'L*', $rsub->(UINT32_SIZE * int($nvalues)) );
}
sub _try_tesha2 {
eval { require Crypt::Random::TESHA2; Crypt::Random::TESHA2->import(); 1; }
or return;
my $isstrong = Crypt::Random::TESHA2::is_strong();
my $name = join('-', 'TESHA2', ($isstrong) ? 'strong' : 'weak');
return ($name, \&Crypt::Random::TESHA2::random_bytes, 0, 1);
}
sub _try_dev_urandom {
return unless -r "/dev/urandom";
return ('/dev/urandom', sub { __read_file('/dev/urandom', @_); }, 0, 0);
}
sub _try_dev_random {
return unless -r "/dev/random";
# FreeBSD's /dev/random is 256-bit Yarrow non-blocking.
# Is it 'strong'? Debatable -- we'll say it is.
my $blocking = ($^O eq 'freebsd') ? 0 : 1;
return ('/dev/random', sub { __read_file('/dev/random', @_); }, $blocking, 1);
}
sub __read_file {
my ($file, $nbytes) = @_;
return unless defined $nbytes && $nbytes > 0;
sysopen(my $fh, $file, O_RDONLY);
binmode $fh;
my($s, $buffer, $nread) = ('', '', 0);
while ($nread < $nbytes) {
my $thisread = sysread $fh, $buffer, $nbytes-$nread;
# Count EOF as an error.
croak "Error reading $file: $!\n" unless defined $thisread && $thisread > 0;
$s .= $buffer;
$nread += length($buffer);
#die unless $nread == length($s); # assert
}
croak "Internal file read error: wanted $nbytes, read $nread"
unless $nbytes == length($s); # assert
return $s;
}
# Most of this is taken without notice from Crypt::URandom 0.28 and
# Crypt::Random::Source::Strong::Win32 0.07.
# Kudos to David Dick and Max Kanat-Alexander for doing all the work.
#
# See some documentation here:
# http://msdn.microsoft.com/en-us/library/aa379942.aspx
# where they note that the output of these is really a well seeded CSPRNG:
# either FIPS 186-2 (older) or AES-CTR (Vista SP1 and newer).
sub _try_win32 {
return unless $^O eq 'MSWin32';
# Cygwin has /dev/random at least as far back as 2000.
eval { require Win32; require Win32::API; require Win32::API::Type; 1; }
or return;
use constant CRYPT_SILENT => 0x40; # Never display a UI.
use constant PROV_RSA_FULL => 1; # Which service provider.
use constant VERIFY_CONTEXT => 0xF0000000; # Don't need existing keypairs.
use constant W2K_MAJOR_VERSION => 5; # Windows 2000
use constant W2K_MINOR_VERSION => 0;
my ($major, $minor) = (Win32::GetOSVersion())[1, 2];
return if $major < W2K_MAJOR_VERSION;
if ($major == W2K_MAJOR_VERSION && $minor == W2K_MINOR_VERSION) {
# We are Windows 2000. Use the older CryptGenRandom interface.
my $crypt_acquire_context_a =
Win32::API->new( 'advapi32', 'CryptAcquireContextA', 'PPPNN',
'I' );
return unless defined $crypt_acquire_context_a;
my $context = chr(0) x Win32::API::Type->sizeof('PULONG');
my $result = $crypt_acquire_context_a->Call(
$context, 0, 0, PROV_RSA_FULL, CRYPT_SILENT | VERIFY_CONTEXT );
return unless $result;
my $pack_type = Win32::API::Type::packing('PULONG');
$context = unpack $pack_type, $context;
my $crypt_gen_random =
Win32::API->new( 'advapi32', 'CryptGenRandom', 'NNP', 'I' );
return unless defined $crypt_gen_random;
return ('CryptGenRandom',
sub {
my $nbytes = shift;
my $buffer = chr(0) x $nbytes;
my $result = $crypt_gen_random->Call($context, $nbytes, $buffer);
croak "CryptGenRandom failed: $^E" unless $result;
return $buffer;
},
0, 1); # Assume non-blocking and strong
} else {
my $rtlgenrand = Win32::API->new( 'advapi32', <<'_RTLGENRANDOM_PROTO_');
INT SystemFunction036(
PVOID RandomBuffer,
ULONG RandomBufferLength
)
_RTLGENRANDOM_PROTO_
return unless defined $rtlgenrand;
return ('RtlGenRand',
sub {
my $nbytes = shift;
my $buffer = chr(0) x $nbytes;
my $result = $rtlgenrand->Call($buffer, $nbytes);
croak "RtlGenRand failed: $^E" unless $result;
return $buffer;
},
0, 1); # Assume non-blocking and strong
}
return;
}
sub _try_egd {
# For locations, we'll look in the files OpenSSL's RAND_egd looks, as well
# as /etc/entropy which egd 0.9 recommends. This also works with PRNGD.
# PRNGD uses a seed+CSPRNG so is non-blocking, but we can't tell them apart.
foreach my $device (qw( /var/run/egd-pool /dev/egd-pool /etc/egd-pool /etc/entropy )) {
next unless -r $device && -S $device;
eval { require IO::Socket; 1; } or return;
# We're looking for a socket that returns the entropy available when given
# that command. Set timeout to 1 to prevent hanging -- if it is a socket
# but won't return the available entropy in under a second, move on.
my $socket = IO::Socket::UNIX->new(Peer => $device, Timeout => 1);
next unless $socket;
$socket->syswrite( pack("C", 0x00), 1) or next;
die if $socket->error;
my($entropy_string, $nread);
# Sadly this doesn't honor the timeout. We'll have to do an eval / alarm.
# We only timeout here if this is a live socket to a sleeping process.
eval {
local $SIG{ALRM} = sub { die "alarm\n" };
alarm 1;
$nread = $socket->sysread($entropy_string, 4);
alarm 0;
};
if ($@) {
die unless $@ eq "alarm\n";
next;
}
next unless defined $nread && $nread == 4;
my $entropy_avail = unpack("N", $entropy_string);
return ('EGD', sub { __read_egd($device, @_); }, 1, 1);
}
return;
}
sub __read_egd {
my ($device, $nbytes) = @_;
return unless defined $device;
return unless defined $nbytes && int($nbytes) > 0;
croak "$device doesn't exist!" unless -r $device && -S $device;
my $socket = IO::Socket::UNIX->new(Peer => $device);
croak "Can't talk to EGD on $device. $!" unless $socket;
my($s, $buffer, $toread) = ('', '', $nbytes);
while ($toread > 0) {
my $this_request = ($toread > 255) ? 255 : $toread;
# Use the blocking interface.
$socket->syswrite( pack("CC", 0x02, $this_request), 2);
my $this_grant = $socket->sysread($buffer, $this_request);
croak "Error reading EDG data from $device: $!\n"
unless defined $this_grant && $this_grant == $this_request;
$s .= $buffer;
$toread -= length($buffer);
}
croak "Internal EGD read error: wanted $nbytes, read ", length($s), ""
unless $nbytes == length($s); # assert
return $s;
}
1;
__END__
# ABSTRACT: Simple method to get strong randomness
=pod
=head1 NAME
Crypt::Random::Seed - Simple method to get strong randomness
=head1 VERSION
Version 0.03
=head1 SYNOPSIS
use Crypt::Random::Seed;
my $source = new Crypt::Random::Seed;
die "No strong sources exist" unless defined $source;
my $seed_string = $source->random_bytes(4);
my @seed_values = $source->random_values(4);
# Only non-blocking sources
my $nonblocking_source = Crypt::Random::Seed->new( NonBlocking=>1 );
# Blacklist sources (never choose the listed sources)
my $nowin32_source = Crypt::Random::Seed->new( Never=>['Win32'] );
# Whitelist sources (only choose from these sources)
my $devr_source = Crypt::Random::Seed->new( Only=>['TESHA2'] );
# Supply a custom source.
my $user_src = Crypt::Random::Seed->new( Source=>sub { myfunc(shift) } );
# Or supply a list of [name, sub, is_blocking, is_strong]
$user_src = Crypt::Random::Seed->new(
Source=>['MyRandomFunction',sub {myfunc(shift)},0,1] );
# Given a source there are a few things we can do:
say "My randomness source is ", $source->name();
say "I am a blocking source" if $source->is_blocking();
say "I am a strong randomness source" if $source->is_strong()
say "Four 8-bit numbers:",
join(",", map { ord $source->random_bytes(1) } 1..4);'
say "Four 32-bit numbers:", join(",", $source->random_values(4));
=head1 DESCRIPTION
A simple mechanism to get strong randomness. The main purpose of this
module is to provide a simple way to generate a seed for a PRNG such as
L<Math::Random::ISAAC>, for use in cryptographic key generation, or as the
seed for an upstream module such as L<Bytes::Random::Secure>. Flags for
requiring non-blocking sources are allowed, as well as a very simple
method for plugging in a source.
The randomness sources used are, in order:
=over 4
=item User supplied.
If the constructor is called with a Source defined, then it is used. It
is not checked vs. other flags (NonBlocking, Never, Only).
=item Win32 Crypto API.
This will use C<CryptGenRandom> on Windows 2000 and C<RtlGenRand> on
Windows XP and newer. According to MSDN, these are well-seeded CSPRNGs
(FIPS 186-2 or AES-CTR), so will be non-blocking.
=item EGD / PRNGD.
This looks for sockets that speak the L<EGD|http://egd.sourceforge.net/>
protocol, including L<PRNGD|http://prngd.sourceforge.net/>. These are
userspace entropy daemons that are commonly used by OpenSSL, OpenSSH, and
GnuGP. The locations searched are C</var/run/egd-pool>, C</dev/egd-pool>,
C</etc/egd-pool>, and C</etc/entropy>. EGD is blocking, while PRNGD is
non-blocking (like the Win32 API, it is really a seeded CSPRNG). However
there is no way to tell them apart, so we treat it as blocking. If your
O/S supports /dev/random, consider L<HAVEGED|http://www.issihosts.com/haveged/>
as an alternative (a system daemon that refills /dev/random as needed).
=item /dev/random.
The strong source of randomness on most UNIX-like systems. Cygwin uses
this, though it maps to the Win32 API. On almost all systems this is a
blocking source of randomness -- if it runs out of estimated entropy, it
will hang until more has come into the system. If this is an issue,
which it often is on embedded devices, running a tool such as
L<HAVEGED|http://www.issihosts.com/haveged/> will help immensely.
=item /dev/urandom.
A nonblocking source of randomness that we label as weak, since it will
continue providing output even if the actual entropy has been exhausted.
=item TESHA2.
L<Crypt::Random::TESHA2> is a Perl module that generates random bytes from
an entropy pool fed with timer/scheduler variations. Measurements and
tests are performed on installation to determine whether the source is
considered strong or weak. This is entirely in portable userspace,
which is good for ease of use, but really requires user verification
that it is working as expected if we expect it to be strong. The
concept is similar to L<Math::TrulyRandom> though updated to something
closer to what TrueRand 2.1 does vs. the obsolete version 1 that
L<Math::TrulyRandom> implements. It is very slow and has wide speed
variability across platforms : I've seen numbers ranging from 40 to
150,000 bits per second.
=back
A source can also be supplied in the constructor. Each of these sources will
have its debatable points about perceived strength. E.g. Why is /dev/urandom
considered weak while Win32 is strong? Can any userspace method such as
TrueRand or TESHA2 be considered strong?
=head2 SOURCE TABLE
This table summarizes the default sources:
+------------------+-------------+------------+--------------------+
| SOURCE | STRENGTH | BLOCKING | NOTE |
|------------------+-------------+------------+--------------------|
| RtlGenRandom | Strong(1) | No | Default WinXP+ |
|------------------+-------------+------------+--------------------|
| CryptGenRandom | Strong(1) | No | Default Win2000 |
|------------------+-------------+------------+--------------------|
| EGD | Strong | Yes(2) | also PRNGD, etc. |
|------------------+-------------+------------+--------------------|
| /dev/random | Strong | Yes | Typical UNIX |
|------------------+-------------+------------+--------------------|
| /dev/urandom | Weak | No | Typical UNIX NB |
|------------------+-------------+------------+--------------------|
| TESHA2-strong | Strong | No | |
|------------------+-------------+------------+--------------------|
| TESHA2-weak | Weak | No | |
+------------------+-------------+------------+--------------------+
The alias 'Win32' can be used in whitelist and blacklist and will match both
the Win32 sources C<RtlGenRandom> and C<CryptGenRandom>. The alias 'TESHA2'
may be similarly used and matches both the weak and strong sources.
1) Both CryptGenRandom and RtlGenRandom are considered strong by this
package, even though both are seeded CSPRNGs so should be the equal of
/dev/urandom in this respect. The CryptGenRandom function used in
Windows 2000 has some known issues so should be considered weaker.
2) EGD is blocking, PRNGD is not. We cannot tell the two apart. There are
other software products that use the same protocol, and each will act
differently. E.g. EGD mixes in system entropy on every request, while
PRNGD mixes on a time schedule.
=head2 STRENGTH
In theory, a strong generator will provide true entropy. Even if a third
party knew a previous result and the entire state of the generator at any
time up to when their value was returned, they could still not effectively
predict the result of the next returned value. This implies the generator
must either be blocking to wait for entropy (e.g. /dev/random) or go through
some possibly time-consuming process to gather it (TESHA2, EGD, the HAVEGE
daemon refilling /dev/random). Note: strong in this context means practically
strong, as most computers don't have a true hardware entropy generator. The
goal is to make all the attackers ill-gotten knowledge give them no better
solution than if they did not have the information.
Creating a satisfactory strength measurement is problematic. The Win32
Crypto API is considered "strong" by most customers and every other Perl
module, however it is a well seeded CSPRNG according to the MSDN docs,
so is not a strong source based on the definition in the previous paragraph.
Similarly, almost all sources consider /dev/urandom to be weak, as once it
runs out of entropy it returns a deterministic function based on its state
(albeit one that cannot be run either direction from a returned result if the
internal state is not known).
Because of this confusion, I have removed the C<Weak> configuration option
that was present in version 0.01. It will now be ignored. You should be
able to use a combination of whitelist, blacklist, and the source's
C<is_strong> return value to decide if this meets your needs. On Win32, you
really only have a choice of Win32 and TESHA2. The former is going to be
what most people want, and can be chosen even with non-blocking set. On most
UNIX systems, C</dev/random> will be chosen for blocking and C</dev/urandom>
for non-blocking, which is what should be done in most cases.
=head2 BLOCKING
EGD and /dev/random are blocking sources. This means that if they run out of
estimated entropy, they will pause until they've collected more. This means
your program also pauses. On typical workstations this may be a few seconds
or even minutes. On an isolated network server this may cause a delay of
hours or days. EGD is proactive about gathering more entropy as fast as it
can. Running a tool such as the HAVEGE daemon or timer_entropyd can make
/dev/random act like a non-blocking source, as the entropy daemon will wake
up and refill the pool almost instantly.
Win32, PRNGD, and /dev/urandom are fast nonblocking sources. When they run
out of entropy, they use a CSPRNG to keep supplying data at high speed.
However this means that there is no additional entropy being supplied.
TESHA2 is nonblocking, but can be very slow. /dev/random can be faster if run
on a machine with lots of activity. On an isolated server, TESHA2 may be
much faster. Also note that the blocking sources such as EGD and /dev/random
both try to maintain reasonably large entropy pools, so small requests can be
supplied without blocking.
=head2 IN PRACTICE
Use the default to get the best source known. If you know more about the
sources available, you can use a whitelist, blacklist, or a custom source.
In general, to get the best source (typically Win32 or /dev/random):
my $source = Crypt::Random::Seed->new();
To get a good non-blocking source (Win32 or /dev/urandom):
my $source = Crypt::Random::Seed->new(NonBlocking => 1);
=head1 METHODS
=head2 new
The constructor with no arguments will find the first available source in its
fixed list and return an object that performs the defined methods. If no
sources could be found (quite unusual) then the returned value will be undef.
Optional parameters are passed in as a hash and may be mixed.
=head3 NonBlocking => I<boolean>
Only non-blocking sources will be allowed. In practice this means EGD
and /dev/random will not be chosen (except on FreeBSD where it is
non-blocking).
=head3 Only => [I<list of strings>]
Takes an array reference containing one or more string source names. No
source whose name does not match one of these strings will be chosen. The
string 'Win32' will match either of the Win32 sources, and 'TESHA2' will match
both the strong and weak versions.
=head3 Never => [I<list of strings>]
Takes an array reference containing one or more string source names. No
source whose name matches one of these strings will be chosen. The string
'Win32' will match either of the Win32 sources, and 'TESHA2' will match both
the strong and weak versions.
=head3 Source => sub { I<...> }
Uses the given anonymous subroutine as the generator. The subroutine will
be given an integer (the argument to C<random_bytes>) and should return
random data in a string of the given length. For the purposes of the other
object methods, the returned object will have the name 'User', and be
considered non-blocking and non-strong.
=head3 Source => ['I<name>', sub { I<...> }, I<is_blocking>, I<is_strong>]
Similar to the simpler source routine, but also allows the other source
parameters to be defined. The name may not be one of the standard names
listed in the L</"name"> section.
=head2 random_bytes($n)
Takes an integer and returns a string of that size filled with random data.
Returns an empty string if the argument is not defined or is not more than
zero.
=head2 random_values($n)
Takes an integer and returns an array of that many random 32-bit values.
Returns an empty array if the argument is not defined or is not more than
zero.
=head2 name
Returns the text name of the random source. This will be one of:
C<User> for user defined,
C<CryptGenRandom> for Windows 2000 Crypto API,
C<RtlGenRand> for Windows XP and newer Crypto API,
C<EGD> for a known socket speaking the EGD protocol,
C</dev/random> for the UNIX-like strong randomness source,
C</dev/urandom> for the UNIX-like non-blocking randomness source,
C<TESHA2-strong> for the userspace entropy method when considered strong,
C<TESHA2-weak> for the userspace entropy method when considered weak.
Other methods may be supported in the future. User supplied sources may be
named anything other than one of the defined names.
=head2 is_strong
Returns 1 or 0 indicating whether the source is considered a strong source
of randomness. See the L</"STRENGTH"> section for more discussion of what
this means, and the L<source table|/"SOURCE TABLE"> for what we think of each
source.
=head2 is_blocking
Returns 1 or 0 indicating whether the source can block on read. Be aware
that even if a source doesn't block, it may be extremely slow.
=head1 AUTHORS
Dana Jacobsen E<lt>dana@acm.orgE<gt>
=head1 ACKNOWLEDGEMENTS
To the best of my knowledge, Max Kanat-Alexander was the original author of
the Perl code that uses the Win32 API. I used his code as a reference.
David Oswald gave me a lot of help with API discussions and code reviews.
=head1 SEE ALSO
The first question one may ask is "Why yet another module of this type?"
None of the modules on CPAN quite fit my needs, hence this. Some alternatives:
=head2 L<Crypt::Random::Source>
A comprehensive system using multiple plugins. It has a nice API, but
uses L<Any::Moose> which means you're loading up Moose or Mouse just to
read a few bytes from /dev/random. It also has a very long dependency chain,
with on the order of 40 modules being installed as prerequisites (depending
of course on whether you use any of them on other projects). Lastly, it
requires at least Perl 5.8, which may or may not matter to you. But it
matters to some other module builders who end up with the restriction in
their modules.
=head2 L<Crypt::URandom>
A great little module that is almost what I was looking for.
L<Crypt::Random::Seed> will act the same if given the constructor:
my $source = Crypt::Random::Seed->new(
NonBlocking => 1,
Only => [qw(/dev/random /dev/urandom Win32)]
);
croak "No randomness source available" unless defined $source;
Or you can leave out the C<Only> and have TESHA2 as a backup.
=head2 L<Crypt::Random>
Requires L<Math::Pari> which makes it unacceptable in some environments.
Has more features (numbers in arbitrary bigint intervals or bit sizes).
L<Crypt::Random::Seed> is taking a simpler approach, just handling returning
octets and letting upstream modules handle the rest.
=head2 L<Data::Entropy>
An interesting module that contains a source encapsulation (defaults to system
rand, but has many plugins), a good CSPRNG (AES in counter mode), and the
L<Data::Entropy::Algorithms> module with many ways to get bits, ints, bigints,
floats, bigfloats, shuffles, and so forth. From my perspective, the
algorithms module is the highlight, with a lot of interesting code.
=head2 Upstream modules
Some modules that could use this module to help them:
L<Bytes::Random::Secure>,
L<Math::Random::ISAAC>,
L<Math::Random::Secure>,
and L<Math::Random::MT>
to name a few.
=head1 COPYRIGHT
Copyright 2013 by Dana Jacobsen E<lt>dana@acm.orgE<gt>
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
The software is provided "AS IS", without warranty of any kind, express or
implied, including but not limited to the warranties of merchantability,
fitness for a particular purpose and noninfringement. In no event shall the
authors or copyright holders be liable for any claim, damages or other
liability, whether in an action of contract, tort or otherwise, arising from,
out of or in connection with the software or the use or other dealings in
the software.
=cut

416
database/perl/vendor/lib/Crypt/Random/TESHA2.pm vendored Normal file
View File

@@ -0,0 +1,416 @@
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__
# ABSTRACT: Random numbers using timer/schedule entropy
=pod
=head1 NAME
Crypt::Random::TESHA2 - Random numbers using timer/schedule entropy
=head1 VERSION
Version 0.01
=head1 WARNING
I<This module implements userspace voodoo entropy. You should use a proper
O/S supplied entropy source such as /dev/random or the Win32 Crypt API.>
=head1 SYNOPSIS
# Nothing exported by default
use Crypt::Random::TESHA2 qw(random_bytes random_values irand rand);
# Get 64 random bytes
my $seed_string = random_bytes(64);
# Get 16 random 32-bit values
my @seeds = random_values(16);
# Get a 32-bit random integer (value between 0 and 4294967295 inclusive)
my $i = irand();
# rand, like system rand, with 32 bits of randomness.
my $r1 = rand(); # floating point in range [0,1).
my $r2 = rand(1000); # floating point in range [0,1000).
# croak if installation determined we couldn't generate enough entropy
use Crypt::Random::TESHA2 ':strong';
# No warnings even if we are a weak source
use Crypt::Random::TESHA2 ':weak';
# Ask for yourself
die "No key for you!" unless Crypt::Random::TESHA2::is_strong();
=head1 DESCRIPTION
Generate random numbers using entropy gathered from timer / scheduler jitter.
This can be used to generate non-pseudorandom data to seed a PRNG (e.g.
C<srand>/C<rand>, L<Math::Random::MT>, etc.) or CSPRNG (e.g. AES-CTR or
L<Math::Random::ISAAC>). You may use it directly or as part of a random
source module that first checks for O/S randomness sources.
Only Perl CORE modules are used, making this very portable. However, systems
must have a high resolution timer and support C<usleep> from L<Time::HiRes>.
At installation time, measurements are taken of the estimated entropy gathered
by the timer differences. If the results indicated we could not get good
results, then the module will consider itself "weak". On the first use of
any of the functions that return randomness (e.g. random_bytes), the module
will carp about not being a strong randomness source. However, two special
options, ":strong" and ":weak" may be given to the importer to change this
behavior. If ":strong" is used, then the module will croak. If ":weak" is
used, then no carp will be generated. The function C<is_strong> can be used
at any time for finer control. Note that this should be an unusual case, and
neither flag has any effect if the module considers itself strong.
=head1 FUNCTIONS
=head2 random_bytes($n)
Takes an integer and returns a string of that size filled with random data.
=head2 random_values($n)
Takes an integer and returns an array containing that many random 32-bit
integers. The values will be in the range [0,4294967295] (all 32-bit values
are possible).
=head2 irand
Returns a single random 32-bit integer in the range [0,4294967295].
=head2 rand
Returns a random float greater than or equal to 0 and less than the value of
the argument. If no argument is given or the argument is zero, 1 is used.
This has an identical API as system rand, though of course there is no
associated srand function. The result has 32 bits of randomness.
=head2 is_strong
Returns 0 if the installation procedure determined that not enough entropy
could be gathered on this system. Returns 1 if it was able. If 0 is
returned, then the bytes returned may be no better than a CSPRNG using a
convoluted time-based reseed every bit.
=head1 METHOD
The underlying entropy gathering is done using timing differences between
usleep calls. We wrap usleep calls of varying intervals along with some
Perl hash processing inside microsecond timer calls. The two values are
xored. This is the raw entropy source. Eight of these, along with the
current time, are fed to a SHA-256 which can be added to an entropy pool.
Measurements of the raw timer entropy (just the timing differences -- no
hashes, time, counters, xors, or entropy pool) on systems I have available
indicate 1.5 to 4 bits of entropy per usleep. The installation procedure
does a measurement of the 0-order entropy gathered from the raw timing
process, halves it, limits to the range 1/8 - 7/8, and uses that as the
estimated entropy gathered.
The actual output random bytes are generated by an entropy pool that uses
SHA-512 or SHA-256. This adds data as needed from the above method, then
extracts bits as needed to make the output bytes (again using a cryptographic
hash and a counter, which means the entropy pool is not exposed).
The result will easily pass most stream randomness tests (e.g. FIPS-140, ENT,
TestU01 Rabbit), but that is a given based on the last entropy pool stage, so
this just shows we provide decorrelated output, not that we make a good seed.
=head1 LIMITATIONS
Note that pretty much every limitation of this module will apply to
L<Math::TrulyRandom>, which many non-cryptographers still think is
cryptographically secure (it's recommended in both the perl core documentation
as well as L<Math::Random::ISAAC>). If you think that module is great for
your application, then you should be happy with this one. Probably happier
since this is more portable, doesn't hang infinitely, runs much faster,
and generates better output on most systems.
As mentioned in the L<Warnings|/"WARNINGS"> section, this generates userspace
entropy -- what most people used until the waning years of the 20th century.
We should not have to do this on modern systems that have well designed APIs
to get randomness from multiple entropy pools, all managed by production code.
In other words, C</dev/random>.
Performance is slow (about 10,000 times slower than L<Math::Random::ISAAC::XS>),
making this something best to be used to seed a PRNG or CSPRNG, rather than
using directly. On newer Linux systems and Win32 it runs about 10,000 bits
per second. Cygwin runs about 1000 bits per second. Older systems will run
slower of course, such as an old HPPA system I use that runs at 40 bits/s.
Much of the time is spent sleeping.
Gathering entropy with this method depends on high resolution timers. If the
timers have low resolution, especially if we had a system with very fast
yield turnaround, then we would gather very little entropy. One of the tests
tries to determine this, but it isn't perfect. As with all such userspace
systems, you should check that it works before using it for anything critical.
L<RFC4086|http://www.ietf.org/rfc/rfc4086.txt> section 3.4 discusses a few of
the pitfalls of using portable clock-based software, and section 3.6 discusses
the desire for multiple entropy sources.
Because of the use of SHA-2 hashes along with an entropy pool using a counter,
the output stream will pass randomness tests (e.g. FIPS-140, ENT,
TestU01 Rabbit) even if there is I<no> underlying entropy. The installation
measurements should indicate whether this is happening, but it doesn't measure
everything.
=head1 AUTHORS
Dana Jacobsen E<lt>dana@acm.orgE<gt>
=head1 SEE ALSO
=over 4
=item Encyclopedia of Cryptography and Security, volume 2, "Entropy Sources".
The entropy pool implemented in this module follows this design.
=item HAVEGE (L<http://www.issihosts.com/haveged/>)
Uses multiple methods to gather entropy and feed it to the O/S, which
can measure it and add it to a pool. Highly recommended for embedded
or network devices that don't have good external interactions, or when
running programs that use a lot of entropy (e.g. anything that uses
L<Crypt::Random>).
=item timer_entropyd (L<http://www.vanheusden.com/te/>)
Uses a related method (jitter in timing data between usleeps) as this
module, but inefficient and only suitable for bulk feeding of an
entropy pool. Even after von Neumann debiasing, the output has distinct
patterns and at most 0.5 bits of entropy per output bit. HAVEGE is a
superior overall solution. However, note a number of other links at
the site for other sources as well as links to hardware RNGs.
=item L<Math::TrulyRandom>
An old module that uses an obsolete version of Matt Blaze's TrueRand.
TrueRand version 2.1 fixes a number of issues with the output quality
and specifically recommends against using the old method. In addition,
the Perl module will not properly run on most current platforms.
A pure Perl version is included in the examples directory of this
module, but it is still TrueRand version 1 and, like the old module,
will not run on Win32.
=item L<Crypt::Urandom>
A simple module that gets a good source of O/S non-blocking randomness.
=item L<Crypt::Random::Source>
A complicated module that has multiple plugins for randomness sources.
=back
=head1 COPYRIGHT
Copyright 2012-2013 by Dana Jacobsen E<lt>dana@acm.orgE<gt>
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
The software is provided "AS IS", without warranty of any kind, express or
implied, including but not limited to the warranties of merchantability,
fitness for a particular purpose and noninfringement. In no event shall the
authors or copyright holders be liable for any claim, damages or other
liability, whether in an action of contract, tort or otherwise, arising from,
out of or in connection with the software or the use or other dealings in
the software.
=cut

35
database/perl/vendor/lib/Crypt/Random/TESHA2/Config.pm vendored Normal file
View File

@@ -0,0 +1,35 @@
package Crypt::Random::TESHA2::Config;
use strict;
use warnings;
BEGIN {
$Crypt::Random::TESHA2::Config::AUTHORITY = 'cpan:DANAJ';
$Crypt::Random::TESHA2::Config::VERSION = '0.01';
}
# Don't just export the variable, because an evil script could change it.
# DO NOT MANUALLY ALTER THE FOLLOWING LINE: configured in Makefile.PL
# The value should be '1.00' in the distribution.
my $_entropy_per_byte = 7.00;
sub entropy { return $_entropy_per_byte; }
1;
__END__
=pod
=head1 NAME
Crypt::Random::TESHA2::Config - Configuration data
=head1 FUNCTIONS
=head2 entropy
Returns a number of bits per byte of raw entropy expected. This is used
internally.
=cut