/ 
Crypt-DRBG-0.001000
River stage zero No dependents
/ Crypt::DRBG

NAME

Crypt::DRBG - Base class for fast, cryptographically-secure PRNGs

SYNOPSIS

use Crypt::DRBG::HMAC;

my $drbg = Crypt::DRBG::HMAC->new(auto => 1);
my $data = $drbg->generate(42);
... # do something with your 42 bytes here

my $drbg2 = Crypt::DRBG::HMAC->new(seed => "my very secret seed");
my @randdigits = $drbg->randitems(20, [0..9]);
... # do something with your 20 random digits here

DESCRIPTION

Crypt::DRBG is a collection of fast, cryptographically-secure PRNGs (pseudo-random number generators). It can be useful for a variety of situations:

  • Cryptographically secure random numbers are needed in production, but for testing reproducibility is needed

  • A large number of random values are needed, but using /dev/urandom (or the equivalent) frequently or persistently is unsuitable

  • Selection of random values in a range (e.g. digits, letters, identifiers) is required and biasing the results is unacceptable

Crypt::DRBG::HMAC is the recommended class to use, as it's currently the fastest. All algorithms are assumed to provide equivalent security.

SUBROUTINES/METHODS

initialize(%params)

%params can contain the following:

auto

If true, use a safe, cryptographically-secure set of defaults. Equivalent to specifying autoseed, autononce, autopersonalize, and fork_safe.

autoseed

If true, derive a seed from Crypt::URandom, if available, or from /dev/urandom, /dev/arandom, or /dev/random, in that order. Windows support requires Crypt::URandom to function properly.

seed

If a string, use this value as the seed. If a coderef, call this coderef with a single argument (the number of bytes) to obtain an entropy input. Note that if a string is used, an exception will be thrown if a reseed is required.

autononce

If true, derive a nonce automatically.

nonce

If a string, use this value as the nonce. If a coderef, call this coderef with a single argument (the number of bytes) to obtain a nonce.

autopersonalize

If true, derive a personalization string automatically.

personalize

If a string, use this value as the personalization string. If a coderef, call this coderef to obtain a personalization string.

fork_safe

If true, reseed on fork. If false, the parent and child processes will produce the same sequence of bytes (not recommended).

cache

If enabled, keep a cache of this many bytes and use it to satisfy requests before generating more.

$drbg->generate($bytes, $additional_data)

Generate and return $bytes bytes. There is a limit per algorithm on the number of bytes that can be requested at once, which is at least 2^10.

If $additional_data is specified, add this additional data to the DRBG.

If the cache flag was specified on instantiation, bytes will be satisfied from the cache first, unless $additional_data was specified.

$drbg->rand([$n], [$num])

Like Perl's rand, but cryptographically secure. Uses 32-bit values.

Accepts an additional argument, $num, which is the number of values to return. Defaults to 1 (obviously).

Note that just as with Perl's rand, there may be a slight bias with this function. Use randitems if that matters to you.

Returns an array if $num is specified and a single item if it is not.

$drbg->randitems($n, $items)

Select randomly and uniformly from the arrayref $items $n times.

$drbg->randbytes($n, $items)

Select randomly and uniformly from the characters in arrayref $items $n times. Returns a byte string.

This function works just like randitems, but is more efficient if generating a sequence of bytes as a string instead of an array.

AUTHOR

brian m. carlson, <sandals at crustytoothpaste.net>

BUGS

Please report any bugs or feature requests to bug-crypt-drbg at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Crypt-DRBG. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Crypt::DRBG

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2015 brian m. carlson.

This program is distributed under the MIT (X11) License: http://www.opensource.org/licenses/mit-license.php

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.