documentation work

==================
* finished password hash api description
* various documentation cleanups
* removed unused quickstart doc

20 files changed, 238 insertions, 232 deletions

diff --git a/docs/conf.py b/docs/conf.py
index f54dc50..eea6772 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# BPS documentation build configuration file, created by
+# PassLib documentation build configuration file, created by
 # sphinx-quickstart on Mon Mar  2 14:12:06 2009.
 #
 # This file is execfile()d with the current directory set to its containing dir.
diff --git a/docs/contents.rst b/docs/contents.rst
index 0ed0b32..3379578 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -6,17 +6,15 @@ Table Of Contents
 
     Front Page <index>
     install
-    quickstart
     overview
 
-    lib/passlib.base
+    password_hash_api
     lib/passlib.hash
+    lib/passlib.base
     lib/passlib.sqldb
     lib/passlib.unix
     lib/passlib.utils
 
-    password_hash_api
-
     history
     copyright
 
diff --git a/docs/history.rst b/docs/history.rst
index 615574b..520666e 100644
--- a/docs/history.rst
+++ b/docs/history.rst
@@ -9,7 +9,7 @@ Release History
 
 2011-01-05 -- version 0.8
     * various code cleanups preparing for public release
-    * ext-des-crypt, apr-md5-crypt, and other lesser known schemes added.
+    * bsdi-crypt, apr-md5-crypt, and other lesser known schemes added.
     * documentation added
 
 2009-03-10 -- version 0.7
diff --git a/docs/index.rst b/docs/index.rst
index f403aab..3a78d56 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,24 +4,20 @@ PassLib |release| documentation
 
 Introduction
 ============
-Passlib is a collection of routines for managing password hashes
-in wide variety of different uses:
+PassLib is a library for managing password hashes,
+with support for over 18 current and historical :doc:`password hash schemes <lib/passlib.hash>`.
+It can be used for a variety of purposes:
 
-    * cross-platform replacement for stdlib ``crypt()``.
+    * cross-platform replacement for stdlib's ``crypt()``.
     * encrypting & verifying most known hash formats used by:
         - Linux & BSD shadow files
         - Apache htpasswd files
         - MySQL & PostgreSQL user account tables
-    * drop-in secure hashing for new python applications
-    * quickly building a configurable hashing policy
-      for existing python applications and existing hashing schemes.
+    * drop-in password hashing for new python applications.
+    * building a configurable hashing policy
+      for python applications to migrate existing hashing schemes.
 
-A quick sample of some of the more frequently used modules:
-
-    * :mod:`passlib` -- password hashing algorithms
-    * :mod:`passlib.hash` -- module containing all supported password hashes
-
-    ... see the :doc:`library overview <overview>` for a complete list.
+See the :doc:`Library Overview <overview>` for more details.
 
 Quick Links
 ===========
@@ -35,14 +31,14 @@ Quick Links
          <span class="linkdescr">lists all sections and subsections</span></p>
 
           <p class="biglink"><a class="biglink" href="overview.html">Library Overview</a><br>
-         <span class="linkdescr">describes how BPS is laid out</span></p>
+         <span class="linkdescr">describes how PassLib is laid out</span></p>
 
     </td><td width="50%">
 
       <p class="biglink"><a class="biglink" href="genindex.html">General Index</a><br>
          <span class="linkdescr">all functions, classes, terms</span></p>
 
-      <p class="biglink"><a class="biglink" href="modindex.html">Module List</a><br>
+      <p class="biglink"><a class="biglink" href="py-modindex.html">Module List</a><br>
          <span class="linkdescr">quick access to all modules</span></p>
 
       <p class="biglink"><a class="biglink" href="search.html">Search Page</a><br>
diff --git a/docs/install.rst b/docs/install.rst
index 159e634..6b74612 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -17,19 +17,21 @@ The following libraries are not required, but will be used if found:
 
     * If installed, `py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_ will be
       used instead of PassLib's slower pure-python bcrypt implementation.
-      (see :class:`passlib.hash.bcrypt`).
       *This is strongly recommended, as the builtin implementation is VERY slow*.
 
-    * stdlib ``crypt.crypt()`` will be used if present, and if the underlying
+    * stdlib's :mod:`!crypt` module will be used if present, and if the host
       OS supports the specific scheme in question. OS support is autodetected
-      from the following schemes: des-crypt,  md5-crypt, bcrypt, sha256-crypt,
+      for the following schemes: des-crypt,  md5-crypt, bcrypt, sha256-crypt,
       and sha512-crypt.
 
+    * If installed, `M2Crypto <http://chandlerproject.org/bin/view/Projects/MeTooCrypto>`_ will be
+      used to accelerate some internal support functions, but it is not required.
+
 Installing
 ==========
 PassLib can be installed with easy_install, linked/copied into sys.path directly
-from it's source directory, or installed using ``$SOURCE/setup.py install``,
-where ``$SOURCE`` is the path to the PassLib source directory.
+from it's source directory, or installed using :samp:`{$SOURCE}/setup.py install`,
+where :samp:`{$SOURCE}` is the path to the PassLib source directory.
 PassLib is pure python, there is nothing to compile or configure.
 
 Testing
@@ -52,9 +54,13 @@ The latest copy of this documentation should always be available
 at the `PassLib homepage <http://www.assurancetechnologies.com/software/passlib>`_.
 
 If you wish to generate your own copy of the documentation,
-you will need to install `Sphinx <http://sphinx.pocoo.org/>`_ (1.0 or better)
-as well `astdoc <http://www.assurancetechnologies.com/software/astdoc>`_ (a bundle of custom sphinx themes & extensions
-used by Assurance Technologies). Next, download the PassLib source,
-and run ``python $SOURCE/docs/make.py clean html`` (where ``$SOURCE`` is the path to the PassLib source directory).
-Once Sphinx completes it's run, point a web browser to the file at ``$SOURCE/docs/_build/html/index.html``
+you will need to:
+
+* install `Sphinx <http://sphinx.pocoo.org/>`_ (1.0 or better)
+* install `astdoc <http://www.assurancetechnologies.com/software/astdoc>`_ (a bundle of custom sphinx themes & extensions
+  used by Assurance Technologies).
+* download the PassLib source
+* run :samp:`python {$SOURCE}/docs/make.py clean html` (where :samp:`{$SOURCE}` is the path to the PassLib source directory).
+
+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.base.rst b/docs/lib/passlib.base.rst
index a458e0f..a3d6e4a 100644
--- a/docs/lib/passlib.base.rst
+++ b/docs/lib/passlib.base.rst
@@ -2,7 +2,7 @@
 :mod:`passlib.base` - Crypt Contexts
 =============================================
 
-.. currentmodule:: passlib.base
+.. module:: passlib.base
 
 For more complex deployment scenarios than
 the frontend functions described in :doc:`Quick Start </quickstart>`,
diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
index 564f117..2168f1c 100644
--- a/docs/lib/passlib.hash.bcrypt.rst
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -47,7 +47,7 @@ This implementation of bcrypt differs from others in a few ways:
 
   BCrypt does not specify what the behavior should be when
   passed a salt string outside of the regexp range ``[./A-Za-z0-9]``.
-  In order to avoid this situtation, Passlib strictly limits salts to the
+  In order to avoid this situtation, PassLib strictly limits salts to the
   allowed character set, and will throw a ValueError if an invalid
   salt character is encountered.
 
diff --git a/docs/lib/passlib.hash.bigcrypt.rst b/docs/lib/passlib.hash.bigcrypt.rst
index 446077c..6431e5e 100644
--- a/docs/lib/passlib.hash.bigcrypt.rst
+++ b/docs/lib/passlib.hash.bigcrypt.rst
@@ -117,8 +117,8 @@ This implementation of bigcrypt differs from others in two ways:
   various limits on maximum password length (commonly, 128 chars),
   and discard the remaining part of the password.
 
-  Thus, while Passlib should be able to verify all existing
-  bigcrypt hashes, other systems may require hashes generated by Passlib
+  Thus, while PassLib should be able to verify all existing
+  bigcrypt hashes, other systems may require hashes generated by PassLib
   to be truncated to their specific maximum length.
 
 * Unicode Policy:
diff --git a/docs/lib/passlib.hash.bsdi_crypt.rst b/docs/lib/passlib.hash.bsdi_crypt.rst
index e4ab8a3..83937d4 100644
--- a/docs/lib/passlib.hash.bsdi_crypt.rst
+++ b/docs/lib/passlib.hash.bsdi_crypt.rst
@@ -132,7 +132,7 @@ This implementation of bsdi-crypt differs from others in one way:
   PassLib will encode unicode passwords using ``utf-8``
   before running them through bsdi-crypt. If a different
   encoding is desired by an application, the password should be encoded
-  before handing it to Passlib.
+  before handing it to PassLib.
 
 References
 ==========
diff --git a/docs/lib/passlib.hash.des_crypt.rst b/docs/lib/passlib.hash.des_crypt.rst
index 7712c64..4855e9a 100644
--- a/docs/lib/passlib.hash.des_crypt.rst
+++ b/docs/lib/passlib.hash.des_crypt.rst
@@ -108,7 +108,7 @@ This implementation of des-crypt differs from others in a few ways:
   Some implementations of des-crypt allow empty and single-character salt strings.
   However, the behavior in these cases varies wildly between implementations,
   including errors and broken hashes.
-  To avoid all this, Passlib will throw an "invalid salt" if the provided
+  To avoid all this, PassLib will throw an "invalid salt" if the provided
   salt string is not at least 2 characters.
 
 * Restricted salt string character set:
@@ -118,7 +118,7 @@ This implementation of des-crypt differs from others in a few ways:
   a 12-bit integer. Many implementations of des-crypt will
   accept a salt containing other characters, but
   vary wildly in how they are handled, including errors and implementation-specific value mappings.
-  To avoid all this, Passlib will throw an "invalid salt" if the salt
+  To avoid all this, PassLib will throw an "invalid salt" if the salt
   string contains any non-standard characters.
 
 * Unicode Policy:
@@ -134,4 +134,4 @@ This implementation of des-crypt differs from others in a few ways:
 
 References
 ==========
-.. [#] A java implementation of des-crypt, used as base for Passlib's pure-python implementation, is located at `<http://www.dynamic.net.au/christos/crypt/UnixCrypt2.txt>`_
+.. [#] A java implementation of des-crypt, used as base for PassLib's pure-python implementation, is located at `<http://www.dynamic.net.au/christos/crypt/UnixCrypt2.txt>`_
diff --git a/docs/lib/passlib.hash.hex_digests.rst b/docs/lib/passlib.hash.hex_digests.rst
index 7224069..ff4c00f 100644
--- a/docs/lib/passlib.hash.hex_digests.rst
+++ b/docs/lib/passlib.hash.hex_digests.rst
@@ -9,7 +9,7 @@ hexidecimal-encoded message digests, such as MD5 or SHA1.
 Such schemes are *extremely* vulnerable to pre-computed brute-force attacks,
 and should not be used in new applications. However, for the sake
 of backwards compatibility when converting existing applications,
-Passlib provides wrappers for few of the common hashes.
+PassLib provides wrappers for few of the common hashes.
 
 Usage
 =====
diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst
index fb962f9..0644ddb 100644
--- a/docs/lib/passlib.hash.md5_crypt.rst
+++ b/docs/lib/passlib.hash.md5_crypt.rst
@@ -140,13 +140,13 @@ though it is not yet considered broken:
 
 Deviations
 ==========
-Passlib's implementation of md5-crypt differs from the reference implementation (and others) in two ways:
+PassLib's implementation of md5-crypt differs from the reference implementation (and others) in two ways:
 
 * Restricted salt string character set:
 
   The underlying algorithm can unambigously handle salt strings
   which contain any possible byte value besides ``\x00`` and ``$``.
-  However, Passlib strictly limits salts to the
+  However, PassLib strictly limits salts to the
   :mod:`hash 64 <passlib.utils.h64>` character set,
   as nearly all implementations of md5-crypt generate
   and expect salts containing those characters,
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index 2cece32..f163679 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -18,7 +18,7 @@ also be imported and used directly from this package, as in the following exampl
     >>> from passlib.hash import md5_crypt
     >>> hash = md5_crypt.encrypt("password")
 
-Passlib contains the following builtin password algorithms:
+PassLib contains the following builtin password algorithms:
 
 Archaic Unix Schemes
 --------------------
@@ -47,20 +47,10 @@ They all follow the :ref:`modular crypt format <modular-crypt-format>` for encod
     passlib.hash.md5_crypt
     passlib.hash.bcrypt
     passlib.hash.sha1_crypt
+    passlib.hash.sun_md5_crypt
     passlib.hash.sha256_crypt
     passlib.hash.sha512_crypt
 
-.. toctree::
-    :hidden:
-
-    passlib.hash.sun_md5_crypt
-
-.. todo::
-
-    These aren't fully implemented / tested yet:
-
-    * :doc:`passlib.hash.sun_md5_crypt <passlib.hash.sun_md5_crypt>` - MD5-based scheme used by Solaris 10 (NOT related to md5-crypt above).
-
 Non-Standard Unix-Compatible Schemes
 ------------------------------------
 While most of these schemes are not commonly used by any unix flavor to store user passwords,
diff --git a/docs/lib/passlib.hash.sha1_crypt.rst b/docs/lib/passlib.hash.sha1_crypt.rst
index 95b4cd1..6f26bb2 100644
--- a/docs/lib/passlib.hash.sha1_crypt.rst
+++ b/docs/lib/passlib.hash.sha1_crypt.rst
@@ -79,7 +79,7 @@ in a few ways:
 
   The underlying algorithm can unambigously handle salt strings
   which contain any possible byte value besides ``\x00`` and ``$``.
-  However, Passlib strictly limits salts to the
+  However, PassLib strictly limits salts to the
   :mod:`hash 64 <passlib.utils.h64>` character set,
   as nearly all implementations of sha1-crypt generate
   and expect salts containing those characters.
diff --git a/docs/lib/passlib.hash.sha512_crypt.rst b/docs/lib/passlib.hash.sha512_crypt.rst
index 3f73a17..a5c63d5 100644
--- a/docs/lib/passlib.hash.sha512_crypt.rst
+++ b/docs/lib/passlib.hash.sha512_crypt.rst
@@ -88,7 +88,7 @@ and other implementations, in a few ways:
 
   The underlying algorithm can unambigously handle salt strings
   which contain any possible byte value besides ``\x00`` and ``$``.
-  However, Passlib strictly limits salts to the
+  However, PassLib strictly limits salts to the
   :mod:`hash 64 <passlib.utils.h64>` character set,
   as nearly all implementations of sha512-crypt generate
   and expect salts containing those characters,
diff --git a/docs/lib/passlib.hash.sun_md5_crypt.rst b/docs/lib/passlib.hash.sun_md5_crypt.rst
index cd43957..38ed905 100644
--- a/docs/lib/passlib.hash.sun_md5_crypt.rst
+++ b/docs/lib/passlib.hash.sun_md5_crypt.rst
@@ -13,7 +13,7 @@ in common with the :class:`~passlib.hash.md5_crypt` algorithm. It supports
 .. warning::
 
     This implementation has not been compared
-    very carefully against any existing implementations,
+    very carefully against the official implementation or reference documentation,
     and it's behavior may not match under various border cases.
     It should not be relied on for anything but novelty purposes
     for the time being.
@@ -118,7 +118,7 @@ using the following formula:
 
 Deviations
 ==========
-Passlib's implementation of Sun-MD5-Crypt deviates from the official implementation
+PassLib's implementation of Sun-MD5-Crypt deviates from the official implementation
 in at least one way:
 
 * Unicode Policy:
@@ -134,7 +134,7 @@ in at least one way:
   encoding is desired by an application, the password should be encoded
   before handing it to PassLib.
 
-Since Passlib's pure python implmentation was written based on the algorithm
+Since PassLib's pure python implmentation was written based on the algorithm
 description above, and has not been properly tested against a reference implementation,
 it may have other bugs and deviations from the correct behavior.
 
diff --git a/docs/lib/passlib.utils.des.rst b/docs/lib/passlib.utils.des.rst
index fbd68ca..674f934 100644
--- a/docs/lib/passlib.utils.des.rst
+++ b/docs/lib/passlib.utils.des.rst
@@ -7,15 +7,14 @@
 
 .. warning::
 
-    NIST has declared DES to be "inadequate" for encryption purpose.
-    These routines, and algorithms based on them,
+    NIST has declared DES to be "inadequate" for cryptographic purposes.
+    These routines, and the password hashes based on them,
     should not be used in new applications.
 
 This module contains routines for encrypting blocks of data using the DES algorithm.
-
 They do not support multi-block operation or decryption,
-since they are designed for use in password hash algorithms
-such as :class:`~passlib.hash.des_crypt` and :class:`~passlib.hash.ext_des_crypt`.
+since they are designed primarily for use in password hash algorithms
+(such as :class:`~passlib.hash.des_crypt` and :class:`~passlib.hash.bsdi_crypt`).
 
 .. autofunction:: expand_des_key
 .. autofunction:: des_encrypt_block
diff --git a/docs/overview.rst b/docs/overview.rst
index 51559c1..6715133 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -2,7 +2,7 @@
 Library Overview
 ================
 
-Passlib is a collection of routines for managing password hashes
+PassLib is a collection of routines for managing password hashes
 as found in unix /etc/shadow files, as returned by stdlib `crypt()`,
 as stored in mysql and postgres, and various other contexts.
 
diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst
index 97a6798..1c3f6ab 100644
--- a/docs/password_hash_api.rst
+++ b/docs/password_hash_api.rst
@@ -1,110 +1,157 @@
 .. _password-hash-api:
 
-======================
+=================
 Password Hash API
-======================
-
-Motivation
-==========
-Passlib supports many different password hashing schemes.
-A majority of them were originally designed to be used on a unix
-system, follow some variant of the unix ``crypt()`` api,
-and have are encoded using the :ref:`modular-crypt-format`.
-Others were designed for use specific contexts only,
-such as PostgreSQL.
-
-Passlib was designed to provide a uniform interface to implementations
-of all these schemes, as well as hide away as much of the implementation
-detail as possible; both in order to make it easier to integrate password hashing
-into new and existing applications. Because of these goals, some of the methods
-required by the crypt handler api tend to overlap slightly,
-in order to accomodate a wide variety of application requirements,
-and other parts have been kept intentionally non-commital, in order to allow
-flexibility of implementation.
-
-All of the schemes built into passlib implement this interface;
-most them as modules within the :mod:`passlib.hash` package.
+=================
 
 Overview
 ========
-A handler which implements a password hash may be a module, class, or instance
-(though most of the ones builtin to Passlib are classes).
-The only requirement is that it expose a minimum of the following attributes
-and functions (for classes, the following functions must be static or class methods).
-
-All handlers have the following three attributes:
-
-    * ``name`` - unique identifier used to distinguish scheme within
-    * ``setting_kwds`` - list of settings recognized by ``genconfig()`` and ``encrypt()``.
-    * ``context_kwds`` - list of context specified keywords required by algorithm
-
-All handlers have the following five functions:
-
-    * ``encrypt(secret, **context_and_settings) -> hash`` - used for encrypting secret using specified options
-    * ``identify(hash) -> True|False`` - used for identifying hash belonging to this algorithm
-    * ``verify(secret, hash, **context)`` - used for verifying a secret against an existing hash
-
-    * ``genconfig(**settings) -> configuration string`` - used for generating configuration strings.
-    * ``genhash(secret, config, **context) -> hash`` - used for encrypting secret using configuration string or existing hash
-
-Usage Examples
-==============
-
-.. todo::
-
-    show some quick examples using bcrypt.
-
-Informational Attributes
-========================
-.. attribute:: name
+All of the hashes supported by PassLib are implemented using classes
+which support an identical interface; this document describes that
+interface in terms of a non-existent abstract class called :class:`!PasswordHash`.
+All of the :doc:`supported password hashes <lib/passlib.hash>`
+expose (at a minimum) the following methods and attributes:
+
+The `required informational attributes`_
+  These consist of the attributes :attr:`~PasswordHash.name`,
+  :attr:`~PasswordHash.setting_kwds`, and :attr:`~PasswordHash.context_kwds`.
+  They permit users and applications to detect what features a specific :class:`!PasswordHash`
+  allows and/or requires.
+
+The `application interface`_
+  This consists of the :meth:`~PasswordHash.encrypt`,
+  :meth:`~PasswordHash.identify`, and :meth:`~PasswordHash.verify` classmethods.
+  Most applications will only need to make use of these methods.
+
+The `crypt interface`_
+  This consists of the :meth:`~PasswordHash.genconfig`,
+  :meth:`~PasswordHash.genhash`. This mimics the standard unix crypt interface,
+  but is usually used directly by applications.
+
+The `optional informational attributes`_
+  These attributes provide additional information
+  about the capabilities and limitations of certain password hash schemes.
+
+Usage
+=====
+While most uses of PassLib are done through a :class:`~passlib.base.CryptContext` class,
+the various :class:`!PasswordHash` classes can be used directly to manipulate
+passwords:
+
+    >>> # for example, the SHA256-Crypt class:
+    >>> from passlib.hash import sha256_crypt as sc
+
+    >>> # using it to encrypt a password:
+    >>> h = sc.encrypt("password")
+    >>> h
+    '$5$rounds=40000$HIo6SCnVL9zqF8TK$y2sUnu13gp4cv0YgLQMW56PfQjWaTyiHjVbXTgleYG9'
+
+    >>> # subsequent calls to sc.encrypt() will generate a new salt:
+    >>> sc.encrypt("password")
+    '$5$rounds=40000$1JfxoiYM5Pxokyh8$ez8uV8jjXW7SjpaTg2vHJmx3Qn36uyZpjhyC9AfBi7B'
+
+    >>> # the same, but with an explict number of rounds:
+    >>> sc.encrypt("password", rounds=10000)
+    '$5$rounds=10000$UkvoKJb8BPrLnR.D$OrUnOdr.IJx74hmyyzuRdr5k9lSXdkFxKmr7bLQTty5'
+
+    >>> #the identify method can be used to determine the format of an unknown hash:
+    >>> sc.identify(h)
+    True
+
+    >>> #check if some other hash is recognized (in this case, an MD5-Crypt hash)
+    >>> sc.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31')
+    False
+
+    >>> #the verify method encapsulates all hash comparison logic for a class:
+    >>> sc.verify("password", h)
+    True
+    >>> sc.verify("wrongpassword", h)
+    False
+
+.. _required-informational-attributes:
+
+Required Informational Attributes
+=================================
+.. attribute:: PasswordHash.name
 
     A unique name used to identify
-    the particular algorithm this handler implements.
+    the particular scheme this class implements.
 
-    These names should consist only of lowercase a-z, the digits 0-9, and hyphens.
+    These names should consist only of lowercase a-z, the digits 0-9, and underscores.
 
     .. note::
 
-        All handlers built into passlib are implemented as modules
-        whose path corresponds to the name, with an underscore replacing the hyphen.
-        For example, ``des-crypt`` is stored as the module ``passlib.hash.des_crypt``.
+        All handlers built into passlib are implemented as classes
+        located under :samp:`passlib.hash.{name}`, where :samp:`{name}`
+        is both the class name, and the value of the ``name`` attribute.
+        This is not a requirement, and may not be true for externally-defined handers.
 
-.. attribute:: setting_kwds
+.. attribute:: PasswordHash.setting_kwds
 
-    If the algorithm supports per-hash configuration
+    If the scheme supports per-hash configuration
     (such as salts, variable rounds, etc), this attribute
     should contain a tuple of keywords corresponding
     to each of those configuration options.
 
-    This should correspond with the keywords accepted
-    by :func:`genconfig`, see that method for details.
+    This should list all the main configuration keywords accepted
+    by :meth:`~PasswordHash.genconfig` and :meth:`~PasswordHash.encrypt`.
 
-    If no settings are supported, this attribute
-    is an empty tuple.
+    If no configuration options are supported, this attribute should be an empty tuple.
 
-.. attribute:: context_kwds
+    While each class may support a variety of options, each with their own meaning
+    and semantics, the following keywords should have the same behavior
+    across all schemes:
 
-    Some algorithms require external contextual information
-    in order to generate a checksum for a password.
-    An example of this is Postgres' md5 algorithm,
-    which requires the username to be provided
-    (which it uses as a salt).
+    ``salt``
+        If present, this means the algorithm contains some number of bits of salt
+        which should vary with every new hash created.
+
+        Providing this as a keyword should allow the application to select
+        a specific salt string; though not only is this far from needed
+        for most cases, the salt string's content constraints vary for each algorithm.
+
+    ``rounds``
+        If present, this means the algorithm allows for a variable number of rounds
+        to be used, allowing the processor time required to be increased.
+
+        Providing this as a keyword should allow the application to
+        override the class' default number of rounds. While this
+        must be a non-negative integer for all implementations,
+        additional constraints may be present for each algorith
+        (such as the cost varying on a linear or logarithmic scale).
+
+    ``ident``
+        If present, the class supports multiple formats for encoding
+        the same hash. The class's documentation will generally list
+        the allowed values, allowing alternate output formats to be selected.
+
+.. attribute:: PasswordHash.context_kwds
 
     This attribute should contain a tuple of keywords
     which should be passed into :func:`encrypt`, :func:`verify`,
     and :func:`genhash` in order to encrypt a password.
 
+    Some algorithms require external contextual information
+    in order to generate a checksum for a password.
+    An example of this is :doc:`Postgres' MD5 algorithm <lib/passlib.hash.postgres_md5>`,
+    which requires the username to be provided when generating a hash
+    (see that class for an example of how this works in pratice).
+
     Since most password hashes require no external information,
-    this tuple will usually be empty.
+    this tuple will usually be empty, and references
+    to context keywords can be ignored for all but a few classes.
 
-Primary Interface
-=================
-The ``encrypt()``, ``identify()``, and ``verify()`` methods are designed
-to provide an easy interface for applications to encrypt new passwords
-and verify existing passwords, without having to deal with details such
-as salt formats.
+.. _application-interface:
 
-.. function:: encrypt(secret, \*\*settings_and_context)
+Application Interface
+=====================
+The :meth:`~PasswordHash.encrypt`, :meth:`~PasswordHash.identify`, and :meth:`~PasswordHash.verify` methods are designed
+to provide an easy interface for applications. They allow encrypt new passwords
+without having to deal with details such as salt generation, verifying
+passwords without having to deal with hash comparison rules, and determining
+which scheme a hash belongs to when multiple schemes are in use.
+
+.. classmethod:: PasswordHash.encrypt(secret, \*\*settings_and_context)
 
     encrypt secret, returning resulting hash string.
 
@@ -115,12 +162,12 @@ as salt formats.
         but the common case is to encode into utf-8
         before processing.
 
-    :param kwds:
+    :param settings_and_context:
         All other keywords are algorithm-specified,
-        and should be listed in :attr:`setting_kwds`
-        and :attr:`context_kwds`.
+        and should be listed in :attr:`~PasswordHash.setting_kwds`
+        and :attr:`~PasswordHash.context_kwds`.
 
-        Common keywords include ``salt`` and ``rounds``.
+        Common settings keywords include ``salt`` and ``rounds``.
 
     :raises ValueError:
         * if settings are invalid and not correctable.
@@ -134,9 +181,9 @@ as salt formats.
           on the types of characters.
 
     :returns:
-        Hash encoded in algorithm-specified format.
+        Hash string, encoded in algorithm-specific format.
 
-.. function:: identify(hash)
+.. classmethod:: PasswordHash.identify(hash)
 
     identify if a hash string belongs to this algorithm.
 
@@ -150,11 +197,12 @@ as salt formats.
         * ``False`` if none of the above conditions was met.
 
     .. note::
+
         Some handlers may or may not return ``True`` for malformed hashes.
-        Those that do will raise a ValueError once the hash is passed to :func:`verify`.
+        Those that do will raise a ValueError once the hash is passed to :meth:`~PasswordHash.verify`.
         Most handlers, however, will just return ``False``.
 
-.. function:: verify(secret, hash, \*\*context)
+.. classmethod:: PasswordHash.verify(secret, hash, \*\*context)
 
     verify a secret against an existing hash.
 
@@ -169,7 +217,7 @@ as salt formats.
     :param context:
         Any additional keywords will be passed to the encrypt
         method. These should be limited to those listed
-        in :attr:`context_kwds`.
+        in :attr:`~PasswordHash.context_kwds`.
 
     :raises TypeError:
         * if the secret is not a string.
@@ -177,21 +225,24 @@ as salt formats.
     :raises ValueError:
         * if the hash not specified
         * if the hash does not match this algorithm's hash format
-        * if the provided secret contains forbidden chars (see :func:`encrypt`)
+        * if the provided secret contains forbidden characters (see :meth:`~PasswordHash.encrypt`)
 
     :returns:
         ``True`` if the secret matches, otherwise ``False``.
 
-Secondary Interface
-===================
+.. _crypt-interface:
+
+Crypt Interface
+===============
 While the primary interface is generally the most useful when integrating
 password support into an application, those methods are for the most part
-built on top of the secondary interface, which is somewhat simpler
+built on top of the crypt interface, which is somewhat simpler
 for *implementing* new password schemes. It also happens to match
 more closely with the crypt api of most unix systems,
-and consists of two functions: ``genconfig()`` and ``genhash``.
+and consists of two functions: :meth:`~PasswordHash.genconfig()``
+and :meth:`~PasswordHash.genhash()``.
 
-.. function:: genconfig(\*\*settings)
+.. classmethod:: PasswordHash.genconfig(\*\*settings)
 
     returns configuration string encoding settings for hash generation
 
@@ -203,7 +254,7 @@ and consists of two functions: ``genconfig()`` and ``genhash``.
     than just a salt).
 
     This function takes in optional configuration options (a complete list
-    of which should be found in :attr:`setting_kwds`), validates
+    of which should be found in :attr:`~PasswordHash.setting_kwds`), validates
     the inputs, fills in defaults where appropriate, and returns
     a configuration string.
 
@@ -229,7 +280,7 @@ and consists of two functions: ``genconfig()`` and ``genhash``.
       be clipped but accepted.
 
     :param settings:
-        this function takes in keywords as specified in :attr:`setting_kwds`.
+        this function takes in keywords as specified in :attr:`~PasswordHash.setting_kwds`.
         commonly supported keywords include ``salt`` and ``rounds``.
 
     :raises ValueError:
@@ -242,7 +293,7 @@ and consists of two functions: ``genconfig()`` and ``genhash``.
     :returns:
         the configuration string, or ``None`` if the algorithm does not support any configuration options.
 
-.. function:: genhash(secret, config, \*\*context)
+.. classmethod:: PasswordHash.genhash(secret, config, \*\*context)
 
     encrypt secret to hash
 
@@ -254,13 +305,13 @@ and consists of two functions: ``genconfig()`` and ``genhash``.
     :arg config:
         configuration string to use when encrypting secret.
         this can either be an existing hash that was previously
-        returned by :meth:`genhash`, or a configuration string
-        that was previously created by :meth:`genconfig`.
+        returned by :meth:`~PasswordHash.genhash`, or a configuration string
+        that was previously created by :meth:`~PasswordHash.genconfig`.
 
     :param context:
         All other keywords must be external contextual information
         required by the algorithm to create the hash. If any,
-        these kwds must be specified in :attr:`context_kwds`.
+        these kwds must be specified in :attr:`~PasswordHash.context_kwds`.
 
     :raises TypeError:
         * if the configuration string is not provided
@@ -277,56 +328,68 @@ and consists of two functions: ``genconfig()`` and ``genhash``.
 Optional Informational Attributes
 =================================
 Many of the handlers in passlib expose the following informational
-attributes, though their presence and meaning is not uniform
+attributes, though their presence is not uniform
 across all handlers in passlib.
 
-For schemes which support a variable number of rounds,
-the following attributes are usually exposed
-(applications can test by checking for ``getattr(handler,"default_rounds",None)>0``):
+.. todo::
 
-.. attribute:: default_rounds
+    could change these to be required if the appropriate setting kwd is used.
+
+Rounds Information
+------------------
+For schemes which support a variable number of rounds (ie, ``'rounds' in PasswordHash.setting_kwds``),
+the following attributes are usually exposed.
+(Applications can test for this suites' presence by checking if ``getattr(handler,"max_rounds",None)>0``)
+
+.. attribute:: PasswordHash.default_rounds
 
     The default number of rounds that will be used if not
-    explicitly set when calling :func:`encrypt` or :func:`genconfig`.
+    explicitly set when calling :meth:`~PasswordHash.encrypt` or :meth:`~PasswordHash.genconfig`.
 
-.. attribute:: min_rounds
+.. attribute:: PasswordHash.min_rounds
 
     The minimum number of rounds the scheme allows.
     Specifying values below this will generally result
-    in a warning, and ``min_rounds`` will be used instead.
+    in a warning, and :attr:`~!PasswordHash.min_rounds` will be used instead.
 
-.. attribute:: max_rounds
+.. attribute:: PasswordHash.max_rounds
 
     The maximum number of rounds the scheme allows.
     Specifying values above this will generally result
-    in a warning, and ``max_rounds`` will be used instead.
+    in a warning, and :attr:`~!PasswordHash.max_rounds` will be used instead.
 
-.. attribute:: rounds_cost
+.. attribute:: PasswordHash.rounds_cost
 
     Specifies how the rounds value affects the amount of time taken.
     Currently used values are:
 
-    ``linear`` - time taken scales linearly with rounds value (eg: sha512_crypt)
-    ``log2`` - time taken scales exponentially with rounds value (eg: bcrypt)
+    ``linear``
+        time taken scales linearly with rounds value (eg: :class:`~passlib.hash.sha512_crypt`)
+
+    ``log2``
+        time taken scales exponentially with rounds value (eg: :class:`~passlib.hash.bcrypt`)
 
-For schemes which support a salt,
-the following attributes are usually exposed
-(applications can test by checking for ``getattr(handler,"max_salt_chars",None)>0``):
+Salt Information
+----------------
+For schemes which support a salt (ie, ``'salt' in PasswordHash.setting_kwds``),
+the following attributes are usually exposed.
+(Applications can test for this suites' presence by checking if ``getattr(handler,"max_salt_chars",None)>0``)
 
-.. attribute:: max_salt_chars
+.. attribute:: PasswordHash.max_salt_chars
 
     maximum number of characters which will be *used*
-    if a salt string is provided to :func:`genconfig` or :func:`encrypt`.
+    if a salt string is provided to :meth:`~PasswordHash.genconfig` or :meth:`~PasswordHash.encrypt`.
     must be positive integer if salts are supported,
     may be ``None`` or ``0`` if salts are not supported.
 
-.. attribute:: min_salt_chars
+.. attribute:: PasswordHash.min_salt_chars
 
     minimum number of characters required in salt string,
-    if provided to :func:`genconfig` or :func:`encrypt`.
-    must be non-negative integer.
+    if provided to :meth:`~PasswordHash.genconfig` or :meth:`~PasswordHash.encrypt`.
+    must be non-negative integer that is not greater than :attr:`~PasswordHash.max_salt_chars`.
 
-.. attribute:: salt_charset
+.. attribute:: PasswordHash.salt_charset
 
     string containing list of all characters which are allowed
-    to be specified in salt parameter. usually `passlib.utils.h64.CHARS`.
+    to be specified in salt parameter.
+    for most hashes, this is equal to `passlib.utils.h64.CHARS`.
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
deleted file mode 100644
index 3ea0295..0000000
--- a/docs/quickstart.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-========================================
-:mod:`passlib` - Quick Start
-========================================
-
-.. currentmodule:: passlib
-
-Usage Example
-=============
-In order to get off the ground quickly, here's an
-example of how to quickly encrypt and verify passwords
-without having to delve too deeply into this module::
-
-    >>> from bps.security import pwhash
-
-    >>> #encrypt password using strongest algorithm defined by this module
-    >>> hash = pwhash.encrypt("too many secrets")
-    >>> hash
-    $6$rounds=39000$DNnCxm85LEP1WXUh$IVkALQeSuhr2hcUV90Tv8forzli3K.XwX.1JzPjgwltgvCAgllN3x1jNpG9E1C8IQPm0gEIesqATDyKh/nEnh0'
-
-    >>> #verify password against hash
-    >>> pwhash.verify("mypass", hash)
-    False
-    >>> pwhash.verify("too many secrets", hash)
-    True
-
-    >>> #identify the algorithm used in a hash
-    >>> pwhash.identify(hash)
-    'sha512-crypt'
-
-    >>> #choose a specific algorithm to use (instead of the default)
-    >>> hash2 = pwhash.encrypt("too many secrets", alg="bcrypt")
-    '$2a$11$unZuTsMEjeo5mqFX6rmRduQPBDx9t3djd2voi9W.oFhUDQu1NNMcW'
-
-    >>> #check if we used right algorithm
-    >>> pwhash.identify(hash2)
-    'bcrypt'
-
-    >>> #the hash type is autodetected by verify
-    >>> pwhash.verify("too many secrets", hash2)
-    True
-
-Frontend Functions
-==================
-.. function:: encrypt
-.. function:: verify
-.. function:: identify