# `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.

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 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 `PasslibHashWarning` will be issued instead. Correctable errors include `rounds` that are too small or too large, and `salt` strings that are too long.

      Added 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/