Ubuntu Manpage: Math::Random::Secure - Cryptographically-secure, cross-platform replacement for rand()

Provided by: libmath-random-secure-perl_0.080001-1.1_all

NAME

       Math::Random::Secure - Cryptographically-secure, cross-platform replacement for rand()

VERSION

       version 0.080001

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

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.

AUTHORS

       •   Max Kanat-Alexander <mkanat@cpan.org>

       •   Arthur Axel "fREW" Schmidt <math-random-secure@afoolishmanifesto.com>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2010 by BugzillaSource, Inc.

       This is free software, licensed under:

         The Artistic License 2.0 (GPL Compatible)

perl v5.32.0                                       2021-01-06                          Math::Random::Secure(3pm)