1Crypt::PBKDF2(3)      User Contributed Perl Documentation     Crypt::PBKDF2(3)
2
3
4

NAME

6       Crypt::PBKDF2 - The PBKDF2 password hashing algorithm.
7

VERSION

9       version 0.161520
10

SYNOPSIS

12           use Crypt::PBKDF2;
13
14           my $pbkdf2 = Crypt::PBKDF2->new(
15               hash_class => 'HMACSHA1', # this is the default
16               iterations => 1000,       # so is this
17               output_len => 20,         # and this
18               salt_len => 4,            # and this.
19           );
20
21           my $hash = $pbkdf2->generate("s3kr1t_password");
22           if ($pbkdf2->validate($hash, "s3kr1t_password")) {
23               access_granted();
24           }
25

DESCRIPTION

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

ATTRIBUTES

38   hash_class
39       Type: String, Default: HMACSHA1
40
41       The name of the default class that will provide PBKDF2's Pseudo-Random
42       Function (the backend hash). If the value starts with a "+", the "+"
43       will be removed and the remainder will be taken as a fully-qualified
44       package name. Otherwise, the value will be appended to
45       "Crypt::PBKDF2::Hash::".
46
47   hash_args
48       Type: HashRef, Default: {}
49
50       Arguments to be passed to the "hash_class" constructor.
51
52   hasher
53       Type: Object (must fulfill role Crypt::PBKDF2::Hash), Default: None.
54
55       It is also possible to provide a hash object directly; in this case the
56       "hash_class" and "hash_args" are ignored.
57
58   iterations
59       Type: Integer, Default: 1000.
60
61       The default number of iterations of the hashing function to use for the
62       "generate" and "PBKDF2" methods.
63
64   output_len
65       Type: Integer.
66
67       The default size (in bytes, not bits) of the output hash. If a value
68       isn't provided, the output size depends on the "hash_class" / "hasher"
69       selected, and will equal the output size of the backend hash (e.g. 20
70       bytes for HMACSHA1).
71
72   salt_len
73       Type: Integer, Default: 4
74
75       The default salt length (in bytes) for the "generate" method.
76
77   encoding
78       Type: String (either "crypt" or "ldap"), Default: "ldap"
79
80       The hash format to generate. The "ldap" format is intended to be
81       compatible with RFC2307, and looks like:
82
83           {X-PBKDF2}HMACSHA1:AAAD6A:8ODUPA==:1HSdSVVwlWSZhbPGO7GIZ4iUbrk=
84
85       While the "crypt" format is similar to the format used by the crypt()
86       function, except with more structured information in the second (salt)
87       field.  It looks like:
88
89           $PBKDF2$HMACSHA1:1000:4q9OTg==$9Pb6bCRgnct/dga+4v4Lyv8x31s=
90
91       Versions of this module up to 0.110461 generated the "crypt" format, so
92       set that if you want it. Current versions of this module will read
93       either format, but the "ldap" format is preferred.
94
95   length_limit
96       Type: Integer
97
98       The maximum password length to allow, for generate and verify
99       functions.  Allowing passwords of unlimited length can allow a denial-
100       of-service attack in which an attacker asks the server to validate very
101       large passwords.
102
103       For compatibility this attribute is unset by default, but it is
104       recommended to set it to a reasonably small value like 100 -- large
105       enough that users aren't discouraged from having secure passwords, but
106       small enough to limit the computation needed to validate any one
107       password.
108

METHODS

110   generate ($password, [$salt])
111       Generates a hash for the given $password. If $salt is not provided, a
112       random salt with length "salt_len" will be generated.
113
114       There are two output formats available, depending on the setting of the
115       "encoding" attribute: "ldap" and "crypt"; see the documentation for
116       "encoding" for more information.
117
118   validate ($hashed, $password)
119       Validates whether the password $password matches the hash string
120       $hashed. May throw an exception if the format of $hashed is invalid;
121       otherwise, returns true or false. Accepts both formats that the
122       "generate" method can produce.
123
124   PBKDF2 ($salt, $password)
125       The raw PBKDF2 algorithm. Given the $salt and $password, returns the
126       raw binary hash.
127
128   PBKDF2_base64 ($salt, $password)
129       As the "PBKDF2" method, only the output is encoded with MIME::Base64.
130
131   PBKDF2_hex ($salt, $password)
132       As the "PBKDF2" method, only the output is encoded in hexadecimal.
133
134   encode_string ($salt, $hash)
135       Given a generated salt and hash, hash, generates output in the form
136       generated by "generate" and accepted by "validate". Unlikely to be of
137       much use to anyone else.
138
139   decode_string ($hashed)
140       Given a textual hash in the form generated by "generate", decodes it
141       and returns a HashRef containing:
142
143       •   "algorithm": A string representing the hash algorithm used. See
144           "hasher_from_algorithm ($algo_str)".
145
146       •   "iterations": The number of iterations used.
147
148       •   "salt": The salt, in raw binary form.
149
150       •   "hash": The hash, in raw binary form.
151
152       This method is mostly for internal use, but it has been left public as
153       it may come in handy. If the input data is invalid, this method may
154       throw an exception.
155
156   hasher_from_algorithm ($algo_str)
157       Attempts to load and instantiate a "Crypt::PBKDF2::Hash::*" class based
158       on an algorithm string as produced by "encode_string" / "generate".
159
160   clone (%params)
161       Create a new object like this one, but with %params changed.
162

SEE ALSO

164Wikipedia: PBKDF2: <http://en.wikipedia.org/wiki/PBKDF2>
165
166RFC2898, PKCS#5 version 2.0: <http://tools.ietf.org/html/rfc2898>
167
168RFC2307, Using LDAP as a Network Information Service:
169           <http://tools.ietf.org/html/rfc2307>
170

AUTHOR

172       Andrew Rodland <arodland@cpan.org>
173
175       This software is copyright (c) 2016 by Andrew Rodland.
176
177       This is free software; you can redistribute it and/or modify it under
178       the same terms as the Perl 5 programming language system itself.
179
180
181
182perl v5.36.0                      2023-01-20                  Crypt::PBKDF2(3)
Impressum