view release on metacpan or  search on metacpan

lib/Bytes/Random/Secure.pm  view on Meta::CPAN

you ought to, much less need to.  And if you do, you probably want to use the
C<NonBlocking> option, discussed below.  8192 bits is a lot to ask from a
blocking source such as C</dev/random>, and really anything beyond 512 bits in
the seed is probably wasteful.


=head4 PRNG

Reserved for future use.  Eventually the user will be able to select other RNGs
aside from Math::Random::ISAAC.

=head4 Unique

Reserved for future use.

=head4 Other Crypt::Random::Seed Configuration Parameters

For additional seeding control, refer to the POD for L<Crypt::Random::Seed>.
By supplying a Crypt::Random::Seed parameter to Bytes::Random::Secure's
constructor, it will be passed through to Crypt::Random::Seed.  For example:

    my $random = Bytes::Random::Secure->new( NonBlocking => 1, Bits => 64 );

In this example, C<Bits> is used internally, while C<NonBlocking> is passed
through to Crypt::Random::Seed.


=head2 bytes

    my $random_bytes = $random->bytes(1024);

This works just like the C<random_bytes> function.


=head2 string_from

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

Just like C<random_string_from>: Returns a string of random octets selected
from the "Bag" string (in this case ten octets from 'abcdefg').


=head2 bytes_hex

    my $random_hex = $random->bytes_hex(12);

Identical in function to C<random_bytes_hex>.


=head2 bytes_base64

    my $random_base64 = $random->bytes_base64( 32, EOL => "\n" );

Identical in function to C<random_bytes_base64>.


=head2 bytes_qp

    my $random_qp = $random->bytes_qp( 80 );

You guessed it: Identical in function to C<random_bytes_qp>.


=head2 irand

    my $unsigned_long = $random->irand;

Returns a random 32-bit unsigned integer.  The value will satisfy
C<< 0 <= x <= 2**32-1 >>.  This functionality is only available through the OO
interface.

=head2 shuffle

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

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

L<List::Util>, which ships with Perl, includes C<shuffle> function. But that
function is flawed in two ways. First, from a cryptographic standpoint,
it uses Perl's C<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 C<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.

=head1 CONFIGURATION

L<Bytes::Random::Secure>'s interface tries to I<keep it simple>.  There is
generally nothing to configure.  This design, eliminates much of the  potential
for diminishing the quality of the random byte stream through misconfiguration.
The ISAAC algorithm is used as our factory, seeded with a strong source.

There may be times when the default seed characteristics carry too heavy a
burden on system resources.  The default seed for the functions interface is
256 bits of entropy taken from /dev/random (a blocking source on many systems),
or via API calls on Windows.  The default seed size for the OO interface is also
256 bits. If /dev/random should become depleted at the time that this module
attempts to seed the ISAAC generator, there could be delay while additional
system entropy is generated.  If this is a problem, it is possible to override
the default seeding characteristics using the OO interface instead of the
functions interface.  However, under most circumstances, this capability may be
safely ignored.

Beginning with Bytes::Random::Secure version 0.20, L<Crypt::Random::Seed>
provides our strong seed (previously it was Crypt::Random::Source).  This module
gives us excellent "strong source" failsafe behavior, while keeping the
non-core dependencies to a bare minimum.  Best of all, it performs well across
a wide variety of platforms, and is compatible with Perl versions back through
5.6.0.

And as mentioned earlier in this document, there may be circumstances where
the performance of the operating system's strong random source is prohibitive
from using the module's default seeding configuration.  Use the OO interface
instead, and read the documentation for L<Crypt::Random::Seed> to learn what
options are available.