1package Crypt::Random::Seed; 2use strict; 3use warnings; 4use Fcntl; 5use Carp qw/carp croak/; 6 7# cert insists on using constant, but regular critic doesn't like it. 8## no critic (constant) 9 10BEGIN { 11 $Crypt::Random::Seed::AUTHORITY = 'cpan:DANAJ'; 12 $Crypt::Random::Seed::VERSION = '0.03'; 13} 14 15use base qw( Exporter ); 16our @EXPORT_OK = qw( ); 17our %EXPORT_TAGS = (all => [ @EXPORT_OK ]); 18# Export nothing by default 19 20use constant UINT32_SIZE => 4; 21 22# These are the pre-defined names. We don't let user methods use these. 23my %defined_methods = map { $_ => 1 } 24 (qw(CryptGenRandom RtlGenRand EGD /dev/random /dev/urandom 25 TESHA2-strong TESHA2-weak)); 26# If given one of these names as whitelist/blacklist, we add these also. 27my %name_aliases = ( 28 'Win32' => [qw(RtlGenRand CryptGenRandom)], 29 'TESHA2' => [qw(TESHA2-strong TESHA2-weak)], 30); 31 32sub new { 33 my ($class, %params) = @_; 34 my $self = {}; 35 36 # Trying to handle strong vs. weak is fraught with complication, so just 37 # remove the idea entirely. 38 if (defined $params{Weak}) { 39 # In this release, just silently don't use it. 40 delete $params{Weak}; 41 } 42 43 if (defined $params{Source}) { 44 if (ref($params{Source}) eq 'CODE') { 45 $self->{Name} = 'User'; 46 $self->{SourceSub} = $params{Source}; 47 # We don't know if it is blocking or strong, assume neither 48 $self->{Blocking} = 0; 49 $self->{Strong} = 0; 50 } elsif (ref($params{Source}) eq 'ARRAY') { 51 ($self->{Name}, $self->{SourceSub}, $self->{Blocking}, $self->{Strong}) 52 = @{$params{Source}}; 53 # For sanity, don't let them redefine the standard names. 54 croak "Invalid name: $self->{Name}. Name reserved." 55 if defined $defined_methods{$self->{Name}}; 56 } else { 57 croak "Invalid 'Source'. Should be code or array reference."; 58 } 59 } else { 60 # This is a sorted list -- the first one that returns true gets used. 61 my @methodlist = ( 62 \&_try_win32, 63 \&_try_egd, 64 \&_try_dev_random, 65 \&_try_dev_urandom, 66 \&_try_tesha2, 67 ); 68 69 my %whitelist; 70 my $have_whitelist = 0; 71 if (defined $params{Only}) { 72 croak "Parameter 'Only' must be an array ref" unless ref($params{Only}) eq 'ARRAY'; 73 $have_whitelist = 1; 74 $whitelist{$_} = 1 for @{$params{Only}}; 75 while ( my($name, $list) = each %name_aliases) { 76 @whitelist{@$list} = (1) x scalar @$list if $whitelist{$name}; 77 } 78 } 79 my %blacklist; 80 if (defined $params{Never}) { 81 croak "Parameter 'Never' must be an array ref" unless ref($params{Never}) eq 'ARRAY'; 82 $blacklist{$_} = 1 for @{$params{Never}}; 83 while ( my($name, $list) = each %name_aliases) { 84 @blacklist{@$list} = (1) x scalar @$list if $blacklist{$name}; 85 } 86 } 87 88 foreach my $m (@methodlist) { 89 my ($name, $rsub, $isblocking, $isstrong) = $m->(); 90 next unless defined $name; 91 next if $isblocking && ($params{NonBlocking} || $params{Nonblocking} || $params{nonblocking}); 92 #next if !$isstrong && !$params{Weak}; 93 next if $blacklist{$name}; 94 next if $have_whitelist && !$whitelist{$name}; 95 $self->{Name} = $name; 96 $self->{SourceSub} = $rsub; 97 $self->{Blocking} = $isblocking; 98 $self->{Strong} = $isstrong; 99 last; 100 } 101 } 102 # Couldn't find anything appropriate 103 return unless defined $self->{SourceSub}; 104 105 bless $self, $class; 106 return $self; 107} 108 109# Nothing special to do on destroy 110#sub DESTROY { 111# my $self = shift; 112# delete $self->{$_} for keys $self; 113# return; 114#} 115 116sub name { 117 my $self = shift; 118 return $self->{Name}; 119} 120sub is_blocking { 121 my $self = shift; 122 return $self->{Blocking}; 123} 124sub is_strong { 125 my $self = shift; 126 return $self->{Strong}; 127} 128sub random_bytes { 129 my ($self, $nbytes) = @_; 130 return '' unless defined $nbytes && int($nbytes) > 0; 131 my $rsub = $self->{SourceSub}; 132 return unless defined $rsub; 133 return $rsub->(int($nbytes)); 134} 135sub random_values { 136 my ($self, $nvalues) = @_; 137 return unless defined $nvalues && int($nvalues) > 0; 138 my $rsub = $self->{SourceSub}; 139 return unless defined $rsub; 140 return unpack( 'L*', $rsub->(UINT32_SIZE * int($nvalues)) ); 141} 142 143 144sub _try_tesha2 { 145 eval { require Crypt::Random::TESHA2; Crypt::Random::TESHA2->import(); 1; } 146 or return; 147 my $isstrong = Crypt::Random::TESHA2::is_strong(); 148 my $name = join('-', 'TESHA2', ($isstrong) ? 'strong' : 'weak'); 149 return ($name, \&Crypt::Random::TESHA2::random_bytes, 0, 1); 150} 151 152sub _try_dev_urandom { 153 return unless -r "/dev/urandom"; 154 return ('/dev/urandom', sub { __read_file('/dev/urandom', @_); }, 0, 0); 155} 156 157sub _try_dev_random { 158 return unless -r "/dev/random"; 159 # FreeBSD's /dev/random is 256-bit Yarrow non-blocking. 160 # Is it 'strong'? Debatable -- we'll say it is. 161 my $blocking = ($^O eq 'freebsd') ? 0 : 1; 162 return ('/dev/random', sub { __read_file('/dev/random', @_); }, $blocking, 1); 163} 164 165sub __read_file { 166 my ($file, $nbytes) = @_; 167 return unless defined $nbytes && $nbytes > 0; 168 sysopen(my $fh, $file, O_RDONLY); 169 binmode $fh; 170 my($s, $buffer, $nread) = ('', '', 0); 171 while ($nread < $nbytes) { 172 my $thisread = sysread $fh, $buffer, $nbytes-$nread; 173 # Count EOF as an error. 174 croak "Error reading $file: $!\n" unless defined $thisread && $thisread > 0; 175 $s .= $buffer; 176 $nread += length($buffer); 177 #die unless $nread == length($s); # assert 178 } 179 croak "Internal file read error: wanted $nbytes, read $nread" 180 unless $nbytes == length($s); # assert 181 return $s; 182} 183 184# Most of this is taken without notice from Crypt::URandom 0.28 and 185# Crypt::Random::Source::Strong::Win32 0.07. 186# Kudos to David Dick and Max Kanat-Alexander for doing all the work. 187# 188# See some documentation here: 189# http://msdn.microsoft.com/en-us/library/aa379942.aspx 190# where they note that the output of these is really a well seeded CSPRNG: 191# either FIPS 186-2 (older) or AES-CTR (Vista SP1 and newer). 192 193sub _try_win32 { 194 return unless $^O eq 'MSWin32'; 195 # Cygwin has /dev/random at least as far back as 2000. 196 eval { require Win32; require Win32::API; require Win32::API::Type; 1; } 197 or return; 198 199 use constant CRYPT_SILENT => 0x40; # Never display a UI. 200 use constant PROV_RSA_FULL => 1; # Which service provider. 201 use constant VERIFY_CONTEXT => 0xF0000000; # Don't need existing keypairs. 202 use constant W2K_MAJOR_VERSION => 5; # Windows 2000 203 use constant W2K_MINOR_VERSION => 0; 204 205 my ($major, $minor) = (Win32::GetOSVersion())[1, 2]; 206 return if $major < W2K_MAJOR_VERSION; 207 208 if ($major == W2K_MAJOR_VERSION && $minor == W2K_MINOR_VERSION) { 209 # We are Windows 2000. Use the older CryptGenRandom interface. 210 my $crypt_acquire_context_a = 211 Win32::API->new( 'advapi32', 'CryptAcquireContextA', 'PPPNN', 212 'I' ); 213 return unless defined $crypt_acquire_context_a; 214 my $context = chr(0) x Win32::API::Type->sizeof('PULONG'); 215 my $result = $crypt_acquire_context_a->Call( 216 $context, 0, 0, PROV_RSA_FULL, CRYPT_SILENT | VERIFY_CONTEXT ); 217 return unless $result; 218 my $pack_type = Win32::API::Type::packing('PULONG'); 219 $context = unpack $pack_type, $context; 220 my $crypt_gen_random = 221 Win32::API->new( 'advapi32', 'CryptGenRandom', 'NNP', 'I' ); 222 return unless defined $crypt_gen_random; 223 return ('CryptGenRandom', 224 sub { 225 my $nbytes = shift; 226 my $buffer = chr(0) x $nbytes; 227 my $result = $crypt_gen_random->Call($context, $nbytes, $buffer); 228 croak "CryptGenRandom failed: $^E" unless $result; 229 return $buffer; 230 }, 231 0, 1); # Assume non-blocking and strong 232 } else { 233 my $rtlgenrand = Win32::API->new( 'advapi32', <<'_RTLGENRANDOM_PROTO_'); 234INT SystemFunction036( 235 PVOID RandomBuffer, 236 ULONG RandomBufferLength 237) 238_RTLGENRANDOM_PROTO_ 239 return unless defined $rtlgenrand; 240 return ('RtlGenRand', 241 sub { 242 my $nbytes = shift; 243 my $buffer = chr(0) x $nbytes; 244 my $result = $rtlgenrand->Call($buffer, $nbytes); 245 croak "RtlGenRand failed: $^E" unless $result; 246 return $buffer; 247 }, 248 0, 1); # Assume non-blocking and strong 249 } 250 return; 251} 252 253sub _try_egd { 254 # For locations, we'll look in the files OpenSSL's RAND_egd looks, as well 255 # as /etc/entropy which egd 0.9 recommends. This also works with PRNGD. 256 # PRNGD uses a seed+CSPRNG so is non-blocking, but we can't tell them apart. 257 foreach my $device (qw( /var/run/egd-pool /dev/egd-pool /etc/egd-pool /etc/entropy )) { 258 next unless -r $device && -S $device; 259 eval { require IO::Socket; 1; } or return; 260 # We're looking for a socket that returns the entropy available when given 261 # that command. Set timeout to 1 to prevent hanging -- if it is a socket 262 # but won't return the available entropy in under a second, move on. 263 my $socket = IO::Socket::UNIX->new(Peer => $device, Timeout => 1); 264 next unless $socket; 265 $socket->syswrite( pack("C", 0x00), 1) or next; 266 die if $socket->error; 267 my($entropy_string, $nread); 268 # Sadly this doesn't honor the timeout. We'll have to do an eval / alarm. 269 # We only timeout here if this is a live socket to a sleeping process. 270 eval { 271 local $SIG{ALRM} = sub { die "alarm\n" }; 272 alarm 1; 273 $nread = $socket->sysread($entropy_string, 4); 274 alarm 0; 275 }; 276 if ($@) { 277 die unless $@ eq "alarm\n"; 278 next; 279 } 280 next unless defined $nread && $nread == 4; 281 my $entropy_avail = unpack("N", $entropy_string); 282 return ('EGD', sub { __read_egd($device, @_); }, 1, 1); 283 } 284 return; 285} 286 287sub __read_egd { 288 my ($device, $nbytes) = @_; 289 return unless defined $device; 290 return unless defined $nbytes && int($nbytes) > 0; 291 croak "$device doesn't exist!" unless -r $device && -S $device; 292 my $socket = IO::Socket::UNIX->new(Peer => $device); 293 croak "Can't talk to EGD on $device. $!" unless $socket; 294 my($s, $buffer, $toread) = ('', '', $nbytes); 295 while ($toread > 0) { 296 my $this_request = ($toread > 255) ? 255 : $toread; 297 # Use the blocking interface. 298 $socket->syswrite( pack("CC", 0x02, $this_request), 2); 299 my $this_grant = $socket->sysread($buffer, $this_request); 300 croak "Error reading EDG data from $device: $!\n" 301 unless defined $this_grant && $this_grant == $this_request; 302 $s .= $buffer; 303 $toread -= length($buffer); 304 } 305 croak "Internal EGD read error: wanted $nbytes, read ", length($s), "" 306 unless $nbytes == length($s); # assert 307 return $s; 308} 309 3101; 311 312__END__ 313 314# ABSTRACT: Simple method to get strong randomness 315 316=pod 317 318=head1 NAME 319 320Crypt::Random::Seed - Simple method to get strong randomness 321 322 323=head1 VERSION 324 325Version 0.03 326 327 328=head1 SYNOPSIS 329 330 use Crypt::Random::Seed; 331 332 my $source = new Crypt::Random::Seed; 333 die "No strong sources exist" unless defined $source; 334 my $seed_string = $source->random_bytes(4); 335 my @seed_values = $source->random_values(4); 336 337 # Only non-blocking sources 338 my $nonblocking_source = Crypt::Random::Seed->new( NonBlocking=>1 ); 339 340 # Blacklist sources (never choose the listed sources) 341 my $nowin32_source = Crypt::Random::Seed->new( Never=>['Win32'] ); 342 343 # Whitelist sources (only choose from these sources) 344 my $devr_source = Crypt::Random::Seed->new( Only=>['TESHA2'] ); 345 346 # Supply a custom source. 347 my $user_src = Crypt::Random::Seed->new( Source=>sub { myfunc(shift) } ); 348 # Or supply a list of [name, sub, is_blocking, is_strong] 349 $user_src = Crypt::Random::Seed->new( 350 Source=>['MyRandomFunction',sub {myfunc(shift)},0,1] ); 351 352 # Given a source there are a few things we can do: 353 say "My randomness source is ", $source->name(); 354 say "I am a blocking source" if $source->is_blocking(); 355 say "I am a strong randomness source" if $source->is_strong() 356 say "Four 8-bit numbers:", 357 join(",", map { ord $source->random_bytes(1) } 1..4);' 358 say "Four 32-bit numbers:", join(",", $source->random_values(4)); 359 360 361=head1 DESCRIPTION 362 363A simple mechanism to get strong randomness. The main purpose of this 364module is to provide a simple way to generate a seed for a PRNG such as 365L<Math::Random::ISAAC>, for use in cryptographic key generation, or as the 366seed for an upstream module such as L<Bytes::Random::Secure>. Flags for 367requiring non-blocking sources are allowed, as well as a very simple 368method for plugging in a source. 369 370The randomness sources used are, in order: 371 372=over 4 373 374=item User supplied. 375 376If the constructor is called with a Source defined, then it is used. It 377is not checked vs. other flags (NonBlocking, Never, Only). 378 379=item Win32 Crypto API. 380 381This will use C<CryptGenRandom> on Windows 2000 and C<RtlGenRand> on 382Windows XP and newer. According to MSDN, these are well-seeded CSPRNGs 383(FIPS 186-2 or AES-CTR), so will be non-blocking. 384 385=item EGD / PRNGD. 386 387This looks for sockets that speak the L<EGD|http://egd.sourceforge.net/> 388protocol, including L<PRNGD|http://prngd.sourceforge.net/>. These are 389userspace entropy daemons that are commonly used by OpenSSL, OpenSSH, and 390GnuGP. The locations searched are C</var/run/egd-pool>, C</dev/egd-pool>, 391C</etc/egd-pool>, and C</etc/entropy>. EGD is blocking, while PRNGD is 392non-blocking (like the Win32 API, it is really a seeded CSPRNG). However 393there is no way to tell them apart, so we treat it as blocking. If your 394O/S supports /dev/random, consider L<HAVEGED|http://www.issihosts.com/haveged/> 395as an alternative (a system daemon that refills /dev/random as needed). 396 397=item /dev/random. 398 399The strong source of randomness on most UNIX-like systems. Cygwin uses 400this, though it maps to the Win32 API. On almost all systems this is a 401blocking source of randomness -- if it runs out of estimated entropy, it 402will hang until more has come into the system. If this is an issue, 403which it often is on embedded devices, running a tool such as 404L<HAVEGED|http://www.issihosts.com/haveged/> will help immensely. 405 406=item /dev/urandom. 407 408A nonblocking source of randomness that we label as weak, since it will 409continue providing output even if the actual entropy has been exhausted. 410 411=item TESHA2. 412 413L<Crypt::Random::TESHA2> is a Perl module that generates random bytes from 414an entropy pool fed with timer/scheduler variations. Measurements and 415tests are performed on installation to determine whether the source is 416considered strong or weak. This is entirely in portable userspace, 417which is good for ease of use, but really requires user verification 418that it is working as expected if we expect it to be strong. The 419concept is similar to L<Math::TrulyRandom> though updated to something 420closer to what TrueRand 2.1 does vs. the obsolete version 1 that 421L<Math::TrulyRandom> implements. It is very slow and has wide speed 422variability across platforms : I've seen numbers ranging from 40 to 423150,000 bits per second. 424 425=back 426 427A source can also be supplied in the constructor. Each of these sources will 428have its debatable points about perceived strength. E.g. Why is /dev/urandom 429considered weak while Win32 is strong? Can any userspace method such as 430TrueRand or TESHA2 be considered strong? 431 432 433=head2 SOURCE TABLE 434 435This table summarizes the default sources: 436 437 +------------------+-------------+------------+--------------------+ 438 | SOURCE | STRENGTH | BLOCKING | NOTE | 439 |------------------+-------------+------------+--------------------| 440 | RtlGenRandom | Strong(1) | No | Default WinXP+ | 441 |------------------+-------------+------------+--------------------| 442 | CryptGenRandom | Strong(1) | No | Default Win2000 | 443 |------------------+-------------+------------+--------------------| 444 | EGD | Strong | Yes(2) | also PRNGD, etc. | 445 |------------------+-------------+------------+--------------------| 446 | /dev/random | Strong | Yes | Typical UNIX | 447 |------------------+-------------+------------+--------------------| 448 | /dev/urandom | Weak | No | Typical UNIX NB | 449 |------------------+-------------+------------+--------------------| 450 | TESHA2-strong | Strong | No | | 451 |------------------+-------------+------------+--------------------| 452 | TESHA2-weak | Weak | No | | 453 +------------------+-------------+------------+--------------------+ 454 455The alias 'Win32' can be used in whitelist and blacklist and will match both 456the Win32 sources C<RtlGenRandom> and C<CryptGenRandom>. The alias 'TESHA2' 457may be similarly used and matches both the weak and strong sources. 458 459 1) Both CryptGenRandom and RtlGenRandom are considered strong by this 460 package, even though both are seeded CSPRNGs so should be the equal of 461 /dev/urandom in this respect. The CryptGenRandom function used in 462 Windows 2000 has some known issues so should be considered weaker. 463 464 2) EGD is blocking, PRNGD is not. We cannot tell the two apart. There are 465 other software products that use the same protocol, and each will act 466 differently. E.g. EGD mixes in system entropy on every request, while 467 PRNGD mixes on a time schedule. 468 469 470=head2 STRENGTH 471 472In theory, a strong generator will provide true entropy. Even if a third 473party knew a previous result and the entire state of the generator at any 474time up to when their value was returned, they could still not effectively 475predict the result of the next returned value. This implies the generator 476must either be blocking to wait for entropy (e.g. /dev/random) or go through 477some possibly time-consuming process to gather it (TESHA2, EGD, the HAVEGE 478daemon refilling /dev/random). Note: strong in this context means practically 479strong, as most computers don't have a true hardware entropy generator. The 480goal is to make all the attackers ill-gotten knowledge give them no better 481solution than if they did not have the information. 482 483Creating a satisfactory strength measurement is problematic. The Win32 484Crypto API is considered "strong" by most customers and every other Perl 485module, however it is a well seeded CSPRNG according to the MSDN docs, 486so is not a strong source based on the definition in the previous paragraph. 487Similarly, almost all sources consider /dev/urandom to be weak, as once it 488runs out of entropy it returns a deterministic function based on its state 489(albeit one that cannot be run either direction from a returned result if the 490internal state is not known). 491 492Because of this confusion, I have removed the C<Weak> configuration option 493that was present in version 0.01. It will now be ignored. You should be 494able to use a combination of whitelist, blacklist, and the source's 495C<is_strong> return value to decide if this meets your needs. On Win32, you 496really only have a choice of Win32 and TESHA2. The former is going to be 497what most people want, and can be chosen even with non-blocking set. On most 498UNIX systems, C</dev/random> will be chosen for blocking and C</dev/urandom> 499for non-blocking, which is what should be done in most cases. 500 501 502=head2 BLOCKING 503 504EGD and /dev/random are blocking sources. This means that if they run out of 505estimated entropy, they will pause until they've collected more. This means 506your program also pauses. On typical workstations this may be a few seconds 507or even minutes. On an isolated network server this may cause a delay of 508hours or days. EGD is proactive about gathering more entropy as fast as it 509can. Running a tool such as the HAVEGE daemon or timer_entropyd can make 510/dev/random act like a non-blocking source, as the entropy daemon will wake 511up and refill the pool almost instantly. 512 513Win32, PRNGD, and /dev/urandom are fast nonblocking sources. When they run 514out of entropy, they use a CSPRNG to keep supplying data at high speed. 515However this means that there is no additional entropy being supplied. 516 517TESHA2 is nonblocking, but can be very slow. /dev/random can be faster if run 518on a machine with lots of activity. On an isolated server, TESHA2 may be 519much faster. Also note that the blocking sources such as EGD and /dev/random 520both try to maintain reasonably large entropy pools, so small requests can be 521supplied without blocking. 522 523 524=head2 IN PRACTICE 525 526Use the default to get the best source known. If you know more about the 527sources available, you can use a whitelist, blacklist, or a custom source. 528In general, to get the best source (typically Win32 or /dev/random): 529 530 my $source = Crypt::Random::Seed->new(); 531 532To get a good non-blocking source (Win32 or /dev/urandom): 533 534 my $source = Crypt::Random::Seed->new(NonBlocking => 1); 535 536 537=head1 METHODS 538 539=head2 new 540 541The constructor with no arguments will find the first available source in its 542fixed list and return an object that performs the defined methods. If no 543sources could be found (quite unusual) then the returned value will be undef. 544 545Optional parameters are passed in as a hash and may be mixed. 546 547=head3 NonBlocking => I<boolean> 548 549Only non-blocking sources will be allowed. In practice this means EGD 550and /dev/random will not be chosen (except on FreeBSD where it is 551non-blocking). 552 553=head3 Only => [I<list of strings>] 554 555Takes an array reference containing one or more string source names. No 556source whose name does not match one of these strings will be chosen. The 557string 'Win32' will match either of the Win32 sources, and 'TESHA2' will match 558both the strong and weak versions. 559 560=head3 Never => [I<list of strings>] 561 562Takes an array reference containing one or more string source names. No 563source whose name matches one of these strings will be chosen. The string 564'Win32' will match either of the Win32 sources, and 'TESHA2' will match both 565the strong and weak versions. 566 567=head3 Source => sub { I<...> } 568 569Uses the given anonymous subroutine as the generator. The subroutine will 570be given an integer (the argument to C<random_bytes>) and should return 571random data in a string of the given length. For the purposes of the other 572object methods, the returned object will have the name 'User', and be 573considered non-blocking and non-strong. 574 575=head3 Source => ['I<name>', sub { I<...> }, I<is_blocking>, I<is_strong>] 576 577Similar to the simpler source routine, but also allows the other source 578parameters to be defined. The name may not be one of the standard names 579listed in the L</"name"> section. 580 581 582=head2 random_bytes($n) 583 584Takes an integer and returns a string of that size filled with random data. 585Returns an empty string if the argument is not defined or is not more than 586zero. 587 588=head2 random_values($n) 589 590Takes an integer and returns an array of that many random 32-bit values. 591Returns an empty array if the argument is not defined or is not more than 592zero. 593 594=head2 name 595 596Returns the text name of the random source. This will be one of: 597C<User> for user defined, 598C<CryptGenRandom> for Windows 2000 Crypto API, 599C<RtlGenRand> for Windows XP and newer Crypto API, 600C<EGD> for a known socket speaking the EGD protocol, 601C</dev/random> for the UNIX-like strong randomness source, 602C</dev/urandom> for the UNIX-like non-blocking randomness source, 603C<TESHA2-strong> for the userspace entropy method when considered strong, 604C<TESHA2-weak> for the userspace entropy method when considered weak. 605Other methods may be supported in the future. User supplied sources may be 606named anything other than one of the defined names. 607 608=head2 is_strong 609 610Returns 1 or 0 indicating whether the source is considered a strong source 611of randomness. See the L</"STRENGTH"> section for more discussion of what 612this means, and the L<source table|/"SOURCE TABLE"> for what we think of each 613source. 614 615=head2 is_blocking 616 617Returns 1 or 0 indicating whether the source can block on read. Be aware 618that even if a source doesn't block, it may be extremely slow. 619 620 621=head1 AUTHORS 622 623Dana Jacobsen E<lt>dana@acm.orgE<gt> 624 625 626=head1 ACKNOWLEDGEMENTS 627 628To the best of my knowledge, Max Kanat-Alexander was the original author of 629the Perl code that uses the Win32 API. I used his code as a reference. 630 631David Oswald gave me a lot of help with API discussions and code reviews. 632 633 634=head1 SEE ALSO 635 636The first question one may ask is "Why yet another module of this type?" 637None of the modules on CPAN quite fit my needs, hence this. Some alternatives: 638 639=head2 L<Crypt::Random::Source> 640 641A comprehensive system using multiple plugins. It has a nice API, but 642uses L<Any::Moose> which means you're loading up Moose or Mouse just to 643read a few bytes from /dev/random. It also has a very long dependency chain, 644with on the order of 40 modules being installed as prerequisites (depending 645of course on whether you use any of them on other projects). Lastly, it 646requires at least Perl 5.8, which may or may not matter to you. But it 647matters to some other module builders who end up with the restriction in 648their modules. 649 650=head2 L<Crypt::URandom> 651 652A great little module that is almost what I was looking for. 653L<Crypt::Random::Seed> will act the same if given the constructor: 654 655 my $source = Crypt::Random::Seed->new( 656 NonBlocking => 1, 657 Only => [qw(/dev/random /dev/urandom Win32)] 658 ); 659 croak "No randomness source available" unless defined $source; 660 661Or you can leave out the C<Only> and have TESHA2 as a backup. 662 663=head2 L<Crypt::Random> 664 665Requires L<Math::Pari> which makes it unacceptable in some environments. 666Has more features (numbers in arbitrary bigint intervals or bit sizes). 667L<Crypt::Random::Seed> is taking a simpler approach, just handling returning 668octets and letting upstream modules handle the rest. 669 670=head2 L<Data::Entropy> 671 672An interesting module that contains a source encapsulation (defaults to system 673rand, but has many plugins), a good CSPRNG (AES in counter mode), and the 674L<Data::Entropy::Algorithms> module with many ways to get bits, ints, bigints, 675floats, bigfloats, shuffles, and so forth. From my perspective, the 676algorithms module is the highlight, with a lot of interesting code. 677 678 679=head2 Upstream modules 680 681Some modules that could use this module to help them: 682L<Bytes::Random::Secure>, 683L<Math::Random::ISAAC>, 684L<Math::Random::Secure>, 685and L<Math::Random::MT> 686to name a few. 687 688 689=head1 COPYRIGHT 690 691Copyright 2013 by Dana Jacobsen E<lt>dana@acm.orgE<gt> 692 693This program is free software; you can redistribute it and/or modify it 694under the same terms as Perl itself. 695 696The software is provided "AS IS", without warranty of any kind, express or 697implied, including but not limited to the warranties of merchantability, 698fitness for a particular purpose and noninfringement. In no event shall the 699authors or copyright holders be liable for any claim, damages or other 700liability, whether in an action of contract, tort or otherwise, arising from, 701out of or in connection with the software or the use or other dealings in 702the software. 703 704=cut 705