major work on policy system

===========================
* added documentation detailing policy system's keys and functionality
* split policy-related code out of CryptContext into CryptPolicy object
* added 'category' kwd to all relevant CryptContext methods
* implemented parsing & introspection methods for CryptPolicy
* added rounds management to CryptContext, per policy specification

* attempt at documenting passlib.unix (incomplete)

TODO
----
* ability to create composite CryptPolicy objects
* per-hash handling of policy compliance checks
* UTs for policy system

3 files changed, 182 insertions, 31 deletions

diff --git a/docs/lib/passlib.base.rst b/docs/lib/passlib.base.rst
index aa463f9..688df2d 100644
--- a/docs/lib/passlib.base.rst
+++ b/docs/lib/passlib.base.rst
@@ -1,8 +1,8 @@
 =============================================
-:mod:`passlib` - Crypt Contexts
+:mod:`passlib.base` - Crypt Contexts
 =============================================
 
-.. currentmodule:: passlib
+.. currentmodule:: passlib.base
 
 For more complex deployment scenarios than
 the frontend functions described in :doc:`Quick Start <quickstart>`,
@@ -10,26 +10,150 @@ the CryptContext class exists...
 
 .. autoclass:: CryptContext
 
-Predefined Contexts
-===================
-The following context objects are predefined by BPS:
+Context Configuration Policy
+============================
+.. warning::
 
-.. data:: default_context
+    This section's writing and design are still very much in flux.
 
-    This context object contains all the algorithms
-    supported by BPS, listed (mostly) in order of strength.
-    :func:`identify`, :func:`verify`, and :func:`encrypt`
-    are all merely wrappers for this object's methods
-    of the same name.
+Each CryptContext instance is extremely configuration through a wide range
+of options. All of these options can be specified via the CryptContext
+constructor, or by loading the configuration of a section of an ini file
+(allowing an application's password policy to be specified externally).
 
-.. data:: linux_context
+All configuration options are stored in a CryptPolicy object,
+which can be created in the following ways:
 
-    This context object contains only the algorithms
-    in use on modern linux systems (namely:
-    unix-crypt, md5-crypt, sha512-crypt).
+* passing in options as keywords to it's constructor
+* loading options from a section of a :mod:`ConfigParser` ini file.
+* compositing together existing CryptPolicy objects (this allows for default policies, application policies, and run-time policies)
 
-.. data:: bsd_context
+Hash Configuration Options
+==========================
+Options for configuring a specific hash take the form of the name of
+``{name}.{option}`` (eg ``sha512_crypt.default_rounds``); where ``{name}`` is usually the name of a password hash,
+and ``{option}`` is one of the options specified below.
+There are a few reserved hash names:
+Any options of the form ``default.{option}`` will be inherited by ALL hashes
+if they do not have a ``{hash}.{option}`` value overriding the default.
+Any options of the form ``context.{option}`` will be treated as options for the context object itself,
+and not for a specified hash. Any options of the form ``{option}`` are taken to implicitly
+belong to the context, and are treated as if they started with the prefix ``context.``.
+The remaining options -
 
-    This context object contains only the algorithms
-    in use on modern BSD systems (namely:
-    unix-crypt, md5-crypt, bcrypt).
+``context.schemes``
+    comma separated list of the schemes this context should recognize, specified by name.
+    when a context is identifying hashes, it will check each scheme in this list
+    in reverse order. if this value is being specified programmatically,
+    it may also be a python list containing a mixture of names
+    and password hash handler objects.
+
+``context.deprecated``
+    comma separated list of the schemes which this context should recognize,
+    generated hashes only if explicitly requested, and for which ``context.is_compliant()`` should return ``False``.
+    if not specified, none are considered deprecated.
+    this must be a subset of the names listed in context.schemes
+
+``context.fallback``
+    the default scheme context should use for generating new hashes.
+    if not specified, the last entry in ``context/schemes`` is used.
+
+``{hash}.min_rounds``, ``{hash}.max_rounds``
+
+    place limits on the number of rounds allowed for a specific hash.
+
+    * these are configurable per-context limits, hard limits set by algorithm are always applied
+    * if min > max, max will be increased to equal min.
+    * ``context.genconfig()`` or ``config.encrypt()`` - requests outside of these bounds will be clipped.
+    * ``context.is_compliant()`` - existing hashes w/ rounds outside of range are not compliant
+    * for hashes which do not have a rounds parameter, these values are ignored.
+
+``{hash}.default_rounds``
+
+    sets the default number of rounds to use when generating new hashes.
+
+    * if this value is out side of per-policy min/max, it will be clipped just like user provided value.
+    * ``context.genconfig()`` or ``config.encrypt()`` - if rounds are not provided explicitly, this value will be used.
+    * for hashes which do not have a rounds parameter, this value is ignored.
+    * if not specified, max_rounds is used if available, then min_rounds, then the algorithm default.
+
+``{hash}.vary_default_rounds``
+
+    [only applies if ``{hash}.default_rounds`` is specified and > 0]
+
+    if specified, every time a new hash is created using {hash}/default_rounds for it's rounds value,
+    the actual value used is generated at random, using default_rounds as a hint.
+
+    * integer value - a value will be chosen using the formula ``randint(default_rounds-vary_default_rounds, default_rounds+vary_default_rounds)``.
+    * integer value between 0 and 100 with ``%`` suffix - same as above, with integer value equal to ``vary_default_rounds*default_rounds/100``.
+    * note that if algorithms indicate they use a logarthmic rounds parameter, the percent syntax equation uses ``log(vary_default_rounds*(2**default_rounds)/100,2)``,
+      to permit a default value to be applicable to all schemes. XXX: this might be a bad / overly complex idea.
+
+``{hash}.{setting}``
+    any keys which match the name of a configuration parameter accepted by the hash
+    will be used directly as default values.
+
+    * for security purposes, ``salt`` is *forbidden* from being used in this way.
+    * if ``rounds`` is specified directly, it will override the entire min/max/default_rounds framework.
+
+``{hash}.{other}``
+    any keys which do not fall under the above categories will be ignored
+
+User Categories
+===============
+One frequent need is for certain categories of users (eg the root account)
+to have more strigent password requirements than default users.
+PassLib allows this by recognizing options of the format ``{category}.{name}.{option}``,
+and allowing many of it's entry methods to accept an optional ``category`` parameter.
+
+When one is specified, any ``{category}.{name}.{option}`` keywords in the configuration
+will override any ``{name}.{option}`` keywords.
+
+In order to simplify behavior and implementation, categories cannot override the ``context/{option}`` keys.
+
+Default Policies
+================
+PassLib defines a library-default policy, updated perodically, providing (hopefully) sensible defaults for the various contexts.
+When a new CryptContext is created, a policy is generated from it's constructor arguments, which is then composited
+over the library-default policy. You may optionally override the default policy used by overriding the ``policy`` keyword
+of CryptContext. This keyword accepts a single CryptPolicy object or string (which will be treated as an ini file to load);
+it also accepts a list of CryptPolicys and/or strings, which will be composited together along with any constructor options.
+
+Sample Policy File
+==================
+A sample policy file::
+
+    [passlib]
+    #configure what schemes the context supports (note the "context." prefix is implied for these keys)
+    schemes = md5_crypt, sha512_crypt, bcrypt
+    deprecated = md5_crypt
+    fallback = sha512_crypt
+
+    #set some common options for ALL schemes
+    default.vary_default_rounds = 10%
+
+    #setup some hash-specific defaults
+    sha512_crypt.min_rounds = 40000
+    bcrypt.min_rounds = 10
+
+    #create a "root" category, which uses bcrypt by default, and has stronger hashes
+    root.context.fallback = bcrypt
+    root.sha512_crypt.min_rounds = 100000
+    root.bcrypt.min_rounds = 13
+
+.. class:: CryptPolicy
+
+    Stores configuration options for a CryptContext object.
+
+    Construction
+    ------------
+    Policy objects can be constructed by the following methods:
+
+    .. automethod:: from_file
+
+    .. method:: CryptPolicy
+
+        You can specify options directly to the constructor.
+        This accepts dot-seperated keywords such as found in the config file format,
+        but for programmatic convience, it also accepts keys with ``.`` replaced with ``__``,
+        allowing options to be specified programmatically in python.
diff --git a/docs/lib/passlib.unix.rst b/docs/lib/passlib.unix.rst
index 9acf867..254a8f7 100644
--- a/docs/lib/passlib.unix.rst
+++ b/docs/lib/passlib.unix.rst
@@ -1,9 +1,46 @@
 ============================================
-:mod:`passlib.unix` - Password Hash Schemes
+:mod:`passlib.unix` - Unix Password Frontend
 ============================================
 
 .. module:: passlib.unix
-    :synopsis: helpers for encrypting & verifying passwords on unix systems
+    :synopsis: frontend for encrypting & verifying passwords on unix systems
+
+Contexts
+========
+This module provides some pre-configured :class:`CryptContext` instances,
+tailor to the hashes supported on various unix systems.
+
+.. object:: linux_context
+
+    this should recognize the hashes used on most linux systems:
+    :mod:`~passlib.hash.des_crypt`,
+    :mod:`~passlib.hash.md5_crypt`,
+    :mod:`~passlib.hash.sha256_crypt`, and
+    :mod:`~passlib.hash.sha512_crypt` (used as the default).
+
+.. object:: bsd_context
+
+    this should recognize the hashes used on most bsd systems:
+    :mod:`~passlib.hash.des_crypt`,
+    :mod:`~passlib.hash.ext_des_crypt`,
+    :mod:`~passlib.hash.nthash`,
+    :mod:`~passlib.hash.md5_crypt`,
+    :mod:`~passlib.hash.bcrypt` (used as the default).
+
+.. note::
+
+    The above contexts will also recognize password hashes
+    of the form ``!`` or ``*`` as belonging to a special
+    ``unix-disabled`` handler, whose ``verify()`` method
+    always returns ``False``.
+
+Usage
+=====
+
+.. todo::
+
+    show usage example
+
 
 .. _modular-crypt-format:
 
diff --git a/docs/notes.txt b/docs/notes.txt
index 0ff1376..9137e4d 100644
--- a/docs/notes.txt
+++ b/docs/notes.txt
@@ -165,16 +165,6 @@ info about upgrade policy scheme, and sun-md5 ref...
 some sample hashes all using "passwd", including sunmd5
     http://compgroups.net/comp.unix.solaris/password-file-in-linux-and-solaris-8-9
 
-nt-hash
-    md4.new(passwd.encode('utf-16le')).hexdigest().upper()
-
-    mygreatpasswd
-    CFACF72F5EB60EA15F89E3AF66732545
-
-    http://www.faqs.org/rfcs/rfc1320.html
-
-    $3$hash
-
 references for hashes & passwords
     http://cpansearch.perl.org/src/CHANSEN/Authen-Simple-0.4/lib/Authen/Simple/Password.pm
     http://search.cpan.org/~zefram/Authen-Passphrase-0.007/lib/Authen/Passphrase.pm