Skip to content

passlib.hash.phpass - PHPass' Portable Hash

This algorithm is used primarily by PHP software which uses PHPass 1, a PHP library similar to Passlib. The PHPass Portable Hash is a custom password hash used by PHPass as a fallback when none of its other hashes are available. Due to its reliance on MD5, and the simplistic implementation, other hash algorithms should be used if possible.

Tip

password hash usage -- for examples of how to use this class via the common hash interface.

Interface

phpass 

phpass(ident=None, **kwds)

This class implements the PHPass Portable Hash, and follows the :ref:password-hash-api.

It supports a fixed-length salt, and a variable number of rounds.

The :meth:~passlib.ifc.PasswordHash.using method accepts the following optional keywords:

Parameters:

  • salt (str) –

    Optional salt string. If not specified, one will be autogenerated (this is recommended). If specified, it must be 8 characters, drawn from the regexp range [./0-9A-Za-z].

  • rounds (int) –

    Optional number of rounds to use. Defaults to 19, must be between 7 and 30, inclusive. This value is logarithmic, the actual number of iterations used will be :samp:2**{rounds}.

  • ident (str, default: None ) –

    phpBB3 uses H instead of P for its identifier, this may be set to H in order to generate phpBB3 compatible hashes. it defaults to P.

  • relaxed (bool) –

    By default, providing an invalid value for one of the other keywords will result in a :exc:ValueError. If relaxed=True, and the error can be corrected, a :exc:~passlib.exc.PasslibHashWarning will be issued instead. Correctable errors include rounds that are too small or too large, and salt strings that are too long.

    .. versionadded:: 1.6

encrypt classmethod 

encrypt(*args, **kwds)

Legacy alias for :meth:hash.

.. deprecated:: 1.7 This method was renamed to :meth:!hash in version 1.7. This alias will be removed in version 2.0, and should only be used for compatibility with Passlib 1.3 - 1.6.

using classmethod 

using(default_ident=None, ident=None, **kwds)

This mixin adds support for the following :meth:~passlib.ifc.PasswordHash.using keywords:

Parameters:

  • default_ident –

    default identifier that will be used by resulting customized hasher.

  • ident –

    supported as alternate alias for default_ident.

parsehash classmethod 

parsehash(hash, checksum=True, sanitize=False)

[experimental method] parse hash into dictionary of settings.

this essentially acts as the inverse of :meth:hash: for most cases, if hash = cls.hash(secret, **opts), then cls.parsehash(hash) will return a dict matching the original options (with the extra keyword checksum).

this method may not work correctly for all hashes, and may not be available on some few. its interface may change in future releases, if it's kept around at all.

Parameters:

  • hash –

    hash to parse

  • checksum –

    include checksum keyword? (defaults to True)

  • sanitize –

    mask data for sensitive fields? (defaults to False)

bitsize classmethod 

bitsize(rounds=None, vary_rounds=0.1, **kwds)

[experimental method] return info about bitsizes of hash

default_salt_size 

default_salt_size()

default salt size (defaults to max_salt_size)

default_salt_chars 

default_salt_chars()

charset used to generate new salt strings (defaults to salt_chars)

Format

An example hash (of password) is $P$8ohUJ.1sdFw09/bMaAQPTGDNi2BIUt1. A phpass portable hash string has the format $P${rounds}{salt}{checksum}, where:

  • $P$ is the prefix used to identify phpass hashes, following the modular-crypt-format.

  • {rounds} is a single character encoding a 6-bit integer representing the number of rounds used. This is logarithmic, the real number of rounds is 2**rounds. (in the example, rounds is encoded as 8, or 2**13 iterations).

  • {salt} is eight characters drawn from [./0-9A-Za-z], providing a 48-bit salt (ohUJ.1sd in the example).

  • {checksum} is 22 characters drawn from the same set, encoding the 128-bit checksum (Fw09/bMaAQPTGDNi2BIUt1 in the example).

Note

phpBB3 databases uses the alternate prefix $H$, both prefixes are recognized by this implementation, and the checksums are the same.

Algorithm

PHPass uses a straightforward algorithm to calculate the checksum:

  1. an initial result is generated from the MD5 digest of the salt string + the secret.
  2. for 2**{rounds} iterations, a new result is created from the MD5 digest of the last result + the password.
  3. the last result is then encoded according to the format described above.

Deviations

This implementation of phpass differs from the specification in one way:

  • Unicode Policy:

The underlying algorithm takes in a password specified as a series of non-null bytes, and does not specify what encoding should be used; though a us-ascii compatible encoding is implied by nearly all known reference hashes.

In order to provide support for unicode strings, Passlib will encode unicode passwords using utf-8 before running them through phpass. If a different encoding is desired by an application, the password should be encoded before handing it to Passlib.

  1. PHPass homepage, which describes the Portable Hash algorithm - http://www.openwall.com/phpass/ ↩