1Crypt::Random::TESHA2(3U)ser Contributed Perl DocumentatiCornypt::Random::TESHA2(3)
2
6 Crypt::Random::TESHA2 - Random numbers using timer/schedule entropy
7
9 Version 0.01
10
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
17 # Nothing exported by default
18 use Crypt::Random::TESHA2 qw(random_bytes random_values irand rand);
19 # Get 64 random bytes
21 my $seed_string = random_bytes(64);
22 # Get 16 random 32-bit values
24 my @seeds = random_values(16);
25 # Get a 32-bit random integer (value between 0 and 4294967295 inclusive)
27 my $i = irand();
28 # 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 # croak if installation determined we couldn't generate enough entropy
35 use Crypt::Random::TESHA2 ':strong';
36 # No warnings even if we are a weak source
38 use Crypt::Random::TESHA2 ':weak';
39 # Ask for yourself
41 die "No key for you!" unless Crypt::Random::TESHA2::is_strong();
42
44 Generate random numbers using entropy gathered from timer / scheduler
45 jitter.
46 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 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 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
69 random_bytes($n)
70 Takes an integer and returns a string of that size filled with random
71 data.
72 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 irand
79 Returns a single random 32-bit integer in the range [0,4294967295].
80 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 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
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 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 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 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
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 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 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 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 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
161 Dana Jacobsen <dana@acm.org>
162
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 This program is free software; you can redistribute it and/or modify it
194 under the same terms as Perl itself.
195 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.
203perl v5.30.0 2019-07-26 Crypt::Random::TESHA2(3)