added phpass portable hash

3 files changed, 63 insertions, 2 deletions

diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst
index cea2991..76c0b96 100644
--- a/docs/lib/passlib.hash.md5_crypt.rst
+++ b/docs/lib/passlib.hash.md5_crypt.rst
@@ -5,8 +5,7 @@
 .. module:: passlib.hash.md5_crypt
     :synopsis: MD5-Crypt
 
-Also known as BSD-MD5-Crypt,
-this algorithm was developed to replace the aging des-crypt crypt.
+This algorithm was developed to replace the aging des-crypt crypt.
 It is supported by a wide variety of unix flavors, and is found
 in other contexts as well.
 
diff --git a/docs/lib/passlib.hash.phpass.rst b/docs/lib/passlib.hash.phpass.rst
new file mode 100644
index 0000000..3808501
--- /dev/null
+++ b/docs/lib/passlib.hash.phpass.rst
@@ -0,0 +1,61 @@
+==================================================================
+:mod:`passlib.hash.phpass` - PHPass Portable Hash
+==================================================================
+
+.. module:: passlib.hash.phpass
+    :synopsis: PHPass Portable Hash
+
+This algorithm is used primarily by PHP software
+which uses the `PHPass <http://www.openwall.com/phpass/>`_ library,
+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. It's hashes
+can be identified by the :ref:`modular-crypt-format` prefixe
+``$P$`` (or ``$H$`` in phpBB3 databases).
+Due to it's reliance on MD5, and the simplistic implementation,
+other hash algorithms should be used if possible.
+
+Usage
+=====
+.. todo::
+
+    write usage instructions
+
+Functions
+=========
+.. autofunction:: genconfig
+.. autofunction:: genhash
+.. autofunction:: encrypt
+.. autofunction:: identify
+.. autofunction:: verify
+
+Format
+======
+An phpass portable hash string has length 34, with the format ``$P$<rounds><salt><checksum>``;
+where ``<rounds>`` is a single character encoding a 6-bit integer,
+``<salt>`` is an eight-character salt, and ``<checksum>`` is an encoding
+of the 128 bit checksum. All values are encoded using :mod:`hash64 <passlib.utils.h64>`.
+
+An example hash (of ``password``) is ``$P$8ohUJ.1sdFw09/bMaAQPTGDNi2BIUt1``;
+the rounds are encoded in ``8``, the salt is ``ohUJ.1sd``,
+and the checksum is ``Fw09/bMaAQPTGDNi2BIUt1``.
+
+Algorithm
+=========
+PHPass uses a straightforward algorithm:
+
+* an initial result is generated from the MD5 digest of the salt string + the secret.
+* for 2**rounds repetitions, a new result is created from the MD5 digest of the last result + the secret.
+* the last result is then encoded according to the format described above.
+
+Deviations
+==========
+This implementation of phpass differs from the specification:
+
+* Unicode strings are encoded using UTF-8 before being passed into the algorithm.
+  While the original code accepts passwords containing any 8-bit value,
+  it has no specific policy for dealing with unicode.
+
+References
+==========
+* `<http://www.openwall.com/phpass/>` - PHPass homepage, which describes the algorithm
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index eb14aad..91ae6e6 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -47,6 +47,7 @@ the modular crypt format.
     :maxdepth: 1
 
     passlib.hash.apr_md5_crypt
+    passlib.hash.phpass
     passlib.hash.nthash
 
 .. todo::