more work on doc

18 files changed, 130 insertions, 84 deletions

diff --git a/docs/crypt_handler_api.rst b/docs/crypt_handler_api.rst
index e6192f5..f19439c 100644
--- a/docs/crypt_handler_api.rst
+++ b/docs/crypt_handler_api.rst
@@ -1,7 +1,8 @@
 .. _crypt-handler-api:
+.. _password-hash-api:
 
 ======================
-api for crypt handlers
+Password Hash API
 ======================
 
 Motivation
diff --git a/docs/lib/passlib.hash.apr_md5_crypt.rst b/docs/lib/passlib.hash.apr_md5_crypt.rst
index 272c08d..0aefe1d 100644
--- a/docs/lib/passlib.hash.apr_md5_crypt.rst
+++ b/docs/lib/passlib.hash.apr_md5_crypt.rst
@@ -1,9 +1,9 @@
-=============================================================
-:mod:`passlib.hash.apr_md5_crypt` - Apache MD5-Crypt Variant
-=============================================================
+==================================================================
+:mod:`passlib.hash.apr_md5_crypt` - Apache MD5-Crypt password hash
+==================================================================
 
 .. module:: passlib.hash.apr_md5_crypt
-    :synopsis: Apache MD5 Crypt
+    :synopsis: Apache MD5-Crypt variant
 
 Stats: 96 bit checksum, 48 bit salt, :ref:`modular-crypt-format` compatible.
 
diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
index 0b22e07..5c68a22 100644
--- a/docs/lib/passlib.hash.bcrypt.rst
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -1,9 +1,9 @@
 ==================================================================
-:mod:`passlib.hash.bcrypt` - BCrypt
+:mod:`passlib.hash.bcrypt` - BCrypt password hash
 ==================================================================
 
 .. module:: passlib.hash.bcrypt
-    :synopsis: implementation of blowfish-based BCrypt scheme
+    :synopsis: BCrypt
 
 .. todo::
 
diff --git a/docs/lib/passlib.hash.des_crypt.rst b/docs/lib/passlib.hash.des_crypt.rst
index 6b7e195..0487ccf 100644
--- a/docs/lib/passlib.hash.des_crypt.rst
+++ b/docs/lib/passlib.hash.des_crypt.rst
@@ -1,9 +1,9 @@
-========================================================
-:mod:`passlib.hash.des_crypt` - Unix (DES) Crypt
-========================================================
+=======================================================================
+:mod:`passlib.hash.des_crypt` - Tradtional Unix DES Crypt password hash
+=======================================================================
 
 .. module:: passlib.hash.des_crypt
-    :synopsis: implementation of original unix-crypt / des-crypt scheme
+    :synopsis: Traditional Unix (DES) Crypt
 
 .. todo::
 
diff --git a/docs/lib/passlib.hash.ext_des_crypt.rst b/docs/lib/passlib.hash.ext_des_crypt.rst
index 35da109..082a12f 100644
--- a/docs/lib/passlib.hash.ext_des_crypt.rst
+++ b/docs/lib/passlib.hash.ext_des_crypt.rst
@@ -1,9 +1,9 @@
-==================================================================
-:mod:`passlib.hash.ext_des_crypt` - BSDi Extended Unix (DES) Crypt
-==================================================================
+=================================================================================
+:mod:`passlib.hash.ext_des_crypt` - BSDi Extended DES Crypt password hash
+=================================================================================
 
 .. module:: passlib.hash.ext_des_crypt
-    :synopsis: implementation of BSDi extended unix/des crypt scheme
+    :synopsis: BSDi Extended Unix (DES) Crypt
 
 .. todo::
 
diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst
index 78fe3f3..a611959 100644
--- a/docs/lib/passlib.hash.md5_crypt.rst
+++ b/docs/lib/passlib.hash.md5_crypt.rst
@@ -1,9 +1,9 @@
 ==================================================================
-:mod:`passlib.hash.md5_crypt` - MD5-Crypt
+:mod:`passlib.hash.md5_crypt` - MD5 Crypt password hash
 ==================================================================
 
 .. module:: passlib.hash.md5_crypt
-    :synopsis: implementation of MD5-Crypt scheme
+    :synopsis: MD5-Crypt
 
 .. todo::
 
diff --git a/docs/lib/passlib.hash.myql_323.rst b/docs/lib/passlib.hash.mysql_323.rst
index 6bb1467..d2df512 100644
--- a/docs/lib/passlib.hash.myql_323.rst
+++ b/docs/lib/passlib.hash.mysql_323.rst
@@ -1,9 +1,9 @@
-==================================================================
-:mod:`passlib.hash.mysql_323` - MySQL 3.2.3 "OLD_PASSWORD" Scheme
-==================================================================
+========================================================================
+:mod:`passlib.hash.mysql_323` - MySQL 3.2.3 password hash
+========================================================================
 
 .. module:: passlib.hash.mysql_323
-    :synopsis: MySQL 3.2.3 "OLD_PASSWORD" scheme
+    :synopsis: MySQL 3.2.3 password hash
 
 .. todo::
 
diff --git a/docs/lib/passlib.hash.mysql_41.rst b/docs/lib/passlib.hash.mysql_41.rst
index 3665ebf..6b8ba2e 100644
--- a/docs/lib/passlib.hash.mysql_41.rst
+++ b/docs/lib/passlib.hash.mysql_41.rst
@@ -1,9 +1,9 @@
-==================================================================
-:mod:`passlib.hash.mysql_41` - MySQL 4.1 "NEW_PASSWORD" Scheme
-==================================================================
+=====================================================================
+:mod:`passlib.hash.mysql_41` - MySQL 4.1 password hash
+=====================================================================
 
 .. module:: passlib.hash.mysql_41
-    :synopsis: MySQL 4.1 "NEW_PASSWORD" scheme
+    :synopsis: MySQL 4.1 password hash
 
 .. todo::
 
diff --git a/docs/lib/passlib.hash.nthash.rst b/docs/lib/passlib.hash.nthash.rst
new file mode 100644
index 0000000..a8885b5
--- /dev/null
+++ b/docs/lib/passlib.hash.nthash.rst
@@ -0,0 +1,27 @@
+==================================================================
+:mod:`passlib.hash.nthash` - Windows NT-HASH for Unix
+==================================================================
+
+.. module:: passlib.hash.nthash
+    :synopsis: Windows NT-HASH for Unix
+
+.. warning::
+
+    This scheme is notoriously weak (since it's based on :mod:`~passlib.utils.md4`).
+    Online tables exist for quickly performing pre-image attacks on this scheme.
+    **Do not use** in new code.
+
+This handler implements the Windows NT-HASH algorithm,
+encoded in a format compatible with the :ref:`modular-crypt-format`.
+It is found on some unix systems where the administrator has decided
+to store user passwords in a manner compatible with the SMB/CIFS protocol.
+
+It supports two identifiers, ``$3$`` and ``$NT$``, though it defaults to ``$3$``.
+
+In addition to the normal password hash api, this module also exposes
+the following method:
+
+.. function:: raw_nthash(secret, hex=False)
+
+    perform raw nthash calculation, returning either
+    raw digest, or as lower-case hexidecimal characters.
diff --git a/docs/lib/passlib.hash.postgres_md5.rst b/docs/lib/passlib.hash.postgres_md5.rst
index 0b75dd5..7f415f1 100644
--- a/docs/lib/passlib.hash.postgres_md5.rst
+++ b/docs/lib/passlib.hash.postgres_md5.rst
@@ -2,7 +2,7 @@
 :mod:`passlib.hash.postgres_md5` - Postgres MD5 password hash
 ==================================================================
 
-.. module:: passlib.hash.mysql_md5
+.. module:: passlib.hash.postgres_md5
     :synopsis: Postgres MD5 password hash
 
 Stats: 512 bit checksum, username used as salt
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index 313fa2e..28c7990 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -3,27 +3,21 @@
 ============================================
 
 .. module:: passlib.hash
-    :synopsis: package containing handlers for all builtin password hash schemes
+    :synopsis: package containing all builtin password hashes
 
-Overview
-========
-This package contains handlers for all the password hash schemes built into
-passlib. All modules within this package implement a single scheme,
-and follow the :ref:`crypt-handler-api`. They can be imported
-and used directly, eg::
+This subpackage contains handlers for all the password hashes built into
+passlib. As well, any third-party handlers registered using :func:`register_crypt_handler`
+will be inserted into this package.
+
+Each module within this package implements a single password hashing scheme,
+and follows passlib's :ref:`password-hash-api`.
+While many applications may find it easier to use a :class:`CryptContext`
+instance, or retreive handlers via :func:`get_crypt_handler`, they can
+also be imported and used directly from this package:
 
     >>> from passlib.hash import md5_crypt
     >>> hash = md5_crypt.encrypt("password")
 
-As well, any third-party handlers registered with passlib via :func:`register_crypt_handler`
-will be inserted into this package.
-
-Note that many applications may find it easier to use a :class:`CryptContext`
-instance, or retreive handlers via :func:`get_crypt_handler`, rather than
-import directly from this module.
-
-Contents
-========
 Passlib contains the following builtin password algorithms:
 
 Standard Unix Schemes
@@ -32,21 +26,40 @@ All these schemes are/were used by various unix flavors to store user passwords.
 Because of this, all these schemes (except des-crypt and ext-des-crypt) follow
 the :ref:`modular crypt format <modular-crypt-format>`.
 
-* :mod:`~passlib.hash.des_crypt` - Legacy DES-based unix crypt() algorithm.
-* :mod:`~passlib.hash.ext_des_crypt` - Legacy BSDi extension of des-crypt which adds more salt and variable rounds.
-* :mod:`~passlib.hash.md5_crypt` - MD5-based descendant of des-crypt.
-* :mod:`~passlib.hash.bcrypt` - Blowfish-based replacement for md5-crypt, used mostly on BSD systems.
-* :mod:`~passlib.hash.sha256_crypt` - SHA-256 based descendant of MD5 crypt, used mostly on Linux systems.
-* :mod:`~passlib.hash.sha512_crypt` - SHA-512 based descendant of MD5 crypt, used mostly on Linux systems.
+..
+    * :mod:`~passlib.hash.des_crypt` - Legacy DES-based unix crypt() algorithm.
+    * :mod:`~passlib.hash.ext_des_crypt` - Legacy BSDi extension of des-crypt which adds more salt and variable rounds.
+    * :mod:`~passlib.hash.md5_crypt` - MD5-based descendant of des-crypt.
+    * :mod:`~passlib.hash.bcrypt` - Blowfish-based replacement for md5-crypt, used mostly on BSD systems.
+    * :mod:`~passlib.hash.sha256_crypt` - SHA-256 based descendant of MD5 crypt, used mostly on Linux systems.
+    * :mod:`~passlib.hash.sha512_crypt` - SHA-512 based descendant of MD5 crypt, used mostly on Linux systems.
+
+.. toctree::
+    :maxdepth: 1
+
+    passlib.hash.des_crypt
+    passlib.hash.ext_des_crypt
+    passlib.hash.md5_crypt
+    passlib.hash.bcrypt
+    passlib.hash.sha256_crypt
+    passlib.hash.sha512_crypt
 
 Non-Standard Unix-Compatible Schemes
 ------------------------------------
-While few of these schemes were ever used by unix flavors to store user passwords,
+While most of these schemes are rarely used by any unix flavor to store user passwords,
 these are compatible with the :ref:`modular crypt format <modular-crypt-format>`, and can be
-used in contexts which support them in parallel with the others following
-the same format.
+used in contexts which support them, in parallel with the others following
+the modular crypt format.
+
+..
+    * :mod:`~passlib.hash.apr_md5_crypt` - Apache-specific variant of md5-crypt, used in htpasswd files
+    * :mod:`~passlib.hash.nthash` - Windows NT-Hash password hashApache-specific variant of md5-crypt, used in htpasswd files
+
+.. toctree::
+    :maxdepth: 1
 
-* :mod:`~passlib.hash.apr_md5_crypt` - Apache-specific variant of md5-crypt, used in htpasswd files
+    passlib.hash.apr_md5_crypt
+    passlib.hash.nthash
 
 .. todo::
 
@@ -61,6 +74,14 @@ The following schemes are used in very specified contexts,
 and have encoding schemes and other requirements
 not seen outside those specific contexts:
 
-* :mod:`~passlib.hash.mysql_323` - Legacy scheme used by MySQL 3.2.3+ to store user passwords
-* :mod:`~passlib.hash.mysql_41` - Current scheme used by MySQL 4.1+ to store user passwords
-* :mod:`~passlib.hash.postgres_md5` - Current scheme used by PostgreSQL to store user passwords
+.. toctree::
+    :maxdepth: 1
+
+    passlib.hash.mysql_323
+    passlib.hash.mysql_41
+    passlib.hash.postgres_md5
+
+..
+    * :mod:`~passlib.hash.mysql_323` - Legacy scheme used by MySQL 3.2.3+ to store user passwords
+    * :mod:`~passlib.hash.mysql_41` - Current scheme used by MySQL 4.1+ to store user passwords
+    * :mod:`~passlib.hash.postgres_md5` - Current scheme used by PostgreSQL to store user passwords
diff --git a/docs/lib/passlib.hash.sha256_crypt.rst b/docs/lib/passlib.hash.sha256_crypt.rst
index fbb23b0..d725d47 100644
--- a/docs/lib/passlib.hash.sha256_crypt.rst
+++ b/docs/lib/passlib.hash.sha256_crypt.rst
@@ -1,9 +1,9 @@
 ==================================================================
-:mod:`passlib.hash.sha256_crypt` - SHA-256 Crypt
+:mod:`passlib.hash.sha256_crypt` - SHA-256 Crypt password hash
 ==================================================================
 
 .. module:: passlib.hash.sha526_crypt
-    :synopsis: implementation of SHA-256 Crypt scheme
+    :synopsis: SHA-256 Crypt
 
 .. todo::
 
diff --git a/docs/lib/passlib.hash.sha512_crypt.rst b/docs/lib/passlib.hash.sha512_crypt.rst
index 325d963..e9c9b51 100644
--- a/docs/lib/passlib.hash.sha512_crypt.rst
+++ b/docs/lib/passlib.hash.sha512_crypt.rst
@@ -1,16 +1,16 @@
-==================================================================
-:mod:`passlib.hash.sha512_crypt` - SHA-512 Crypt
-==================================================================
+===================================================================
+:mod:`passlib.hash.sha512_crypt` - SHA-512 Crypt password hash
+===================================================================
 
-.. module:: passlib.hash.sha526_crypt
-    :synopsis: implementation of SHA-512 Crypt scheme
+.. module:: passlib.hash.sha512_crypt
+    :synopsis: SHA-512 Crypt
 
-Defined in the same specification, the SHA-512 Crypt scheme is almost identical to SHA-256 Crypt,
-except for the following differences:
+This scheme is identical to :mod:`~passlib.hash.sha256_crypt` in almost every way,
+they are defined by the same specification and have the same design and structure,
+except the following differences:
 
 * it uses the prefix ``$6$`` where the SHA-256 Crypt uses ``$5$``.
-* it uses SHA-512 as it's internal hash function
+* it uses SHA-512 as it's internal hash function instead of SHA-256.
 * it's output hash is correspondingly larger.
 
-For details about this module, see :mod:`~passlib.hash.sha256_crypt`,
-it is exactly the same except for the above differences.
+For details about this module, see :mod:`~passlib.hash.sha256_crypt`.
diff --git a/docs/lib/passlib.hash.sun_md5_crypt.rst b/docs/lib/passlib.hash.sun_md5_crypt.rst
index 7db3bc9..f225f19 100644
--- a/docs/lib/passlib.hash.sun_md5_crypt.rst
+++ b/docs/lib/passlib.hash.sun_md5_crypt.rst
@@ -1,9 +1,9 @@
-=============================================================
-:mod:`passlib.hash.sun_md5_crypt` - Sun MD5-Crypt
-=============================================================
+===============================================================
+:mod:`passlib.hash.sun_md5_crypt` - Sun MD5 Crypt password hash
+===============================================================
 
 .. module:: passlib.hash.sun_md5_crypt
-    :synopsis: Sun MD5 Crypt implementation
+    :synopsis: Sun MD5 Crypt
 
 .. todo::
 
diff --git a/docs/lib/passlib.utils.des.rst b/docs/lib/passlib.utils.des.rst
index f50cc95..52d1c12 100644
--- a/docs/lib/passlib.utils.des.rst
+++ b/docs/lib/passlib.utils.des.rst
@@ -9,9 +9,8 @@ This module contains routines for encrypting blocks of data using the DES algori
 
 They do not support multi-block operation or decryption,
 since they are designed for use in password hash algorithms
-such as :mod:`passlib.hash.des_crypt` and :mod:`passlib.hash.ext_des_crypt`.
+such as :mod:`~passlib.hash.des_crypt` and :mod:`~passlib.hash.ext_des_crypt`.
 
 .. autofunction:: expand_des_key
 .. autofunction:: des_encrypt_block
 .. autofunction:: mdes_encrypt_int_block
-
diff --git a/docs/lib/passlib.utils.md4.rst b/docs/lib/passlib.utils.md4.rst
index fb0f388..5b9ed35 100644
--- a/docs/lib/passlib.utils.md4.rst
+++ b/docs/lib/passlib.utils.md4.rst
@@ -1,9 +1,9 @@
-====================================================
-:mod:`passlib.utils.md4` - MD4-Digest implementation
-====================================================
+========================================================
+:mod:`passlib.utils.md4` - MD4 message digest algorithm
+========================================================
 
 .. module:: passlib.utils.md4
-    :synopsis: implemented of MD4-Digest
+    :synopsis: MD4 message digest algorithm
 
 .. warning::
 
diff --git a/docs/lib/passlib.utils.pbkdf2.rst b/docs/lib/passlib.utils.pbkdf2.rst
index 7bd9ab9..2bade1c 100644
--- a/docs/lib/passlib.utils.pbkdf2.rst
+++ b/docs/lib/passlib.utils.pbkdf2.rst
@@ -1,9 +1,9 @@
-====================================================
-:mod:`passlib.utils.pbkdf2` - PBKDF2 algorithm support
-====================================================
+=============================================================
+:mod:`passlib.utils.pbkdf2` - PBKDF2 key derivation algorithm
+=============================================================
 
 .. module:: passlib.utils.pbkdf2
-    :synopsis: implementation of PBKDF2 algorithm
+    :synopsis: PBKDF2 key derivation algorithm
 
 This module provides a single function, :func:`pbkdf2`,
 which provides the ability to generate an arbitrary
diff --git a/docs/lib/passlib.utils.rst b/docs/lib/passlib.utils.rst
index 00df703..3c6a627 100644
--- a/docs/lib/passlib.utils.rst
+++ b/docs/lib/passlib.utils.rst
@@ -3,10 +3,8 @@
 =============================================
 
 .. module:: passlib.utils
-    :synopsis: helper functions for implementing crypt handlers
+    :synopsis: helper functions for implementing password hashes
 
-Overview
-========
 This module contains a number of utility functions used by passlib
 to implement the builtin handlers, and other code within passlib.
 They may also be useful when implementing custom handlers for existing legacy formats.