updated docs for md5-crypt, django hashes, and django plugin; added django plugin to setup

4 files changed, 77 insertions, 54 deletions

diff --git a/docs/lib/passlib.ext.django.rst b/docs/lib/passlib.ext.django.rst
index 5d6a61c..25147e5 100644
--- a/docs/lib/passlib.ext.django.rst
+++ b/docs/lib/passlib.ext.django.rst
@@ -9,8 +9,8 @@
 .. warning::
 
     This module is currently under development.
-    It will probably work, but has not seen very much
-    testing or real-world use, and may change in future releases;
+    It works and has good unittest coverage,
+    but has not seen very much real-world use;
     *caveat emptor*.
 
 .. todo::
@@ -23,35 +23,36 @@ Overview
 This module is intended for use with
 `Django <http://www.djangoproject.com>`_-based web applications.
 It contains a Django app which allows you to override
-Django's :doc:`default <passlib.hash.django_std>` password hash formats
-with any passlib :doc:`CryptContext <passlib.context>`.
+Django's builtin password hashing routine
+with any Passlib :doc:`CryptContext <passlib.context>` instance.
 By default, it comes configured to add support for
 :class:`~passlib.hash.sha512_crypt`, and will automatically
-upgrade all existing Django passwords as your users log in.
+upgrade all existing Django password hashes as your users log in.
 
-.. note::
-
-    SHA512-Crypt was chosen as probably the best choice for
-    the average Django deployment. Accelerated implementations
-    are available on most Linux systems, as well as Google App Engine.
+:doc:`SHA512-Crypt <passlib.hash.sha512_crypt>`
+was chosen as the best choice for the average Django deployment:
+accelerated implementations are available on most stock Linux systems,
+as well as Google App Engine, and Passlib provides a pure-python
+fallback for all other platforms. 
 
 Installation
 =============
-Installation is simple, just add ``passlib.ext.django`` to
-``settings.INSTALLED_APPS``. This module will handle
+Installation is simple: just add ``"passlib.ext.django"`` to
+Django's ``settings.INSTALLED_APPS``. This app will handle
 everything else.
 
 Once done, when this app is imported by Django,
 it will automatically monkeypatch
 :class:`!django.contrib.auth.models.User`
-to use a Passlib CryptContext instance in place of normal Django
-password authentication. This provides hash migration,
-ability to set stronger policies for superuser & staff passwords,
-and stronger password hashing schemes.
+to use a Passlib :class:`~passlib.context.CryptContext` instance
+in place of the normal Django password authentication routines.
+
+This provides hash migration, the ability to set stronger policies
+for superuser & staff passwords, and stronger password hashing schemes.
 
 Configuration
 =============
-You can set the following options in django ``settings.py``:
+Once installed, you can set the following options in django ``settings.py``:
 
 ``PASSLIB_CONTEXT``
    This may be one of a number of values:
@@ -64,10 +65,10 @@ You can set the following options in django ``settings.py``:
 
      This is the default behavior if ``PASSLIB_CONTEXT`` is not set.
 
-     The exact default policy can be found in
+     The exact default policy used can be found in
      :data:`~passlib.ext.django.utils.DEFAULT_CTX`.
 
-   * ``None``, in which case this app will do nothing when django is loaded.
+   * ``None``, in which case this app will do nothing when Django is loaded.
 
    * A multiline configuration string suitable for passing to
      :meth:`passlib.context.CryptPolicy.from_string`.
@@ -83,9 +84,10 @@ You can set the following options in django ``settings.py``:
    staff to the ``staff`` category, and all other accounts
    assigned to ``None``.
 
-   This allows overriding that logic by specifying an alternate
-   function of the format ``get_category(user) -> category|None``.
-
+   This configuration option allows overriding that logic
+   by specifying an alternate function with the call signature
+   ``get_category(user) -> category|None``.
+   
    .. seealso::
 
         See :ref:`user-categories` for more details about
diff --git a/docs/lib/passlib.hash.django_std.rst b/docs/lib/passlib.hash.django_std.rst
index 9fb4548..1e4be54 100644
--- a/docs/lib/passlib.hash.django_std.rst
+++ b/docs/lib/passlib.hash.django_std.rst
@@ -7,34 +7,49 @@
 .. 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. 
+provides a module for storing user accounts and passwords
+(:mod:`!django.contrib.auth`).
+This module's password hashing code supports a few simple salted digests,
+stored using the format :samp:`{id}${salt}${checksum}` (where :samp:`{id}`
+is an identifier assigned by Django).
+Passlib provides support for all the hashes used by Django:
+
+* :class:`django_salted_sha1` - simple salted SHA1 digest, currently Django's default.
+* :class:`django_salted_md5` - simple salted MD5 digest.
+* :class:`django_des_crypt` - support for legacy :class:`des_crypt` hashes,
+  shoehorned into Django's hash format.
+* :class:`hex_md5` - historical format used by old Django versions.
+
+.. warning::
+
+    All of these hashes are suceptible to brute-force attacks;
+    even the strongest of these (:class:`django_salted_sha1`)
+    is a simple single-round salted digest.
+    They should not be used for any purpose
+    besides manipulating existing Django password hashes.
 
 .. seealso::
 
-    * :data:`passlib.apps.django_context` for a premade Django context
+    * :data:`passlib.apps.django_context` - 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. 
+    * :mod:`passlib.ext.django` - a plugin that
+      updates Django to use a stronger hashing scheme,
+      and migrates existing hashes as users log in.
+
+Salted Hashes
+=============
 
 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='
+    'sha1$c6218$161d1ac8ab38979c5a31cbaba4a67378e7e60845'
 
     >>> lms.identify(h) #check if hash is recognized
     True
@@ -46,8 +61,9 @@ These classes can be used directly as follows::
     >>> lms.verify("secret", h) #verify incorrect password
     False
 
-Salted Hashes
-=============
+Interface
+---------
+
 .. autoclass:: django_salted_md5()
 .. autoclass:: django_salted_sha1()
 
@@ -71,7 +87,7 @@ 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.
@@ -82,7 +98,7 @@ Django's salted hashes should not be considered very secure.
 * 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.
@@ -108,7 +124,7 @@ 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. 
+duplicated as the first two characters of the checksum.
 
 For security issues relating to :class:`!django_des_crypt`,
 see :class:`des_crypt`.
@@ -123,4 +139,3 @@ Other Hashes
     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.ldap_std.rst b/docs/lib/passlib.hash.ldap_std.rst
index fe2cf69..3ae8c33 100644
--- a/docs/lib/passlib.hash.ldap_std.rst
+++ b/docs/lib/passlib.hash.ldap_std.rst
@@ -48,6 +48,12 @@ However, they can be used directly as follows::
 
 Plain Hashes
 ============
+.. warning::
+
+    These hashes should be considered secure in any manner,
+    as they are nothing but raw MD5 & SHA-1 digests,
+    which are extremely vulnerable to brute-force attacks.
+
 .. autoclass:: ldap_md5()
 .. autoclass:: ldap_sha1()
 
@@ -64,10 +70,6 @@ These hashes have the format :samp:`{prefix}{checksum}`.
 An example ldap_md5 hash (of ``password``) is ``{MD5}X03MO1qnZdYdgyfeuILPmQ==``.
 An example ldap_sha1 hash (of ``password``) is ``{SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=``.
 
-These hashes should be considered secure in any manner,
-as they are nothing but raw MD5 & SHA-1 digests,
-which are extremely vulnerable to brute-force attacks.
-
 Salted Hashes
 =============
 .. autoclass:: ldap_salted_md5()
diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst
index 03681c2..d033723 100644
--- a/docs/lib/passlib.hash.md5_crypt.rst
+++ b/docs/lib/passlib.hash.md5_crypt.rst
@@ -59,7 +59,7 @@ The MD5-Crypt algorithm [#f1]_ calculates a checksum as follows:
 1. A password string and salt string are provided.
 
    (The salt should not include the magic prefix,
-   it should match string referred to as :samp:`{salt}` in the format section).
+   it should match the string referred to as :samp:`{salt}` in the format section, above).
 
 2. If needed, the salt should be truncated to a maximum of 8 characters.
 
@@ -81,7 +81,9 @@ The MD5-Crypt algorithm [#f1]_ calculates a checksum as follows:
 
 9. Add the password to digest A.
 
-10. Add the constant string ``$1$`` to digest A.
+10. Add the constant string ``$1$`` to digest A. 
+    (The Apache variant of MD5-Crypt uses ``$apr1$`` instead,
+    this is the only change made by this variant).
 
 11. Add the salt to digest A.
 
@@ -91,13 +93,15 @@ The MD5-Crypt algorithm [#f1]_ calculates a checksum as follows:
 13. For the remaining N bytes of the password string,
     add the first N bytes of digest B to digest A.
 
-14. For each bit of the binary representation of the length
+14. For each bit in the binary representation of the length
     of the password string; starting with the lowest value bit,
-    up to and including the largest bit set to 1:
+    up to and including the largest-valued bit that is set to ``1``:
 
     a. If the current bit is set 1, add the first character of the password to digest A.
     b. Otherwise, add a NULL character to digest A.
 
+    (If the password is the empty string, step 14 is omitted entirely).
+
 15. Finish MD5 digest A.
 
 ..
@@ -110,9 +114,9 @@ The MD5-Crypt algorithm [#f1]_ calculates a checksum as follows:
     c. If the round is even, add the previous round's result to digest C (for round 0, add digest A instead).
     d. If the round is not a multiple of 3, add the salt to digest C.
     e. If the round is not a multiple of 7, add the password to digest C.
-    f. If the round is even, repeat step b.
-    g. If the round is odd, repeat step c.
-    h. Finish MD5 digest C for the round; this is the result for this round.
+    f. If the round is even, add the password to digest C.
+    g. If the round is odd, add the previous round's result to digest C (for round 0, add digest A instead).
+    h. Use the final value of MD5 digest C as the result for this round.
 
 17. Transpose the 16 bytes of the final round's result in the
     following order: ``12,6,0,13,7,1,14,8,2,15,9,3,5,10,4,11``.