1Authen::Passphrase(3pm)User Contributed Perl DocumentatioAnuthen::Passphrase(3pm)
2
6 Authen::Passphrase - hashed passwords/passphrases as objects
7
9 use Authen::Passphrase;
10 $ppr = Authen::Passphrase->from_crypt($passwd);
12 $ppr = Authen::Passphrase->from_rfc2307($userPassword);
13 if($ppr->match($passphrase)) { ...
15 $passphrase = $ppr->passphrase;
17 $crypt = $ppr->as_crypt;
19 $userPassword = $ppr->as_rfc2307;
20
22 This is the base class for a system of objects that encapsulate
23 passphrases. An object of this type is a passphrase recogniser: its
24 job is to recognise whether an offered passphrase is the right one.
25 For security, such passphrase recognisers usually do not themselves
26 know the passphrase they are looking for; they can merely recognise it
27 when they see it. There are many schemes in use to achieve this
28 effect, and the intent of this class is to provide a consistent
29 interface to them all, hiding the details.
30 The CPAN package Authen-Passphrase contains implementations of several
32 specific passphrase schemes in addition to the base class. See the
33 specific classes for notes on the security properties of each scheme.
34 In new systems, if there is a choice of which passphrase algorithm to
35 use, it is recommended to use Authen::Passphrase::SaltedDigest or
36 Authen::Passphrase::BlowfishCrypt. Most other schemes are too weak for
37 new applications, and should be used only for backward compatibility.
38 Side-channel cryptanalysis
40 Both the Authen-Passphrase framework and most of the underlying
41 cryptographic algorithm implementations are vulnerable to side-channel
42 cryptanalytic attacks. However, the impact of this is quite limited.
43 Unlike the case of symmetric encryption, where a side-channel attack
45 can extract the plaintext directly, the cryptographic operations
46 involved in passphrase recognition don't directly process the correct
47 passphrase. A sophisticated side-channel attack, applied when offering
48 incorrect passphrases for checking, could potentially extract salt
49 (from the operation of the hashing algorithm) and the target hash value
50 (from the comparison of hash values). This would enable a
51 cryptanalytic or brute-force attack on the passphrase recogniser to be
52 performed offline. This is not a disaster; the very intent of storing
53 only a hash of the correct passphrase is that leakage of these stored
54 values doesn't compromise the passphrase.
55 In a typical usage scenario for this framework, the side-channel
57 attacks that can be mounted are very restricted. If authenticating
58 network users, typically an attacker has no access at all to power
59 consumption, electromagnetic emanation, and other such side channels.
60 The only side channel that is readily available is timing, and the
61 precision of timing measurements is significantly blunted by the normal
62 processes of network communication. For example, it would not normally
63 be feasible to mount a timing attack against hash value comparison (to
64 see how far through the values the first mismatch was).
65 Perl as a whole has not been built as a platform for side-channel-
67 resistant cryptography, so hardening Authen-Passphrase and its
68 underlying algorithms is not feasible. In any serious use of Perl for
69 cryptography, including for authentication using Authen-Passphrase, an
70 analysis should be made of the exposure to side-channel attacks, and if
71 necessary efforts made to further blunt the timing channel.
72 One timing attack that is very obviously feasible over the network is
74 to determine which of several passphrase hashing algorithms is being
75 used. This can potentially distinguish between classes of user
76 accounts, or distinguish between existing and non-existing user
77 accounts when an attacker is guessing usernames. To obscure this
78 information requires an extreme restriction of the timing channel, most
79 likely by explicitly pausing to standardise the amount of time spent on
80 authentication. This defence also rules out essentially all other
81 timing attacks.
82
84 Because hashed passphrases frequently need to be stored, various
85 encodings of them have been devised. This class has constructors and
86 methods to support these.
87 crypt encoding
89 The Unix crypt() function, which performs passphrase hashing, returns
90 hashes in a textual format intended to be stored in a text file. In
91 particular, such hashes are stored in /etc/passwd (and now /etc/shadow)
92 to control access to Unix user accounts. The same textual format has
93 been adopted and extended by other passphrase-handling software such as
94 password crackers.
95 For historical reasons, there are several different syntaxes used in
97 this format. The original DES-based password scheme represents its
98 hashes simply as a string of thirteen base 64 digits. An extended
99 variant of this scheme uses nineteen base 64 digits, preceded by an "_"
100 marker. A more general syntax was developed later, which starts the
101 string with "$", an alphanumeric scheme identifier, and another "$".
102 In addition to actual passphrase hashes, the crypt format can also
104 represent a couple of special cases. The empty string indicates that
105 there is no access control; it is possible to login without giving a
106 passphrase. Finally, any string that is not a possible output of
107 crypt() may be used to prevent login completely; "*" is the usual
108 choice, but other strings are used too.
109 crypt strings are intended to be used in text files that use colon and
111 newline characters as delimiters. This module treats the crypt string
112 syntax as being limited to ASCII graphic characters excluding colon.
113 RFC 2307 encoding
115 RFC 2307 describes an encoding system for passphrase hashes, to be used
116 in the "userPassword" attribute in LDAP databases. It encodes hashes
117 as ASCII text, and supports several passphrase schemes in an extensible
118 way by starting the encoding with an alphanumeric scheme identifier
119 enclosed in braces. There are several standard scheme identifiers.
120 The "{CRYPT}" scheme allows the use of any crypt encoding.
121 This module treats the RFC 2307 string syntax as being limited to ASCII
123 graphic characters.
124 The RFC 2307 encoding is a good one, and is recommended for storage and
126 exchange of passphrase hashes.
127
129 Authen::Passphrase->from_crypt(PASSWD)
130 Returns a passphrase recogniser object matching the supplied crypt
131 encoding. This constructor may only be called on the base class,
132 not any subclass.
133 The specific passphrase recogniser class is loaded at runtime, so
135 successfully loading "Authen::Passphrase" does not guarantee that
136 it will be possible to use a specific type of passphrase
137 recogniser. If necessary, check separately for presence and
138 loadability of the recogniser class.
139 Known scheme identifiers:
141 $1$ A baroque passphrase scheme based on MD5, designed by Poul-
143 Henning Kamp and originally implemented in FreeBSD. See
144 Authen::Passphrase::MD5Crypt.
145 $2$
147 $2a$
148 Two versions of a passphrase scheme based on Blowfish, designed
149 by Niels Provos and David Mazieres for OpenBSD. See
150 Authen::Passphrase::BlowfishCrypt.
151 $3$ The NT-Hash scheme, which stores the MD4 hash of the passphrase
153 expressed in Unicode. See Authen::Passphrase::NTHash.
154 $IPB2$
156 Invision Power Board 2.x salted MD5
157 $K4$
159 Kerberos AFS DES
160 $LM$
162 Half of the Microsoft LAN Manager hash scheme. The two halves
163 of a LAN Manager hash can be separated and manipulated
164 independently; this represents such an isolated half. See
165 Authen::Passphrase::LANManagerHalf.
166 $NT$
168 The NT-Hash scheme, which stores the MD4 hash of the passphrase
169 expressed in Unicode. See Authen::Passphrase::NTHash.
170 The $3$ identifier refers to the same hash algorithm, but has a
172 slightly different textual format (an extra "$").
173 $P$ Portable PHP password hash (phpass), based on MD5. See
175 Authen::Passphrase::PHPass.
176 $VMS1$
178 $VMS2$
179 $VMS3$
180 Three variants of the Purdy polynomial system used in VMS. See
181 Authen::Passphrase::VMSPurdy.
182 $af$
184 Kerberos v4 TGT
185 $apr1$
187 A variant of the $1$ scheme, used by Apache.
188 $krb5$
190 Kerberos v5 TGT
191 The historical formats supported are:
193 "bbbbbbbbbbbbb"
195 ("b" represents a base 64 digit.) The original DES-based Unix
196 password hash scheme. See Authen::Passphrase::DESCrypt.
197 "_bbbbbbbbbbbbbbbbbbb"
199 ("b" represents a base 64 digit.) Extended DES-based
200 passphrase hash scheme from BSDi. See
201 Authen::Passphrase::DESCrypt.
202 "" Accept any passphrase. See Authen::Passphrase::AcceptAll.
204 "*" To handle historical practice, anything non-empty but shorter
206 than 13 characters and not starting with "$" is treated as
207 deliberately rejecting all passphrases. (See
208 Authen::Passphrase::RejectAll.) Anything 13 characters or
209 longer, or starting with "$", that is not recognised as a hash
210 is treated as an error.
211 There are also two different passphrase schemes that use a crypt
213 string consisting of 24 base 64 digits. One is named "bigcrypt"
214 and appears in HP-UX, Digital Unix, and OSF/1 (see
215 Authen::Passphrase::BigCrypt). The other is named "crypt16" and
216 appears in Ultrix and Tru64 (see Authen::Passphrase::Crypt16).
217 These schemes conflict. Neither of them is accepted as a crypt
218 string by this constructor; such strings are regarded as invalid
219 encodings.
220 Authen::Passphrase->from_rfc2307(USERPASSWORD)
222 Returns a passphrase recogniser object matching the supplied RFC
223 2307 encoding. This constructor may only be called on the base
224 class, not any subclass.
225 The specific passphrase recogniser class is loaded at runtime. See
227 the note about this for the "from_crypt" constructor above.
228 Known scheme identifiers:
230 {CLEARTEXT}
232 Passphrase stored in cleartext. See Authen::Passphrase::Clear.
233 {CRYPT}
235 The scheme identifier is followed by a crypt string.
236 {CRYPT16}
238 Used ambiguously by Exim, to refer to either crypt16 (see
239 Authen::Passphrase::Crypt16) or bigcrypt (see
240 Authen::Passphrase::BigCrypt) depending on compilation options.
241 This is a bug, resulting from a confusion between the two
242 algorithms. This module does not support any meaning for this
243 scheme identifier.
244 {K5KEY}
246 Not a real passphrase scheme, but a placeholder to indicate
247 that a Kerberos key stored separately should be checked
248 against. No data follows the scheme identifier.
249 {KERBEROS}
251 Not a real passphrase scheme, but a placeholder to indicate
252 that Kerberos should be invoked to check against a user's
253 passphrase. The scheme identifier is followed by the user's
254 username, in the form "name@realm".
255 {LANM}
257 Synonym for {LANMAN}, used by CommuniGate Pro.
258 {LANMAN}
260 The Microsoft LAN Manager hash scheme. See
261 Authen::Passphrase::LANManager.
262 {MD4}
264 The MD4 digest of the passphrase is stored. See
265 Authen::Passphrase::SaltedDigest.
266 {MD5}
268 The MD5 digest of the passphrase is stored. See
269 Authen::Passphrase::SaltedDigest.
270 {MSNT}
272 The NT-Hash scheme, which stores the MD4 hash of the passphrase
273 expressed in Unicode. See Authen::Passphrase::NTHash.
274 {NS-MTA-MD5}
276 An MD5-based scheme used by Netscape Mail Server. See
277 Authen::Passphrase::NetscapeMail.
278 {RMD160}
280 The RIPEMD-160 digest of the passphrase is stored. See
281 Authen::Passphrase::SaltedDigest.
282 {SASL}
284 Not a real passphrase scheme, but a placeholder to indicate
285 that SASL should be invoked to check against a user's
286 passphrase. The scheme identifier is followed by the user's
287 username.
288 {SHA}
290 The SHA-1 digest of the passphrase is stored. See
291 Authen::Passphrase::SaltedDigest.
292 {SMD5}
294 The MD5 digest of the passphrase plus a salt is stored. See
295 Authen::Passphrase::SaltedDigest.
296 {SSHA}
298 The SHA-1 digest of the passphrase plus a salt is stored. See
299 Authen::Passphrase::SaltedDigest.
300 {UNIX}
302 Not a real passphrase scheme, but a placeholder to indicate
303 that Unix mechanisms should be used to check against a Unix
304 user's login passphrase. The scheme identifier is followed by
305 the user's username.
306 {WM-CRY}
308 Synonym for {CRYPT}, used by CommuniGate Pro.
309
311 $ppr->match(PASSPHRASE)
312 Checks whether the supplied passphrase is correct. Returns a truth
313 value.
314 $ppr->passphrase
316 If a matching passphrase can be easily determined by the passphrase
317 recogniser then this method will return it. This is only feasible
318 for very weak passphrase schemes. The method "die"s if it is
319 infeasible.
320 $ppr->as_crypt
322 Encodes the passphrase recogniser in crypt format and returns the
323 encoded result. "die"s if the passphrase recogniser cannot be
324 represented in this form.
325 $ppr->as_rfc2307
327 Encodes the passphrase recogniser in RFC 2307 format and returns
328 the encoded result. "die"s if the passphrase recogniser cannot be
329 represented in this form.
330
332 This class is designed to be subclassed, and cannot be instantiated
333 alone. Any subclass must implement the "match" method. That is the
334 minimum required.
335 Subclasses should implement the "as_crypt" and "as_rfc2307" methods and
337 the "from_crypt" and "from_rfc2307" constructors wherever appropriate,
338 with the following exception. If a passphrase scheme has a crypt
339 encoding but no native RFC 2307 encoding, so it can be RFC 2307 encoded
340 only by using the "{CRYPT}" scheme, then "as_rfc2307" and
341 "from_rfc2307" should not be implemented by the class. There is a
342 default implementation of the "as_rfc2307" method that uses "{CRYPT}"
343 and "as_crypt", and a default implementation of the "from_rfc2307"
344 method that recognises "{CRYPT}" and passes the embedded crypt string
345 to the "from_crypt" constructor.
346 Implementation of the "passphrase" method is entirely optional. It
348 should be attempted only for schemes that are so ludicrously weak as to
349 allow passphrases to be cracked reliably in a short time. Dictionary
350 attacks are not appropriate implementations.
351
353 MooseX::Types::Authen::Passphrase, crypt(3), RFC 2307
354
356 Andrew Main (Zefram) <zefram@fysh.org>
357
359 Copyright (C) 2006, 2007, 2009, 2010, 2012 Andrew Main (Zefram)
360 <zefram@fysh.org>
361
363 This module is free software; you can redistribute it and/or modify it
364 under the same terms as Perl itself.
365perl v5.38.0 2023-07-20 Authen::Passphrase(3pm)