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

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

IMPLEMENTATION DETAILS

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

SUPPORT

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

BUGS

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

AUTHOR

181       Max Kanat-Alexander <mkanat@cpan.org>
182

COPYRIGHT AND LICENSE

184       Copyright (C) 2010 BugzillaSource, Inc.
185
186       This library (the entirety of Math-Random-Secure) is free software; you
187       can redistribute it and/or modify it under the terms of the Artistic
188       License 2.0. For details, see the full text of the license at
189       http://opensource.org/licenses/artistic-license-2.0.php
190       <http://opensource.org/licenses/artistic-license-2.0.php>.
191
192       This program is distributed in the hope that it will be useful, but it
193       is provided "as is" and without any express or implied warranties. For
194       details, see the full text of the license at
195       http://opensource.org/licenses/artistic-license-2.0.php
196       <http://opensource.org/licenses/artistic-license-2.0.php>.
197
198
199
200perl v5.12.3                      2011-01-25           Math::Random::Secure(3)