Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Authen::Passphrase(3) User Contributed Perl DocumentationAuthen::Passphrase(3)

NAME
       Authen::Passphrase - hashed passwords/passphrases as objects

SYNOPSIS
	       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;

DESCRIPTION
       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.  See the
       specific	classes	for notes on the security properties of	each scheme.
       In new systems, if there	is a choice of which passphrase	algorithm to
       use, it is recommended to use Authen::Passphrase::SaltedDigest or
       Authen::Passphrase::BlowfishCrypt.  Most	other schemes are too weak for
       new applications, and should be used only for backward compatibility.

   Side-channel	cryptanalysis
       Both the	Authen-Passphrase framework and	most of	the underlying
       cryptographic algorithm implementations are vulnerable to side-channel
       cryptanalytic attacks.  However,	the impact of this is quite limited.

       Unlike the case of symmetric encryption,	where a	side-channel attack
       can extract the plaintext directly, the cryptographic operations
       involved	in passphrase recognition don't	directly process the correct
       passphrase.  A sophisticated side-channel attack, applied when offering
       incorrect passphrases for checking, could potentially extract salt
       (from the operation of the hashing algorithm) and the target hash value
       (from the comparison of hash values).  This would enable	a
       cryptanalytic or	brute-force attack on the passphrase recogniser	to be
       performed offline.  This	is not a disaster; the very intent of storing
       only a hash of the correct passphrase is	that leakage of	these stored
       values doesn't compromise the passphrase.

       In a typical usage scenario for this framework, the side-channel
       attacks that can	be mounted are very restricted.	 If authenticating
       network users, typically	an attacker has	no access at all to power
       consumption, electromagnetic emanation, and other such side channels.
       The only	side channel that is readily available is timing, and the
       precision of timing measurements	is significantly blunted by the	normal
       processes of network communication.  For	example, it would not normally
       be feasible to mount a timing attack against hash value comparison (to
       see how far through the values the first	mismatch was).

       Perl as a whole has not been built as a platform	for side-channel-
       resistant cryptography, so hardening Authen-Passphrase and its
       underlying algorithms is	not feasible.  In any serious use of Perl for
       cryptography, including for authentication using	Authen-Passphrase, an
       analysis	should be made of the exposure to side-channel attacks,	and if
       necessary efforts made to further blunt the timing channel.

       One timing attack that is very obviously	feasible over the network is
       to determine which of several passphrase	hashing	algorithms is being
       used.  This can potentially distinguish between classes of user
       accounts, or distinguish	between	existing and non-existing user
       accounts	when an	attacker is guessing usernames.	 To obscure this
       information requires an extreme restriction of the timing channel, most
       likely by explicitly pausing to standardise the amount of time spent on
       authentication.	This defence also rules	out essentially	all other
       timing attacks.

PASSPHRASE ENCODINGS
       Because hashed passphrases frequently need to be	stored,	various
       encodings of them have been devised.  This class	has constructors and
       methods to support these.

   crypt encoding
       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 encoding
       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.

CONSTRUCTORS
       Authen::Passphrase->from_crypt(PASSWD)
	   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:

	   $1$ A baroque passphrase scheme based on MD5, designed by Poul-
	       Henning Kamp and	originally implemented in FreeBSD.  See
	       Authen::Passphrase::MD5Crypt.

	   $2$
	   $2a$
	       Two versions of a passphrase scheme based on Blowfish, designed
	       by Niels	Provos and David Mazieres for OpenBSD.	See
	       Authen::Passphrase::BlowfishCrypt.

	   $3$ The NT-Hash scheme, which stores	the MD4	hash of	the passphrase
	       expressed in Unicode.  See Authen::Passphrase::NTHash.

	   $IPB2$
	       Invision	Power Board 2.x	salted MD5

	   $K4$
	       Kerberos	AFS DES

	   $LM$
	       Half of the Microsoft LAN Manager hash scheme.  The two halves
	       of a LAN	Manager	hash can be separated and manipulated
	       independently; this represents such an isolated half.  See
	       Authen::Passphrase::LANManagerHalf.

	   $NT$
	       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 "$").

	   $P$ Portable	PHP password hash (phpass), based on MD5.  See
	       Authen::Passphrase::PHPass.

	   $VMS1$
	   $VMS2$
	   $VMS3$
	       Three variants of the Purdy polynomial system used in VMS.  See
	       Authen::Passphrase::VMSPurdy.

	   $af$
	       Kerberos	v4 TGT

	   $apr1$
	       A variant of the	$1$ scheme, used by Apache.

	   $krb5$
	       Kerberos	v5 TGT

	   The historical formats supported are:

	   "bbbbbbbbbbbbb"
	       ("b" represents a base 64 digit.)  The original DES-based Unix
	       password	hash scheme.  See Authen::Passphrase::DESCrypt.

	   "_bbbbbbbbbbbbbbbbbbb"
	       ("b" represents a base 64 digit.)  Extended DES-based
	       passphrase hash scheme from BSDi.  See
	       Authen::Passphrase::DESCrypt.

	   ""  Accept any passphrase.  See Authen::Passphrase::AcceptAll.

	   "*" To handle historical practice, anything non-empty but shorter
	       than 13 characters and not starting with	"$" is treated as
	       deliberately rejecting all passphrases.	(See
	       Authen::Passphrase::RejectAll.)	Anything 13 characters or
	       longer, or starting with	"$", that is not recognised as a hash
	       is treated as an	error.

	   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.

       Authen::Passphrase->from_rfc2307(USERPASSWORD)
	   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:

	   {CLEARTEXT}
	       Passphrase stored in cleartext.	See Authen::Passphrase::Clear.

	   {CRYPT}
	       The scheme identifier is	followed by a crypt string.

	   {CRYPT16}
	       Used ambiguously	by Exim, to refer to either crypt16 (see
	       Authen::Passphrase::Crypt16) or bigcrypt	(see
	       Authen::Passphrase::BigCrypt) depending on compilation options.
	       This is a bug, resulting	from a confusion between the two
	       algorithms.  This module	does not support any meaning for this
	       scheme identifier.

	   {K5KEY}
	       Not a real passphrase scheme, but a placeholder to indicate
	       that a Kerberos key stored separately should be checked
	       against.	 No data follows the scheme identifier.

	   {KERBEROS}
	       Not a real passphrase scheme, but a placeholder to indicate
	       that Kerberos should be invoked to check	against	a user's
	       passphrase.  The	scheme identifier is followed by the user's
	       username, in the	form "name@realm".

	   {LANM}
	       Synonym for {LANMAN}, used by CommuniGate Pro.

	   {LANMAN}
	       The Microsoft LAN Manager hash scheme.  See
	       Authen::Passphrase::LANManager.

	   {MD4}
	       The MD4 digest of the passphrase	is stored.  See
	       Authen::Passphrase::SaltedDigest.

	   {MD5}
	       The MD5 digest of the passphrase	is stored.  See
	       Authen::Passphrase::SaltedDigest.

	   {MSNT}
	       The NT-Hash scheme, which stores	the MD4	hash of	the passphrase
	       expressed in Unicode.  See Authen::Passphrase::NTHash.

	   {NS-MTA-MD5}
	       An MD5-based scheme used	by Netscape Mail Server.  See
	       Authen::Passphrase::NetscapeMail.

	   {RMD160}
	       The RIPEMD-160 digest of	the passphrase is stored.  See
	       Authen::Passphrase::SaltedDigest.

	   {SASL}
	       Not a real passphrase scheme, but a placeholder to indicate
	       that SASL should	be invoked to check against a user's
	       passphrase.  The	scheme identifier is followed by the user's
	       username.

	   {SHA}
	       The SHA-1 digest	of the passphrase is stored.  See
	       Authen::Passphrase::SaltedDigest.

	   {SMD5}
	       The MD5 digest of the passphrase	plus a salt is stored.	See
	       Authen::Passphrase::SaltedDigest.

	   {SSHA}
	       The SHA-1 digest	of the passphrase plus a salt is stored.  See
	       Authen::Passphrase::SaltedDigest.

	   {UNIX}
	       Not a real passphrase scheme, but a placeholder to indicate
	       that Unix mechanisms should be used to check against a Unix
	       user's login passphrase.	 The scheme identifier is followed by
	       the user's username.

	   {WM-CRY}
	       Synonym for {CRYPT}, used by CommuniGate	Pro.

METHODS
       $ppr->match(PASSPHRASE)
	   Checks whether the supplied passphrase is correct.  Returns a truth
	   value.

       $ppr->passphrase
	   If a	matching passphrase can	be easily determined by	the passphrase
	   recogniser then this	method will return it.	This is	only feasible
	   for very weak passphrase schemes.  The method "die"s	if it is
	   infeasible.

       $ppr->as_crypt
	   Encodes the passphrase recogniser in	crypt format and returns the
	   encoded result.  "die"s if the passphrase recogniser	cannot be
	   represented in this form.

       $ppr->as_rfc2307
	   Encodes the passphrase recogniser in	RFC 2307 format	and returns
	   the encoded result.	"die"s if the passphrase recogniser cannot be
	   represented in this form.

SUBCLASSING
       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.

SEE ALSO
       MooseX::Types::Authen::Passphrase, crypt(3), RFC	2307

AUTHOR
       Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT
       Copyright (C) 2006, 2007, 2009, 2010, 2012 Andrew Main (Zefram)
       <zefram@fysh.org>

LICENSE
       This module is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.1			  2021-02-28		 Authen::Passphrase(3)

NAME | SYNOPSIS | DESCRIPTION | PASSPHRASE ENCODINGS | CONSTRUCTORS | METHODS | SUBCLASSING | SEE ALSO | AUTHOR | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Authen::Passphrase&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help