kivitendo/modules/fallback/PBKDF2/Tiny.pm @ a5381b8b
| c157c911 | Moritz Bunkus | use strict;
|
|
use warnings;
|
|||
package PBKDF2::Tiny;
|
|||
# ABSTRACT: Minimalist PBKDF2 (RFC 2898) with HMAC-SHA1 or HMAC-SHA2
|
|||
our $VERSION = '0.005';
|
|||
use Carp ();
|
|||
use Exporter 5.57 qw/import/;
|
|||
our @EXPORT_OK = qw/derive derive_hex verify verify_hex hmac digest_fcn/;
|
|||
my ( $BACKEND, $LOAD_ERR );
|
|||
for my $mod (qw/Digest::SHA Digest::SHA::PurePerl/) {
|
|||
$BACKEND = $mod, last if eval "require $mod; 1";
|
|||
$LOAD_ERR ||= $@;
|
|||
}
|
|||
die $LOAD_ERR if !$BACKEND;
|
|||
#--------------------------------------------------------------------------#
|
|||
# constants and lookup tables
|
|||
#--------------------------------------------------------------------------#
|
|||
# function coderef placeholder, block size in bytes, digest size in bytes
|
|||
my %DIGEST_TYPES = (
|
|||
'SHA-1' => [ undef, 64, 20 ],
|
|||
'SHA-224' => [ undef, 64, 28 ],
|
|||
'SHA-256' => [ undef, 64, 32 ],
|
|||
'SHA-384' => [ undef, 128, 48 ],
|
|||
'SHA-512' => [ undef, 128, 64 ],
|
|||
);
|
|||
for my $type ( keys %DIGEST_TYPES ) {
|
|||
no strict 'refs';
|
|||
( my $name = lc $type ) =~ s{-}{};
|
|||
$DIGEST_TYPES{$type}[0] = \&{"$BACKEND\::$name"};
|
|||
}
|
|||
my %INT = map { $_ => pack( "N", $_ ) } 1 .. 16;
|
|||
#--------------------------------------------------------------------------#
|
|||
# public functions
|
|||
#--------------------------------------------------------------------------#
|
|||
#pod =func derive
|
|||
#pod
|
|||
#pod $dk = derive( $type, $password, $salt, $iterations, $dk_length )
|
|||
#pod
|
|||
#pod The C<derive> function outputs a binary string with the derived key.
|
|||
#pod The first argument indicates the digest function to use. It must be one
|
|||
#pod of: SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.
|
|||
#pod
|
|||
#pod If a password or salt are not provided, they default to the empty string, so
|
|||
#pod don't do that! L<RFC 2898
|
|||
#pod recommends|https://tools.ietf.org/html/rfc2898#section-4.1> a random salt of at
|
|||
#pod least 8 octets. If you need a cryptographically strong salt, consider
|
|||
#pod L<Crypt::URandom>.
|
|||
#pod
|
|||
#pod The password and salt should encoded as octet strings. If not (i.e. if
|
|||
#pod Perl's internal 'UTF8' flag is on), then an exception will be thrown.
|
|||
#pod
|
|||
#pod The number of iterations defaults to 1000 if not provided. If the derived
|
|||
#pod key length is not provided, it defaults to the output size of the digest
|
|||
#pod function.
|
|||
#pod
|
|||
#pod =cut
|
|||
sub derive {
|
|||
my ( $type, $passwd, $salt, $iterations, $dk_length ) = @_;
|
|||
my ( $digester, $block_size, $digest_length ) = digest_fcn($type);
|
|||
$passwd = '' unless defined $passwd;
|
|||
$salt = '' unless defined $salt;
|
|||
$iterations ||= 1000;
|
|||
$dk_length ||= $digest_length;
|
|||
# we insist on octet strings for password and salt
|
|||
Carp::croak("password must be an octet string, not a character string")
|
|||
if utf8::is_utf8($passwd);
|
|||
Carp::croak("salt must be an octet string, not a character string")
|
|||
if utf8::is_utf8($salt);
|
|||
my $key = ( length($passwd) > $block_size ) ? $digester->($passwd) : $passwd;
|
|||
my $passes = int( $dk_length / $digest_length );
|
|||
$passes++ if $dk_length % $digest_length; # need part of an extra pass
|
|||
my $dk = "";
|
|||
for my $i ( 1 .. $passes ) {
|
|||
$INT{$i} ||= pack( "N", $i );
|
|||
my $digest = my $result =
|
|||
"" . hmac( $salt . $INT{$i}, $key, $digester, $block_size );
|
|||
for my $iter ( 2 .. $iterations ) {
|
|||
$digest = hmac( $digest, $key, $digester, $block_size );
|
|||
$result ^= $digest;
|
|||
}
|
|||
$dk .= $result;
|
|||
}
|
|||
return substr( $dk, 0, $dk_length );
|
|||
}
|
|||
#pod =func derive_hex
|
|||
#pod
|
|||
#pod Works just like L</derive> but outputs a hex string.
|
|||
#pod
|
|||
#pod =cut
|
|||
sub derive_hex { unpack( "H*", &derive ) }
|
|||
#pod =func verify
|
|||
#pod
|
|||
#pod $bool = verify( $dk, $type, $password, $salt, $iterations, $dk_length );
|
|||
#pod
|
|||
#pod The C<verify> function checks that a given derived key (in binary form) matches
|
|||
#pod the password and other parameters provided using a constant-time comparison
|
|||
#pod function.
|
|||
#pod
|
|||
#pod The first parameter is the derived key to check. The remaining parameters
|
|||
#pod are the same as for L</derive>.
|
|||
#pod
|
|||
#pod =cut
|
|||
sub verify {
|
|||
my ( $dk1, @derive_args ) = @_;
|
|||
my $dk2 = derive(@derive_args);
|
|||
# shortcut if input dk is the wrong length entirely; this is not
|
|||
# constant time, but this doesn't really give much away as
|
|||
# the keys are of different types anyway
|
|||
return unless length($dk1) == length($dk2);
|
|||
# if lengths match, do constant time comparison to avoid timing attacks
|
|||
my $match = 1;
|
|||
for my $i ( 0 .. length($dk1) - 1 ) {
|
|||
$match &= ( substr( $dk1, $i, 1 ) eq substr( $dk2, $i, 1 ) ) ? 1 : 0;
|
|||
}
|
|||
return $match;
|
|||
}
|
|||
#pod =func verify_hex
|
|||
#pod
|
|||
#pod Works just like L</verify> but the derived key must be a hex string (without a
|
|||
#pod leading "0x").
|
|||
#pod
|
|||
#pod =cut
|
|||
sub verify_hex {
|
|||
my $dk = pack( "H*", shift );
|
|||
return verify( $dk, @_ );
|
|||
}
|
|||
#pod =func digest_fcn
|
|||
#pod
|
|||
#pod ($fcn, $block_size, $digest_length) = digest_fcn('SHA-1');
|
|||
#pod $digest = $fcn->($data);
|
|||
#pod
|
|||
#pod This function is used internally by PBKDF2::Tiny, but made available in case
|
|||
#pod it's useful to someone.
|
|||
#pod
|
|||
#pod Given one of the valid digest types, it returns a function reference that
|
|||
#pod digests a string of data. It also returns block size and digest length for that
|
|||
#pod digest type.
|
|||
#pod
|
|||
#pod =cut
|
|||
sub digest_fcn {
|
|||
my ($type) = @_;
|
|||
Carp::croak("Digest function '$type' not supported")
|
|||
unless exists $DIGEST_TYPES{$type};
|
|||
return @{ $DIGEST_TYPES{$type} };
|
|||
}
|
|||
#pod =func hmac
|
|||
#pod
|
|||
#pod $key = $digest_fcn->($key) if length($key) > $block_size;
|
|||
#pod $hmac = hmac( $data, $key, $digest_fcn, $block_size );
|
|||
#pod
|
|||
#pod This function is used internally by PBKDF2::Tiny, but made available in case
|
|||
#pod it's useful to someone.
|
|||
#pod
|
|||
#pod The first two arguments are the data and key inputs to the HMAC function. Both
|
|||
#pod should be encoded as octet strings, as underlying HMAC/digest functions may
|
|||
#pod croak or may give unexpected results if Perl's internal UTF-8 flag is on.
|
|||
#pod
|
|||
#pod B<Note>: if the key is longer than the digest block size, it must be
|
|||
#pod preprocessed using the digesting function.
|
|||
#pod
|
|||
#pod The third and fourth arguments must be a digesting code reference (from
|
|||
#pod L</digest_fcn>) and block size.
|
|||
#pod
|
|||
#pod =cut
|
|||
# hmac function adapted from Digest::HMAC by Graham Barr and Gisle Aas.
|
|||
# Compared to that implementation, this *requires* a preprocessed
|
|||
# key and block size, which makes iterative hmac slightly more efficient.
|
|||
sub hmac {
|
|||
my ( $data, $key, $digest_func, $block_size ) = @_;
|
|||
my $k_ipad = $key ^ ( chr(0x36) x $block_size );
|
|||
my $k_opad = $key ^ ( chr(0x5c) x $block_size );
|
|||
&$digest_func( $k_opad, &$digest_func( $k_ipad, $data ) );
|
|||
}
|
|||
1;
|
|||
# vim: ts=4 sts=4 sw=4 et:
|
|||
__END__
|
|||
=pod
|
|||
=encoding UTF-8
|
|||
=head1 NAME
|
|||
PBKDF2::Tiny - Minimalist PBKDF2 (RFC 2898) with HMAC-SHA1 or HMAC-SHA2
|
|||
=head1 VERSION
|
|||
version 0.005
|
|||
=head1 SYNOPSIS
|
|||
use PBKDF2::Tiny qw/derive verify/;
|
|||
my $dk = derive( 'SHA-1', $pass, $salt, $iters );
|
|||
if ( verify( $dk, 'SHA-1', $pass, $salt, $iters ) ) {
|
|||
# password is correct
|
|||
}
|
|||
=head1 DESCRIPTION
|
|||
This module provides an L<RFC 2898|https://tools.ietf.org/html/rfc2898>
|
|||
compliant PBKDF2 implementation using HMAC-SHA1 or HMAC-SHA2 in under 100 lines
|
|||
of code. If you are using Perl 5.10 or later, it uses only core Perl modules.
|
|||
If you are on an earlier version of Perl, you need L<Digest::SHA> or
|
|||
L<Digest::SHA::PurePerl>.
|
|||
All documented functions are optionally exported. No functions are exported by default.
|
|||
=head1 FUNCTIONS
|
|||
=head2 derive
|
|||
$dk = derive( $type, $password, $salt, $iterations, $dk_length )
|
|||
The C<derive> function outputs a binary string with the derived key.
|
|||
The first argument indicates the digest function to use. It must be one
|
|||
of: SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.
|
|||
If a password or salt are not provided, they default to the empty string, so
|
|||
don't do that! L<RFC 2898
|
|||
recommends|https://tools.ietf.org/html/rfc2898#section-4.1> a random salt of at
|
|||
least 8 octets. If you need a cryptographically strong salt, consider
|
|||
L<Crypt::URandom>.
|
|||
The password and salt should encoded as octet strings. If not (i.e. if
|
|||
Perl's internal 'UTF8' flag is on), then an exception will be thrown.
|
|||
The number of iterations defaults to 1000 if not provided. If the derived
|
|||
key length is not provided, it defaults to the output size of the digest
|
|||
function.
|
|||
=head2 derive_hex
|
|||
Works just like L</derive> but outputs a hex string.
|
|||
=head2 verify
|
|||
$bool = verify( $dk, $type, $password, $salt, $iterations, $dk_length );
|
|||
The C<verify> function checks that a given derived key (in binary form) matches
|
|||
the password and other parameters provided using a constant-time comparison
|
|||
function.
|
|||
The first parameter is the derived key to check. The remaining parameters
|
|||
are the same as for L</derive>.
|
|||
=head2 verify_hex
|
|||
Works just like L</verify> but the derived key must be a hex string (without a
|
|||
leading "0x").
|
|||
=head2 digest_fcn
|
|||
($fcn, $block_size, $digest_length) = digest_fcn('SHA-1');
|
|||
$digest = $fcn->($data);
|
|||
This function is used internally by PBKDF2::Tiny, but made available in case
|
|||
it's useful to someone.
|
|||
Given one of the valid digest types, it returns a function reference that
|
|||
digests a string of data. It also returns block size and digest length for that
|
|||
digest type.
|
|||
=head2 hmac
|
|||
$key = $digest_fcn->($key) if length($key) > $block_size;
|
|||
$hmac = hmac( $data, $key, $digest_fcn, $block_size );
|
|||
This function is used internally by PBKDF2::Tiny, but made available in case
|
|||
it's useful to someone.
|
|||
The first two arguments are the data and key inputs to the HMAC function. Both
|
|||
should be encoded as octet strings, as underlying HMAC/digest functions may
|
|||
croak or may give unexpected results if Perl's internal UTF-8 flag is on.
|
|||
B<Note>: if the key is longer than the digest block size, it must be
|
|||
preprocessed using the digesting function.
|
|||
The third and fourth arguments must be a digesting code reference (from
|
|||
L</digest_fcn>) and block size.
|
|||
=begin Pod::Coverage
|
|||
=end Pod::Coverage
|
|||
=head1 SEE ALSO
|
|||
=over 4
|
|||
=item *
|
|||
L<Crypt::PBKDF2>
|
|||
=item *
|
|||
L<Digest::PBDKF2>
|
|||
=back
|
|||
=for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan
|
|||
=head1 SUPPORT
|
|||
=head2 Bugs / Feature Requests
|
|||
Please report any bugs or feature requests through the issue tracker
|
|||
at L<https://github.com/dagolden/PBKDF2-Tiny/issues>.
|
|||
You will be notified automatically of any progress on your issue.
|
|||
=head2 Source Code
|
|||
This is open source software. The code repository is available for
|
|||
public review and contribution under the terms of the license.
|
|||
L<https://github.com/dagolden/PBKDF2-Tiny>
|
|||
git clone https://github.com/dagolden/PBKDF2-Tiny.git
|
|||
=head1 AUTHOR
|
|||
David Golden <dagolden@cpan.org>
|
|||
=head1 COPYRIGHT AND LICENSE
|
|||
This software is Copyright (c) 2014 by David Golden.
|
|||
This is free software, licensed under:
|
|||
The Apache License, Version 2.0, January 2004
|
|||
=cut
|