File: //usr/local/share/man/man3/Crypt::PBKDF2.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Crypt::PBKDF2 3"
.TH Crypt::PBKDF2 3 "2016-05-31" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Crypt::PBKDF2 \- The PBKDF2 password hashing algorithm.
.SH "VERSION"
.IX Header "VERSION"
version 0.161520
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Crypt::PBKDF2;
\&
\& my $pbkdf2 = Crypt::PBKDF2\->new(
\& hash_class => \*(AqHMACSHA1\*(Aq, # 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();
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1PBKDF2\s0 is a secure password hashing algorithm that uses the techniques of
\&\*(L"key strengthening\*(R" to make the complexity of a brute-force attack
arbitrarily high. \s-1PBKDF2\s0 uses any other cryptographic hash or cipher (by
convention, usually \s-1HMAC\-SHA1,\s0 but \f(CW\*(C`Crypt::PBKDF2\*(C'\fR 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.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "hash_class"
.IX Subsection "hash_class"
\&\fBType:\fR String, \fBDefault:\fR \s-1HMACSHA1\s0
.PP
The name of the default class that will provide \s-1PBKDF2\s0's Pseudo-Random
Function (the backend hash). If the value starts with a \f(CW\*(C`+\*(C'\fR, the \f(CW\*(C`+\*(C'\fR will
be removed and the remainder will be taken as a fully-qualified package
name. Otherwise, the value will be appended to \f(CW\*(C`Crypt::PBKDF2::Hash::\*(C'\fR.
.SS "hash_args"
.IX Subsection "hash_args"
\&\fBType:\fR HashRef, \fBDefault:\fR {}
.PP
Arguments to be passed to the \f(CW\*(C`hash_class\*(C'\fR constructor.
.SS "hasher"
.IX Subsection "hasher"
\&\fBType:\fR Object (must fulfill role Crypt::PBKDF2::Hash), \fBDefault:\fR None.
.PP
It is also possible to provide a hash object directly; in this case the
\&\f(CW\*(C`hash_class\*(C'\fR and \f(CW\*(C`hash_args\*(C'\fR are ignored.
.SS "iterations"
.IX Subsection "iterations"
\&\fBType:\fR Integer, \fBDefault:\fR 1000.
.PP
The default number of iterations of the hashing function to use for the
\&\f(CW\*(C`generate\*(C'\fR and \f(CW\*(C`PBKDF2\*(C'\fR methods.
.SS "output_len"
.IX Subsection "output_len"
\&\fBType:\fR Integer.
.PP
The default size (in bytes, not bits) of the output hash. If a value isn't
provided, the output size depends on the \f(CW\*(C`hash_class\*(C'\fR / \f(CW\*(C`hasher\*(C'\fR
selected, and will equal the output size of the backend hash (e.g. 20 bytes
for \s-1HMACSHA1\s0).
.SS "salt_len"
.IX Subsection "salt_len"
\&\fBType:\fR Integer, \fBDefault:\fR 4
.PP
The default salt length (in bytes) for the \f(CW\*(C`generate\*(C'\fR method.
.SS "encoding"
.IX Subsection "encoding"
\&\fBType:\fR String (either \*(L"crypt\*(R" or \*(L"ldap\*(R"), \fBDefault:\fR \*(L"ldap\*(R"
.PP
The hash format to generate. The \*(L"ldap\*(R" format is intended to be compatible
with \s-1RFC2307,\s0 and looks like:
.PP
.Vb 1
\& {X\-PBKDF2}HMACSHA1:AAAD6A:8ODUPA==:1HSdSVVwlWSZhbPGO7GIZ4iUbrk=
.Ve
.PP
While the \*(L"crypt\*(R" format is similar to the format used by the \f(CW\*(C`crypt()\*(C'\fR
function, except with more structured information in the second (salt) field.
It looks like:
.PP
.Vb 1
\& $PBKDF2$HMACSHA1:1000:4q9OTg==$9Pb6bCRgnct/dga+4v4Lyv8x31s=
.Ve
.PP
Versions of this module up to 0.110461 generated the \*(L"crypt\*(R" format, so set
that if you want it. Current versions of this module will read either format,
but the \*(L"ldap\*(R" format is preferred.
.SS "length_limit"
.IX Subsection "length_limit"
\&\fBType:\fR Integer
.PP
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.
.PP
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.
.SH "METHODS"
.IX Header "METHODS"
.SS "generate ($password, [$salt])"
.IX Subsection "generate ($password, [$salt])"
Generates a hash for the given \f(CW$password\fR. If \f(CW$salt\fR is not provided,
a random salt with length \f(CW\*(C`salt_len\*(C'\fR will be generated.
.PP
There are two output formats available, depending on the setting of the
\&\f(CW\*(C`encoding\*(C'\fR attribute: \*(L"ldap\*(R" and \*(L"crypt\*(R"; see the documentation for
\&\*(L"encoding\*(R" for more information.
.ie n .SS "validate ($hashed, $password)"
.el .SS "validate ($hashed, \f(CW$password\fP)"
.IX Subsection "validate ($hashed, $password)"
Validates whether the password \f(CW$password\fR matches the hash string
\&\f(CW$hashed\fR. May throw an exception if the format of \f(CW$hashed\fR is invalid;
otherwise, returns true or false. Accepts both formats that the \*(L"generate\*(R"
method can produce.
.ie n .SS "\s-1PBKDF2\s0 ($salt, $password)"
.el .SS "\s-1PBKDF2\s0 ($salt, \f(CW$password\fP)"
.IX Subsection "PBKDF2 ($salt, $password)"
The raw \s-1PBKDF2\s0 algorithm. Given the \f(CW$salt\fR and \f(CW$password\fR, returns the
raw binary hash.
.ie n .SS "PBKDF2_base64 ($salt, $password)"
.el .SS "PBKDF2_base64 ($salt, \f(CW$password\fP)"
.IX Subsection "PBKDF2_base64 ($salt, $password)"
As the \f(CW\*(C`PBKDF2\*(C'\fR method, only the output is encoded with MIME::Base64.
.ie n .SS "PBKDF2_hex ($salt, $password)"
.el .SS "PBKDF2_hex ($salt, \f(CW$password\fP)"
.IX Subsection "PBKDF2_hex ($salt, $password)"
As the \f(CW\*(C`PBKDF2\*(C'\fR method, only the output is encoded in hexadecimal.
.ie n .SS "encode_string ($salt, $hash)"
.el .SS "encode_string ($salt, \f(CW$hash\fP)"
.IX Subsection "encode_string ($salt, $hash)"
Given a generated salt and hash, hash, generates output in the form generated by
\&\f(CW\*(C`generate\*(C'\fR and accepted by \f(CW\*(C`validate\*(C'\fR. Unlikely to be of much use to anyone
else.
.SS "decode_string ($hashed)"
.IX Subsection "decode_string ($hashed)"
Given a textual hash in the form generated by \f(CW\*(C`generate\*(C'\fR, decodes it and
returns a HashRef containing:
.IP "\(bu" 4
\&\f(CW\*(C`algorithm\*(C'\fR: A string representing the hash algorithm used. See
\&\*(L"hasher_from_algorithm ($algo_str)\*(R".
.IP "\(bu" 4
\&\f(CW\*(C`iterations\*(C'\fR: The number of iterations used.
.IP "\(bu" 4
\&\f(CW\*(C`salt\*(C'\fR: The salt, in raw binary form.
.IP "\(bu" 4
\&\f(CW\*(C`hash\*(C'\fR: The hash, in raw binary form.
.PP
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.
.SS "hasher_from_algorithm ($algo_str)"
.IX Subsection "hasher_from_algorithm ($algo_str)"
Attempts to load and instantiate a \f(CW\*(C`Crypt::PBKDF2::Hash::*\*(C'\fR class based on
an algorithm string as produced by \f(CW\*(C`encode_string\*(C'\fR / \f(CW\*(C`generate\*(C'\fR.
.SS "clone (%params)"
.IX Subsection "clone (%params)"
Create a new object like this one, but with \f(CW%params\fR changed.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
\&\fBWikipedia: \s-1PBKDF2\s0\fR: <http://en.wikipedia.org/wiki/PBKDF2>
.IP "\(bu" 4
\&\fB\s-1RFC2898,\s0 PKCS#5 version 2.0\fR: <http://tools.ietf.org/html/rfc2898>
.IP "\(bu" 4
\&\fB\s-1RFC2307,\s0 Using \s-1LDAP\s0 as a Network Information Service\fR:
<http://tools.ietf.org/html/rfc2307>
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Rodland <arodland@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2016 by Andrew Rodland.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.