Crypt::Random::Seed - phpMan

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

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:

  Crypt::Random::Source
    A comprehensive system using multiple plugins. It has a nice API, but
    uses 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.

  Crypt::URandom
    A great little module that is almost what I was looking for.
    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 "Only" and have TESHA2 as a backup.

  Crypt::Random
    Requires Math::Pari which makes it unacceptable in some environments.
    Has more features (numbers in arbitrary bigint intervals or bit sizes).
    Crypt::Random::Seed is taking a simpler approach, just handling
    returning octets and letting upstream modules handle the rest.

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

  Upstream modules
    Some modules that could use this module to help them:
    Bytes::Random::Secure, Math::Random::ISAAC, Math::Random::Secure, and
    Math::Random::MT to name a few.

COPYRIGHT
    Copyright 2013 by Dana Jacobsen <dana AT 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.