updated various bit of documentation; made 1.6 changelog presentable

10 files changed, 393 insertions, 323 deletions

diff --git a/CHANGES b/CHANGES
index 8838521..4e05706 100644
--- a/CHANGES
+++ b/CHANGES
@@ -7,209 +7,255 @@ Release History
 **1.6** (NOT YET RELEASED)
 ==========================
 
-    Hashes
-
-        * The :doc:`bcrypt <lib/passlib.hash.bcrypt>` class now supports
-          crypt_blowfish's ``$2y$`` hash prefix (though it will not generate
-          them by default).
-
-        * The *unix_fallback* handler has been deprecated, and will be removed
-          in Passlib 1.8. Please use the improved replacement,
-          :doc:`unix_disabled <lib/passlib.hash.unix_disabled>`,
-          instead.
-
-        * Added support for Window's Domain Cached Credentials (aka
-          "dcc", "mscache", "mscash"), versions 1 and 2:
-          :doc:`msdcc <lib/passlib.hash.msdcc>` and
-          :doc:`msdcc2 <lib/passlib.hash.msdcc2>`.
-
-        * The rarely-used hash previously known as ``nthash`` has been renamed to
-          :class:`~passlib.hash.bsd_nthash`, to better indicate it's lineage;
-          a new :class:`~passlib.hash.nthash` class now directly implements
-          the plain hexidecimal Windows NT password hash.
-
-        * added support for Windows' :doc:`lmhash <lib/passlib.hash.lmhash>`
-          (aka Lan Manager password hash).
-
-        * added support for Cisco :doc:`PIX <lib/passlib.hash.cisco_pix>` and
-          :doc:`Type 7 <lib/passlib.hash.cisco_type7>` password hashes.
-          (Cisco Type 5 passwords seem to be the same as
-          :doc:`md5_crypt <lib/passlib.hash.md5_crypt>`).
-
-        * added support for MS SQL Server password hashes (
-          :doc:`mssql2000 <lib/passlib.hash.mssql2000>` and
-          :doc:`mssql2005 <lib/passlib.hash.mssql2005>`).
-
-        * added support for the hashes added in Django 1.4:
-          :class:`~passlib.hash.django_bcrypt`,
-          :class:`~passlib.hash.django_pbkdf2_sha256`,
-          :class:`~passlib.hash.django_pbkdf2_sha1`.
-          Also added the :class:`~passlib.apps.django14`
-          predefined :class:`!CryptContext`.
-
-        * Passlib now offers the :doc:`scram <lib/passlib.hash.scram>` hash,
-          specially designed for storing digest information for verifying
-          a user against the SCRAM protocol (:rfc:`5802`). It can also
-          be used to verify users in the same way as any other password
-          hash in Passlib, though it offers no particular advantages
-          outside of this special case.
-
-        * Fixed rare ``'NoneType' object has no attribute 'decode'`` error
-          that sometimes occurred on platforms with a deviant implementation
-          of :func:`!os_crypt`.
-
-        * The :doc:`ldap salted digests </lib/passlib.hash.ldap_std>`
-          now support salts from 4-16 bytes :issue:`30`.
-
-        * :class:`bsdi_crypt` now issues a warning if an even number of rounds
-          is requested by the application, due to a known weakness in DES.
-
-        * All hashes will now throw :exc:`~passlib.exc.PasswordSizeError`
-          if the provided password is larger than 4096 characters.
-
-          This limit should be above any reasonable password size,
-          and prevents various things including DOS abuse of hashes
-          that have an expensive password-length-dependant stage,
-          and for OS's which have a buggy :func:`!crypt.crypt` implementation.
-
-    CryptContext
-
-        .. currentmodule:: passlib.context
-
-        * The :class:`!CryptContext` option
-          :ref:`min_verify_time <min-verify-time>` has been deprecated,
-          will be ignored in release 1.7, and will be removed in release 1.8.
-
-        * The :class:`!CryptContext` option ``deprecated`` can now be set
-          to the special string ``"auto"``, in which case all schemes
-          except for the default will be automatically flagged as deprecated.
-
-        * The internals of :class:`!CryptContext` have been rewritten
-          drastically. It's methods should now be stricter and more informative
-          about invalid values; and common :class:`!CryptContext` operations
-          should be faster, and have shorter internal code paths.
-
-        * The :attr:`!CryptContext.policy` attr, and the supporting
-          :class:`!CryptPolicy` class, have been deprecated in their entirety.
-
-          They will not be removed until Passlib 1.8, to give applications
-          which used these features time to migrate. Applications which did
-          not use either of these features explicitly should be unaffected by
-          this change.
-
-          The functionality of :class:`!CryptPolicy` has been merged
-          into the :class:`CryptContext` class, in order to simplify
-          the exposed interface. Information on migrating can be found
-          in the :class:`CryptPolicy` documentation, as well as in
-          the :exc:`DeprecationWarning` messages issued when a :class:`!CryptPolicy`
-          is invoked.
-
-        * :meth:`CryptContext.from_path` and :meth:`CryptContext.from_string`
-          (and the legacy :class:`CryptPolicy` object) now use stdlib's
-          :class:`!SafeConfigParser`.
-
-          Previous releases used the original :class:`!ConfigParser` interpolation.
-          Passlib 1.5 switched to :class:`SafeConfigParser`,
-          but kept support for the old format as a (deprecated) fallback.
-          This fallback has been removed in 1.6; any
-          legacy config files may need to double any raw ``%`` characters
-          in order to load successfully.
-
-    Utils
-
-        .. currentmodule:: passlib.utils.handlers
-
-        * Internal handler framework (:mod:`passlib.utils.handlers`) rewritten
-          drastically. Provides stricter input checking, reduction in
-          boilerplate code.
-
-        * :class:`~passlib.utils.handlers.GenericHandler` and related mixins
-          changed in backward-incompatible way: the ``strict`` keyword
-          was removed. :class:`!GenericHandler` now defaults to a behavior
-          which matches ``strict=True``: the constructor strictly requires
-          all values be specified, and that all values be within correct bounds.
-          The new keywords ``use_defaults`` and ``relaxed`` can be used
-          to disable these two requirements, respectively.
-
-        * :class:`~passlib.utils.handlers.StaticHandler` now derived from
-          :class:`!GenericHandler`, and required ``_calc_checksum()`` be
-          implemented instead of ``encrypt()``.
-
-        * :class:`~passlib.utils.handlers.GenericHandler` and related mixins
-          changed in backward-incompatible way: the :samp:`norm_{xxx}`
-          classmethods have been renamed to :samp:`_norm_{xxx}`, and turned
-          into instance methods. Similar renames were done for
-          ``calc_calchecksum`` and ``generate_salt``.
-
-        * Calls to :meth:`HasManyBackends.set_backend`
-          should now use the string ``"any"`` instead of the value ``None``.
-          ``None`` was deprecated in release 1.5, and is no longer supported.
-          This affects all schemes in :mod:`passlib.hash` which support
-          multiple backends.
+.. _whats-new:
 
-        .. currentmodule:: passlib.utils
+Overview
+--------
 
-        * :mod:`!passlib.utils.h64` has been replaced by an instance of the
-          new :class:`~passlib.utils.Base64Engine` class. This  instance is
-          imported under the same name, and has (mostly) the same interface;
-          but should be faster, more flexible, and better unit-tested.
+    Welcome to Passlib 1.6.
 
-        * deprecated some unused functions in :mod:`!passlib.utils`,
-          they will be removed in release 1.7.
+    The main goal of this release was to clean up the codebase, reducing
+    the amount of internally-redundant code, and simplify the publically
+    exposed interface. This release also brings with it
+    a number of other improvements, including: 10 or so new hash algorithms,
+    additional security precautions for the existing ones, numerous
+    execution-time improvements, and reorganized documentation.
 
-    Other
+    .. note::
 
-        * Added :mod:`passlib.ext.django`, a Django plugin which can be used to
-          override Django's password hashing framework with a custom Passlib
-          policy (An undocumented beta version was present in the 1.5 release).
+        In order to simplify the publically exposed interface, a number
+        of the more cumbersome and less-used aspects (particularly the
+        semi-internal :class:`!CryptPolicy` class) have been deprecated.
+        This should not affect 99% of the code using Passlib.
+
+        Just the same, *all deprecated interfaces are still supported, and will continue
+        to be supported for at least one more major release*.
+        To help with migration, all deprecated functions will issue an informative :exc:`DeprecationWarning`
+        when they are invoked, detailing their suggested replacement.
+
+New Hashes
+----------
+    The release adds support for a number of hash algorithms:
+
+    :doc:`cisco_pix <lib/passlib.hash.cisco_pix>`, :doc:`cisco_type7 <lib/passlib.hash.cisco_type7>`
+        Two hash formats frequently found on various
+        Cisco devices *(for Cisco Type 5 hashes, see*
+        :doc:`md5_crypt <lib/passlib.hash.md5_crypt>` *).*
+
+    :ref:`django_pbkdf2_sha256 <django-1.4-hashes>`, :ref:`django_pbkdf2_sha1 <django-1.4-hashes>`, :ref:`django_bcrypt <django-1.4-hashes>`
+        All three of the new hash schemes introduced in Django 1.4.
+
+    :doc:`lmhash <lib/passlib.hash.lmhash>`, :doc:`nthash <lib/passlib.hash.nthash>`
+        Microsoft's legacy "Lan Manager" hash, and the replacement
+        "NT password hash". *(the old* ``nthash`` *algorithm in Passlib 1.5 has been renamed to*
+        :class:`~passlib.hash.bsd_nthash` *, to reflect it's lineage)*.
+
+    :doc:`msdcc <lib/passlib.hash.msdcc>`, :doc:`msdcc2 <lib/passlib.hash.msdcc2>`
+        Microsoft Windows' Domain Cached Credentials, versions 1 and 2.
+        This algorithm also goes by the names "DCC", "MSCache", and "MSCash".
+
+    :doc:`mssql2000 <lib/passlib.hash.mssql2000>`, :doc:`mssql2005 <lib/passlib.hash.mssql2005>`
+        Hash algorithms used by MS SQL Server 2000 and later.
+
+    :doc:`scram <lib/passlib.hash.scram>`
+        A hash format added specifically for storing the complex digest
+        information needed to authenticate a user via the SCRAM protocol
+        (:rfc:`5802`). It can also be used in the same way as any other
+        password hash in Passlib.
+
+Existing Hashes
+---------------
+    Additionally, the following new features have been added to the existing hashes:
+
+    .. _password-size-limit:
+
+    *Password Size Limit*
+        All hashes in Passlib will now throw :exc:`~passlib.exc.PasswordSizeError`
+        if handed a password that's larger than 4096 characters.
+
+        This limit should be larger than any reasonable password size,
+        and prevents various things including DOS abuses, and exploitation
+        of OSes with a buggy :func:`!crypt` implementation.
+        See :exc:`!PasswordSizeError` for how to change
+        this limit.
+
+    .. _consteq-issue:
+
+    *Constant Time Comparison*
+        All hash comparisons in Passlib now use a "constant time" [#consteq]_
+        comparison function :func:`~passlib.utils.consteq` instead
+        of ``==``.
+
+        This change is motivated a well-known `hmac timing attack <http://rdist.root.org/2009/05/28/timing-attack-in-google-keyczar-library/>`_
+        which exploits short-circuit string comparisons.
+        While this attack is not currently feasible against
+        most password hashes, some of the weaker unsalted
+        hashes supported Passlib may be vulnerable; and this
+        change has been made preventatively to all of them.
+
+        .. [#consteq] "constant time" is a misnomer, it actually takes ``THETA(len(righthand_value))`` time.
+
+    :doc:`bcrypt <lib/passlib.hash.bcrypt>`
+        The BCrypt hash now supports the *crypt_blowfish* project's
+        ``$2y$`` hash prefix.
+
+        As well, Passlib now offers an (experimental) pure-python BCrypt
+        implementation. Unfortunately, it's still *way too slow* to be
+        suitable for production use; and is disabled by default.
+        If you really need it, see the BCrypt :ref:`documentation <bcrypt-backends>`
+        for how to enable it.
+
+    :doc:`bsdi_crypt <lib/passlib.hash.bsdi_crypt>`
+        BSDi-Crypt will now issue a :exc:`~passlib.exc.PasslibSecurityWarning`
+        if an application requests an even number of rounds, due to
+        a known weakness in DES. Existing hashes with an even number of rounds will
+        now be flagged by :meth:`CryptContext.needs_update() <passlib.context.CryptContext.needs_update>`.
+
+    :doc:`ldap_salted_{digest} </lib/passlib.hash.ldap_std>`
+        The LDAP salted digests now support salts of any size
+        from 4-16 bytes, though they still default to 8 (:issue:`30`).
+
+    :doc:`md5_crypt </lib/passlib.hash.md5_crypt>`, :doc:`sha256_crypt </lib/passlib.hash.md5_crypt>`, :doc:`sha512_crypt </lib/passlib.hash.md5_crypt>`
+        The builtin implementation of these hashes has been
+        sped up by about 25%, using an additional pre-computation step.
+
+    :doc:`unix_disabled <lib/passlib.hash.unix_disabled>`
+        The :class:`!unix_fallback` handler has been deprecated,
+        and will be removed in Passlib 1.8.
+        Applications should use the stricter-but-equivalent
+        :class:`!unix_disabled` handler instead.
+
+        This most likely only affects internal Passlib code.
+
+CryptContext
+------------
 
-        * The api for the :mod:`passlib.apache` module has been updated
-          to add more flexibility, and to fix some ambiguous method
-          and keyword names. The old names are still supported, but deprecated,
-          and will be removed in Passlib 1.8.
+    .. currentmodule:: passlib.context
 
-        * Handle platform-specific error strings returned by :func:`!crypt.crypt`.
+    The :ref:`CryptContext <context-overview>` class has had a thorough
+    internal overhaul. While the primary interface has not changed
+    at all, the internals are much stricter about input validation,
+    common methods have shorter code-paths,  and the
+    construction and introspection of :class:`!CryptContext` objects
+    has been greatly simplified.
+    Changes include:
+
+    * All new (and hopefully clearer) :ref:`tutorial <context-tutorial>`
+      and :ref:`reference <context-reference>` documentation.
+
+    * The :class:`CryptPolicy` class and the :attr:`!CryptContext.policy` attribute have been deprecated.
+
+        This was a semi-internal class, which most applications
+        were not involved with at all, but to be conservative about
+        breaking things, the existing CryptPolicy interface
+        will remain in-place and supported until Passlib 1.8.
+
+        All of the functionality of this class has been rolled into
+        :class:`!CryptContext` itself, so there's one less class to remember.
+        Most of the methods exposed by :class:`!CryptPolicy` are now
+        :class:`!CryptContext` methods.
+        Information on migrating existing code can be found in
+        the deprecation warnings issued by the class itself,
+        and in the :class:`CryptPolicy` documentation.
+
+    * Two new class constructors have been added: :meth:`CryptContext.from_path`
+      and :meth:`CryptContext.from_string`, for loading CryptContext objects
+      directly from a configuration file.
+
+    * The :ref:`deprecated <context-deprecated-option>` keyword
+      can now be set to the special string ``"auto"``; which will
+      automatically deprecate all schemes except for the default one.
+
+    * The :ref:`min_verify_time <context-min-verify-time-option>` keyword
+      has been deprecated, will be ignored in release 1.7, and will be removed in release 1.8.
+      It was never very useful, and now complicates the internal code needlessly.
+
+    * All string parsing now uses stdlib's :class:`!SafeConfigParser`.
+
+      Previous releases used the original :class:`!ConfigParser` interpolation;
+      which was deprecated in Passlib 1.5, and has now been removed.
+      This should only affect strings which contained raw ``%`` characters,
+      they will now need to be escaped via ``%%``.
+
+Other Modules
+-------------
+
+    * The api for the :mod:`passlib.apache` module has been updated
+      to add more flexibility, and to fix some ambiguous method
+      and keyword names. The old interface is still supported, but deprecated,
+      and will be removed in Passlib 1.8.
+
+    * Added the :data:`~passlib.apps.django14_context` preset to the
+      the :mod:`!passlib.apps` module. this preconfigured CryptContext
+      object should support all the hashes found in a typical Django 1.4
+      deployment.
+
+    * **new**: Added :mod:`passlib.ext.django`, a Django plugin which can be used to
+      override Django's password hashing framework with a custom Passlib
+      policy (an undocumented beta version of this was present in the 1.5 release).
+
+Bugfixes
+--------
+
+    * Handle platform-specific error strings that may be returned by the
+      :func:`!crypt` methods of some OSes.
+
+    * Fixed rare ``'NoneType' object has no attribute 'decode'``
+      error that sometimes occurred on platforms with a deviant implementation
+      of :func:`!crypt`.
+
+Internal Changes
+----------------
+    *The following changes should not affect most end users,
+    and have been documented just to keep track of them:*
+
+    .. currentmodule:: passlib.utils.handlers
+
+    * Passlib is now source-compatible with Python 2.5+ and Python 3.x.
+      It no longer requires the use of the :command:`2to3` command
+      to translate it for Python 3.
+
+    * The unittest suite has been rewritten. It handles a number of additional
+      border cases, enforcing uniform behavior across all hashes, and
+      even features the addition of some simplistic fuzz testing.
+      It will take a bit longer to run though. While not perfect,
+      statement coverage is at about 95%.
+
+    * The internal framework used to construct the hash classes (:mod:`passlib.utils.handlers`)
+      was rewritten drastically. The new version provides stricter input checking,
+      reduction in boilerplate code. *These changes should not affect any
+      publically exposed routines*.
+
+        - :class:`~passlib.utils.handlers.GenericHandler`'s
+          ``strict`` keyword was removed, ``strict=True`` is now
+          the class's default behavior: all values must be specified,
+          and be within the correct bounds. The new keywords
+          ``use_defaults`` and ``relaxed`` can be used to disable
+          these two requirements.
+
+        - Most of the private methods of :class:`~passlib.utils.handlers.GenericHandler`
+          were renamed to begin with an underscore, to clarify their status;
+          and turned into instance methods, to simplify the internals.
+          (for example, :samp:`norm_salt` was renamed to :samp:`_norm_salt`).
+
+        - :class:`~passlib.utils.handlers.StaticHandler` now derives from
+          :class:`!GenericHandler`, and requires ``_calc_checksum()`` be
+          implemented instead of ``encrypt()``. The old style is supported
+          but deprecated, and support will be removed in Passlib 1.8.
+
+        - Calls to :meth:`HasManyBackends.set_backend`
+          should now use the string ``"any"`` instead of the value ``None``.
+          ``None`` was deprecated in release 1.5, and is no longer supported.
 
-        * Passlib is now source-compatible with Python 2.5+ and Python 3,
-          and no longer requires the use of :command:`2to3` to run under Python 3.
+    .. currentmodule:: passlib.utils
 
-        * Hash unittest framework rewritten. More border cases handled,
-          some simple fuzz testing added.
+    * :mod:`!passlib.utils.h64` has been replaced by an instance of the
+      new :class:`~passlib.utils.Base64Engine` class. This  instance is
+      imported under the same name, and has (mostly) the same interface;
+      but should be faster, more flexible, and better unit-tested.
 
-        .. currentmodule:: passlib.hash
-
-        .. _consteq-issue:
-
-        * All digest comparisons within Passlib are now done using
-          a "constant time" comparison function :func:`~passlib.utils.consteq`,
-          instead of ``==``.
-
-          *In detail:*
-
-              This change is motivated by an `hmac timing attack <http://rdist.root.org/2009/05/28/timing-attack-in-google-keyczar-library/>`_
-              which exploits ``==``'s short-circuit comparison algorithm.
-              This attack is generally not applicable to password hashes,
-              as it requires the attacker to both know the salt,
-              and be able to generate digests beginning with a specific prefix.
-              However, while this task should be computationally difficult
-              against modern hashes (such as :class:`sha512_crypt`), this
-              change should pre-emptively protect Passlib in case someone
-              constructs a such an attack in the future. Furthermore, some of
-              the legacy hashes supported by Passlib (such as
-              :class:`mysql323`) are already weak enough to be vulnerable.
-
-        * Builtin implementations of :class:`md5_crypt`,
-          :class:`sha256_crypt`, and :class:`sha512_crypt` sped up by
-          about 25% due via additional pre-computation step.
-
-        * Restored builtin pure-python BCrypt implementation
-          (:mod:`passlib.utils._slow_bcrypt`) that was removed in v1.3.
-          This implementation is still *WAY* to slow to be suitable
-          for production. However, it's almost fast enough under PyPy,
-          and might be sped up in the future... so while it is disabled
-          by default, developers who really want to use it
-          should set the environment variable ``PASSLIB_BUILTIN_BCRYPT=enabled``
-          before loading Passlib.
+    * deprecated some unused support functions within :mod:`!passlib.utils`,
+      they will be removed in release 1.7.
 
 **1.5.3** (2011-10-08)
 ======================
@@ -311,141 +357,151 @@ Release History
 **1.5** (2011-07-11)
 ====================
 
-    *"20% more unicode than the leading breakfast cereal"*
+*"20% more unicode than the leading breakfast cereal"*
 
-    The main new feature in this release is that
-    Passlib now supports Python 3 (via the 2to3 tool).
-    Everything has been recoded to have better separation
-    between unicode and bytes, and to use unicode internally
-    where possible.
-    When run under Python 2, Passlib 1.5 attempts
-    to provide the same behavior as Passlib 1.4;
-    but when run under Python 3, most functions
-    will return unicode instead of ascii bytes.
+The main new feature in this release is that
+Passlib now supports Python 3 (via the 2to3 tool).
+Everything has been recoded to have better separation
+between unicode and bytes, and to use unicode internally
+where possible.
+When run under Python 2, Passlib 1.5 attempts
+to provide the same behavior as Passlib 1.4;
+but when run under Python 3, most functions
+will return unicode instead of ascii bytes.
 
-    Besides this major change, there have
-    been some other additions:
+Besides this major change, there have
+been some other additions:
 
-    Hashes
+Hashes
+------
 
-        * added support for Cryptacular's PBKDF2 format.
-        * added support for the FSHP family of hashes.
-        * added support for using BCryptor as BCrypt backend.
-        * added support for all of Django's hash formats.
+    * added support for Cryptacular's PBKDF2 format.
+    * added support for the FSHP family of hashes.
+    * added support for using BCryptor as BCrypt backend.
+    * added support for all of Django's hash formats.
 
-    CryptContext
+CryptContext
+------------
 
-        .. currentmodule:: passlib.context
+    .. currentmodule:: passlib.context
 
-        * interpolation deprecation:
+    * interpolation deprecation:
 
-          :meth:`CryptPolicy.from_path` and :meth:`CryptPolicy.from_string`
-          now use :class:`!SafeConfigParser` instead of :class:`!ConfigParser`.
-          This may cause some existing config files containing unescaped ``%``
-          to result in errors; Passlib 1.5 will demote these to warnings,
-          but any extant config files should be updated,
-          as the errors will be fatal in Passlib 1.6.
+      :meth:`CryptPolicy.from_path` and :meth:`CryptPolicy.from_string`
+      now use :class:`!SafeConfigParser` instead of :class:`!ConfigParser`.
+      This may cause some existing config files containing unescaped ``%``
+      to result in errors; Passlib 1.5 will demote these to warnings,
+      but any extant config files should be updated,
+      as the errors will be fatal in Passlib 1.6.
 
-        * added encoding keyword to :class:`!CryptPolicy`'s
-          :meth:`!.from_path()`, :meth:`!.from_string`,
-          and :meth:`!.to_string` methods.
+    * added encoding keyword to :class:`!CryptPolicy`'s
+      :meth:`!.from_path()`, :meth:`!.from_string`,
+      and :meth:`!.to_string` methods.
 
-        * both classes in :mod:`passlib.apache`
-          now support specifying an encoding for the username/realm.
+    * both classes in :mod:`passlib.apache`
+      now support specifying an encoding for the username/realm.
 
-    Documentation
+Documentation
+-------------
 
-        * Password Hash API expanded to include explicit
-          :ref:`unicode vs bytes policy <hash-unicode-behavior>`.
-        * Added quickstart guide to documentation.
-        * Various minor improvements.
+    * Password Hash API expanded to include explicit
+      :ref:`unicode vs bytes policy <hash-unicode-behavior>`.
+    * Added quickstart guide to documentation.
+    * Various minor improvements.
 
-    Internals
+Internals
+---------
 
-        * Added more handler utility functions to reduce code duplication.
-        * Expanded kdf helpers in :mod:`passlib.utils.pbkdf2`.
-        * Removed deprecated parts of :mod:`passlib.utils.handlers`.
-        * Various minor changes to
-          :class:`passlib.utils.handlers.HasManyBackends`;
-          main change is that multi-backend handlers now raise
-          :exc:`~passlib.exc.MissingBackendError`
-          if no backends are available.
+    * Added more handler utility functions to reduce code duplication.
+    * Expanded kdf helpers in :mod:`passlib.utils.pbkdf2`.
+    * Removed deprecated parts of :mod:`passlib.utils.handlers`.
+    * Various minor changes to
+      :class:`passlib.utils.handlers.HasManyBackends`;
+      main change is that multi-backend handlers now raise
+      :exc:`~passlib.exc.MissingBackendError`
+      if no backends are available.
 
-    Other
+Other
+-----
 
-        * Builtin tests now use :mod:`!unittest2` if available.
-        * Setup script no longer requires distribute or setuptools.
-        * added (undocumented, experimental) Django app
-          for overriding Django's default hash format,
-          see ``docs/lib/passlib.ext.django.rst`` for more.
+    * Builtin tests now use :mod:`!unittest2` if available.
+    * Setup script no longer requires distribute or setuptools.
+    * added (undocumented, experimental) Django app
+      for overriding Django's default hash format,
+      see ``docs/lib/passlib.ext.django.rst`` for more.
 
 **1.4** (2011-05-04)
 ====================
 
-    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
-          known to be supported by OS crypt()
-        * added 3 custom PBKDF2 schemes for general use,
-          as well as 3 LDAP-compatible versions.
-        * added support for Dwayne Litzenberger's PBKDF2 scheme.
-        * added support for Grub2's PBKDF2 hash scheme.
-        * added support for Atlassian's PBKDF2 password hash
-        * added support for all hashes used by the Roundup Issue Tracker
-        * bsdi_crypt, sha1_crypt now check for OS crypt() support
-        * ``salt_size`` keyword added to encrypt() method of all
-          the hashes which support variable-length salts.
-        * security fix: disabled unix_fallback's "wildcard password" support
-          unless explicitly enabled by user.
-
-    CryptContext
-
-        * host_context now dynamically detects which formats
-          OS crypt() supports, instead of guessing based on sys.platform.
-        * added predefined context for Roundup Issue Tracker database.
-        * added CryptContext.verify_and_update() convience method,
-          to make it easier to perform both operations at once.
-        * *bugfix:* fixed NameError in category+min_verify_time border case
-        * apps & hosts modules now use new
-          :class:`LazyCryptContext` wrapper class -
-          this should speed up initial import,
-          and reduce memory by not loading uneeded hashes.
-
-    Documentation
-
-        * greatly expanded documentation on how to use CryptContexts.
-        * roughly documented framework for writing & testing
-          custom password handlers.
-        * various minor improvements.
-
-    Internals
-
-        * added generate_password() convenience method
-        * refactored framework for building hash handlers,
-          using new mixin-based system.
-        * deprecated old handler framework - will remove in 1.5
-        * deprecated list_to_bytes & bytes_to_list - not used, will remove in 1.5
-
-    Other
-
-        * password hash api - as part of cleaning up optional attributes
-          specification, renamed a number of them to reduce ambiguity:
-
-            - renamed *{xxx}_salt_chars* attributes -> *xxx_salt_size*
-            - renamed *salt_charset* -> *salt_chars*
-            - old attributes still present, but deprecated - will remove in 1.5
-
-        * password hash api - tightened specifications for salt & rounds parameters,
-          added support for hashes w/ no max salt size.
-
-        * improved password hash api conformance tests
-
-        * PyPy compatibility
+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
+      known to be supported by OS crypt()
+    * added 3 custom PBKDF2 schemes for general use,
+      as well as 3 LDAP-compatible versions.
+    * added support for Dwayne Litzenberger's PBKDF2 scheme.
+    * added support for Grub2's PBKDF2 hash scheme.
+    * added support for Atlassian's PBKDF2 password hash
+    * added support for all hashes used by the Roundup Issue Tracker
+    * bsdi_crypt, sha1_crypt now check for OS crypt() support
+    * ``salt_size`` keyword added to encrypt() method of all
+      the hashes which support variable-length salts.
+    * security fix: disabled unix_fallback's "wildcard password" support
+      unless explicitly enabled by user.
+
+CryptContext
+------------
+
+    * host_context now dynamically detects which formats
+      OS crypt() supports, instead of guessing based on sys.platform.
+    * added predefined context for Roundup Issue Tracker database.
+    * added CryptContext.verify_and_update() convience method,
+      to make it easier to perform both operations at once.
+    * *bugfix:* fixed NameError in category+min_verify_time border case
+    * apps & hosts modules now use new
+      :class:`LazyCryptContext` wrapper class -
+      this should speed up initial import,
+      and reduce memory by not loading uneeded hashes.
+
+Documentation
+-------------
+
+    * greatly expanded documentation on how to use CryptContexts.
+    * roughly documented framework for writing & testing
+      custom password handlers.
+    * various minor improvements.
+
+Internals
+---------
+
+    * added generate_password() convenience method
+    * refactored framework for building hash handlers,
+      using new mixin-based system.
+    * deprecated old handler framework - will remove in 1.5
+    * deprecated list_to_bytes & bytes_to_list - not used, will remove in 1.5
+
+Other
+-----
+
+    * password hash api - as part of cleaning up optional attributes
+      specification, renamed a number of them to reduce ambiguity:
+
+        - renamed *{xxx}_salt_chars* attributes -> *xxx_salt_size*
+        - renamed *salt_charset* -> *salt_chars*
+        - old attributes still present, but deprecated - will remove in 1.5
+
+    * password hash api - tightened specifications for salt & rounds parameters,
+      added support for hashes w/ no max salt size.
+
+    * improved password hash api conformance tests
+
+    * PyPy compatibility
 
 **1.3.1** (2011-03-28)
 ======================
diff --git a/docs/conf.py b/docs/conf.py
index d9ed120..d28206c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -77,7 +77,7 @@ index_doc = 'index'
 
 # General information about the project.
 project = u'Passlib'
-copyright = u'2008-2011, Assurance Technologies, LLC'
+copyright = u'2008-2012, Assurance Technologies, LLC'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/docs/index.rst b/docs/index.rst
index 5118c31..433c251 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -30,6 +30,10 @@ using the :doc:`SHA256-Crypt </lib/passlib.hash.sha256_crypt>` algorithm::
 Contents
 ========
 
+.. rst-class:: floater
+
+.. seealso:: :ref:`What's new in Passlib 1.6 <whats-new>`
+
 Introductory Materials
 ----------------------
 
diff --git a/docs/install.rst b/docs/install.rst
index 4f7742c..5007686 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -50,6 +50,8 @@ To install from a source directory using :command:`setup.py`::
 
     python setup.py install
 
+.. rst-class:: html-toggle
+
 Testing
 =======
 Passlib contains a comprehensive set of unittests providing nearly complete coverage.
@@ -59,18 +61,21 @@ and are designed to be run using the
 
 Once Passlib and Nose have been installed, the tests may be run from the source directory::
 
-    # to run the platform-relevant tests...
-    nosetests -v --tests passlib/tests
+    # to run the full passlib test suite...
+    PASSLIB_TEST_MODE="full" nosetests -v --tests passlib/tests
+
+Tests may also be run via ``setup.py test`` or the included ``tox.ini`` file.
 
-    # to run all tests...
-    PASSLIB_TESTS="all" nosetests -v --tests passlib/tests
+.. note::
 
-    # to run nose with the optional coverage plugin...
-    # (results will be in build/coverage)
-    PASSLIB_TESTS="all" nosetests -v --tests passlib/tests --with-coverage \
-        --cover-package=passlib --cover-html --cover-html-dir build/coverage
+    Due to the critical nature of password hashing, Passlib's unittest framework
+    is rather extensive, covering the behavior of all the classes, 8-bit
+    test vectors for all supported hashes, and some primitive fuzz testing;
+    it occupies ~38% of the Passlib codebase. Because of this, the full test
+    suite make take some time to run. Setting ``PASSLIB_TEST_MODE`` to
+    ``"quick"`` or ``"default"`` will speed things up.
 
-(There will be a large proportion of skipped tests, this is normal).
+.. rst-class:: html-toggle
 
 Documentation
 =============
diff --git a/docs/lib/passlib.context.rst b/docs/lib/passlib.context.rst
index 210569c..185b183 100644
--- a/docs/lib/passlib.context.rst
+++ b/docs/lib/passlib.context.rst
@@ -147,6 +147,8 @@ Options which directly affect the behavior of the CryptContext instance:
 
     .. seealso:: :ref:`context-migration-example` in the tutorial
 
+.. _context-min-verify-time-option:
+
 ``min_verify_time``
 
     If specified, unsuccessful :meth:`~CryptContext.verify`
diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
index 70c6341..f917dae 100644
--- a/docs/lib/passlib.hash.bcrypt.rst
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -40,6 +40,8 @@ Interface
 =========
 .. autoclass:: bcrypt()
 
+.. _bcrypt-backends:
+
 .. note::
 
     This class will use the first available of four possible backends:
diff --git a/docs/lib/passlib.hash.scram.rst b/docs/lib/passlib.hash.scram.rst
index 9a232a4..177ed3b 100644
--- a/docs/lib/passlib.hash.scram.rst
+++ b/docs/lib/passlib.hash.scram.rst
@@ -136,7 +136,7 @@ any digests. An example would be::
 
 The algorithm used to calculate each digest is::
 
-    pbkdf2(salsprep(password).encode("utf-8"), salt, rounds, -1, alg)
+    pbkdf2(salsprep(password).encode("utf-8"), salt, rounds, alg_digest_size, "hmac-"+alg)
 
 ...as laid out in the SCRAM specification [#scram]_. All digests
 should verify against the same password, or the hash is considered malformed.
diff --git a/docs/lib/passlib.hash.sha256_crypt.rst b/docs/lib/passlib.hash.sha256_crypt.rst
index bbe9c4e..c0f44d8 100644
--- a/docs/lib/passlib.hash.sha256_crypt.rst
+++ b/docs/lib/passlib.hash.sha256_crypt.rst
@@ -5,8 +5,10 @@
 .. currentmodule:: passlib.hash
 
 SHA-256 Crypt and SHA-512 Crypt were developed in 2008 by Ulrich Drepper [#f1]_,
-designed as the successor to :class:`~passlib.hash.md5_crypt`. They include fixes
-and advancements such as variable rounds, and use of NIST-approved cryptographic primitives.
+designed as the successor to :class:`~passlib.hash.md5_crypt`.
+They include fixes and advancements such as variable rounds, and use of NIST-approved cryptographic primitives.
+The design involves repeated composition of the underlying digest algorithm,
+using various arbitrary permutations of inputs.
 SHA-512 / SHA-256 Crypt are currently the default password hash for many systems
 (notably Linux), and have no known weaknesses.
 SHA-256 Crypt is one of the three hashes Passlib :ref:`recommends <recommended-hashes>`
diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst
index 13ace1d..4dc2314 100644
--- a/docs/password_hash_api.rst
+++ b/docs/password_hash_api.rst
@@ -389,7 +389,7 @@ There is currently one additional support method, :meth:`~PasswordHash.identify`
 
         If you are considering using this method to select from multiple
         algorithms in order to verify a password, you may be better served
-        by the :doc:`CryptContext <context-overview>` class.
+        by the :ref:`CryptContext <context-overview>` class.
 
 ..
     the undocumented and experimental support methods currently include
diff --git a/passlib/registry.py b/passlib/registry.py
index 68109cc..59c885e 100644
--- a/passlib/registry.py
+++ b/passlib/registry.py
@@ -252,7 +252,6 @@ def register_crypt_handler(handler, force=False, _attr=None):
     """
     # validate handler
     if not is_crypt_handler(handler):
-        # TODO: make an official interface
         raise ExpectedTypeError(handler, "password hash handler", "handler")
     if not handler:
         raise AssertionError("``bool(handler)`` must be True")