Beta Shell v2.0

File Manager

~ /usr/share/doc/perl-Math-Random-Secure
Name	Size	Perms	Modified	Actions
[ .. / .. ]
Changes	2.03 KB	-rw-r--r--	2017-03-12 22:45:37	Edit Del
README	7.6 KB	-rw-r--r--	2017-03-12 22:45:37	Edit Del
Editing: README (7.6 KB)

SYNOPSIS

     # Replace rand().
     use Math::Random::Secure qw(rand);
    
     # Get a random number between 0 and 1
     my $float = rand();
    
     # Get a random integer (faster than int(rand))
     use Math::Random::Secure qw(irand);
     my $int = irand();
    
     # Random integer between 0 and 9 inclusive.
     $int = irand(10);
    
     # Random floating-point number greater than or equal to 0.0 and
     # less than 10.0.
     $float = rand(10);

DESCRIPTION

    This module is intended to provide a cryptographically-secure
    replacement for Perl's built-in rand function. "Crytographically
    secure", in this case, means:

      * No matter how many numbers you see generated by the random number
      generator, you cannot guess the future numbers, and you cannot guess
      the seed.

      * There are so many possible seeds that it would take decades,
      centuries, or millenia for an attacker to try them all.

      * The seed comes from a source that generates relatively strong
      random data on your platform, so the seed itself will be as random as
      possible.

      See "IMPLEMENTATION DETAILS" for more information about the
      underlying systems used to implement all of these guarantees, and
      some important caveats if you're going to use this module for some
      very-high-security purpose.

METHODS

 rand

    Should work exactly like Perl's built-in rand. Will automatically call
    srand if srand has never been called in this process or thread.

    There is one limitation--Math::Random::Secure is backed by a 32-bit
    random number generator. So if you are on a 64-bit platform and you
    specify a limit that is greater than 2^32, you are likely to get
    less-random data.

 srand

    Note: Under normal circumstances, you should not call this function, as
    rand and irand will automatically call it for you the first time they
    are used in a thread or process.

    Seeds the random number generator, much like Perl's built-in srand,
    except that it uses a much larger and more secure seed. The seed should
    be passed as a string of bytes, at least 8 bytes in length, and more
    ideally between 32 and 64 bytes. (See "seed" in
    Math::Random::Secure::RNG for more info.)

    If you do not pass a seed, a seed will be generated automatically using
    a secure mechanism. See "IMPLEMENTATION DETAILS" for more information.

    This function returns the seed that generated (or the seed that was
    passed in, if you passed one in).

 irand

    Works somewhat like "rand", except that it returns a 32-bit integer
    between 0 and 2^32. Should be faster than doing int(rand).

    Note that because it returns 32-bit integers, specifying a limit
    greater than 2^32 will have no effect.

IMPLEMENTATION DETAILS

    Currently, Math::Random::Secure is backed by Math::Random::ISAAC, a
    cryptographically-strong random number generator with no known serious
    weaknesses. If there are significant weaknesses found in ISAAC, we will
    change our backend to a more-secure random number generator. The goal
    is for Math::Random::Secure to be cryptographically strong, not to
    represent some specific random number generator.

    Math::Random::Secure seeds itself using Crypt::Random::Source. The
    underlying implementation uses /dev/urandom on Unix-like platforms, and
    the RtlGenRandom or CryptGenRandom functions on Windows 2000 and above.
    (There is no support for versions of Windows before Windows 2000.) If
    any of these seeding sources are not available and you have other
    Crypt::Random::Source modules installed, Math::Random::Secure will use
    those other sources to seed itself.

 Making Math::Random::Secure Even More Secure

    We use /dev/urandom on Unix-like systems, because one of the
    requirements of duplicating rand is that we never block waiting for
    seed data, and /dev/random could do that. However, it's possible that
    /dev/urandom could run out of "truly random" data and start to use its
    built-in pseudo-random number generator to generate data. On most
    systems, this should still provide a very good seed for nearly all
    uses, but it may not be suitable for very high-security cryptographic
    circumstances.

    For Windows, there are known issues with CryptGenRandom on Windows 2000
    and versions of Windows XP before Service Pack 3. However, there is no
    other built-in method of getting secure random data on Windows, and I
    suspect that these issues will not be significant for most applications
    of Math::Random::Secure.

    If either of these situations are a problem for your use, you can
    create your own Math::Random::Secure::RNG object with a different
    "seeder" argument, and set $Math::Random::Secure::RNG to your own
    instance of Math::Random::Secure::RNG. The "seeder" is an instance of
    Crypt::Random::Source::Base, which should allow you to use most
    random-data sources in existence for your seeder, should you wish.

 Seed Exhaustion

    Perl's built-in srand reads 32 bits from /dev/urandom. By default, we
    read 512 bits. This means that we are more likely to exhaust available
    truly-random data than the built-in srand is, and cause /dev/urandom to
    fall back on its psuedo-random number generator. Normally this is not a
    problem, since "srand" is only called once per Perl process or thread,
    but it is something that you should be aware of if you are going to be
    in a situation where you have many new Perl processes or threads and
    you have very high security requirements (on the order of generating
    private SSH or GPG keypairs, SSL private keys, etc.).

SEE ALSO

    http://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator

      Describes the requirements and nature of a cryptographically-secure
      random number generator.

    http://en.wikipedia.org/wiki/CryptGenRandom,

      More information about the Windows functions we use to seed
      ourselves. The article also has some information about the weaknesses
      in Windows 2000's CryptGenRandom implementation.

    http://www.computerworld.com/s/article/9048438/Microsoft_confirms_that_XP_contains_random_number_generator_bug

      A news article about the Windows 2000/XP CryptGenRandom weakness,
      fixed in Vista and XP Service Pack 3.

    http://en.wikipedia.org/wiki/Random_number_generator_attack

      A description of ways to attack a random number generator, which can
      help in understanding why such a generator needs to be secure.

    Math::Random::Secure::RNG

      The underlying random-number generator and seeding code for
      Math::Random::Secure.

    Crypt::Source::Random

    Crypt::Random

    Math::TrulyRandom

      All of these modules contain generators for "truly random" data, but
      they don't contain a simple rand replacement and they can be very
      slow.

SUPPORT

    Right now, the best way to get support for Math::Random::Secure is to
    email the author using the email address in the "AUTHORS" section
    below.

BUGS

    Math::Random::Secure is relatively new, as of December 2010, but the
    modules that underlie it are very well-tested and have a long history.
    However, the author still welcomes all feedback and bug reports,
    particularly those having to do with the security assurances provided
    by this module.

    You can report a bug by emailing bug-Math-Random-Secure@rt.cpan.org or
    by using the RT web interface at
    https://rt.cpan.org/Ticket/Display.html?Queue=Math-Random-Secure. If
    your bug report is security-sensitive, you may also email it directly
    to the author using the email address in the "AUTHORS" section below.