libpbkdf2-tiny-perl 0.005-2 / usr / share / perl5 / PBKDF2 / Tiny.pm

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