Ubuntu Manpage: Crypt::PBKDF2 - The PBKDF2 password hashing algorithm.

Provided by: libcrypt-pbkdf2-perl_0.160410-1_all

NAME

       Crypt::PBKDF2 - The PBKDF2 password hashing algorithm.

VERSION

       version 0.160410

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.

   encoding
       Type: String (either "crypt" or "ldap"), Default: "ldap"

       The hash format to generate. The "ldap" format is intended to be compatible with RFC2307,
       and looks like:

           {X-PBKDF2}HMACSHA1:AAAD6A:8ODUPA==:1HSdSVVwlWSZhbPGO7GIZ4iUbrk=

       While the "crypt" format is similar to the format used by the "crypt()" function, except
       with more structured information in the second (salt) field.  It looks like:

           $PBKDF2$HMACSHA1:1000:4q9OTg==$9Pb6bCRgnct/dga+4v4Lyv8x31s=

       Versions of this module up to 0.110461 generated the "crypt" format, so set that if you
       want it. Current versions of this module will read either format, but the "ldap" format is
       preferred.

   length_limit
       Type: Integer

       The maximum password length to allow, for generate and verify functions.  Allowing
       passwords of unlimited length can allow a denial-of-service attack in which an attacker
       asks the server to validate very large passwords.

       For compatibility this attribute is unset by default, but it is recommended to set it to a
       reasonably small value like 100 -- large enough that users aren't discouraged from having
       secure passwords, but small enough to limit the computation needed to validate any one
       password.

METHODS

generate ($password, [$salt])
Generates a hash for the given $password. If $salt is not provided, a random salt with
length "salt_len" will be generated.

There are two output formats available, depending on the setting of the "encoding"
attribute: "ldap" and "crypt"; see the documentation for "encoding" for more information.

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. Accepts
both formats that the "generate" method can produce.

PBKDF2 ($salt, $password)
The raw PBKDF2 algorithm. Given the $salt and $password, returns the raw binary hash.

PBKDF2_base64 ($salt, $password)
As the "PBKDF2" method, only the output is encoded with MIME::Base64.

PBKDF2_hex ($salt, $password)
As the "PBKDF2" method, only the output is encoded in hexadecimal.

encode_string ($salt, $hash)
Given a generated salt and hash, 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".

clone (%params)
Create a new object like this one, but with %params changed.

AUTHOR

       Andrew Rodland <arodland@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2016 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.