/ 
Crypt-PBKDF2-0.101170
River stage three • 7 direct dependents • 146 total dependents
8 ++
/ Crypt::PBKDF2

NAME

Crypt::PBKDF2 - The PBKDF2 password hashing algorithm.

VERSION

version 0.101170

SYNOPSIS

    use Crypt::PBKDF2;

    my $pbkdf2 = Crypt::PBKDF2->new(
        hash_class => 'HMACSHA1' # this is the default
        iterations => 1000,      # so is this
        output_len => 20,        # and this
        salt_len => 4,           # and this.
    );

    my $hash = $pbkdf2->generate("s3kr1t_password");
    if ($pbkdf2->validate($hash, "s3kr1t_password")) {
        access_granted();
    }

DESCRIPTION

PBKDF2 is a secure password hashing algorithm that uses the techniques of "key strengthening" to make the complexity of a brute-force attack arbitrarily high. PBKDF2 uses any other cryptographic hash or cipher (by convention, usually HMAC-SHA1, but Crypt::PBKDF2 is fully pluggable), and allows for an arbitrary number of iterations of the hashing function, and a nearly unlimited output hash size (up to 2**32 - 1 times the size of the output of the backend hash). The hash is salted, as any password hash should be, and the salt may also be of arbitrary size.

ATTRIBUTES

hash_class

Type: String

Default: HMACSHA1

The name of the default class that will provide PBKDF2's Pseudo-Random Function (the backend hash). If the value starts with a +, the + will be removed and the remainder will be taken as a fully-qualified package name. Otherwise, the value will be appended to Crypt::PBKDF2::Hash::.

hash_args

Type: HashRef

Default: {}

Arguments to be passed to the hash_class constructor.

hasher

Type: Object (must fulfill role Crypt::PBKDF2::Hash)

Default: None.

It is also possible to provide a hash object directly; in this case the hash_class and hash_args are ignored.

iterations

Type: Integer

Default: 1000

The default number of iterations of the hashing function to use for the generate and PBKDF2 methods.

output_len

Type: Integer

The default size (in bytes, not bits) of the output hash. If a value isn't provided, the output size depends on the hash_class/hasher selected, and will equal the output size of the backend hash (e.g. 20 bytes for HMACSHA1).

salt_len

Type: Integer

Default: 4

The default salt length (in bytes) for the generate method.

METHODS

generate ($password, :$salt, :$iterations, :$hasher, :$output_len)

Generates a hash for the given $password. If $salt is not provided, a random salt with length salt_len will be generated. If $hasher is not provided, either the hasher or hash_class/hash_args attributes will be used. If $iterations or $output_len are not provided, defaults will be taken from the corresponding attributes.

The output looks something like the following (generated with the HMACSHA1 hash, at the default 1000 iterations and default output length):

    $PBKDF2$HMACSHA1:1000:akrvug==$Zi+c82tnjpcrRmUAHRd8h4ZRR5M=

The format has been chosen to be broadly similar to that used by crypt(), only with somewhat more structured information in the second (salt) field.

validate ($hashed, $password)

Validates whether the password $password matches the hash string $hashed. May throw an exception if the format of $hashed is invalid; otherwise, returns true or false.

PBKDF2 ($salt, $password, :$iterations, :$hasher, :$output_len)

The raw PBKDF2 algorithm. Given the $salt and $password, returns the raw binary hash. If $hasher is not provided, either the hasher or hash_class/hash_args object attributes will be used. If $iterations or $output_len are not provided, they will default to their corresponding attributes.

PBKDF2_base64 ($salt, $password, :$iterations, :$hasher, :$output_len)

As the PBKDF2 method, only the output is encoded with MIME::Base64.

PBKDF2_hex ($salt, $password, :$iterations, :$hasher, :$output_len)

As the PBKDF2 method, only the output is encoded in hexadecimal.

encode_string ($salt, $hash, $hasher)

Given a generated salt and hash, and the hasher object that produced the hash, generates output in the form generated by generate and accepted by validate. Unlikely to be of much use to anyone else.

decode_string ($hashed)

Given a textual hash in the form generated by generate, decodes it and returns a HashRef containing:

  • algorithm: A string representing the hash algorithm used. See "hasher_from_algorithm ($algo_str)".

  • iterations: The number of iterations used.

  • salt: The salt, in raw binary form.

  • hash: The hash, in raw binary form.

This method is mostly for internal use, but it has been left public as it may come in handy. If the input data is invalid, this method may throw an exception.

hasher_from_algorithm ($algo_str)

Attempts to load and instantiate a Crypt::PBKDF2::Hash::* class based on an algorithm string as produced by encode_string / generate.

SEE ALSO

AUTHOR

  Andrew Rodland <arodland@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Andrew Rodland.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.