Math::Random::Secure(3pm)

1Math::Random::Secure(3)User Contributed Perl DocumentatioMnath::Random::Secure(3)
2
3
4

NAME

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

VERSION

10       version 0.080001
11

SYNOPSIS

13        # Replace rand().
14        use Math::Random::Secure qw(rand);
15
16        # Get a random number between 0 and 1
17        my $float = rand();
18
19        # Get a random integer (faster than int(rand))
20        use Math::Random::Secure qw(irand);
21        my $int = irand();
22
23        # Random integer between 0 and 9 inclusive.
24        $int = irand(10);
25
26        # Random floating-point number greater than or equal to 0.0 and
27        # less than 10.0.
28        $float = rand(10);
29

DESCRIPTION

31       This module is intended to provide a cryptographically-secure
32       replacement for Perl's built-in "rand" function. "Crytographically
33       secure", in this case, means:
34
35       •   No matter how many numbers you see generated by the random number
36           generator, you cannot guess the future numbers, and you cannot
37           guess the seed.
38
39       •   There are so many possible seeds that it would take decades,
40           centuries, or millenia for an attacker to try them all.
41
42       •   The seed comes from a source that generates relatively strong
43           random data on your platform, so the seed itself will be as random
44           as possible.
45
46           See "IMPLEMENTATION DETAILS" for more information about the
47           underlying systems used to implement all of these guarantees, and
48           some important caveats if you're going to use this module for some
49           very-high-security purpose.
50

METHODS

52   rand
53       Should work exactly like Perl's built-in "rand". Will automatically
54       call "srand" if "srand" has never been called in this process or
55       thread.
56
57       There is one limitation--Math::Random::Secure is backed by a 32-bit
58       random number generator. So if you are on a 64-bit platform and you
59       specify a limit that is greater than 2^32, you are likely to get less-
60       random data.
61
62   srand
63       Note: Under normal circumstances, you should not call this function, as
64       "rand" and "irand" will automatically call it for you the first time
65       they are used in a thread or process.
66
67       Seeds the random number generator, much like Perl's built-in "srand",
68       except that it uses a much larger and more secure seed. The seed should
69       be passed as a string of bytes, at least 8 bytes in length, and more
70       ideally between 32 and 64 bytes. (See "seed" in
71       Math::Random::Secure::RNG for more info.)
72
73       If you do not pass a seed, a seed will be generated automatically using
74       a secure mechanism. See "IMPLEMENTATION DETAILS" for more information.
75
76       This function returns the seed that generated (or the seed that was
77       passed in, if you passed one in).
78
79   irand
80       Works somewhat like "rand", except that it returns a 32-bit integer
81       between 0 and 2^32. Should be faster than doing "int(rand)".
82
83       Note that because it returns 32-bit integers, specifying a limit
84       greater than 2^32 will have no effect.
85

IMPLEMENTATION DETAILS

87       Currently, Math::Random::Secure is backed by Math::Random::ISAAC, a
88       cryptographically-strong random number generator with no known serious
89       weaknesses. If there are significant weaknesses found in ISAAC, we will
90       change our backend to a more-secure random number generator. The goal
91       is for Math::Random::Secure to be cryptographically strong, not to
92       represent some specific random number generator.
93
94       Math::Random::Secure seeds itself using Crypt::Random::Source. The
95       underlying implementation uses /dev/urandom on Unix-like platforms, and
96       the "RtlGenRandom" or "CryptGenRandom" functions on Windows 2000 and
97       above. (There is no support for versions of Windows before Windows
98       2000.)  If any of these seeding sources are not available and you have
99       other Crypt::Random::Source modules installed, Math::Random::Secure
100       will use those other sources to seed itself.
101
102   Making Math::Random::Secure Even More Secure
103       We use /dev/urandom on Unix-like systems, because one of the
104       requirements of duplicating "rand" is that we never block waiting for
105       seed data, and /dev/random could do that. However, it's possible that
106       /dev/urandom could run out of "truly random" data and start to use its
107       built-in pseudo-random number generator to generate data. On most
108       systems, this should still provide a very good seed for nearly all
109       uses, but it may not be suitable for very high-security cryptographic
110       circumstances.
111
112       For Windows, there are known issues with "CryptGenRandom" on Windows
113       2000 and versions of Windows XP before Service Pack 3. However, there
114       is no other built-in method of getting secure random data on Windows,
115       and I suspect that these issues will not be significant for most
116       applications of Math::Random::Secure.
117
118       If either of these situations are a problem for your use, you can
119       create your own Math::Random::Secure::RNG object with a different
120       "seeder" argument, and set $Math::Random::Secure::RNG to your own
121       instance of Math::Random::Secure::RNG. The "seeder" is an instance of
122       Crypt::Random::Source::Base, which should allow you to use most random-
123       data sources in existence for your seeder, should you wish.
124
125   Seed Exhaustion
126       Perl's built-in "srand" reads 32 bits from /dev/urandom. By default, we
127       read 512 bits. This means that we are more likely to exhaust available
128       truly-random data than the built-in "srand" is, and cause /dev/urandom
129       to fall back on its psuedo-random number generator. Normally this is
130       not a problem, since "srand" is only called once per Perl process or
131       thread, but it is something that you should be aware of if you are
132       going to be in a situation where you have many new Perl processes or
133       threads and you have very high security requirements (on the order of
134       generating private SSH or GPG keypairs, SSL private keys, etc.).
135

SUPPORT

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

BUGS

171       Math::Random::Secure is relatively new, as of December 2010, but the
172       modules that underlie it are very well-tested and have a long history.
173       However, the author still welcomes all feedback and bug reports,
174       particularly those having to do with the security assurances provided
175       by this module.
176
177       You can report a bug by emailing "bug-Math-Random-Secure@rt.cpan.org"
178       or by using the RT web interface at
179       <https://rt.cpan.org/Ticket/Display.html?Queue=Math-Random-Secure>. If
180       your bug report is security-sensitive, you may also email it directly
181       to the author using the email address in the "AUTHORS" section below.
182

AUTHORS

184       •   Max Kanat-Alexander <mkanat@cpan.org>
185
186       •   Arthur Axel "fREW" Schmidt
187           <math-random-secure@afoolishmanifesto.com>
188

COPYRIGHT AND LICENSE

190       This software is Copyright (c) 2010 by BugzillaSource, Inc.
191
192       This is free software, licensed under:
193
194         The Artistic License 2.0 (GPL Compatible)
195
196
197
198perl v5.34.0                      2022-01-21           Math::Random::Secure(3)