1=pod 2 3=head1 NAME 4 5Bytes::Random::Secure::Tiny - A tiny Perl extension to generate 6cryptographically-secure random bytes. 7 8=head1 SYNOPSIS 9 10 use Bytes::Random::Secure::Tiny; 11 12 my $rng = Bytes::Random::Secure->new; # Seed with 256 bits. 13 14 my $bytes = $rng->bytes(32); # A string of 32 random bytes. 15 my $long = $rng->irand; # 32-bit random unsigned int. 16 my $hex = $rng->bytes_hex(10); # 10 random bytes as hex digits. 17 my $string = $rng->string_from('abc', 10); # Random string from a, b, & c. 18 19 20=head1 DESCRIPTION 21 22L<Bytes::Random::Secure::Tiny> provides random bytes from a cryptographically 23secure random number generator (ISAAC), seeded from strong entropy sources on 24a wide variety of platforms. It does so without external dependencies (except 25on Windows), and has a minimal but useful user interface patterned after the 26module L<Bytes::Random::Secure>. 27 28L<Bytes::Random::Secure> has a handful of dependencies. And its UI may be 29bigger than a typical user needs. L<Bytes::Random::Secure::Tiny> is designed 30to provide what 90% of Bytes::Random::Secure's users need, but with a simpler 31user interface, and in a single module with no dependencies beyond core Perl. 32 33In most cases this module may be used as a light-weight drop-in replacement 34for L<Bytes::Random::Secure>. 35 36=head1 RATIONALE 37 38This module aims to provide a generalized tool for generating cryptographically 39secure randomness in a way that can fit into many applications while providing 40a zero dependency toolchain, and a user interface that is both minimal and 41simple. Common use-cases may include: 42 43=over 4 44 45=item * Creating temporary passphrases. 46 47=item * Generating random salts. 48 49=item * Generating a secret that can be hashed along with session cookies. 50 51=item * Nonces. 52 53=item * Feeding secure key-gen utilities. 54 55=back 56 57L<Bytes::Random::Secure::Tiny> employs several well-designed algorithms 58adapted from established CPAN tools to generate a strong random seed, and then 59to instantiate a high quality cryptographically secure pseudo-random number 60generator based on the seed. It has taken significant research to come up with 61a strong and sensible choice of established and published algorithms. The 62interface is designed with minimalism and simplicity in mind. 63 64In particular, the CSPRNG is based on the same algorithm used by 65L<Math::Random::ISAAC>, and the seeding is based on algorithms from 66L<Crypt::Random::Seed>. 67 68Furthermore, this module runs its randomness through both statistical tests 69and NIST L<FIPS-140|https://en.wikipedia.org/wiki/FIPS_140> tests to verify 70integrity. 71 72As a C<::Tiny> module, the additional goals of low (or no) dependencies and a 73light-weight code base make this an ideal choice for environments where heavier 74dependency chains are problematic. 75 76=head1 EXPORTS 77 78Nothing is exported. 79 80=head1 METHODS 81 82=head2 new 83 84 my $rng = Bytes::Random::Secure::Tiny->new; 85 86Instantiate the pseudo-random number generator object. The seeding of the ISAAC 87CSPRING defaults to 256 bits from a non-blocking entropy source. The CSPRNG 88object should be instantiated as infrequently as practical; there is no benefit 89to re-seeding, with the single cavaet that the CSPRNG object should not be 90shared by threads or forked processes. 91 92=head3 Constructor Parameters 93 94Parameters described below are optional and case-insensitive. 95 96=over 4 97 98=item bits 99 100 my $rng = Bytes::Random::Secure::Tiny->new(bits => 512); 101 102Number of bits to use in seeding. Must be a value between 64 and 8192 103inclusive, and must satisfy C<bits==2**n>. The default value is 256. 104 105=item nonblocking 106 107 my $nb_rng = Bytes::Random::Secure::Tiny->new(nonblocking=>1); 108 my $bl_rng = Bytes::Random::Secure::Tiny->new(nonblocking=>0); 109 110If set to a false value, a blocking entropy source may be used in seeding. This 111is generally not necessary, as the non-blocking sources used are considered by 112most to be strong enough for cryptographic purposes. 113 114Instantiating with a blocking source can exhaust system entropy (this has been 115seen in testing), and in such cases C<new> will block until sufficient entropy 116is generated. 117 118The default is to use a non-blocking source, and you should probably accept 119that default. 120 121=back 122 123=head2 bytes 124 125 my $random_bytes = $rng->bytes($n); 126 127Returns a string of C<$n> random bytes. C<$n> must be a positive integer. 128 129=head2 bytes_hex 130 131 my $random_hex = $rng->bytes_hex(6); # E.g. f35dde7c02a4 132 133Returns a string of hex digits. Each byte is represented by two lower-cased hex 134digits. Therefore, C<< $rng->bytes_hex(1) >> will return a string of length 2, 135such as C<7F>. There is no C<0x> prepended to the hex digits. 136 137=head2 string_from 138 139 my $random_string = $rng->string_from('abcdefg', 10); 140 141Returns a string of random octets selected from the "Bag" string (in this case 142ten octets from 'abcdefg'). Repeated bag characters are weighted according to 143their frequency. For example, given the bag 'aabc', the character 'a' will be 144selected approximately 50% of the time, though being I<random>, there are no 145guarantees it will be selected at all. For the bag 'abc', each character has 146the same weight. The output may contain duplicate characters. For example: 147 148 say $rng->string_from('a', 10); # Must always be 'aaaaaaaaaa' 149 150=head2 irand 151 152 my $unsigned_long = $random->irand; 153 154Returns a pseudo-random 32-bit unsigned integer. The value will satisfy 155C<< 0 <= x <= 2**32-1 >>. 156 157=head2 shuffle 158 159 my $aref_shuffled = $random->shuffle($aref); 160 161Shuffles the contents of a reference to an array in sitiu, and returns 162the same reference. 163 164L<List::Util>, which ships with Perl, includes C<shuffle> function. But that 165function is flawed in two ways. First, from a cryptographic standpoint, 166it uses Perl's C<rand>, which is not a CSPRNG, and therefore is inadequate. 167 168Second, because Perl's rand has an internal state of just 32 bits, it cannot 169possibly generate all permutations of arrays containing 13 or more elements. 170 171This module's C<shuffle> uses a CSPRNG, and also benefits from large seeds 172and a huge internal state. ISAAC can be seeded with up to 8192 bits, yielding 1732^8192 possible initial states, and 2^8288 possible internal states. A seed of 1748192 bits will assure that for arrays of up to 966 elements every permutation 175is accessible. 176 177=head1 CONFIGURATION 178 179Nothing to configure. 180 181=head1 DEPENDENCIES 182 183This module requires Perl 5.8 or newer. Unicode support in C<string_from> is 184best with Perl 5.8.9 or newer. See the INSTALLATION section in this document 185for details. 186 187=head1 OPTIONAL DEPENDENCIES 188 189L<Bytes::Random::Secure::Tiny> uses an embedded version of the ISAAC 190algorithm adapted from L<Math::Random::ISAAC> as its CSPRNG, but will 191silently upgrade to using L<Math::Random::ISAAC> proper if it is available 192on the target system. 193 194C<Bytes::Random::Secure::Tiny> seeds using an embedded adaptation of 195L<Crypt::Random::Seed>, but it will silently upgrade to using 196L<Crypt::Random::Seed> proper if it is available on the target system. 197 198If performance is a consideration and you are able to install 199L<Math::Random::ISAAC::XS>, do so; L<Bytes::Random::Secure::Tiny> will 200silently upgrade to using C<Math::Random::ISAAC::XS> instead of the embedded 201ISAAC CSPRING. L<Math::Random::ISAAC::XS> implements the same ISAAC CSPRNG 202algorithm in C and XS for speed. 203 204=head1 FORK AND THREAD SAFETY 205 206When programming for parallel computation, create a unique 207C<Bytes::Random::Secure::Tiny> object within each process or thread. 208L<Bytes::Random::Secure::Tiny> uses a CSPRNG, and sharing the same RNG between 209threads or processes will share the same seed and the same starting point. By 210instantiating the B::R::S::T object after forking or creating threads, a unique 211randomness stream will be created per thread or process. 212 213Always share the same RNG object between all non-concurrent consumers within 214a process, but never share the same RNG between threads or forked processes. 215 216=head1 ADDITIONAL DISCUSSION 217 218=head2 STRONG RANDOMNESS 219 220It's easy to generate weak pseudo-random bytes. It's also easy to think you're 221generating strong pseudo-random bytes when really you're not. And it's hard to 222test for pseudo-random cryptographic acceptable quality. There are many high 223quality random number generators that are suitable for statistical purposes, 224but not necessarily up to the rigors of cryptographic use. 225 226Assuring strong (ie, secure) random bytes in a way that works across a wide 227variety of platforms is also challenging. A primary goal for this module is to 228provide cryptographically secure pseudo-random bytes while still meeting the 229secondary goals of simplicity, minimalism, and no dependencies. If more 230fine-grained control over seeding methods is needed, use 231L<Bytes::Random::Secure> instead. 232 233=head2 ISAAC 234 235The L<ISAAC algorithm|https://en.wikipedia.org/wiki/ISAAC_(cipher)> is 236considered a cryptographically strong pseudo-random number generator. It has 2371.0e2466 possible initial states. The best known attack for discovering initial 238state would theoretically take a complexity of approximately 4.67e1240, which 239is of no practical consequence to ISAAC's security. Cycles are guaranteed to 240have a minimum length of 2**40, with an average cycle of 2**8295. Because there 241is no practical attack capable of discovering initial state, and because the 242average cycle is so long, it's generally unnecessary to re-seed a running 243application. The results are uniformly distributed, unbiased, and unpredictable 244unless the seed is known. 245 246To confirm the quality of the CSPRNG, this module's test suite implements the 247L<FIPS-140-1|http://csrc.nist.gov/publications/fips/fips1401.htm> tests for 248strong random number generators. See the comments in C<t/27-fips140-1.t> for 249details. 250 251=head2 UNICODE SUPPORT 252 253The C<string_from> method permits the user to pass a "bag" (or source) string 254containing Unicode characters. For any modern Perl version, this will work 255just as you would hope. But some versions of Perl older than 5.8.9 exhibited 256varying degrees of bugginess in their handling of Unicode. If you're depending 257on the Unicode features of this module while using Perl versions older than 2585.8.9 be sure to test thoroughly, and don't be surprised when the outcome isn't 259as expected. ...this is to be expected. Upgrade. This module works at the 260octet level, not grapheme cluster. 261 262=head2 MODULO BIAS 263 264Care is taken so that there is no modulo bias in the randomness returned. This 265is exactly I<why> the C<string_from> method is preferable to a home-grown 266random string solution. However, the algorithm to eliminate modulo bias can 267impact the performance of the C<string_from> method. Any time the length of the 268bag string is significantly less than the nearest greater or equal factor of 2692**32, performance will degrade. Unfortunately there is no known algorithm that 270improves upon this situation. Fortunately, for sanely sized strings, it's a 271minor issue. To put it in perspective, even in the case of passing a "bag" 272string of length 2**31 (which is huge), the expected time to return random 273bytes will only double. 274 275=head1 INSTALLATION 276 277No special requirements. 278 279=head1 SEE ALSO 280 281If support for hardware entropy generators is needed, use 282L<Bytes::Random::Secure>. Other good CSPRNG's include L<Crypt::Random> and 283L<Math::Random::Secure>. 284 285=head1 AUTHOR 286 287David Oswald I<< <davido@cpan.org> >> 288 289=head1 BUGS 290 291Please report any bugs or feature requests to 292C<bug-bytes-random-secure at rt.cpan.org>, or through the web interface at 293L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bytes-Random-Secure-Tiny>. I 294will be notified, and then you'll automatically be notified of progress on 295your bug as I make changes. 296 297=head1 SUPPORT 298 299You can find documentation for this module with the perldoc command. 300 301 perldoc Bytes::Random::Secure 302 303You can also look for information at: 304 305=over 4 306 307=item * Github Repo: L<https://github.com/daoswald/Bytes-Random-Secure-Tiny> 308 309=item * RT: CPAN's request tracker (report bugs here) 310 311L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Bytes-Random-Secure-Tiny> 312 313=item * AnnoCPAN: Annotated CPAN documentation 314 315L<http://annocpan.org/dist/Bytes-Random-Secure-Tiny> 316 317=item * CPAN Ratings 318 319L<http://cpanratings.perl.org/d/Bytes-Random-Secure-Tiny> 320 321=item * Search CPAN 322 323L<http://search.cpan.org/dist/Bytes-Random-Secure-Tiny/> 324 325=back 326 327=head1 ACKNOWLEDGEMENTS 328 329Dana Jacobsen ( I<< <dana@acm.org> >> ) for his work that led to 330L<Crypt::Random::Seed>, and for ideas and code reviews. 331 332=head1 LICENSE AND COPYRIGHT 333 334Copyright 2015 David Oswald. 335 336This program is free software; you can redistribute it and/or modify it 337under the terms of either: the GNU General Public License as published 338by the Free Software Foundation; or the Artistic License. 339 340See http://dev.perl.org/licenses/ for more information. 341 342=cut 343 344