1Math::Random::ISAAC(3)User Contributed Perl DocumentationMath::Random::ISAAC(3)
2
3
4

NAME

6       Math::Random::ISAAC - Perl interface to the ISAAC PRNG algorithm
7

VERSION

9       version 1.004
10

SYNOPSIS

12         use Math::Random::ISAAC;
13
14         my $rng = Math::Random::ISAAC->new(@seeds);
15
16         for (0..30) {
17           print 'Result: ' . $rng->irand() . "\n";
18         }
19

DESCRIPTION

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
26       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
33       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
38   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
42         Seeding a random number generator is essentially the same problem as
43         encrypting the seed with a block cipher.
44
45       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
52       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
56       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
61       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
68       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
73       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

METHODS

82   new
83         Math::Random::ISAAC->new( @seeds )
84
85       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
89       Example code:
90
91         my $rng = Math::Random::ISAAC->new(time);
92
93       This method will return an appropriate Math::Random::ISAAC object or
94       throw an exception on error.
95
96   rand
97         $rng->rand()
98
99       Returns a random double-precision floating point number which is
100       normalized between 0 and 1 (inclusive; it's a closed interval).
101
102       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
106       Example code:
107
108         my $next = $rng->rand();
109
110       This method will return a double-precision floating point number or
111       throw an exception on error.
112
113   irand
114         $rng->irand()
115
116       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
119       Example code:
120
121         my $next = $rng->irand();
122
123       This method will return a 32-bit unsigned integer or throw an exception
124       on error.
125

PURPOSE

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
131       If, for some reason, you need to determine what version of the module
132       is actually being included by "Math::Random::ISAAC", then:
133
134         print 'Backend type: ', $Math::Random::ISAAC::DRIVER, "\n";
135
136       In order to force use of one or the other, simply load the appropriate
137       module:
138
139         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

ACKNOWLEDGEMENTS

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
150       •   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

SEE ALSO

156       Math::Random::ISAAC::XS, the C/XS optimized version of this module,
157       which will be used automatically if available.
158
159       <http://burtleburtle.net/bob/rand/isaacafa.html>, Bob Jenkins' page
160       about ISAAC, which explains the algorithm as well as potential attacks.
161
162       <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
168       <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

CAVEATS

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
178           But he also provides a simple workaround:
179
180             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
185       •   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

BUGS

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
193       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

AUTHOR

197       Jonathan Yu <jawnsy@cpan.org>
198
200       Legally speaking, this package and its contents are:
201
202         Copyright (c) 2011 by Jonathan Yu <jawnsy@cpan.org>.
203
204       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
209       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.
216
217
218
219perl v5.34.0                      2022-01-21            Math::Random::ISAAC(3)
Impressum