added support for Cryptacular's PBKDF2 format

3 files changed, 74 insertions, 0 deletions

diff --git a/docs/lib/passlib.hash.cta_pbkdf2_sha1.rst b/docs/lib/passlib.hash.cta_pbkdf2_sha1.rst
new file mode 100644
index 0000000..2814764
--- /dev/null
+++ b/docs/lib/passlib.hash.cta_pbkdf2_sha1.rst
@@ -0,0 +1,70 @@
+=================================================================
+:class:`passlib.hash.cta_pbkdf2_sha1` - Cryptacular's PBKDF2 hash
+=================================================================
+
+.. index:: pbkdf2 hash; cryptacular
+
+.. currentmodule:: passlib.hash
+
+This class provides an implementation of Cryptacular's
+PBKDF2-HMAC-SHA1 hash format [#cta]_. PBKDF2 is a key derivation function [#pbkdf2]_
+that is ideally suited as the basis for a password hash, as it provides
+variable length salts, variable number of rounds.
+
+.. seealso::
+
+    :doc:`passlib.hash.pbkdf2_digest <passlib.hash.pbkdf2_digest>`
+    for some other PBKDF2-based hashes.
+    
+    :doc:`passlib.hash.dlitz_pbkdf2_sha1 <passlib.hash.dlitz_pbkdf2_sha1>`
+    for another hash which looks almost exactly like this one.
+
+Usage
+=====
+This class support both rounds and salts,
+and can be used in the exact same manner
+as :doc:`SHA-512 Crypt <passlib.hash.sha512_crypt>`.
+
+Interface
+=========
+.. autoclass:: cta_pbkdf2_sha1()
+
+.. rst-class:: html-toggle
+
+Format & Algorithm
+==================
+
+A example hash (of ``password``) is:
+
+    ``$p5k2$2710$oX9ZZOcNgYoAsYL-8bqxKg==$AU2JLf2rNxWoZxWxRCluY0u6h6c=``
+
+All of this scheme's hashes have the format :samp:`$p5k2${rounds}${salt}${checksum}`,
+where:
+
+* ``$p5k2$`` is used as the :ref:`modular-crypt-format` identifier.
+
+* :samp:`{rounds}` is the number of PBKDF2 iterations to perform,
+  stored as lowercase hexidecimal number with no zero-padding (in the example: ``2710`` or 10000 iterations).
+
+* :samp:`{salt}` is the salt string encoding using
+  base64 (with ``-_`` as the high values).
+  ``oX9ZZOcNgYoAsYL-8bqxKg==`` in the example.
+
+* :samp:`{checksum}` is 28 characters encoding
+  the resulting 20-byte PBKDF2 derived key using
+  base64 (with ``-_`` as the high values).
+  ``AU2JLf2rNxWoZxWxRCluY0u6h6c=`` in the example.
+
+In order to generate the checksum, the password is first encoded into UTF-8 if it's unicode.
+The salt is decoded from it's base64 representation.
+PBKDF2 is called using the encoded password, the full salt,
+the specified number of rounds, and using HMAC-SHA1 as it's psuedorandom function.
+20 bytes of derived key are requested, and the resulting key is encoded and used
+as the checksum portion of the hash.
+
+References
+==========
+
+.. [#cta] The reference for this hash format - `<https://bitbucket.org/dholth/cryptacular/>`_.
+
+.. [#pbkdf2] The specification for the PBKDF2 algorithm - `<http://tools.ietf.org/html/rfc2898#section-5.2>`_.
diff --git a/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst b/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst
index 7b61146..95dedbe 100644
--- a/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst
+++ b/docs/lib/passlib.hash.dlitz_pbkdf2_sha1.rst
@@ -15,6 +15,9 @@ variable length salts, variable number of rounds.
 
     :doc:`passlib.hash.pbkdf2_digest <passlib.hash.pbkdf2_digest>`
     for some other PBKDF2-based hashes.
+    
+    :doc:`passlib.hash.cta_pbkdf2_sha1 <passlib.hash.cta_pbkdf2_sha1>`
+    for another hash which looks almost exactly like this one.
 
 Usage
 =====
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index eb8450e..3c840f1 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -90,6 +90,7 @@ compatible by along side others in this section.
     passlib.hash.phpass
     passlib.hash.nthash
     passlib.hash.pbkdf2_digest
+    passlib.hash.cta_pbkdf2_sha1
     passlib.hash.dlitz_pbkdf2_sha1
 
 Special note should be made of the fallback helper,