Authen::Passphrase
Authen::Passphrase
Authen::Passphrase - hashed passwords/passphrases as objects
use Authen::Passphrase;
$ppr = Authen::Passphrase->from_crypt($passwd);
$ppr = Authen::Passphrase->from_rfc2307($userPassword);
if($ppr->match($passphrase)) { ...
$passphrase = $ppr->passphrase;
$crypt = $ppr->as_crypt;
$userPassword = $ppr->as_rfc2307;
This is the base class for a system of objects that encapsulate passphrases. An object of this type is a passphrase recogniser: its job is to recognise whether an offered passphrase is the right one. For security, such passphrase recognisers usually do not themselves know the passphrase they are looking for; they can merely recognise it when they see it. There are many schemes in use to achieve this effect, and the intent of this class is to provide a consistent interface to them all, hiding the details.
The CPAN package Authen::Passphrase contains implementations of several specific passphrase schemes in addition to the base class.
Because hashed passphrases frequently need to be stored, various encodings of them have been devised. This class has constructors and methods to support these.
The Unix crypt() function, which performs passphrase hashing, returns hashes in a textual format intended to be stored in a text file. In particular, such hashes are stored in /etc/passwd (and now /etc/shadow) to control access to Unix user accounts. The same textual format has been adopted and extended by other passphrase-handling software such as password crackers.
For historical reasons, there are several different syntaxes used in this format. The original DES-based password scheme represents its hashes simply as a string of thirteen base 64 digits. An extended variant of this scheme uses nineteen base 64 digits, preceded by an "_" marker. A more general syntax was developed later, which starts the string with "$", an alphanumeric scheme identifier, and another "$".
In addition to actual passphrase hashes, the crypt format can also represent a couple of special cases. The empty string indicates that there is no access control; it is possible to login without giving a passphrase. Finally, any string that is not a possible output of crypt() may be used to prevent login completely; "*" is the usual choice, but other strings are used too.
crypt strings are intended to be used in text files that use colon and newline characters as delimiters. This module treats the crypt string syntax as being limited to ASCII graphic characters excluding colon.
RFC 2307 describes an encoding system for passphrase hashes, to be used in the "userPassword" attribute in LDAP databases. It encodes hashes as ASCII text, and supports several passphrase schemes in an extensible way by starting the encoding with an alphanumeric scheme identifier enclosed in braces. There are several standard scheme identifiers. The "{CRYPT}" scheme allows the use of any crypt encoding.
This module treats the RFC 2307 string syntax as being limited to ASCII graphic characters.
The RFC 2307 encoding is a good one, and is recommended for storage and exchange of passphrase hashes.
Returns a passphrase recogniser object matching the supplied crypt encoding. This constructor may only be called on the base class, not any subclass.
The specific passphrase recogniser class is loaded at runtime, so
successfully loading Authen::Passphrase does not guarantee that
it will be possible to use a specific type of passphrase recogniser.
If necessary, check separately for presence and loadability of the
recogniser class.
Known scheme identifiers:
The NT-Hash scheme, which stores the MD4 hash of the passphrase expressed in Unicode. See Authen::Passphrase::NTHash.
The $3$ identifier refers to the same hash algorithm, but has a slightly different textual format (an extra "$").
The historical formats supported are:
There are also two different passphrase schemes that use a crypt string consisting of 24 base 64 digits. One is named "bigcrypt" and appears in HP-UX, Digital Unix, and OSF/1 (see Authen::Passphrase::BigCrypt). The other is named "crypt16" and appears in Ultrix and Tru64 (see Authen::Passphrase::Crypt16). These schemes conflict. Neither of them is accepted as a crypt string by this constructor; such strings are regarded as invalid encodings.
Returns a passphrase recogniser object matching the supplied RFC 2307 encoding. This constructor may only be called on the base class, not any subclass.
The specific passphrase recogniser class is loaded at runtime. See the
note about this for the from_crypt constructor above.
Known scheme identifiers:
dies if it is infeasible.
dies if the passphrase recogniser cannot be represented in
this form.
Encodes the passphrase recogniser in RFC 2307 format and returns
the encoded result. dies if the passphrase recogniser cannot be
represented in this form.
This class is designed to be subclassed, and cannot be instantiated alone.
Any subclass must implement the match method. That is the minimum
required.
Subclasses should implement the as_crypt and as_rfc2307 methods
and the from_crypt and from_rfc2307 constructors wherever
appropriate, with the following exception. If a passphrase scheme has
a crypt encoding but no native RFC 2307 encoding, so it can be RFC 2307
encoded only by using the "{CRYPT}" scheme, then as_rfc2307 and
from_rfc2307 should not be implemented by the class. There is a
default implementation of the as_rfc2307 method that uses "{CRYPT}"
and as_crypt, and a default implementation of the from_rfc2307
method that recognises "{CRYPT}" and passes the embedded crypt string
to the from_crypt constructor.
Implementation of the passphrase method is entirely optional.
It should be attempted only for schemes that are so ludicrously weak as
to allow passphrases to be cracked reliably in a short time. Dictionary
attacks are not appropriate implementations.
crypt(3), RFC 2307
Andrew Main (Zefram) <zefram@fysh.org>
Copyright (C) 2006, 2007, 2009 Andrew Main (Zefram) <zefram@fysh.org>
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.