CryptContext documentation: split interface listing to separate file; added large amount of integration example code

4 files changed, 224 insertions, 16 deletions

diff --git a/docs/lib/passlib.context-interface.rst b/docs/lib/passlib.context-interface.rst
new file mode 100644
index 0000000..372dd98
--- /dev/null
+++ b/docs/lib/passlib.context-interface.rst
@@ -0,0 +1,22 @@
+.. index:: CryptContext; interface
+
+.. _cryptcontext-interface:
+
+===============================================
+:mod:`passlib.context` - CryptContext Interface
+===============================================
+
+.. currentmodule:: passlib.context
+
+This details all the constructors and methods provided by :class:`!CryptContext`
+and :class:`!CryptPolicy`.
+
+.. seealso::
+
+    * :doc:`passlib.context-options` -- for a list of all the keyword options accepted by these classes.
+
+    * :doc:`passlib.context` -- for an overview and some usage examples.
+
+.. autoclass:: CryptContext(schemes=None, policy=<default policy>, \*\*kwds)
+
+.. autoclass:: CryptPolicy(\*\*kwds)
diff --git a/docs/lib/passlib.context-options.rst b/docs/lib/passlib.context-options.rst
index d2202b7..b15dc5d 100644
--- a/docs/lib/passlib.context-options.rst
+++ b/docs/lib/passlib.context-options.rst
@@ -1,5 +1,4 @@
-.. index::
-    single: CryptContext; constructor options
+.. index:: CryptContext; constructor options
 
 .. _cryptcontext-options:
 
@@ -14,6 +13,10 @@ These are divides into the "context options", which affect
 the context instance directly, and the "hash options",
 which affect the context treats a particular type of hash:
 
+.. seealso::
+
+    :doc:`passlib.context` -- for an overview of the classes and some usage examples.
+
 Context Options
 ===============
 The following keyword options are accepted by both the :class:`CryptContext`
@@ -27,9 +30,9 @@ of the :class:`!CryptContext` instance itself:
     For use in INI files, this may also be specified as a single comma-separated string
     of handler names.
 
-    Any names specified must be registered globally with PassLib.
-
-    Example: ``schemes=["sha256_crypt", "md5_crypt", "des_crypt"]``.
+    Potential names can include the name of any class importable from the :mod:`passlib.hash` module.
+    For example, to specify the :class:`passlib.hash.sha256_crypt` and the :class:`passlib.hash.des_crypt` schemes
+    should be supported for your new context, set ``schemes=["sha256_crypt", "des_crypt"]``.
 
 ``deprecated``
 
@@ -49,6 +52,7 @@ of the :class:`!CryptContext` instance itself:
 
     Specifies the name of the default handler to use when encrypting a new password.
     If no default is specified, the first handler listed in ``schemes`` will be used.
+    Any name specified *must* be in the list of supported schemes (see the ``schemes`` kwd).
 
     Example: ``default="sha256_crypt"``.
 
@@ -203,7 +207,7 @@ A sample policy file::
     bcrypt.min_rounds = 10
 
     #create a "admin" category, which uses bcrypt by default, and has stronger hashes
-    admin.context.fallback = bcrypt
+    admin.context.default = bcrypt
     admin.sha512_crypt.min_rounds = 100000
     admin.bcrypt.min_rounds = 13
 
@@ -224,7 +228,7 @@ And the equivalent as a set of python keyword options::
         bcrypt__min_rounds = 10,
 
         #create a "admin" category, which uses bcrypt by default, and has stronger hashes
-        admin__context__fallback = bcrypt
+        admin__context__default = bcrypt
         admin__sha512_crypt__min_rounds = 100000
         admin__bcrypt__min_rounds = 13
     )
diff --git a/docs/lib/passlib.context.rst b/docs/lib/passlib.context.rst
index 13cbde8..036af13 100644
--- a/docs/lib/passlib.context.rst
+++ b/docs/lib/passlib.context.rst
@@ -1,3 +1,7 @@
+.. index:: CryptContext; usage examples, CryptContext; overview
+
+.. _cryptcontext-overview:
+
 ==============================================
 :mod:`passlib.context` - CryptContext Overview
 ==============================================
@@ -21,8 +25,17 @@ about which ones are deprecated, which is the default,
 and what configuration constraints an application has placed
 on a particular hash.
 
-Usage
-=====
+.. seealso::
+
+    * :doc:`passlib.context-interface` -- for a list of all class and instance methods
+
+    * :doc:`passlib.context-options` -- for a list of all the keyword options accepted by these classes.
+
+Usage Examples
+==============
+
+Basic Usage
+-----------
 To start off with a simple example of how to create and use a CryptContext::
 
     >>> from passlib.context import CryptContext
@@ -59,6 +72,8 @@ To start off with a simple example of how to create and use a CryptContext::
     >>> myctx.identify(hash1, resolve=True)
     <class 'passlib.handlers.md5_crypt.md5_crypt'>
 
+Policy Examination
+------------------
 If introspection of a :class:`!CryptContext` instance
 is needed, all configuration options are stored in a :class:`CryptPolicy` instance accessible through
 their ``policy`` attribute::
@@ -74,12 +89,176 @@ their ``policy`` attribute::
     >>> myctx.policy.get_handler()
     <class 'passlib.handlers.md5_crypt.md5_crypt'>
 
-Interface
-=========
-This details the constructors and methods provided by :class:`!CryptContext`
-and :class:`!CryptPolicy`. A list of all the keyword options accepted by these classes is listed separately
-in :doc:`passlib.context-options`.
+Full Integration
+----------------
+The following is an extended example of how PassLib can be integrated into an existing
+application to provide runtime policy changes, deprecated hash migration,
+and other features. This is example uses a lot of different features,
+and many developers will want to pick and choose what they need from this example.
+
+Policy Options File
+...................
+Instead of creating a CryptContext instance manually,
+or importing an existing one (eg :data:`~passlib.apps.custom_app_context`),
+applications with advanced policy requirements may want to create a hash policy file
+(options show below are detailed in :ref:`cryptcontext-options`)::
+
+    ; the options file uses the INI file format,
+    ; and passlib will only read the section named "passlib",
+    ; so it can be included along with other application configuration.
+
+    [passlib]
+
+    ;setup the context to support pbkdf2_sha1, along with legacy md5_crypt hashes:
+    schemes = pbkdf2_sha1, md5_crypt
+
+    ;flag md5_crypt as deprecated
+    ;   (existing md5_crypt hashes will be flagged as needs-updating)
+    deprecated = md5_crypt
+
+    ;set verify to always take at least 1/10th of a second
+    min_verify_time = 0.1
+
+    ;set boundaries for pbkdf2 rounds parameter
+    ;   (pbkdf2 hashes outside this range will be flagged as needs-updating)
+    pbkdf2_sha1.min_rounds = 10000
+    pbkdf2_sha1.max_rounds = 50000
+
+    ;set the default rounds to use when encrypting new passwords.
+    ;the 'vary' field will cause each new hash to randomly vary
+    ;from the default by the specified %.
+    pbkdf2_sha1.default_rounds = 20000
+    pbkdf2_sha1.vary_rounds = 10%
+
+    ;applications can choose to treat certain user accounts differently,
+    ;by assigning different types of account to a 'user category',
+    ;and setting special policy options for that category.
+    ;this create a category named 'admin', which will have a larger default rounds value.
+    admin.pbkdf2_sha1.min_rounds = 40000
+    admin.pbkdf2_sha1.default_rounds = 50000
+
+Integrating a CryptContext
+--------------------------
+Integrating a crypt context is merely a matter of adding the following
+bits of code to your application.
+
+1. Within a common module in your application (eg ``myapp.model.security``)::
+
+        #
+        #create a crypt context that can be imported and used wherever is needed...
+        #the instance will be configured later.
+        #
+        from passlib.context import CryptContext
+        user_pwd_context = CryptContext()
+
+2. Within some startup function within your application::
+
+        #
+        #when the app starts, import the context from step 1 and
+        #configure it... such as by loading a policy file (see above)
+        #
+
+        from myapp.model.security import user_pwd_context
+        from passlib.context import CryptPolicy
+
+        def myapp_startup():
+
+            #
+            # ... other code ...
+            #
+
+            user_pwd_context.policy = CryptPolicy.from_path(path_to_policy_file)
+
+            #
+            #if you want to reconfigure the context without restarting the application,
+            #simply repeat the above step at another point.
+            #
+
+            #
+            # ... other code ...
+            #
+
+
+3. When it comes time to create a new user's password, insert
+   the following code in the correct function::
+
+
+        from myapp.model.security import user_pwd_context
+
+        def handle_user_creation():
+
+            #
+            # ... other code ...
+            #
+
+            #
+            #   'secret' containing the putative password
+            #   'category' containing a category assigned to the user account
+            #
+            #the 'category' kwd can be omitted, OR:
+            #set to a string matching a user category specified in the policy file,
+            #in which case the category-specific policy settings will be enforced.
+            #for this example, assume it's None for most users, and "admin" for special users.
+            #this namespace is entirely application chosen, it just has to match the policy file.
+            #
+
+            hash = user_pwd_context.encrypt(secret, category=category)
+
+            #... perform appropriate actions to store hash...
+
+            #
+            # ... other code ...
+            #
+
+4. Finally, when it comes time to check a users' password, insert
+   the following code at the correct place::
+
+        from myapp.model.security import user_pwd_context
+
+        def handle_user_login():
+
+            #
+            # ... other code ...
+            #
+
+            #
+            #this example both checks the user's password AND upgrades deprecated hashes...
+            #given the following variables:
+            #   'hash' containing the specified user's hash,
+            #   'secret' containing the putative password
+            #   'category' containing a category assigned to the user account
+            #
+            #see note in step 3 about the category kwd
+            #
+
+
+            ok, new_hash = user_pwd_context.verify_and_update(secret, hash, category=category)
+            if not ok:
+                #... password did not match. do mean things ...
+            else:
+                #... password matched ...
+
+                if new_hash:
+                    # old hash was deprecated by policy.
+
+                    # ... replace hash w/ new_hash for user account ...
+
+                #... do successful login actions ...
+
+   For those who don't want to use any of the hash update features,
+   the following template can be used instead::
+
+        from myapp.model.security import user_pwd_context
+
+        def handle_user_login():
 
-.. autoclass:: CryptContext(schemes=None, policy=<default policy>, \*\*kwds)
+            #
+            # ... other code ...
+            #
 
-.. autoclass:: CryptPolicy(\*\*kwds)
+            ok = user_pwd_context.verify(secret, hash, category=category)
+            if not ok:
+                #... password did not match. do mean things ...
+            else:
+                #... password matched ...
+                #... do successful login actions ...
diff --git a/docs/lib/passlib.utils.rst b/docs/lib/passlib.utils.rst
index 616ef52..486b447 100644
--- a/docs/lib/passlib.utils.rst
+++ b/docs/lib/passlib.utils.rst
@@ -20,6 +20,9 @@ String Manipulation
 Bytes Manipulation
 ==================
 
+.. autofunction:: adapted_b64_encode
+.. autofunction:: adapted_b64_decode
+
 .. autofunction:: bytes_to_int
 .. autofunction:: int_to_bytes
 .. autofunction:: list_to_bytes