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 it’s other hashes are available. Due to it’s reliance on MD5, and the simplistic implementation, other hash algorithms should be used if possible.

See also

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

Interface

class passlib.hash.phpass

This class implements the PHPass Portable Hash, and follows the Password Hash Interface.

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

The encrypt() and genconfig() methods accept 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 16, must be between 7 and 30, inclusive. This value is logarithmic, the actual number of iterations used will be 2**rounds.
• ident (str) – phpBB3 uses H instead of P for it’s 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 ValueError. If relaxed=True, and the error can be corrected, a PasslibHashWarning will be issued instead. Correctable errors include rounds that are too small or too large, and salt strings that are too long.

  New in version 1.6.

Format

An example hash (of password) is $P$8ohUJ.1sdFw09/bMaAQPTGDNi2BIUt1. A phpass portable hash string has the format $P$roundssaltchecksum, 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

Note that 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.

Footnotes

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