Ubuntu Manpage: Crypt::Random::Seed - Simple method to get strong randomness

Provided by: libcrypt-random-seed-perl_0.03-1_all

NAME

       Crypt::Random::Seed - Simple method to get strong randomness

VERSION

       Version 0.03

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));

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 Math::Random::ISAAC, for use in cryptographic key generation, or as
the seed for an upstream module such as 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:

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).

Win32 Crypto API.
This will use "CryptGenRandom" on Windows 2000 and "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.

EGD / PRNGD.
This looks for sockets that speak the EGD <http://egd.sourceforge.net/> protocol, including PRNGD
<http://prngd.sourceforge.net/>. These are userspace entropy daemons that are commonly used by
OpenSSL, OpenSSH, and GnuGP. The locations searched are "/var/run/egd-pool", "/dev/egd-pool",
"/etc/egd-pool", and "/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 HAVEGED <http://www.issihosts.com/haveged/> as
an alternative (a system daemon that refills /dev/random as needed).

/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 HAVEGED <http://www.issihosts.com/haveged/> will
help immensely.

/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.

TESHA2.
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 Math::TrulyRandom though updated to something
closer to what TrueRand 2.1 does vs. the obsolete version 1 that 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.

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?

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
"RtlGenRandom" and "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.

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 "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 "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, "/dev/random" will be chosen for blocking and "/dev/urandom" for
non-blocking, which is what should be done in most cases.

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.

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);

METHODS

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.

NonBlocking => 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).

Only => [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.

Never => [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.

Source => sub { ... }

Uses the given anonymous subroutine as the generator. The subroutine will be given an integer (the
argument to "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.

Source => ['name', sub { ... }, is_blocking, 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 "name" section.

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.

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.

name
Returns the text name of the random source. This will be one of: "User" for user defined,
"CryptGenRandom" for Windows 2000 Crypto API, "RtlGenRand" for Windows XP and newer Crypto API, "EGD" for
a known socket speaking the EGD protocol, "/dev/random" for the UNIX-like strong randomness source,
"/dev/urandom" for the UNIX-like non-blocking randomness source, "TESHA2-strong" for the userspace
entropy method when considered strong, "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.

is_strong
Returns 1 or 0 indicating whether the source is considered a strong source of randomness. See the
"STRENGTH" section for more discussion of what this means, and the source table for what we think of each
source.

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.

AUTHORS

       Dana Jacobsen <dana@acm.org>

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.

COPYRIGHT

       Copyright 2013 by Dana Jacobsen <dana@acm.org>

       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.

perl v5.14.2                                       2013-02-16                           Crypt::Random::Seed(3pm)