various documentation updates

9 files changed, 144 insertions, 109 deletions

diff --git a/CHANGES b/CHANGES
index bb9725f..8de3788 100644
--- a/CHANGES
+++ b/CHANGES
@@ -6,6 +6,11 @@ Release History
 
 **1.4** (NOT YET RELEASED)
 
+    This release contains a large number of changes, both large and small.
+    It adds a number of PBKDF2-based schemes, better support
+    for LDAP-format hashes, improved documentation,
+    and faster load times. In detail...
+
     Hashes
 
         * added LDAP ``{CRYPT}`` support for all hashes
diff --git a/docs/index.rst b/docs/index.rst
index 97e62a6..34f6e90 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,23 +2,28 @@
 PassLib |release| documentation
 ==========================================
 
-Introduction
-============
-PassLib is a library for encrypting, verifying, and managing password hashes.
-It supports over 20 different password hash schemes.
-It can be used for a variety of purposes:
-
-* cross-platform replacement for stdlib's :func:`!crypt`.
-* encrypting & verifying most known hash formats used by:
-    - Linux & BSD shadow files
-    - Apache htpasswd & htdigest files
+Welcome
+=======
+Passlib is a password hashing library for Python, which provides cross-platform
+implementations of over 20 password hashing algorithms;
+as well as a framework for managing and migrating existing password hashes.
+It's designed to be useful for a large range of tasks...
+
+* as a cross-platform replacement for stdlib's :func:`!crypt` --> :data:`~passlib.hosts.host_context`.
+
+* encrypting & verifying most hash formats used by:
+    - Linux & BSD shadow files --> :mod:`passlib.hosts`
+    - Apache htpasswd & htdigest files --> :mod:`passlib.apache`
     - MySQL, PostgreSQL, and Oracle user account tables
-    - LDAP style password hashes
-* drop-in password hash support for new python applications.
+    - OpenLDAP password hashes
+    - Many other applications --> :mod:`passlib.apps`.
+
+* drop-in password hash support for new python applications --> :data:`~passlib.apps.custom_app_context`.
+
 * building a configurable hashing policy
-  for python applications to migrate existing hashing schemes.
+  for python applications to migrate existing hashing schemes --> :mod:`passlib.context`.
 
-See the library overview for usage examples.
+See the :doc:`library overview <overview>` for more details and usage examples.
 
 Quick Links
 ===========
@@ -30,28 +35,38 @@ Quick Links
         <td width="50%" valign="top">
             <p class="biglink">
                 <a class="biglink" href="overview.html">Library Overview</a><br>
-                <span class="linkdescr">describes how PassLib is laid out</span>
+                <span class="linkdescr">describes how Passlib is laid out</span>
             </p>
 
             <p class="biglink">
+                <a class="biglink" href="lib/passlib.hash.html"><i>passlib.hash</i> module</a><br>
+                <span class="linkdescr">complete list of supported password hash algorithms</span>
+            </p>
+        </td>
+        <td width="50%" valign="top">
+            <p class="biglink">
                 <a class="biglink" href="install.html">Installation</a><br>
                 <span class="linkdescr">requirements and installation instructions</span>
             </p>
 
             <p class="biglink">
-                <a class="biglink" href="lib/passlib.hash.html"><i>passlib.hash</i> module</a><br>
-                <span class="linkdescr">complete list of supported password hash algorithms</span>
+                <a class="biglink" href="history.html">Changelog</a><br>
+                <span class="linkdescr">history of current and past releases</span>
             </p>
-        </td>
     </tr>
     </table>
 
 Online Resources
 ================
-* **Homepage**:   `<http://code.google.com/p/passlib>`_
-* **Docs**:       `<http://packages.python.org/passlib>`_
-* **Discussion**: `<http://groups.google.com/group/passlib-users>`_
 
-* **Downloads**:   `<http://code.google.com/p/passlib/downloads>`_
-* **PyPI**:       `<http://pypi.python.org/pypi/passlib>`_
-* **Source**:     `<http://code.google.com/p/passlib/source>`_
+.. rst-class:: html-plain-table
+
+=============== ===================================================
+**Homepage**:   `<http://code.google.com/p/passlib>`_
+**Docs**:       `<http://packages.python.org/passlib>`_
+**Discussion**: `<http://groups.google.com/group/passlib-users>`_
+
+**PyPI**:       `<http://pypi.python.org/pypi/passlib>`_
+**Downloads**:  `<http://code.google.com/p/passlib/downloads>`_
+**Source**:     `<http://code.google.com/p/passlib/source>`_
+=============== ===================================================
diff --git a/docs/install.rst b/docs/install.rst
index f780428..f95a494 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -4,37 +4,36 @@ Installation
 
 Requirements
 ============
-* Python 2.5 - 2.7 is required.
+* Python 2.5 - 2.7.
 
-    .. note::
+    PassLib has not been tested with Python 2.4 or earlier,
+    and no guarantees are made about whether PassLib will work with those versions.
 
-        PassLib has not been tested with Python 2.4 or earlier,
-        and no guarantees are made about whether PassLib will work with those versions.
+    Python 3.x is not yet supported, work is `ongoing <http://code.google.com/p/passlib/issues/detail?id=1>`_.
 
-    .. note::
-
-        Python 3.x is **not** yet supported, work is ongoing.
+    Passlib is pure-python, and should be useable on all platforms
+    (eg CPython, PyPy, and Jython).
 
 * `py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_ (optional)
 
    If installed, pybcrypt will be used to support the BCrypt hash algorithm.
    This is required if you want to handle BCrypt hashes,
-   and stdlib :mod:`!crypt` does not support BCrypt
-   (which is pretty much all non-BSD systems).
+   and your OS does not provide native BCrypt support
+   via stdlib's :mod:`!crypt`. This includes pretty much all non-BSD systems.
 
 * `M2Crypto <http://chandlerproject.org/bin/view/Projects/MeTooCrypto>`_ (optional)
 
-   If installed, M2Crypto will be used to accelerate some
-   internal support functions, but it is not required.
-
-PassLib is pure-python, and should be useable on all platforms.
+   If installed, M2Crypto will be used to accelerate some internal
+   functions used by PBKDF2-based hashes, but it is not required
+   even in that case.
 
 Installing
 ==========
-* To install from source directory using ``setup.py`` (requires Setuptools or Distribute)::
+* To install from source directory using ``setup.py``
+  (requires Setuptools or Distribute)::
 
-   python setup.py build
-   sudo python setup.py install
+        python setup.py build
+        sudo python setup.py install
 
 * To install using easy_install::
 
@@ -70,5 +69,5 @@ you will need to:
 2. install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_.
 3. download the PassLib source
 4. from the PassLib source directory, run :samp:`python docs/make.py clean html`.
-5. Once Sphinx completes it's run, point a web browser to the file at :samp:`docs/_build/html/index.html`
+5. Once Sphinx completes it's run, point a web browser to the file at :samp:`{$SOURCE}/docs/_build/html/index.html`
    to access the PassLib documentation in html format.
diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst
index 56ab1da..3d97cda 100644
--- a/docs/lib/passlib.apps.rst
+++ b/docs/lib/passlib.apps.rst
@@ -143,20 +143,23 @@ PostgreSQL
 
 Roundup
 =======
-The `Roundup Issue Tracker <http://www.roundup-tracker.org>` has long
+The `Roundup Issue Tracker <http://www.roundup-tracker.org>`_ has long
 supported a series of different methods for encoding passwords.
+The following contexts are available for reading Roundup password hash fields:
 
 .. data:: roundup10_context
 
     This object should recognize all password hashes used by Roundup:
-    :class:`ldap_hex_sha1` (the default), :class:`ldap_hex_md5`, :class:`ldap_des_crypt`,
-    and :class:`roundup_plaintext`.
+    :class:`~passlib.hash.ldap_hex_sha1` (the default),
+    :class:`~passlib.hash.ldap_hex_md5`, :class:`~passlib.hash.ldap_des_crypt`,
+    and :class:`~passlib.hash.roundup_plaintext`.
 
 .. data:: roundup15_context
 
     As of 2011-04-28, the next release of Roundup will add support
-    for :class:`ldap_pbkdf2_sha1`. This context supports all the :data:`roundup10_context`
-    hashes, but adds this hash as well (as uses it as the default).
+    for :class:`~passlib.hash.ldap_pbkdf2_sha1`. This context supports
+    all the :data:`roundup10_context` hashes, but adds this hash as well
+    (and uses it as the default).
 
     .. note::
 
diff --git a/docs/lib/passlib.context.rst b/docs/lib/passlib.context.rst
index ecc795e..1f40571 100644
--- a/docs/lib/passlib.context.rst
+++ b/docs/lib/passlib.context.rst
@@ -9,6 +9,8 @@
 .. module:: passlib.context
     :synopsis: CryptContext class for managing multiple password hash schemes
 
+Motivation
+==========
 Though there is a wide range of password hashing schemes,
 within a specific context (like a linux "shadow" file)
 only a select list of schemes will be used.
@@ -28,10 +30,13 @@ Passlib also offers a number of predefined :class:`!CryptContext` instances
 which can be used out-of-the box (see :mod:`passlib.apps` and :mod:`passlib.hosts`),
 or :ref:`modified <using-predefined-contexts>` to suit the application.
 
+Subtopics
+=========
 New users should see the usage examples
-to get a feel for how the :class:`!CryptContext` class works.
+in the next section to get a feel for how the :class:`!CryptContext` class works.
 
 .. toctree::
+    :maxdepth: 1
 
     passlib.context-usage
     passlib.context-interface
diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst
index fac5ca9..a87a338 100644
--- a/docs/lib/passlib.hash.pbkdf2_digest.rst
+++ b/docs/lib/passlib.hash.pbkdf2_digest.rst
@@ -2,7 +2,7 @@
 :samp:`passlib.hash.pbkdf2_{digest}` - Generic PBKDF2 Hashes
 ===============================================================
 
-.. index:: pbkdf2 hash; generic mcf 
+.. index:: pbkdf2 hash; generic mcf
 
 .. currentmodule:: passlib.hash
 
@@ -42,8 +42,6 @@ Interface
 
 .. autoclass:: pbkdf2_sha512()
 
-.. rst-class:: html-toggle
-
 Format & Algorithm
 ==================
 An example :class:`!pbkdf2_sha256` hash (of ``password``)::
diff --git a/docs/modular_crypt_format.rst b/docs/modular_crypt_format.rst
index d485821..ee901d0 100644
--- a/docs/modular_crypt_format.rst
+++ b/docs/modular_crypt_format.rst
@@ -45,13 +45,11 @@ by the modular crypt format hashes found in passlib:
 
 1. Hash strings must use only 7-bit ascii characters.
 
-   This is not strictly enforced at all;
-   for example Linux will accept 8-bit characters
-   within hash salt strings. However, **no** known
-   system generates hashes violating this rule;
-   and no such test vectors exist either,
-   so it can probably be assumed to be a case
-   of "permissive in what you accept, strict in what you generate".
+   No known OS or application generates hashes which violate this rule.
+   However, some systems (eg Linux's shadow routines) will happily
+   and correctly accept hashes which contain 8-bit characters in their salt.
+   This is probably a case of "permissive in what you accept,
+   strict in what you generate".
 
 2. Hash strings should always start with the prefix :samp:`${identifier}$`,
    where :samp:`{identifier}` is a short string uniquely identifying
@@ -69,17 +67,17 @@ by the modular crypt format hashes found in passlib:
    identifying strings (eg ``$sha1$`` for :class:`sha1_crypt`);
    so in general identifier strings should not be assumed to use a single character.
 
-3. Aside from the prefix, hashes should contain only ascii letters a-z A-Z,
-   ascii numbers 0-9, and the characters ``./``; though additionally ``$``
-   may/should be used as an internal field separator.
+3. Hashes should contain only ascii letters ``a``-``z`` and ``A``-``Z``,
+   ascii numbers 0-9, and the characters ``./``; though additionally
+   they should use the ``$`` character as an internal field separator.
 
    This is the least adhered-to of any modular crypt format rule.
-   Other characters (such as ``=``, ``,``) are sometimes
-   used by various formats.
+   Other characters (such as ``=,-``) are sometimes
+   used by various formats, though sparingly.
 
    The only hard and fast stricture
-   is that ``:`` and non-printable characters be avoided,
-   since this would interfere with parsing of /etc/passwd
+   is that ``:;!*`` and non-printable characters be avoided,
+   since this would interfere with parsing of /etc/shadow
    where these hashes are typically stored.
 
    Pretty much all modular-crypt-format hashes
@@ -96,7 +94,7 @@ by the modular crypt format hashes found in passlib:
    to a "configuration string" containing just
    the identifying prefix, rounds, salt, etc.
 
-   This string then encodes all the information
+   This configuration string then encodes all the information
    generated needed to generate a new hash
    in order to verify a password, without
    having to perform excessive parsing.
@@ -104,6 +102,12 @@ by the modular crypt format hashes found in passlib:
    Most modular crypt format hashes follow this,
    though some (like :class:`~passlib.hash.bcrypt`) omit the ``$`` separator.
 
+   As well, there is no set standard about whether configuration
+   strings should or should not include a trailing ``$`` at the end,
+   though the general rule is that a hash behave the same regardless
+   (:class:`~passlib.hash.sun_md5_crypt` behaves particularly poorly
+   regarding this last point).
+
 .. note::
 
     All of the above is guesswork based on examination of existing
@@ -125,15 +129,15 @@ identifying prefix.
 ==================================== ================== =========== =========== =========== ===========
 Scheme                               Prefix             Linux       FreeBSD     NetBSD      OpenBSD
 ==================================== ================== =========== =========== =========== ===========
-:class:`~passlib.hash.nthash`        ``$3$``                        y
 :class:`~passlib.hash.des_crypt`     n/a                y           y           y           y
 :class:`~passlib.hash.bsdi_crypt`    ``_``                          y           y
 :class:`~passlib.hash.md5_crypt`     ``$1$``            y           y           y           y
 :class:`~passlib.hash.sun_md5_crypt` ``$md5$``
 :class:`~passlib.hash.bcrypt`        ``$2$``, ``$2a$``              y           y           y
-:class:`~passlib.hash.sha1_crypt`    ``$sha1$``                                 y
+:class:`~passlib.hash.nthash`        ``$3$``                        y
 :class:`~passlib.hash.sha256_crypt`  ``$5$``            y
 :class:`~passlib.hash.sha512_crypt`  ``$6$``            y
+:class:`~passlib.hash.sha1_crypt`    ``$sha1$``                                 y
 ==================================== ================== =========== =========== =========== ===========
 
 .. note::
diff --git a/docs/overview.rst b/docs/overview.rst
index a6e91e0..4d83ad5 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -8,8 +8,8 @@ as stored in mysql and postgres, and various other places.
 PassLib's contents can be roughly grouped into three categories:
 password hashes, password contexts, and utility functions.
 
-Password Hash Schemes
-=====================
+Password Hashes
+===============
 All of the hash schemes supported by passlib are implemented
 as classes importable from the :mod:`passlib.hash` module.
 All of these classes support a single uniform interface of standard class methods.
@@ -49,35 +49,12 @@ Mature applications frequently have to deal with tables of existing password
 hashes. Over time, they have to migrate to newer and stronger schemes; as well as raise
 the requirements for existing algorithms as more processing power becomes available.
 In this case, directly importing and handling the various schemes
-generally becomes complicated and tedious. For these and similar use-cases,
-the :mod:`passlib.context` module provides the :class:`!CryptContext` class, which handles
-multiple password hash schemes, deprecation of old hashes, and
-many other policy requirements.
-
-In addition to using the class itself, PassLib provides a number of
-pre-configured :class:`!CryptContext` instances
-in order to get users started quickly:
-
-* The :mod:`passlib.apache` module contains classes
-  for managing htpasswd and htdigest files.
-
-* The :mod:`passlib.apps` module contains pre-configured
-  instances for managing hashes used by postgres, mysql, and ldap.
+generally becomes complicated and tedious.
 
-* The :mod:`passlib.hosts` module contains pre-configured
-  instances for managing hashes as found in the /etc/shadow files
-  on Linux and BSD systems.
-
-* And finally the :mod:`passlib.context` module, which provides
-  the :class:`!CryptContext` class itself, allowing
-  an application to setup the particular configuration it required.
-
-.. note::
-
-    For new applications which just need drop-in support for some manner
-    of password encryption, so they can secure store passwords
-    and then forget about it, they should use
-    the :data:`passlib.apps.custom_app_context` object.
+The :mod:`passlib.context` module provides the :class:`!CryptContext` class and other
+utilties to help with these use-cases. This class handles
+managing multiple password hash schemes, deprecation & migration of old hashes, and
+many other policy requirements.
 
 A quick example of how a password context can be used::
 
@@ -97,6 +74,29 @@ A quick example of how a password context can be used::
     >>> lc.verify('password', 'q1Oyx5r9mdGZ2')
     True
 
+.. note::
+
+    For new applications which just need drop-in support for some manner
+    of password encryption, so they can secure store passwords
+    and then forget about it, they should use
+    the :data:`passlib.apps.custom_app_context` object.
+
+Predefined Password Contexts
+============================
+In addition to the :mod:`passlib.context` module,
+PassLib provides a number of pre-configured :class:`!CryptContext` instances
+in order to get users started quickly:
+
+* The :mod:`passlib.apache` module contains classes
+  for managing htpasswd and htdigest files.
+
+* The :mod:`passlib.apps` module contains pre-configured
+  instances for managing hashes used by Postgres, Mysql, and LDAP, and others.
+
+* The :mod:`passlib.hosts` module contains pre-configured
+  instances for managing hashes as found in the /etc/shadow files
+  on Linux and BSD systems.
+
 Utility Functions
 =================
 The :mod:`passlib.registry` and :mod:`passlib.utils` modules contain a large number
diff --git a/setup.py b/setup.py
index 1426981..9601a50 100644
--- a/setup.py
+++ b/setup.py
@@ -12,10 +12,23 @@ from passlib import __version__ as version
 #=========================================================
 #setup
 #=========================================================
+DESCRIPTION = "comprehensive password hashing framework supporting over 20 schemes"
+
+LONG_DESCRIPTION = """\
+PassLib is a password hash library, which provides cross-platform
+implementations of over 20 password hashing algorithms; as well as a framework for managing
+and migrating existing password hashes. It's designed to be useful
+for any task from quickly verifying a hash found in /etc/shadow,
+to providing full-strength password hashing for multi-user applications.
+"""
+
+KEYWORDS = "password secret hash security crypt md5-crypt sha256-crypt sha512-crypt bcrypt htpasswd htdigest pbkdf2"
+
 setup(
     #package info
     packages = find_packages(),
     package_data = { "passlib": ["*.cfg"] },
+    zip_safe=True,
 
     # metadata
     name = "passlib",
@@ -25,18 +38,12 @@ setup(
     license = "BSD",
 
     url = "http://code.google.com/p/passlib/",
-    download_url = "http://code.google.com/p/passlib/downloads/list",
-
-    description = "comprehensive password hashing framework supporting over 20 schemes",
-    long_description = """\
-PassLib is a password hash library, which provides cross-platform
-implementations of over 20 password hashing algorithms; as well as a framework for managing
-and migrating existing password hashes. It's designed to be useful
-for any task from quickly verifying a hash found in /etc/shadow,
-to providing full-strength password hashing for multi-user applications.
-""",
+    #er, is download url for the sdist, or for the project?
+##    download_url = "http://code.google.com/p/passlib/downloads/list",
 
-    keywords = "password secret hash security crypt md5-crypt sha256-crypt sha512-crypt bcrypt htpasswd htdigest pbkdf2",
+    description = DESCRIPTION,
+    long_description = LONG_DESCRIPTION,
+    keywords = KEYWORDS,
     classifiers = [
         "Development Status :: 5 - Production/Stable",
         "Intended Audience :: Developers",
@@ -49,7 +56,6 @@ to providing full-strength password hashing for multi-user applications.
         "Topic :: Security :: Cryptography",
         "Topic :: Software Development :: Libraries",
     ],
-    zip_safe=True,
 
     test_suite = 'nose.collector',
 )