1Math::Random::ISAAC(3)User Contributed Perl DocumentationMath::Random::ISAAC(3)
2
6 Math::Random::ISAAC - Perl interface to the ISAAC PRNG algorithm
7
9 version 1.004
10
12 use Math::Random::ISAAC;
13 my $rng = Math::Random::ISAAC->new(@seeds);
15 for (0..30) {
17 print 'Result: ' . $rng->irand() . "\n";
18 }
19
21 As with other Pseudo-Random Number Generator (PRNG) algorithms like the
22 Mersenne Twister (see Math::Random::MT), this algorithm is designed to
23 take some seed information and produce seemingly random results as
24 output.
25 However, ISAAC (Indirection, Shift, Accumulate, Add, and Count) has
27 different goals than these commonly used algorithms. In particular,
28 it's really fast - on average, it requires only 18.75 machine cycles to
29 generate a 32-bit value. This makes it suitable for applications where
30 a significant amount of random data needs to be produced quickly, such
31 solving using the Monte Carlo method or for games.
32 The results are uniformly distributed, unbiased, and unpredictable
34 unless you know the seed. The algorithm was published by Bob Jenkins in
35 the late 90s and despite the best efforts of many security researchers,
36 no feasible attacks have been found to date.
37 USAGE WARNING
39 There was no method supplied to provide the initial seed data by the
40 author. On his web site, Bob Jenkins writes:
41 Seeding a random number generator is essentially the same problem as
43 encrypting the seed with a block cipher.
44 In the same spirit, by default, this module does not seed the algorithm
46 at all -- it simply fills the state with zeroes -- if no seed is
47 provided. The idea is to remind users that selecting good seed data
48 for their purpose is important, and for the module to conveniently set
49 it to something like "localtime" behind-the-scenes hurts users in the
50 long run, since they don't understand the limitations of doing so.
51 The type of seed you might want to use depends entirely on the purpose
53 of using this algorithm in your program in the first place. Here are
54 some possible seeding methods:
55 1 Math::TrulyRandom
57 The Math::TrulyRandom module provides a way of obtaining truly
58 random data by using timing interrupts. This is probably one of the
59 better ways to seed the algorithm.
60 2 /dev/random
62 Using the system random device is, in principle, the best idea,
63 since it gathers entropy from various sources including interrupt
64 timing, other device interrupts, etc. However, it's not portable to
65 anything other than Unix-like platforms, and might not produce good
66 data on some systems.
67 3 localtime()
69 This works for basic things like simulations, but results in not-
70 so-random output, especially if you create new instances quickly
71 (as the seeds would be the same within per-second resolution).
72 4 Time::HiRes
74 In theory, using Time::HiRes is the same as option (2), but you get
75 a higher resolution time so you're less likely to have the same
76 seed twice. Note that you need to transform the output into an
77 integer somehow, perhaps by taking the least significant bits or
78 using a hash function. This would be less prone to duplicate
79 instances, but it's still not ideal.
80
82 new
83 Math::Random::ISAAC->new( @seeds )
84 Creates a "Math::Random::ISAAC" object, based upon either the optimized
86 C/XS version of the algorithm, Math::Random::ISAAC::XS, or falls back
87 to the included Pure Perl module, Math::Random::ISAAC::PP.
88 Example code:
90 my $rng = Math::Random::ISAAC->new(time);
92 This method will return an appropriate Math::Random::ISAAC object or
94 throw an exception on error.
95 rand
97 $rng->rand()
98 Returns a random double-precision floating point number which is
100 normalized between 0 and 1 (inclusive; it's a closed interval).
101 Internally, this simply takes the uniformly distributed unsigned
103 integer from "$rng->irand()" and divides it by "2**32-1" (maximum
104 unsigned integer size)
105 Example code:
107 my $next = $rng->rand();
109 This method will return a double-precision floating point number or
111 throw an exception on error.
112 irand
114 $rng->irand()
115 Returns the next unsigned 32-bit random integer. It will return a value
117 with a value such that: 0 <= x <= 2**32-1.
118 Example code:
120 my $next = $rng->irand();
122 This method will return a 32-bit unsigned integer or throw an exception
124 on error.
125
127 The intent of this module is to provide single simple interface to the
128 two compatible implementations of this module, namely,
129 Math::Random::ISAAC::XS and Math::Random::ISAAC::PP.
130 If, for some reason, you need to determine what version of the module
132 is actually being included by "Math::Random::ISAAC", then:
133 print 'Backend type: ', $Math::Random::ISAAC::DRIVER, "\n";
135 In order to force use of one or the other, simply load the appropriate
137 module:
138 use Math::Random::ISAAC::XS;
140 my $rng = Math::Random::ISAAC::XS->new();
141 # or
142 use Math::Random::ISAAC::PP;
143 my $rng = Math::Random::ISAAC::PP->new();
144
146 • Special thanks to Bob Jenkins <bob_jenkins@burtleburtle.net> for
147 devising this very clever algorithm and releasing it into the
148 public domain.
149 • Thanks to John L. Allen (contact unknown) for providing a Perl port
151 of the original ISAAC code, upon which "Math::Random::ISAAC::PP" is
152 heavily based. His version is available on Bob's web site, in the
153 SEE ALSO section.
154
156 Math::Random::ISAAC::XS, the C/XS optimized version of this module,
157 which will be used automatically if available.
158 <http://burtleburtle.net/bob/rand/isaacafa.html>, Bob Jenkins' page
160 about ISAAC, which explains the algorithm as well as potential attacks.
161 <http://eprint.iacr.org/2006/438.pdf>, a paper entitled "On the pseudo-
163 random generator ISAAC," which claims there are many seeds which will
164 produce non-uniform results. The author, Jean-Philippe Aumasson, argues
165 ISAAC should be using rotations (circular shifts) instead of normal
166 shifts to increase diffusion of the state, among other things.
167 <http://eprint.iacr.org/2001/049.pdf>, a paper by Marina Pudovkina
169 discussing plaintext attacks on the ISAAC keystream generator. Among
170 other things, it notes that the time complexity is Tmet = 4.67*10^1240,
171 so it remains a secure cipher for practical applications.
172
174 • There is no method that allows re-seeding of algorithms. This is
175 not really necessary because one can simply call "new" again with
176 the new seed data periodically.
177 But he also provides a simple workaround:
179 As ISAAC is intended to be a secure cipher, if you want to reseed it,
181 one way is to use some other cipher to seed some initial version of ISAAC,
182 then use ISAAC's output as a seed for other instances of ISAAC whenever
183 they need to be reseeded.
184 • There is no way to clone a PRNG instance. I'm not sure why this is
186 might even be necessary or useful. File a bug report with an
187 explanation why and I'll consider adding it to the next release.
188
190 Please report any bugs or feature requests on the bugtracker website
191 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Math-Random-ISAAC
192 When submitting a bug or request, please include a test-file or a patch
194 to an existing test-file that illustrates the bug or desired feature.
195
197 Jonathan Yu <jawnsy@cpan.org>
198
200 Legally speaking, this package and its contents are:
201 Copyright (c) 2011 by Jonathan Yu <jawnsy@cpan.org>.
203 But this is really just a legal technicality that allows the author to
205 offer this package under the public domain and also a variety of
206 licensing options. For all intents and purposes, this is public domain
207 software, which means you can do whatever you want with it.
208 The software is provided "AS IS", without warranty of any kind, express
210 or implied, including but not limited to the warranties of
211 merchantability, fitness for a particular purpose and noninfringement.
212 In no event shall the authors or copyright holders be liable for any
213 claim, damages or other liability, whether in an action of contract,
214 tort or otherwise, arising from, out of or in connection with the
215 software or the use or other dealings in the software.
216perl v5.36.0 2023-01-20 Math::Random::ISAAC(3)