NAME¶
Bytes::Random::Secure - Perl extension to generate cryptographically-secure
random bytes.
SYNOPSIS¶
use Bytes::Random::Secure qw(
random_bytes random_bytes_base64 random_bytes_hex
);
my $bytes = random_bytes(32); # A string of 32 random bytes.
my $bytes = random_string_from( 'abcde', 10 ); # 10 random a,b,c,d, and e's.
my $bytes_as_base64 = random_bytes_base64(57); # Base64 encoded rand bytes.
my $bytes_as_hex = random_bytes_hex(8); # Eight random bytes as hex digits.
my $bytes_as_quoted_printable = random_bytes_qp(100); # QP encoded bytes.
my $random = Bytes::Random::Secure->new(
Bits => 64,
NonBlocking => 1,
); # Seed with 64 bits, and use /dev/urandom (or other non-blocking).
my $bytes = $random->bytes(32); # A string of 32 random bytes.
my $long = $random->irand; # 32-bit random integer.
DESCRIPTION¶
Bytes::Random::Secure provides two interfaces for obtaining crypto-quality
random bytes. The simple interface is built around plain functions. For
greater control over the Random Number Generator's seeding, there is an Object
Oriented interface that provides much more flexibility.
The "functions" interface provides functions that can be used any time
you need a string of a specific number of random bytes. The random bytes are
available as simple strings, or as hex-digits, Quoted Printable, or MIME
Base64. There are equivalent methods available from the OO interface, plus a
few others.
This module can be a drop-in replacement for Bytes::Random, with the primary
enhancement of using a cryptographic-quality random number generator to create
the random data. The "random_bytes" function emulates the user
interface of Bytes::Random's function by the same name. But with
Bytes::Random::Secure the random number generator comes from
Math::Random::ISAAC, and is suitable for cryptographic purposes. The harder
problem to solve is how to seed the generator. This module uses
Crypt::Random::Seed to generate the initial seeds for Math::Random::ISAAC.
In addition to providing "random_bytes()", this module also provides
several functions not found in Bytes::Random: "random_string_from",
"random_bytes_base64()", "random_bytes_hex", and
"random_bytes_qp".
And finally, for those who need finer control over how Crypt::Random::Seed
generates its seed, there is an object oriented interface with a constructor
that facilitates configuring the seeding process, while providing methods that
do everything the "functions" interface can do (truth be told, the
functions interface is just a thin wrapper around the OO version, with some
sane defaults selected). The OO interface also provides an "irand"
method, not available through the functions interface.
RATIONALE¶
There are many uses for cryptographic quality randomness. This module aims to
provide a generalized tool that can fit into many applications while providing
a minimal dependency chain, and a user interface that is simple. You're free
to come up with your own use-cases, but there are several obvious ones:
- •
- Creating temporary passphrases ("random_string_from()").
- •
- Generating per-account random salt to be hashed along with passphrases
(and stored alongside them) to prevent rainbow table attacks.
- •
- Generating a secret that can be hashed along with a cookie's session
content to prevent cookie forgeries.
- •
- Building raw cryptographic-quality pseudo-random data sets for testing or
sampling.
- •
- Feeding secure key-gen utilities.
Why use this module? This module employs several well-designed CPAN tools to
first generate a strong random seed, and then to instantiate a high quality
random number generator based on the seed. The code in this module really just
glues together the building blocks. However, it has taken a good deal of
research to come up with what I feel is a strong tool-chain that isn't going
to fall back to a weak state on some systems. The interface is designed with
simplicity in mind, to minimize the potential for misconfiguration.
EXPORTS¶
By default "random_bytes" is the only function exported. Optionally
"random_string_from", "random_bytes_base64",
"random_bytes_hex", and "random_bytes_qp" may be exported.
FUNCTIONS¶
The
functions interface seeds the ISAAC generator on first use with a 256
bit seed that uses Crypt::Random::Seed's default configuration as a strong
random seed source.
random_bytes¶
my $random_bytes = random_bytes( 512 );
Returns a string containing as many random bytes as requested. Obviously the
string isn't useful for display, as it can contain any byte value from 0
through 255.
The parameter is a byte-count, and must be an integer greater or equal to zero.
random_string_from¶
my $random_bytes = random_string_from( $bag, $length );
my $random_bytes = random_string_from( 'abc', 50 );
$bag is a string of characters from which "random_string_from" may
choose in building a random string. We call it a 'bag', because it's
permissible to have repeated chars in the bag (if not, we could call it a
set). Repeated digits get more weight. For example, "random_string_from(
'aab', 1 )" would have a 66.67% chance of returning an 'a', and a 33.33%
chance of returning a 'b'. For unweighted distribution, ensure there are no
duplicates in $bag.
This
isn't a "draw and discard", or a permutation algorithm;
each character selected is independent of previous or subsequent selections;
duplicate selections are possible by design.
Return value is a string of size $length, of characters chosen at random from
the 'bag' string.
It is perfectly legal to pass a Unicode string as the "bag", and in
that case, the yield will include Unicode characters selected from those
passed in via the bag string.
This function is useful for random string generation such as temporary random
passwords.
random_bytes_base64¶
my $random_bytes_b64 = random_bytes_base64( $num_bytes );
my $random_bytes_b64_formatted = random_bytes_base64( $num_bytes, $eol );
Returns a MIME Base64 encoding of a string of $number_of_bytes random bytes.
Note, it should be obvious, but is worth mentioning that a base64 encoding of
base256 data requires more digits to represent the bytes requested. The actual
number of digits required, including padding is "4(n/3)".
Furthermore, the Base64 standard is to add padding to the end of any string
for which "length % 57" is a non-zero value.
If an $eol is specified, the character(s) specified will be used as line
delimiters after every 76th character. The default is "qq{\n}". If
you wish to eliminate line-break insertions, specify an empty string:
"q{}".
random_bytes_hex¶
my $random_bytes_as_hex = random_bytes_hex( $num_bytes );
Returns a string of hex digits representing the string of $number_of_bytes
random bytes.
It's worth mentioning that a hex (base16) representation of base256 data
requires two digits for every byte requested. So "length(
random_bytes_hex( 16 ) )" will return 32, as it takes 32 hex digits to
represent 16 bytes. Simple stuff, but better to mention it now than forget and
set a database field that's too narrow.
random_bytes_qp¶
my $random_bytes_qp = random_bytes_qp( $num_bytes );
my $random_bytes_qp_formatted = random_bytes_qp( $num_bytes, $eol );
Produces a string of $num_bytes random bytes, using MIME Quoted Printable
encoding (as produced by MIME::QuotedPrint's "encode_qp" function.
The default configuration uses "\n" as a line break after every 76
characters, and the "binmode" setting is used to guarantee a
lossless round trip. If no line break is wanted, pass an empty string as $eol.
METHODS¶
The
Object Oriented interface provides methods that mirror the
"functions" interface. However, the OO interface offers the
advantage that the user can control how many bits of entropy are used in
seeding, and even how Crypt::Random::Seed is configured.
new¶
my $random = Bytes::Random::Secure->new( Bits => 512 );
my $bytes = $random->bytes( 32 );
The constructor is used to specify how the ISAAC generator is seeded. Future
versions may also allow for alternate CSPRNGs to be selected. If no parameters
are passed the default configuration specifies 256 bits for the seed. The rest
of the default configuration accepts the Crypt::Random::Seed defaults, which
favor the strongest operating system provided entropy source, which in many
cases may be "blocking".
CONSTRUCTOR PARAMETERS
Bits
my $random = Bytes::Random::Secure->new( Bits => 128 );
The "Bits" parameter specifies how many bits (rounded up to nearest
multiple of 32) will be used in seeding the ISAAC random number generator. The
default is 256 bits of entropy. But in some cases it may not be necessary, or
even wise to pull so many bits of entropy out of "/dev/random" (a
blocking source).
Any value between 64 and 8192 will be accepted. If an out-of-range value is
specified, or a value that is not a multiple of 32, a warning will be
generated and the parameter will be rounded up to the nearest multiple of 32
within the range of 64 through 8192 bits. So if 16384 is specified, you will
get 8192. If 33 is specified, you will get 64.
Note: In the Perlish spirit of "
no arbitrary limits",
the maximum number of bits this module accepts is 8192, which is the maximum
number that ISAAC can utilize. But just because you
can specify a seed
of 8192 bits doesn't mean you ought to, much less need to. And if you do, you
probably want to use the "NonBlocking" option, discussed below. 8192
bits is a lot to ask from a blocking source such as "/dev/random",
and really anything beyond 512 bits in the seed is probably wasteful.
PRNG
Reserved for future use. Eventually the user will be able to select other RNGs
aside from Math::Random::ISAAC.
Unique
Reserved for future use.
Other Crypt::Random::Seed Configuration Parameters
For additional seeding control, refer to the POD for 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, "Bits" is used internally, while
"NonBlocking" is passed through to Crypt::Random::Seed.
bytes¶
my $random_bytes = $random->bytes(1024);
This works just like the "random_bytes" function.
string_from¶
my $random_string = $random->string_from( 'abcdefg', 10 );
Just like "random_string_from": Returns a string of random octets
selected from the "Bag" string (in this case ten octets from
'abcdefg').
bytes_hex¶
my $random_hex = $random->bytes_hex(12);
Identical in function to "random_bytes_hex".
bytes_base64¶
my $random_base64 = $random->bytes_base64( 32, EOL => "\n" );
Identical in function to "random_bytes_base64".
bytes_qp¶
my $random_qp = $random->bytes_qp( 80 );
You guessed it: Identical in function to "random_bytes_qp".
irand¶
my $unsigned_long = $random->irand;
Returns a random 32-bit unsigned integer. The value will satisfy "0 <= x
<= 2**32-1". This functionality is only available through the OO
interface.
CONFIGURATION¶
Bytes::Random::Secure's interface tries to
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, 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 Crypt::Random::Seed to learn what
options are available.
Prior to version 0.20, a heavy dependency chain was required for reliably and
securely seeding the ISAAC generator. Earlier versions required
Crypt::Random::Source, which in turn required Any::Moose. Thanks to Dana
Jacobsen's new Crypt::Random::Seed module, this situation has been resolved.
So if you're looking for a secure random bytes solution that "just
works" portably, and on Perl versions as far back as 5.6.0, you've come
to the right place. Users of older versions of this module are encouraged to
update to version 0.20 or higher to benefit from the improved user interface
and lighter dependency chain.
OPTIONAL (RECOMMENDED) DEPENDENCY¶
If performance is a consideration, you may also install Math::Random::ISAAC::XS.
Bytes::Random::Secure's random number generator uses Math::Random::ISAAC. That
module implements the ISAAC algorithm in pure Perl. However, if you install
Math::Random::ISAAC::XS, you get the same algorithm implemented in C/XS, which
will provide better performance. If you need to produce your random bytes more
quickly, simply installing Math::Random::ISAAC::XS will result in it
automatically being used, and a pretty good performance improvement will
coincide.
CAVEATS¶
FORK AND THREAD SAFETY¶
When programming for parallel computation, avoid the "functions"
interface
do use the Object Oriented interface, and create a unique
"Bytes::Random::Secure" object within each process or thread.
Bytes::Random::Secure uses a CSPRNG, and sharing the same RNG between threads
or processes will share the same seed and the same starting point. This is
probably not what one would want to do. By instantiating the B::R::S object
after forking or creating threads, a unique randomness stream will be created
per thread or process.
STRONG RANDOMNESS¶
It's easy to generate weak pseudo-random bytes. It's also easy to think you're
generating strong pseudo-random bytes when really you're not. And it's hard to
test for pseudo-random cryptographic acceptable quality. There are many high
quality random number generators that are suitable for statistical purposes,
but not necessarily up to the rigors of cryptographic use.
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. A secondary goal is to
provide a simple user experience (thus reducing the propensity for getting it
wrong). A tertiary goal is to minimize the dependencies required to achieve
the primary and secondary goals, to the extent that is practical.
ISAAC¶
The ISAAC algorithm is considered to be a cryptographically strong pseudo-random
number generator. There are 1.0e2466 initial states. The best known attack for
discovering initial state would theoretically take a complexity of
approximately 4.67e1240, which has no practical impact on ISAAC's security.
Cycles are guaranteed to have a minimum length of 2**40, with an average cycle
of 2**8295. Because there is no practical attack capable of discovering
initial state, and because the average cycle is so long, it's generally
unnecessary to re-seed a running application. The results are uniformly
distributed, unbiased, and unpredictable unless the seed is known.
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.
DEPENDENCIES¶
To keep the dependencies as light as possible this module uses some ideas from
Math::Random::Secure. That module is an excellent resource, but implements a
broader range of functionality than is needed here. So we just borrowed from
it.
The primary source of random data in this module comes from the excellent
Math::Random::ISAAC. To be useful and secure, even Math::Random::ISAAC needs a
cryptographically sound seed, which we derive from Crypt::Random::Seed. There
are no known weaknesses in the ISAAC algorithm. And Crypt::Random::Seed does a
very good job of preventing fall-back to weak seed sources.
This module requires Perl 5.6 or newer. The module also uses a number of core
modules, some of which require newer versions than those contemporary with
5.6. Unicode support in "random_string_from" is best with Perl 5.8.9
or newer. See the INSTALLATION section in this document for details.
If Test::Warn is installed, test coverage is 100%. For those who don't want to
bother installing Test::Warn, you can just take our word for it. It's an
optional installation dependency.
BLOCKING ENTROPY SOURCE¶
It is possible (and has been seen in testing) that the system's random entropy
source might not have enough entropy in reserve to generate the seed requested
by this module without blocking. If you suspect that you're a victim of
blocking from reads on "/dev/random", one option is to manipulate
the random seed configuration by using the object oriented interface.
This module seeds as lazily as possible so that using the module, and even
instantiating a Bytes::Random::Secure object will not trigger reads from
"/dev/random". Only the first time the object is used to deliver
random bytes will the RNG be seeded. Long-running scripts may prefer to force
early seeding as close to start-up time as possible, rather than allowing it
to happen later in a program's run-time. This can be achieved simply by
invoking any of the functions or methods that return a random byte. As soon as
a random byte is requested for the first time, the CSPRNG will be seeded.
UNICODE SUPPORT¶
The "random_string_from" function, and "string_from" method
permit the user to pass a "bag" (or source) string containing
Unicode characters. For any modern Perl version, this will work just as you
would hope. But some versions of Perl older than 5.8.9 exhibited varying
degrees of bugginess in their handling of Unicode. If you're depending on the
Unicode features of this module while using Perl versions older than 5.8.9 be
sure to test thoroughly, and don't be surprised when the outcome isn't as
expected. ...this is to be expected. Upgrade.
No other functions or methods in this module get anywhere near Perl's Unicode
features. So as long as you're not passing Unicode source strings to
"random_string_from", you have nothing to worry about, even if
you're using Perl 5.6.0.
MODULO BIAS¶
Care is taken so that there is no modulo bias in the randomness returned either
by "random_bytes" or its siblings, nor by
"random_string_from". As a matter if fact, this is exactly
why the "random_string_from" function is useful. However, the
algorithm to eliminate modulo bias can impact the performance of the
"random_string_from" function. Any time the length of the bag string
is significantly less than the nearest greater or equal factor of 2**32,
performance will degrade. Unfortunately there is no known algorithm that
improves upon this situation. Fortunately, for sanely sized strings, it's a
minor issue. To put it in perspective, even in the case of passing a
"bag" string of length 2**31 (which is huge), the expected time to
return random bytes will only double. Given that the entire Unicode range is
just over a million possible code-points, it seems unlikely that the normal
use case would ever have to be concerned with the performance of the
"random_string_from" function.
INSTALLATION¶
This module should install without any fuss on modern versions of Perl. For
older Perl versions (particularly 5.6 and early 5.8.x's), it may be necessary
to update your CPAN installer to a more modern version before installing this
this module.
Another alternative for those with old Perl versions who don't want to update
their CPAN installer (You must know you're crazy, right?): Review
"Makefile.PL" and assure that you've got the dependencies listed
under "PREREQ_PM" and "BUILD_REQUIRES", in at least the
minimum versions specified. Then proceed as usual.
This module only has two non-Core dependencies. But it does expect that some of
the Core dependencies are newer than those supplied with 5.6 or early 5.8's.
If you keep your CPAN installer up-to-date, you shouldn't have to think about
this, as it will usually just "do the right thing", pulling in newer
dependency versions as directed by the module's META files.
Test coverage for Bytes::Random::Secure is 100% (per Devel::Cover) on any system
that has Test::Warn installed. But to keep the module light-weight, Test::Warn
is not dragged in by default at installation time.
AUTHOR¶
David Oswald "<davido [at] cpan (dot) org>"
BUGS¶
Please report any bugs or feature requests to "bug-bytes-random-secure at
rt.cpan.org", or through the web interface at
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bytes-Random-Secure>. 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 Bytes::Random::Secure
You can also look for information at:
- •
- Github Repo: <https://github.com/daoswald/Bytes-Random-Secure>
- •
- RT: CPAN's request tracker (report bugs here)
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Bytes-Random-Secure>
- •
- AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Bytes-Random-Secure>
- •
- CPAN Ratings
<http://cpanratings.perl.org/d/Bytes-Random-Secure>
- •
- Search CPAN
<http://search.cpan.org/dist/Bytes-Random-Secure/>
ACKNOWLEDGEMENTS¶
Dana Jacobsen (
<dana@acm.org> ) for his work that led to
Crypt::Random::Seed, thereby significantly reducing the dependencies while
improving the portability and backward compatibility of this module. Also for
providing a patch to this module that greatly improved the performance of
"random_bytes".
Dana Jacosen also provided extensive input, code reviews, and testing that
helped to guide the direction this module has taken. The code for the
FIPS-140-1 tests was taken directly from Crypt::Random::TESHA2. Thanks!
Bytes::Random for implementing a nice, simple interface that this module
patterns itself after.
LICENSE AND COPYRIGHT¶
Copyright 2012 David Oswald.
This program is free software; you can redistribute it and/or modify it under
the terms of either: the GNU General Public License as published by the Free
Software Foundation; or the Artistic License.
See
http://dev.perl.org/licenses/ for more information.