new

    my $rng = Bytes::Random::Secure::Tiny->new;

Instantiate the pseudo-random number generator object. The seeding of the ISAAC CSPRING defaults to 256 bits from a non-blocking entropy source. The CSPRNG object should be instantiated as infrequently as practical; there is no benefit to re-seeding, with the single cavaet that the CSPRNG object should not be shared by threads or forked processes.

Constructor Parameters

Parameters described below are optional and case-insensitive.

bits

    my $rng = Bytes::Random::Secure::Tiny->new(bits => 512);
    

Number of bits to use in seeding. Must be a value between 64 and 8192 inclusive, and must satisfy "bits==2**n". The default value is 256.

nonblocking

    my $nb_rng = Bytes::Random::Secure::Tiny->new(nonblocking=>1);
    my $bl_rng = Bytes::Random::Secure::Tiny->new(nonblocking=>0);
    

If set to a false value, a blocking entropy source may be used in seeding. This is generally not necessary, as the non-blocking sources used are considered by most to be strong enough for cryptographic purposes.

Instantiating with a blocking source can exhaust system entropy (this has been seen in testing), and in such cases "new" will block until sufficient entropy is generated.

The default is to use a non-blocking source, and you should probably accept that default.

bytes

    my $random_bytes = $rng->bytes($n);

Returns a string of $n random bytes. $n must be a positive integer.

bytes_hex

    my $random_hex = $rng->bytes_hex(6); # E.g. f35dde7c02a4

Returns a string of hex digits. Each byte is represented by two lower-cased hex digits. Therefore, "$rng->bytes_hex(1)" will return a string of length 2, such as "7F". There is no "0x" prepended to the hex digits.

string_from

    my $random_string = $rng->string_from('abcdefg', 10);

Returns a string of random octets selected from the "Bag" string (in this case ten octets from 'abcdefg'). Repeated bag characters are weighted according to their frequency. For example, given the bag 'aabc', the character 'a' will be selected approximately 50% of the time, though being random, there are no guarantees it will be selected at all. For the bag 'abc', each character has the same weight. The output may contain duplicate characters. For example:

    say $rng->string_from('a', 10); # Must always be 'aaaaaaaaaa'

irand

    my $unsigned_long = $random->irand;

Returns a pseudo-random 32-bit unsigned integer. The value will satisfy "0 <= x <= 2**32-1".

shuffle

    my $aref_shuffled = $random->shuffle($aref);

Shuffles the contents of a reference to an array in sitiu, and returns the same reference.

List::Util, which ships with Perl, includes "shuffle" function. But that function is flawed in two ways. First, from a cryptographic standpoint, it uses Perl's "rand", which is not a CSPRNG, and therefore is inadequate.

Second, because Perl's rand has an internal state of just 32 bits, it cannot possibly generate all permutations of arrays containing 13 or more elements.

This module's "shuffle" uses a CSPRNG, and also benefits from large seeds and a huge internal state. ISAAC can be seeded with up to 8192 bits, yielding 2^8192 possible initial states, and 2^8288 possible internal states. A seed of 8192 bits will assure that for arrays of up to 966 elements every permutation is accessible.

STRONG RANDOMNESS

Assuring strong (ie, secure) random bytes in a way that works across a wide variety of platforms is also challenging. A primary goal for this module is to provide cryptographically secure pseudo-random bytes while still meeting the secondary goals of simplicity, minimalism, and no dependencies. If more fine-grained control over seeding methods is needed, use Bytes::Random::Secure instead.

ISAAC

To confirm the quality of the CSPRNG, this module's test suite implements the FIPS-140-1 <http://csrc.nist.gov/publications/fips/fips1401.htm> tests for strong random number generators. See the comments in "t/27-fips140-1.t" for details.

UNICODE SUPPORT

MODULO BIAS