1Crypt::Random::TESHA2(3U)ser Contributed Perl DocumentatiCornypt::Random::TESHA2(3)
2
3
4

NAME

6       Crypt::Random::TESHA2 - Random numbers using timer/schedule entropy
7

VERSION

9       Version 0.01
10

WARNING

12       This module implements userspace voodoo entropy.  You should use a
13       proper O/S supplied entropy source such as /dev/random or the Win32
14       Crypt API.
15

SYNOPSIS

17         # Nothing exported by default
18         use Crypt::Random::TESHA2 qw(random_bytes random_values irand rand);
19
20         # Get 64 random bytes
21         my $seed_string = random_bytes(64);
22
23         # Get 16 random 32-bit values
24         my @seeds = random_values(16);
25
26         # Get a 32-bit random integer (value between 0 and 4294967295 inclusive)
27         my $i = irand();
28
29         # rand, like system rand, with 32 bits of randomness.
30         my $r1 = rand();      # floating point in range [0,1).
31         my $r2 = rand(1000);  # floating point in range [0,1000).
32
33
34         # croak if installation determined we couldn't generate enough entropy
35         use Crypt::Random::TESHA2 ':strong';
36
37         # No warnings even if we are a weak source
38         use Crypt::Random::TESHA2 ':weak';
39
40         # Ask for yourself
41         die "No key for you!" unless Crypt::Random::TESHA2::is_strong();
42

DESCRIPTION

44       Generate random numbers using entropy gathered from timer / scheduler
45       jitter.
46
47       This can be used to generate non-pseudorandom data to seed a PRNG (e.g.
48       "srand"/"rand", Math::Random::MT, etc.) or CSPRNG (e.g. AES-CTR or
49       Math::Random::ISAAC).  You may use it directly or as part of a random
50       source module that first checks for O/S randomness sources.
51
52       Only Perl CORE modules are used, making this very portable.  However,
53       systems must have a high resolution timer and support "usleep" from
54       Time::HiRes.
55
56       At installation time, measurements are taken of the estimated entropy
57       gathered by the timer differences.  If the results indicated we could
58       not get good results, then the module will consider itself "weak".  On
59       the first use of any of the functions that return randomness (e.g.
60       random_bytes), the module will carp about not being a strong randomness
61       source.  However, two special options, ":strong" and ":weak" may be
62       given to the importer to change this behavior.  If ":strong" is used,
63       then the module will croak.  If ":weak" is used, then no carp will be
64       generated.  The function "is_strong" can be used at any time for finer
65       control.  Note that this should be an unusual case, and neither flag
66       has any effect if the module considers itself strong.
67

FUNCTIONS

69   random_bytes($n)
70       Takes an integer and returns a string of that size filled with random
71       data.
72
73   random_values($n)
74       Takes an integer and returns an array containing that many random
75       32-bit integers.  The values will be in the range [0,4294967295] (all
76       32-bit values are possible).
77
78   irand
79       Returns a single random 32-bit integer in the range [0,4294967295].
80
81   rand
82       Returns a random float greater than or equal to 0 and less than the
83       value of the argument.  If no argument is given or the argument is
84       zero, 1 is used.  This has an identical API as system rand, though of
85       course there is no associated srand function.  The result has 32 bits
86       of randomness.
87
88   is_strong
89       Returns 0 if the installation procedure determined that not enough
90       entropy could be gathered on this system.  Returns 1 if it was able.
91       If 0 is returned, then the bytes returned may be no better than a
92       CSPRNG using a convoluted time-based reseed every bit.
93

METHOD

95       The underlying entropy gathering is done using timing differences
96       between usleep calls.  We wrap usleep calls of varying intervals along
97       with some Perl hash processing inside microsecond timer calls.  The two
98       values are xored.  This is the raw entropy source.  Eight of these,
99       along with the current time, are fed to a SHA-256 which can be added to
100       an entropy pool.
101
102       Measurements of the raw timer entropy (just the timing differences --
103       no hashes, time, counters, xors, or entropy pool) on systems I have
104       available indicate 1.5 to 4 bits of entropy per usleep.  The
105       installation procedure does a measurement of the 0-order entropy
106       gathered from the raw timing process, halves it, limits to the range
107       1/8 - 7/8, and uses that as the estimated entropy gathered.
108
109       The actual output random bytes are generated by an entropy pool that
110       uses SHA-512 or SHA-256.  This adds data as needed from the above
111       method, then extracts bits as needed to make the output bytes (again
112       using a cryptographic hash and a counter, which means the entropy pool
113       is not exposed).
114
115       The result will easily pass most stream randomness tests (e.g.
116       FIPS-140, ENT, TestU01 Rabbit), but that is a given based on the last
117       entropy pool stage, so this just shows we provide decorrelated output,
118       not that we make a good seed.
119

LIMITATIONS

121       Note that pretty much every limitation of this module will apply to
122       Math::TrulyRandom, which many non-cryptographers still think is
123       cryptographically secure (it's recommended in both the perl core
124       documentation as well as Math::Random::ISAAC).  If you think that
125       module is great for your application, then you should be happy with
126       this one.  Probably happier since this is more portable, doesn't hang
127       infinitely, runs much faster, and generates better output on most
128       systems.
129
130       As mentioned in the Warnings section, this generates userspace entropy
131       -- what most people used until the waning years of the 20th century.
132       We should not have to do this on modern systems that have well designed
133       APIs to get randomness from multiple entropy pools, all managed by
134       production code.  In other words, "/dev/random".
135
136       Performance is slow (about 10,000 times slower than
137       Math::Random::ISAAC::XS), making this something best to be used to seed
138       a PRNG or CSPRNG, rather than using directly.  On newer Linux systems
139       and Win32 it runs about 10,000 bits per second.  Cygwin runs about 1000
140       bits per second.  Older systems will run slower of course, such as an
141       old HPPA system I use that runs at 40 bits/s.  Much of the time is
142       spent sleeping.
143
144       Gathering entropy with this method depends on high resolution timers.
145       If the timers have low resolution, especially if we had a system with
146       very fast yield turnaround, then we would gather very little entropy.
147       One of the tests tries to determine this, but it isn't perfect.  As
148       with all such userspace systems, you should check that it works before
149       using it for anything critical.  RFC4086
150       <http://www.ietf.org/rfc/rfc4086.txt> section 3.4 discusses a few of
151       the pitfalls of using portable clock-based software, and section 3.6
152       discusses the desire for multiple entropy sources.
153
154       Because of the use of SHA-2 hashes along with an entropy pool using a
155       counter, the output stream will pass randomness tests (e.g. FIPS-140,
156       ENT, TestU01 Rabbit) even if there is no underlying entropy.  The
157       installation measurements should indicate whether this is happening,
158       but it doesn't measure everything.
159

AUTHORS

161       Dana Jacobsen <dana@acm.org>
162

SEE ALSO

164       Encyclopedia of Cryptography and Security, volume 2, "Entropy Sources".
165       The entropy pool implemented in this module follows this design.
166       HAVEGE (<http://www.issihosts.com/haveged/>) Uses multiple methods to
167       gather entropy and feed it to the O/S, which can measure it and add it
168       to a pool.  Highly recommended for embedded or network devices that
169       don't have good external interactions, or when running programs that
170       use a lot of entropy (e.g. anything that uses Crypt::Random).
171       timer_entropyd (<http://www.vanheusden.com/te/>) Uses a related method
172       (jitter in timing data between usleeps) as this module, but inefficient
173       and only suitable for bulk feeding of an entropy pool.  Even after von
174       Neumann debiasing, the output has distinct patterns and at most 0.5
175       bits of entropy per output bit.  HAVEGE is a superior overall solution.
176       However, note a number of other links at the site for other sources as
177       well as links to hardware RNGs.
178       Math::TrulyRandom An old module that uses an obsolete version of Matt
179       Blaze's TrueRand. TrueRand version 2.1 fixes a number of issues with
180       the output quality and specifically recommends against using the old
181       method.  In addition, the Perl module will not properly run on most
182       current platforms. A pure Perl version is included in the examples
183       directory of this module, but it is still TrueRand version 1 and, like
184       the old module, will not run on Win32.
185       Crypt::Urandom A simple module that gets a good source of O/S non-
186       blocking randomness.
187       Crypt::Random::Source A complicated module that has multiple plugins
188       for randomness sources.
189
191       Copyright 2012-2013 by Dana Jacobsen <dana@acm.org>
192
193       This program is free software; you can redistribute it and/or modify it
194       under the same terms as Perl itself.
195
196       The software is provided "AS IS", without warranty of any kind, express
197       or implied, including but not limited to the warranties of
198       merchantability, fitness for a particular purpose and noninfringement.
199       In no event shall the authors or copyright holders be liable for any
200       claim, damages or other liability, whether in an action of contract,
201       tort or otherwise, arising from, out of or in connection with the
202       software or the use or other dealings in the software.
203
204
205
206perl v5.28.1                      2013-01-11          Crypt::Random::TESHA2(3)
Impressum