1Authen::Passphrase(3) User Contributed Perl DocumentationAuthen::Passphrase(3)
2
3
4

NAME

6       Authen::Passphrase - hashed passwords/passphrases as objects
7

SYNOPSIS

9               use Authen::Passphrase;
10
11               $ppr = Authen::Passphrase->from_crypt($passwd);
12               $ppr = Authen::Passphrase->from_rfc2307($userPassword);
13
14               if($ppr->match($passphrase)) { ...
15
16               $passphrase = $ppr->passphrase;
17
18               $crypt = $ppr->as_crypt;
19               $userPassword = $ppr->as_rfc2307;
20

DESCRIPTION

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
31       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
39   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
44       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
56       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
66       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
73       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

PASSPHRASE ENCODINGS

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
88   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
96       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
103       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
110       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
114   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
122       This module treats the RFC 2307 string syntax as being limited to ASCII
123       graphic characters.
124
125       The RFC 2307 encoding is a good one, and is recommended for storage and
126       exchange of passphrase hashes.
127

CONSTRUCTORS

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
134           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
140           Known scheme identifiers:
141
142           $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
146           $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
152           $3$ The NT-Hash scheme, which stores the MD4 hash of the passphrase
153               expressed in Unicode.  See Authen::Passphrase::NTHash.
154
155           $IPB2$
156               Invision Power Board 2.x salted MD5
157
158           $K4$
159               Kerberos AFS DES
160
161           $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
167           $NT$
168               The NT-Hash scheme, which stores the MD4 hash of the passphrase
169               expressed in Unicode.  See Authen::Passphrase::NTHash.
170
171               The $3$ identifier refers to the same hash algorithm, but has a
172               slightly different textual format (an extra "$").
173
174           $P$ Portable PHP password hash (phpass), based on MD5.  See
175               Authen::Passphrase::PHPass.
176
177           $VMS1$
178           $VMS2$
179           $VMS3$
180               Three variants of the Purdy polynomial system used in VMS.  See
181               Authen::Passphrase::VMSPurdy.
182
183           $af$
184               Kerberos v4 TGT
185
186           $apr1$
187               A variant of the $1$ scheme, used by Apache.
188
189           $krb5$
190               Kerberos v5 TGT
191
192           The historical formats supported are:
193
194           "bbbbbbbbbbbbb"
195               ("b" represents a base 64 digit.)  The original DES-based Unix
196               password hash scheme.  See Authen::Passphrase::DESCrypt.
197
198           "_bbbbbbbbbbbbbbbbbbb"
199               ("b" represents a base 64 digit.)  Extended DES-based
200               passphrase hash scheme from BSDi.  See
201               Authen::Passphrase::DESCrypt.
202
203           ""  Accept any passphrase.  See Authen::Passphrase::AcceptAll.
204
205           "*" 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
212           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
221       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
226           The specific passphrase recogniser class is loaded at runtime.  See
227           the note about this for the "from_crypt" constructor above.
228
229           Known scheme identifiers:
230
231           {CLEARTEXT}
232               Passphrase stored in cleartext.  See Authen::Passphrase::Clear.
233
234           {CRYPT}
235               The scheme identifier is followed by a crypt string.
236
237           {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
245           {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
250           {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
256           {LANM}
257               Synonym for {LANMAN}, used by CommuniGate Pro.
258
259           {LANMAN}
260               The Microsoft LAN Manager hash scheme.  See
261               Authen::Passphrase::LANManager.
262
263           {MD4}
264               The MD4 digest of the passphrase is stored.  See
265               Authen::Passphrase::SaltedDigest.
266
267           {MD5}
268               The MD5 digest of the passphrase is stored.  See
269               Authen::Passphrase::SaltedDigest.
270
271           {MSNT}
272               The NT-Hash scheme, which stores the MD4 hash of the passphrase
273               expressed in Unicode.  See Authen::Passphrase::NTHash.
274
275           {NS-MTA-MD5}
276               An MD5-based scheme used by Netscape Mail Server.  See
277               Authen::Passphrase::NetscapeMail.
278
279           {RMD160}
280               The RIPEMD-160 digest of the passphrase is stored.  See
281               Authen::Passphrase::SaltedDigest.
282
283           {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
289           {SHA}
290               The SHA-1 digest of the passphrase is stored.  See
291               Authen::Passphrase::SaltedDigest.
292
293           {SMD5}
294               The MD5 digest of the passphrase plus a salt is stored.  See
295               Authen::Passphrase::SaltedDigest.
296
297           {SSHA}
298               The SHA-1 digest of the passphrase plus a salt is stored.  See
299               Authen::Passphrase::SaltedDigest.
300
301           {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
307           {WM-CRY}
308               Synonym for {CRYPT}, used by CommuniGate Pro.
309

METHODS

311       $ppr->match(PASSPHRASE)
312           Checks whether the supplied passphrase is correct.  Returns a truth
313           value.
314
315       $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
321       $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
326       $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

SUBCLASSING

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
336       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
347       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

SEE ALSO

353       MooseX::Types::Authen::Passphrase, crypt(3), RFC 2307
354

AUTHOR

356       Andrew Main (Zefram) <zefram@fysh.org>
357
359       Copyright (C) 2006, 2007, 2009, 2010, 2012 Andrew Main (Zefram)
360       <zefram@fysh.org>
361

LICENSE

363       This module is free software; you can redistribute it and/or modify it
364       under the same terms as Perl itself.
365
366
367
368perl v5.34.0                      2021-07-22             Authen::Passphrase(3)
Impressum