added documentation for Django hashes & context

3 files changed, 140 insertions, 1 deletions

diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst
index b5da280..40d3b7a 100644
--- a/docs/lib/passlib.apps.rst
+++ b/docs/lib/passlib.apps.rst
@@ -43,6 +43,18 @@ Custom Applications
 
     The :doc:`/new_app_quickstart`.
 
+.. index:: django; crypt context
+
+Django
+======
+.. data:: django_context
+
+    This object provides a pre-configured :class:`!CryptContext` instance
+    for handling `Django <http://www.djangoproject.com>`_
+    password hashes, as used by Django's ``django.contrib.auth`` module.
+    It recognizes all the :doc:`builtin Django hashes <passlib.hash.django_std>`.
+    It defaults to using the :class:`~passlib.hash.django_salted_sha1` hash.
+    
 .. _ldap-contexts:
 
 LDAP
diff --git a/docs/lib/passlib.hash.django_std.rst b/docs/lib/passlib.hash.django_std.rst
new file mode 100644
index 0000000..9fb4548
--- /dev/null
+++ b/docs/lib/passlib.hash.django_std.rst
@@ -0,0 +1,126 @@
+.. index:: django; hash formats
+
+=============================================================
+:samp:`passlib.hash.django_{digest}` - Django-specific Hashes
+=============================================================
+
+.. currentmodule:: passlib.hash
+
+The `Django <http://www.djangoproject.com>`_ web framework
+provides a module for storing user accounts and passwords.
+This module's password storage supports a few simple salted digests,
+stored using a format similar to the :ref:`modular-crypt-format`.
+They are simple single-round salted digests, similar in security
+but different in form to :class:`~passlib.hash.ldap_salted_sha1`.
+Lacking a variable number of rounds, and placing the salt
+first in the digest, they are weak against brute-force attacks,
+and should probably not be used outside of Django. 
+
+.. seealso::
+
+    * :data:`passlib.apps.django_context` for a premade Django context
+      which can read all of the formats listed below.
+
+..
+    * :mod:`passlib.ext.django` for a Django app that can replace
+      the Django's default hash implementation with a custom Passlib context. 
+
+Usage
+=====
+These classes can be used directly as follows::
+
+    >>> from passlib.hash import django_salted_sha1 as dss
+    
+    >>> #encrypt password
+    >>> h = dss.encrypt("password")
+    >>> h
+    '{SMD5}OqsUXNHIhHbznxrqHoIM+ZT8DmE='
+
+    >>> lms.identify(h) #check if hash is recognized
+    True
+    >>> lms.identify('JQMuyS6H.AGMo') #check if some other hash is recognized
+    False
+
+    >>> lms.verify("password", h) #verify correct password
+    True
+    >>> lms.verify("secret", h) #verify incorrect password
+    False
+
+Salted Hashes
+=============
+.. autoclass:: django_salted_md5()
+.. autoclass:: django_salted_sha1()
+
+Format
+------
+An example :class:`!django_salted_sha1` hash (of ``password``) is:
+
+    ``sha1$f8793$c4cd18eb02375a037885706d414d68d521ca18c7``
+
+Both of Django's salted hashes have the same basic format,
+:samp:`{ident}${salt}${checksum}`, where:
+
+* :samp:`{ident}` is an identifier (``sha1`` in the case of the example,
+  ``md5`` for :class:`!django_salted_md5`).
+
+* :samp:`{salt}` consists of (usually 5) lowercase hexidecimal digits (``f8793`` in the example).
+
+* :samp:`{checksum}` is lowercase hexidecimal encoding of the checksum.
+
+The checksum is generated by concatenating the salt digits followed
+by the password, and hashing them using the specified digest (MD5 or SHA-1).
+The digest is then encoded to hexidecimal.
+If the password is unicode, it is converted to ``utf-8`` first.
+    
+Security Issues
+---------------
+Django's salted hashes should not be considered very secure.
+
+* They use only a single round of digests with known collision
+  and pre-image attacks (SHA1 & MD5).
+
+* While it could be increased, they currently use only 20 bits
+  of entropy in their salt, which is borderline insufficient to defeat
+  rainbow tables.
+  
+* They digest the encoded hexidecimal salt, not the raw bytes,
+  increasing the odds that a particular salt+password string
+  will be present in a pre-computed tables of ascii digests.
+
+Des Crypt
+=========
+
+.. autoclass:: django_des_crypt()
+
+Format
+------
+An example :class:`!django_des_crypt` hash (of ``password``) is
+``crypt$cd1a4$cdlRbNJGImptk``; the general format is the same
+as the salted hashes: :samp:`{ident}${salt}${checksum}`, where:
+
+* :samp:`{ident}` is the identifier ``crypt``.
+
+* :samp:`{salt}` is 5 lowercase hexidecimal digits (``cd1a4`` in the example).
+
+* :samp:`{checksum}` is a :class:`!des_crypt` hash (``cdlRbNJGImptk`` in the example).
+
+It should be noted that this class essentially just shoe-horns
+:class:`des_crypt` into a format compatible with the Django salted hashes (above).
+It has a few quirks, such as the fact that only the first two characters
+of the salt are used by :class:`!des_crypt`, and they are in turn
+duplicated as the first two characters of the checksum. 
+
+For security issues relating to :class:`!django_des_crypt`,
+see :class:`des_crypt`.
+
+Other Hashes
+============
+
+.. autoclass:: django_disabled
+
+.. note::
+
+    Older versions of Django may also have
+    passwords encoded using :class:`~passlib.hash.hex_md5`,
+    though this has been deprecated by Django.
+  
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index 2e719e6..e9242d8 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -185,9 +185,10 @@ in one of the above categories:
 .. toctree::
     :maxdepth: 1
 
+    passlib.hash.django_std
+    passlib.hash.grub_pbkdf2_sha512
     passlib.hash.hex_digests
     passlib.hash.plaintext
-    passlib.hash.grub_pbkdf2_sha512
 
 References
 ==========