PHPass’ Portable Hash — Passlib v1.7.4 Documentation (original) (raw)

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.

Interface¶

class passlib.hash. phpass¶

This class implements the PHPass Portable Hash, and follows the PasswordHash API.

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

The 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 2**rounds. ident (str) – 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 ValueError. If relaxed=True, and the error can be corrected, a PasslibHashWarningwill be issued instead. Correctable errors include roundsthat 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$_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

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:

an initial result is generated from the MD5 digest of the salt string + the secret.
for 2**_rounds_ iterations, a new result is created from the MD5 digest of the last result + the password.
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-8before 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/