This algorithm is used primarily by PHP software
which uses PHPass ,
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.
password hash usage –
for examples of how to use this class via the common hash interface.
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:
- 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.
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 that phpBB3 databases uses the alternate prefix $H$, both prefixes
are recognized by this implementation, and the checksums are the same.
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.
This implementation of phpass differs from the specification in one way:
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.