Commit d4a41732 authored by gregor herrmann's avatar gregor herrmann

Import original source of Bytes-Random-Secure 0.25

parents
Revision history for Bytes::Random::Secure
0.25 2012-02-23
- Removed the speed test / fall-back from t/27-fips140-1.t; it's unnecessary,
and could cause divide by zero errors on really fast systems.
0.24 2012-02-22
- Added a small explanation of Test::Warn optional dependency to the
DEPENDENCIES section of the POD. Most of the explanation is in the
INSTALLATION section.
- Added t/27-fips140-1.t: Code taken directly from Dana Jacobsen's
Crypt::Random::TESHA2 module's test suite. This test implements the
FIPS 140-1 tests. See http://csrc.nist.gov/publications/fips/fips1401.htm
- Removed "slow" tests from t/20-functions.t: The FIPS-140 tests are superior
and make the older slow tests unnecessary.
0.23 2012-02-11
- Clarified the (small) magnitude of the performance issues surrounding
random_string_from() (MODULO BIAS section of POD). (DANAJ's suggestion.)
- Added a test for _closest_divisor().
- Added a POD section discussing ISAAC's strengths.
- Increased SEED_MAX bits from 512 (arbitrary) to 8192 (theoretical
max for ISAAC). Added explanation to POD, and adjusted tests.
- Minor corrections in # code comments (accuracy).
- Added irand() object method per Dana Jacobsen's request and
code contribution.
- POD and tests for irand().
- Test::Warn is now an optional dependency. By ensuring that Test::Warn is
installed, the module has 100% test coverage (per Devel::Cover).
0.22 2013-01-29
- Implement suggestions from Dana Jacobsen (Unicode tests, specify minimum
versions for dependencies, document installation on older Perls).
- POD correction -- Removed reference to config_seed.
- POD: Added INSTALLATION section to address issues with older Perls.
- POD: Clarified "CAVEATS" with discussion of Unicode support in pre-5.8.9.
- Added t/23-string_from_unicode.t to test Unicode on Perl 5.8.9+.
- Added a Unicode example to examples/random_from.pl.
- Set a CONFIGURE_REQUIRES to pull in a recent ExtUtils::MakeMaker.
- Set minimum versions on some Core modules from which we're using newer
features, or which behaved badly in old 5.6.x-contemporary versions.
0.21 2013-01-24
- All functions and methods will now throw an exception if the byte-count
parameter is passed something that doesn't look like an integer >= 0.
- examples/*.pl updated to demonstrate new features.
- Remove silly check for "bag" strings longer than 2**32.
- Eliminate a line of unreachable code from _closest_divisor().
- Test coverage is now 100%.
0.20 2013-01-24
- This is a major release. Much thanks to Dana Jacobson for his ideas,
suggestions, code reviews, and for writing Crypt::Random::Seed.
- Major refactoring / rewrite.
- Built an OO base layer over which the functions interface is a thin wrapper.
- OO interface exposed publically.
- Documented all functions. (POD)
- removed config_seed() (never publically released).
- Seed defaults for both interfaces are 256 bits.
- Major enhancements to test suite. (Coverage is 99.3%)
- ALL OF THE FOLLOWING CHANGES ARE FROM (UNRELEASED) 0.13:
- * Compatible with Perl 5.6.
- * Dropped Crypt::Random::Source dependency in favor of Crypt::Random::Seed.
- * Seeding is lazy.
- * Minimum seed size: 2-longs (64 bits). Maximum, 16 longs (512 bits).
- * Documented how to configure seeding.
0.13 2013-01-15 (Never released)
- POD clarification, enhancement.
- Improved backwards compatibility support for Perl v5.6.x.
- Eliminated Crypt::Random::Source dependency in favor of Crypt::Random::Seed;
Thanks to Dana Jacobsen for creating that light-weight and powerful tool.
- Added some seed tests.
- Made Test::Pod::Coverage a 'RELEASE_TESTING' only test.
- Made seeding and RNG-instantiation "lazy" so that
"use Bytes::Random::Secure;" only drains system entropy if random bytes are
actually requested. (Thanks again to Dana Jacobsen for the idea).
- Modified _seed() to pass seed configuration through to Crypt::Random::Seed's
constructor.
- Added a config_seed() class method to facilitate configuration of
the Crypt::Random::Seed object used in seeding the ISAAC algorithm.
- Minimum seed size set to 2-longs, max to 16-longs (default).
- Documented how to configure the seeding, and explained why it might be
useful to do so (drain less system entropy).
- Added META.* tests.
0.12 2012-12-09
- Applied rewrite of random_bytes() from Dana Jacobsen, that improves
performance while at the same time making better use of the 32 bit random
value returned by ISAAC.
- POD fixes/tweaks.
0.11 2012-12-05
- Fixed a few issues where v0.10 broke compatibility with Perls older than
v5.10. (Removed // operator.)
- POD improvements.
- Added a few entries in MANIFEST.SKIP.
0.10 2012-12-04
- Better handling of random_bytes() (no parameter passed): Now defaults to
zero bytes explicitly, so we don't get "uninitialized values" warnings.
- Added random_string_from($bag,$length) function.
- Added tests for no param list, as well as for new random_string_from()
function and its support functions.
- POD enhancements.
- Removed bytes pragma; it wasn't necessary, and prevented support for
unicode code points in random_string_from()'s bag.
0.09 2012-11-02
- "Changes" is now CPAN::Changes::Spec compliant.
- Added t/09-changes.t to verify spec compliance.
0.08 2012-10-28
- Added an example in the ./examples/ directory.
- Added a minimum Perl version to the distribution metadata.
0.07 2012-09-23
- Refined t/20-functionality.t's approach toward verifying bytes seem well
behaved.
- Corrected a couple of POD problems.
- Note: Under Moose the test suite generates a few warnings. Not sure what
the best solution will be (they're harmless but annoying).
0.06 2012-09-21
- Fixed the optionality of t/21-bytes_random_tests.t.
- Documented the install process in README.
0.05 2012-09-20
- POD revisions: Better details on dependencies, minimizing bloat, and
Win32-specific requirements.
- 21-bytes_random_tests.t is now optional, because Statistics::Basic will
fail to install in some environments due to a problem in one of its
dependencies (Number::Format).
0.04 2012-09-19
- Added t/21-bytes_random_tests.t, which is an adaptation of the test suite
for the Bytes::Random module.
- Added a BUILD_REQUIRES dependency to accommodate the Bytes::Random tests.
0.03 2012-09-18
- POD enhancements, explaining the dependency chain, and how to minimize
the Any::Moose impact by ensuring Mouse is installed.
- Removed syntax that was only valid for newer versions of Perl. We should
be 5.6.x compatible now.
- Placed the random number factory in a closure, making it only accessable
by the accessor random_bytes().
- Added some tests for seed generation since we took that functionality
away from Math::Random::Secure when we removed it from our list of
dependencies in v0.02.
- Added a Win32 test to Makefile.PL so that a Windows-only dependency will
be included if necessary.
0.02 2012-09-17
- Removed Math::Random::Secure dependency.
- Added Math::Random::ISAAC and Crypt::Random::Source dependencies (they
were already dependencies of Math::Random::Secure, so we're actually a
little lighter-weight now).
- POD enhancements: Explain Math::Random::ISAAC::XS plugin, explain
dependency chain, and explain why it gets a whole lot worse under Windows.
0.01 2012-09-06
- Initial CPAN release.
Changes
lib/Bytes/Random/Secure.pm
Makefile.PL
MANIFEST This list of files
README
META.json
META.yml
t/00-boilerplate.t
t/01-manifest.t
t/02-pod.t
t/03-pod-coverage.t
t/04-perlcritic.t
t/05-kwalitee.t
t/06-meta-yaml.t
t/07-meta-json.t
t/09-changes.t
t/10-prereqs.t
t/11-load.t
t/20-functions.t
t/21-bytes_random_tests.t
t/22-random_string_from.t
t/23-string_from_unicode.t
t/24-oo_construct.t
t/26-oo_public.t
t/27-fips140-1.t
examples/random-sha512.pl
examples/random-sha512-oo.pl
examples/random-from.pl
{
"abstract" : "Perl extension to generate cryptographically-secure",
"author" : [
"David Oswald <davido@cpan.org>"
],
"dynamic_config" : 1,
"generated_by" : "ExtUtils::MakeMaker version 6.6302, CPAN::Meta::Converter version 2.120921",
"license" : [
"perl_5"
],
"meta-spec" : {
"url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
"version" : "2"
},
"name" : "Bytes-Random-Secure",
"no_index" : {
"directory" : [
"t",
"inc"
]
},
"prereqs" : {
"build" : {
"requires" : {
"Test::More" : "0.98"
}
},
"configure" : {
"requires" : {
"ExtUtils::MakeMaker" : "6.56"
}
},
"runtime" : {
"requires" : {
"Carp" : "0",
"Crypt::Random::Seed" : "0",
"MIME::Base64" : "0",
"MIME::QuotedPrint" : "3.03",
"Math::Random::ISAAC" : "0",
"Scalar::Util" : "1.21",
"perl" : "5.006000"
}
}
},
"release_status" : "stable",
"resources" : {},
"version" : "0.25"
}
---
abstract: 'Perl extension to generate cryptographically-secure'
author:
- 'David Oswald <davido@cpan.org>'
build_requires:
Test::More: 0.98
configure_requires:
ExtUtils::MakeMaker: 6.56
dynamic_config: 1
generated_by: 'ExtUtils::MakeMaker version 6.6302, CPAN::Meta::Converter version 2.120921'
license: perl
meta-spec:
url: http://module-build.sourceforge.net/META-spec-v1.4.html
version: 1.4
name: Bytes-Random-Secure
no_index:
directory:
- t
- inc
requires:
Carp: 0
Crypt::Random::Seed: 0
MIME::Base64: 0
MIME::QuotedPrint: 3.03
Math::Random::ISAAC: 0
Scalar::Util: 1.21
perl: 5.006000
resources: {}
version: 0.25
use 5.006000;
use strict;
use warnings;
use ExtUtils::MakeMaker;
my %PREREQ_PM = (
'Crypt::Random::Seed' => '0', # Provides a high quality seed.
'Math::Random::ISAAC' => '0', # Provides our random number generator.
'MIME::Base64' => '0', # Core.
'MIME::QuotedPrint' => '3.03', # Core, but minimum version requirement.
'Carp' => '0', # Core.
'Scalar::Util' => '1.21', # Core, but minimum version requirement.
);
WriteMakefile(
NAME => 'Bytes::Random::Secure',
AUTHOR => q{David Oswald <davido@cpan.org>},
VERSION_FROM => 'lib/Bytes/Random/Secure.pm',
ABSTRACT_FROM => 'lib/Bytes/Random/Secure.pm',
( $ExtUtils::MakeMaker::VERSION >= 6.3002
? ( 'LICENSE' => 'perl' )
: () ),
PL_FILES => {},
CONFIGURE_REQUIRES => {
'ExtUtils::MakeMaker' => '6.56',
},
BUILD_REQUIRES => {
'Test::More' => '0.98', # A recent version is needed.
},
MIN_PERL_VERSION => '5.006000',
PREREQ_PM => \%PREREQ_PM,
META_MERGE => {
'resources' => {
'repository' => {
'url' => 'git://github.com/daoswald/Bytes-Random-Secure.git',
'web' => 'http://github.com/daoswald/Bytes-Random-Secure',
'type' => 'git',
},
},
},
dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
clean => { FILES => 'Bytes-Random-Secure-*', },
);
Bytes::Random::Secure
Generate strings of cryptographic-quality pseudo-random bytes as a string of
raw bytes, hex digits, MIME Base64, MIME QuotedPrintable, or just long ints.
CONFIGURATION
If you require better performance, install Math::Random::ISAAC::XS. It will
be automatically detected, and will provide better performance as you generate
random bytes.
INSTALLATION
To install this module, run the following commands:
perl Makefile.PL
make
make test
make install
Or preferably, let your favorite CPAN installer do the work for you. Users
are encouraged to use a fairly modern version of their CPAN installer,
particularly if building this distribution on Perl versions that
preceed Perl 5.8.9.
SUPPORT AND DOCUMENTATION
After installing, you can find documentation for this module with the
perldoc command.
perldoc Bytes::Random::Secure
You can also look for information at:
Github Repository
https://github.com/daoswald/Bytes-Random-Secure.git
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/
LICENSE AND COPYRIGHT
Copyright (C) 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.
use strict;
use warnings;
use utf8;
use Bytes::Random::Secure qw( random_string_from );
my $quantity = 64;
my $bag = 'abcde';
# Generate a random string of 64 characters, each selected from
# the "bag" of 'a' through 'e', inclusive.
my $string = random_string_from( $bag, $quantity );
print $string, "\n";
# Unicode strings are ok too (Perl 5.8.9 or better):
if( $^V && $^V ge v5.8.9 ) {
$string = random_string_from( 'Ѧѧ', 64 );
binmode STDOUT, ':encoding(UTF-8)';
print $string, "\n";
}
use strict;
use warnings;
use Bytes::Random::Secure qw();
use Digest::SHA qw( sha512_base64 );
my $quantity = 128;
# Instantiate a random generator with a customized seed:
my $random = Bytes::Random::Secure->new( Bits => 64, NonBlocking => 1 );
# Get a string of 128 random bytes.
my $bytes = $random->bytes($quantity);
# And just for fun, generate a base64 encoding of a sha2-512 digest of the
# random byte string.
my $digest = sha512_base64( $bytes );
print "$digest\n";
use strict;
use warnings;
use Bytes::Random::Secure qw( random_bytes );
use Digest::SHA qw( sha512_base64 );
my $quantity = 128;
# Get a string of 128 random bytes.
my $bytes = random_bytes($quantity);
# And just for fun, generate a base64 encoding of a sha2-512 digest of the
# random byte string.
my $digest = sha512_base64( $bytes );
print "$digest\n";
This diff is collapsed.
#!/usr/bin/env perl
use 5.006;
use strict;
use warnings;
use Test::More tests => 3;
sub not_in_file_ok {
my ( $filename, %regex ) = @_;
my %violated;
## no critic (RequireBriefOpen)
open my $fh, '<', $filename
or die "couldn't open $filename for reading: $!";
while ( my $line = <$fh> ) {
while ( my ( $desc, $regex ) = each %regex ) {
if ( $line =~ $regex ) {
push @{ $violated{$desc} ||= [] }, $.;
}
}
}
close $fh;
if (%violated) {
fail("$filename contains boilerplate text");
diag "$_ appears on lines @{$violated{$_}}" for keys %violated;
}
else {
pass("$filename contains no boilerplate text");
}
return;
}
sub module_boilerplate_ok {
my ($module) = @_;
not_in_file_ok(
$module => 'the great new $MODULENAME' => qr/ - The great new /,
'boilerplate description' => qr/Quick summary of what the module/,
'stub function definition' => qr/function[12]/,
);
return;
}
not_in_file_ok(
README => "The README is used..." => qr/The README is used/,
"'version information here'" => qr/to provide version information/,
);
not_in_file_ok( Changes => "placeholder date/time" => qr(Date/time) );
module_boilerplate_ok('lib/Bytes/Random/Secure.pm');
#!/usr/bin/env perl
use strict;
use warnings;
use Test::More;
unless ( $ENV{RELEASE_TESTING} ) {
plan( skip_all => "Author tests not required for installation" );
}
eval "use Test::CheckManifest 0.9"; ## no critic (eval)
plan skip_all => "Test::CheckManifest 0.9 required" if $@;
ok_manifest();
## no critic(RCS,VERSION,explicit,Module)
use strict;
use warnings;
use Test::More;
if ( $ENV{RELEASE_TESTING} ) {
eval 'use Test::Pod 1.00'; ## no critic (eval)
if ($@) { plan skip_all => 'Test::Pod 1.00 required for testing POD'; }
}
else {
plan skip_all => 'Skip Test::Pod tests unless environment variable '
. 'RELEASE_TESTING is set.';
}
all_pod_files_ok();
#!/usr/bin/env perl
use strict;
use warnings;
use Test::More;
# Minimum versions:
my $min_tpc = '1.08'; # Test::Pod::Coverage minimum.
# Older versions of Pod::Coverage don't recognize some common POD styles.
my $min_pc = '0.18'; # Pod::Coverage minimum.
unless(
$ENV{RELEASE_TESTING}
&& eval "use Test::Pod::Coverage $min_tpc; 1;" ## no critic (eval)
&& eval "use Pod::Coverage $min_pc; 1;" ## no critic (eval)
) {
plan skip_all =>
"POD Coverage tests only run when RELEASE_TESTING is set, *and*\n" .
"both Test::Pod::Coverage and Pod::Coverage are available on target system.";
}
all_pod_coverage_ok();
#!/usr/bin/env perl
use strict;
use warnings;
use Test::More;
use English qw( -no_match_vars );
# To enable this suite one must set the RELEASE_TESTING environment variable
# to a true value.
# This prevents author tests from running on a user install.
# It's possible users would have their own conflicting Perl::Critic config,
# so it would be a bad idea to let this test run on users systems.
if ( not $ENV{RELEASE_TESTING} ) {
my $msg = 'Author Test: Set $ENV{RELEASE_TESTING} to a true value to run.';
plan( skip_all => $msg );
}
# We also don't want to force a dependency on Test::Perl::Critic, so if the
# user doesn't have the module, we won't run the test.
eval { require Test::Perl::Critic; 1; };
if ($EVAL_ERROR) {
my $msg = 'Author Test: Test::Perl::Critic required to criticise code.';
plan( skip_all => $msg );
}
# Set a higher severity level. Note: List/BinarySearch.pm meets level 2.
Test::Perl::Critic->import( -severity => 4 );
# We want to test the primary module components (blib/) as well as the
# test suite (t/).
my @directories = qw{ blib/ t/ };
Test::Perl::Critic::all_critic_ok(@directories);
done_testing();
## no critic(RCS,VERSION,explicit,Module)
use strict;
use warnings;
use Test::More;
# To enable this suite one must set $ENV{RELEASE_TESTING} to a true value.
# This prevents author tests from running on a user install.
if ( not $ENV{RELEASE_TESTING} ) {
my $msg = 'Author Test: Set $ENV{RELEASE_TESTING} to a true value to run.';
plan( skip_all => $msg );
}
eval { require Test::Kwalitee; Test::Kwalitee->import() }; ## no critic (eval)
if ($@) {
plan( skip_all => 'Test::Kwalitee not installed; skipping' );
}
done_testing();
# Clean up. I haven't traced out where this is getting created, but we
# certainly don't need to leave it behind as clutter.
if ( -e 'Debian_CPANTS.txt' ) {
unlink 'Debian_CPANTS.txt';
}
## no critic(RCS,VERSION,explicit,Module,eval)
use strict;
use warnings;
use Test::More;
if( ! $ENV{RELEASE_TESTING} ) {
plan skip_all =>
'Author only test: META.yml tests run only if RELEASE_TESTING set.';
}
elsif ( ! eval 'use Test::CPAN::Meta::YAML; 1;' ) {
plan skip_all =>
'Author META.yml test requires Test::CPAN::Meta::YAML.'
}
else {
note 'Testing META.yml';
}
meta_yaml_ok();
## no critic(RCS,VERSION,explicit,Module,eval)
use strict;
use warnings;
use Test::More;
if( ! $ENV{RELEASE_TESTING} ) {
plan skip_all =>
'Author only test: META.json tests run only if RELEASE_TESTING set.';
}
elsif ( ! eval 'use Test::CPAN::Meta::JSON; 1;' ) {
plan skip_all =>
'Author META.json test requires Test::CPAN::Meta::JSON.'
}
else {
note 'Testing META.json';
}
meta_json_ok();
#!/usr/bin/env perl
use strict;
use warnings;
use Test::More;
plan skip_all => 'Author tests skipped. Set $ENV{RELEASE_TESTING} to run'
unless $ENV{RELEASE_TESTING};
plan skip_all => 'Test::CPAN::Changes required for this test'
unless eval 'use Test::CPAN::Changes; 1;'; ## no critic (eval)
changes_ok();
done_testing();
## no critic (RCS,VERSION,encapsulation,Module)
use strict;
use warnings;
use Test::More;
BEGIN {
use_ok('MIME::Base64');
use_ok('MIME::QuotedPrint');
use_ok('Math::Random::ISAAC');
use_ok('Crypt::Random::Seed');
}
done_testing();
## no critic (RCS,VERSION,encapsulation,Module)
use strict;
use warnings;
use Test::More tests => 1;
BEGIN {
use_ok( 'Bytes::Random::Secure' ) || print "Bail out!\n";
}
diag(
"Testing Bytes::Random::Secure $Bytes::Random::Secure::VERSION, Perl $], $^X"
);
## no critic (RCS,VERSION,encapsulation,Module)
use strict;
use warnings;
use Test::More;
use 5.006000;
BEGIN{
@main::functions = qw/ random_bytes random_bytes_hex
random_bytes_base64 random_bytes_qp
random_string_from /;
use_ok( 'Bytes::Random::Secure', @main::functions );
}
can_ok( 'Bytes::Random::Secure', @main::functions ); # Fully qualified.
can_ok( 'main', @main::functions ); # Imported.
foreach my $want ( qw/ 0 1 2 3 4 5 6 7 8 16 17 1024 10000 / ) {
my $correct = $want >= 0 ? $want : 0;
is( length random_bytes( $want ), $correct,
"random_bytes($want) returns $correct bytes." );
}
{
local $@;
eval {
my $bytes = random_bytes( -1 );
};
like( $@, qr/Byte count must be a positive integer/,
'random_bytes: requesting negative byte count throws an exception.' );
}
{