updated docs

24 files changed, 413 insertions, 114 deletions

diff --git a/docs/lib/passlib.hash/algorithms.rst b/docs/lib/_scratch1.rst
index 4c00293..4c00293 100644
--- a/docs/lib/passlib.hash/algorithms.rst
+++ b/docs/lib/_scratch1.rst
diff --git a/docs/lib/passlib.hash/implementation.rst b/docs/lib/_scratch2.rst
index d80ac56..d80ac56 100644
--- a/docs/lib/passlib.hash/implementation.rst
+++ b/docs/lib/_scratch2.rst
diff --git a/docs/lib/passlib.hash/contexts.rst b/docs/lib/passlib.base.rst
index aa463f9..aa463f9 100644
--- a/docs/lib/passlib.hash/contexts.rst
+++ b/docs/lib/passlib.base.rst
diff --git a/docs/lib/passlib.gen.rst b/docs/lib/passlib.gen.rst
deleted file mode 100644
index b8778e9..0000000
--- a/docs/lib/passlib.gen.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-================================================
-:mod:`passlib.gen` -- Password Generation
-================================================
-
-.. module:: passlib.gen
-    :synopsis: password generation algorithms
-
-The following single function allows
-easy password generation in a number of styles:
-
-.. autofunction:: generate_secret
-
-.. todo::
-    document internal classes
diff --git a/docs/lib/passlib.hash.apr_md5_crypt.rst b/docs/lib/passlib.hash.apr_md5_crypt.rst
new file mode 100644
index 0000000..272c08d
--- /dev/null
+++ b/docs/lib/passlib.hash.apr_md5_crypt.rst
@@ -0,0 +1,24 @@
+=============================================================
+:mod:`passlib.hash.apr_md5_crypt` - Apache MD5-Crypt Variant
+=============================================================
+
+.. module:: passlib.hash.apr_md5_crypt
+    :synopsis: Apache MD5 Crypt
+
+Stats: 96 bit checksum, 48 bit salt, :ref:`modular-crypt-format` compatible.
+
+This format is a variation of :mod:`~passlib.hash.md5_crypt`,
+primarily used by the Apache webserver in ``htpasswd`` files.
+
+This format is identical to md5-crypt, except for two things:
+it uses ``$apr1$`` as a prefix where md5-crypt uses ``$1$``,
+and inserts ``$apr1$`` where md5-crypt inserts ``$1$`` into
+it's internal hash calculation. Thus, this algorithm is just
+as strong as md5-crypt, but the formats (and their contained checksums)
+are in no way compatible with eachother.
+
+Implementation
+==============
+PassLib contains a builtin pure-python implementation of apr-md5-crypt,
+based of the specification at `http://httpd.apache.org/docs/2.2/misc/password_encryptions.html`,
+but code shared with :mod:`~passlib.hash.md5_crypt`.
diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
new file mode 100644
index 0000000..0b22e07
--- /dev/null
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -0,0 +1,10 @@
+==================================================================
+:mod:`passlib.hash.bcrypt` - BCrypt
+==================================================================
+
+.. module:: passlib.hash.bcrypt
+    :synopsis: implementation of blowfish-based BCrypt scheme
+
+.. todo::
+
+    write documentation
diff --git a/docs/lib/passlib.hash.des_crypt.rst b/docs/lib/passlib.hash.des_crypt.rst
new file mode 100644
index 0000000..6b7e195
--- /dev/null
+++ b/docs/lib/passlib.hash.des_crypt.rst
@@ -0,0 +1,10 @@
+========================================================
+:mod:`passlib.hash.des_crypt` - Unix (DES) Crypt
+========================================================
+
+.. module:: passlib.hash.des_crypt
+    :synopsis: implementation of original unix-crypt / des-crypt scheme
+
+.. todo::
+
+    write documentation
diff --git a/docs/lib/passlib.hash.ext_des_crypt.rst b/docs/lib/passlib.hash.ext_des_crypt.rst
new file mode 100644
index 0000000..35da109
--- /dev/null
+++ b/docs/lib/passlib.hash.ext_des_crypt.rst
@@ -0,0 +1,10 @@
+==================================================================
+:mod:`passlib.hash.ext_des_crypt` - BSDi Extended Unix (DES) Crypt
+==================================================================
+
+.. module:: passlib.hash.ext_des_crypt
+    :synopsis: implementation of BSDi extended unix/des crypt scheme
+
+.. todo::
+
+    write documentation
diff --git a/docs/lib/passlib.hash.md5_crypt.rst b/docs/lib/passlib.hash.md5_crypt.rst
new file mode 100644
index 0000000..78fe3f3
--- /dev/null
+++ b/docs/lib/passlib.hash.md5_crypt.rst
@@ -0,0 +1,10 @@
+==================================================================
+:mod:`passlib.hash.md5_crypt` - MD5-Crypt
+==================================================================
+
+.. module:: passlib.hash.md5_crypt
+    :synopsis: implementation of MD5-Crypt scheme
+
+.. todo::
+
+    write documentation
diff --git a/docs/lib/passlib.hash.myql_323.rst b/docs/lib/passlib.hash.myql_323.rst
new file mode 100644
index 0000000..6bb1467
--- /dev/null
+++ b/docs/lib/passlib.hash.myql_323.rst
@@ -0,0 +1,10 @@
+==================================================================
+:mod:`passlib.hash.mysql_323` - MySQL 3.2.3 "OLD_PASSWORD" Scheme
+==================================================================
+
+.. module:: passlib.hash.mysql_323
+    :synopsis: MySQL 3.2.3 "OLD_PASSWORD" scheme
+
+.. todo::
+
+    write documentation
diff --git a/docs/lib/passlib.hash.mysql_41.rst b/docs/lib/passlib.hash.mysql_41.rst
new file mode 100644
index 0000000..3665ebf
--- /dev/null
+++ b/docs/lib/passlib.hash.mysql_41.rst
@@ -0,0 +1,10 @@
+==================================================================
+:mod:`passlib.hash.mysql_41` - MySQL 4.1 "NEW_PASSWORD" Scheme
+==================================================================
+
+.. module:: passlib.hash.mysql_41
+    :synopsis: MySQL 4.1 "NEW_PASSWORD" scheme
+
+.. todo::
+
+    write documentation
diff --git a/docs/lib/passlib.hash.postgres_md5.rst b/docs/lib/passlib.hash.postgres_md5.rst
new file mode 100644
index 0000000..0b75dd5
--- /dev/null
+++ b/docs/lib/passlib.hash.postgres_md5.rst
@@ -0,0 +1,33 @@
+==================================================================
+:mod:`passlib.hash.postgres_md5` - Postgres MD5 password hash
+==================================================================
+
+.. module:: passlib.hash.mysql_md5
+    :synopsis: Postgres MD5 password hash
+
+Stats: 512 bit checksum, username used as salt
+
+This implements the md5-based hash algorithm used by Postgres to store
+passwords in the pg_shadow table.
+
+This algorithm shouldn't be used for any purpose besides Postgres interaction,
+it's a weak unsalted algorithm which could be attacked with a rainbow table
+built against common user names.
+
+.. warning::
+    This algorithm is slightly different from most of the others,
+    in that both encrypt() and verify() require you pass in
+    the name of the user account via the required 'user' keyword,
+    since postgres uses this in place of a salt :(
+
+Usage Example::
+
+    >>> from passlib.hash import postgres_md5 as pm
+    >>> pm.encrypt("mypass", user="postgres")
+    'md55fba2ea04fd36069d2574ea71c8efe9d'
+    >>> pm.verify("mypass", 'md55fba2ea04fd36069d2574ea71c8efe9d', user="postgres")
+    True
+
+.. todo::
+
+    find references
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index 621ed0d..313fa2e 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -1,44 +1,66 @@
-=============================================
-:mod:`passlib` - Password Hashing
-=============================================
+============================================
+:mod:`passlib.hash` - Password Hash Schemes
+============================================
 
-.. module:: passlib
-    :synopsis: password hashing (unix-crypt, md5-crypt, etc)
+.. module:: passlib.hash
+    :synopsis: package containing handlers for all builtin password hash schemes
 
 Overview
 ========
-This module handles encrypting and verifying password hashes
-(such as from unix shadow files). This module contains implementations of most
-of the modern password hashing algorithms,
-as well as a complex framework for implementing
-new algorithms, managing hashes generated
-within different contexts with different supported
-algorithms, and other features.
+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::
 
-The algorithms currently supported by default in BPS:
+    >>> from passlib.hash import md5_crypt
+    >>> hash = md5_crypt.encrypt("password")
 
-    * Unix-Crypt
-    * MD5-Crypt
-    * BCrypt
-    * SHA-Crypt (256 & 512 bit modes)
+As well, any third-party handlers registered with passlib via :func:`register_crypt_handler`
+will be inserted into this package.
 
-    * PostgreSQL & MySQL password hashes
+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.
 
-Sections
+Contents
 ========
-The documentation for the pwhash module is broken into the following sections:
-
-* :doc:`Quick Start <passlib/quickstart>` -- frontend funcs for quickly creating / validating hashes
-* :doc:`Crypt Contexts <passlib/contexts>` -- for using just the algorithms your application needs
-* :doc:`Crypt Algorithms <passlib/algorithms>` -- details of the algorithms BPS implements
-* :doc:`Implementing a Custom Crypt Algorithm <passlib/implementation>` -- Roll your own
-* :doc:`Helper Functions <passlib/utils>`
-
-.. toctree::
-    :hidden:
-
-    passlib/quickstart
-    passlib/contexts
-    passlib/algorithms
-    passlib/implementation
-    passlib/utils
+Passlib contains the following builtin password algorithms:
+
+Standard Unix Schemes
+---------------------
+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.
+
+Non-Standard Unix-Compatible Schemes
+------------------------------------
+While few of these schemes were ever used by unix flavors 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.
+
+* :mod:`~passlib.hash.apr_md5_crypt` - Apache-specific variant of md5-crypt, used in htpasswd files
+
+.. todo::
+
+    These aren't fully implemented / tested yet:
+
+    * :mod:`~passlib.hash.nthash` - modular-crypt-format encoding of legacy NTHASH algorithm
+    * :mod:`~passlib.hash.sun_md5_crypt` - MD5-based crypt descendant used by Solaris 10 (NOT related to md5-crypt above).
+
+Other Schemes
+-------------
+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
diff --git a/docs/lib/passlib.hash.sha256_crypt.rst b/docs/lib/passlib.hash.sha256_crypt.rst
new file mode 100644
index 0000000..fbb23b0
--- /dev/null
+++ b/docs/lib/passlib.hash.sha256_crypt.rst
@@ -0,0 +1,10 @@
+==================================================================
+:mod:`passlib.hash.sha256_crypt` - SHA-256 Crypt
+==================================================================
+
+.. module:: passlib.hash.sha526_crypt
+    :synopsis: implementation of SHA-256 Crypt scheme
+
+.. todo::
+
+    write documentation
diff --git a/docs/lib/passlib.hash.sha512_crypt.rst b/docs/lib/passlib.hash.sha512_crypt.rst
new file mode 100644
index 0000000..325d963
--- /dev/null
+++ b/docs/lib/passlib.hash.sha512_crypt.rst
@@ -0,0 +1,16 @@
+==================================================================
+:mod:`passlib.hash.sha512_crypt` - SHA-512 Crypt
+==================================================================
+
+.. module:: passlib.hash.sha526_crypt
+    :synopsis: implementation of SHA-512 Crypt scheme
+
+Defined in the same specification, the SHA-512 Crypt scheme is almost identical to SHA-256 Crypt,
+except for 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'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.
diff --git a/docs/lib/passlib.hash.sun_md5_crypt.rst b/docs/lib/passlib.hash.sun_md5_crypt.rst
new file mode 100644
index 0000000..7db3bc9
--- /dev/null
+++ b/docs/lib/passlib.hash.sun_md5_crypt.rst
@@ -0,0 +1,10 @@
+=============================================================
+:mod:`passlib.hash.sun_md5_crypt` - Sun MD5-Crypt
+=============================================================
+
+.. module:: passlib.hash.sun_md5_crypt
+    :synopsis: Sun MD5 Crypt implementation
+
+.. todo::
+
+    write documentation
diff --git a/docs/lib/passlib.hash/quickstart.rst b/docs/lib/passlib.hash/quickstart.rst
deleted file mode 100644
index c6128f8..0000000
--- a/docs/lib/passlib.hash/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
-==================
-.. autofunction:: encrypt
-.. autofunction:: verify
-.. autofunction:: identify
diff --git a/docs/lib/passlib.hash/utils.rst b/docs/lib/passlib.hash/utils.rst
deleted file mode 100644
index 752e381..0000000
--- a/docs/lib/passlib.hash/utils.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-=============================================
-:mod:`passlib` - Helper Functions
-=============================================
-
-.. currentmodule:: passlib
-
-A couple of utility functions are available,
-mainly useful when writing custom password hash algorithms.
-The ``h64_*`` series of functions all provide
-utilities for encoding & decoding strings
-under the modified base64 system used by most
-of the standard unix hash algorithms.
-
-.. autofunction:: h64_encode
-.. autofunction:: h64_decode
-.. autofunction:: h64_gen_salt
-
-.. autofunction:: is_crypt_context
-.. autofunction:: is_crypt_handler
diff --git a/docs/lib/passlib.unix.rst b/docs/lib/passlib.unix.rst
new file mode 100644
index 0000000..9acf867
--- /dev/null
+++ b/docs/lib/passlib.unix.rst
@@ -0,0 +1,30 @@
+============================================
+:mod:`passlib.unix` - Password Hash Schemes
+============================================
+
+.. module:: passlib.unix
+    :synopsis: helpers for encrypting & verifying passwords on unix systems
+
+.. _modular-crypt-format:
+
+Modular Crypt Format
+====================
+A vast majority of the schemes used on unix systems (and supported by this library)
+follow the "Modular Crypt Format", introduced around the time :mod:`~passlib.hash.md5_crypt` was developed.
+This scheme allows hashes generates by multiple schemes to co-exist within a database,
+by requiring that all hash string begin with a unique prefix ``$identifier$``;
+where ``identifier`` is a short alphanumeric string globally identifying
+hashes generated by that algorithm.
+
+While not part of the specification, most modular crypt -compatible hashes
+were designed to be used by unix systems to store user account passwords
+in ``/etc/passwd`` or ``/etc/shadow``. Because of this, most of them
+follow another defacto limitations: they avoid using the characters
+``:``, ``\n``, and ``\x00`` anywhere in their encoded hash.
+In fact, for the most part they avoid using any characters except
+``a-zA-Z0-9./``, and ``$`` as an internal separator, though
+this can be violated on some systems if the user intervenes.
+
+.. note::
+    :mod:`passlib.hash.des_crypt` and :mod:`passlib.hash.ext_des_crypt`
+    do not follow this protocol, since they predate it by many years.
diff --git a/docs/lib/passlib.utils.des.rst b/docs/lib/passlib.utils.des.rst
new file mode 100644
index 0000000..f50cc95
--- /dev/null
+++ b/docs/lib/passlib.utils.des.rst
@@ -0,0 +1,17 @@
+=============================================
+:mod:`passlib.utils.des` - DES routines
+=============================================
+
+.. module:: passlib.utils.des
+    :synopsis: routines for performing DES encryption
+
+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 :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.h64.rst b/docs/lib/passlib.utils.h64.rst
new file mode 100644
index 0000000..b5f249b
--- /dev/null
+++ b/docs/lib/passlib.utils.h64.rst
@@ -0,0 +1,42 @@
+================================================
+:mod:`passlib.utils.h64` - Hash-64 Codec helpers
+================================================
+
+
+.. module:: passlib.utils.h64
+    :synopsis: Hash-64 Codec helpers
+
+Many of the password hash algorithms in passlib
+use a encoding scheme very similar to (but not compatible with)
+the standard base64 encoding scheme. the main differences are that
+it assigns the characters *completely* different numeric values compared
+to base64, as well as using ``.`` instead of ``+`` in it's character set.
+
+This encoding system appears to have originated with des-crypt hash,
+but is used by md5-crypt, sha-256-crypt, and others.
+within passlib, this encoding is referred as ``hash64`` encoding,
+and this module contains various utilities functions for encoding
+and decoding strings in that format.
+
+.. note::
+    It may *look* like bcrypt uses this scheme,
+    when in fact bcrypt uses the standard base64 encoding scheme,
+    but with ``+`` replaced with ``.``.
+
+.. data:: CHARS
+
+    The character set used by the Hash-64 format.
+    Index in character set denotes 6-bit integer value.
+
+.. autofunction:: encode_3_offsets
+.. autofunction:: encode_2_offsets
+.. autofunction:: encode_1_offset
+
+.. autofunction:: decode_int12
+.. autofunction:: encode_int12
+
+.. autofunction:: decode_int24
+.. autofunction:: encode_int24
+
+.. autofunction:: decode_int64
+.. autofunction:: encode_int64
diff --git a/docs/lib/passlib.utils.md4.rst b/docs/lib/passlib.utils.md4.rst
new file mode 100644
index 0000000..fb0f388
--- /dev/null
+++ b/docs/lib/passlib.utils.md4.rst
@@ -0,0 +1,20 @@
+====================================================
+:mod:`passlib.utils.md4` - MD4-Digest implementation
+====================================================
+
+.. module:: passlib.utils.md4
+    :synopsis: implemented of MD4-Digest
+
+.. warning::
+
+    This digest is considered **VERY INSECURE**,
+    and not suitable for any new cryptographic activities.
+    Trivial-cost real-world attacks exist for all
+    password algorithms, stream ciphers, etc, that have
+    been based on MD4.
+    Do not use this hash or derived schemes unless you *really* have to.
+
+This module implements the MD4 hash algorithm in pure python,
+based on the `rfc 1320 <http://www.faqs.org/rfcs/rfc1320.html>`_ specification of MD4.
+
+.. autoclass:: md4
diff --git a/docs/lib/passlib.utils.pbkdf2.rst b/docs/lib/passlib.utils.pbkdf2.rst
new file mode 100644
index 0000000..7bd9ab9
--- /dev/null
+++ b/docs/lib/passlib.utils.pbkdf2.rst
@@ -0,0 +1,15 @@
+====================================================
+:mod:`passlib.utils.pbkdf2` - PBKDF2 algorithm support
+====================================================
+
+.. module:: passlib.utils.pbkdf2
+    :synopsis: implementation of PBKDF2 algorithm
+
+This module provides a single function, :func:`pbkdf2`,
+which provides the ability to generate an arbitrary
+length key using the PBKDF2 key derivation algorithm,
+as specified in `rfc 2898 <http://tools.ietf.org/html/rfc2898>`_.
+This function can be helpful in creating password hashes
+using schemes which have been based around the pbkdf2 algorithm.
+
+.. autofunction:: pbkdf2
diff --git a/docs/lib/passlib.utils.rst b/docs/lib/passlib.utils.rst
new file mode 100644
index 0000000..00df703
--- /dev/null
+++ b/docs/lib/passlib.utils.rst
@@ -0,0 +1,79 @@
+=============================================
+:mod:`passlib.utils` - Helper Functions
+=============================================
+
+.. module:: passlib.utils
+    :synopsis: helper functions for implementing crypt handlers
+
+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.
+
+Decorators
+==========
+.. autofunction:: classproperty
+.. autofunction:: abstractmethod
+.. autofunction:: abstractclassmethod
+
+String Manipulation
+===================
+.. autofunction:: splitcomma
+
+Bytes Manipulation
+==================
+
+.. autofunction:: bytes_to_int
+.. autofunction:: int_to_bytes
+.. autofunction:: list_to_bytes
+.. autofunction:: bytes_to_list
+
+.. autofunction:: xor_bytes
+
+Randomness
+==========
+.. data:: rng
+
+    The random number generator used by passlib to generate
+    salt strings and other things which don't require a
+    cryptographically strong source of randomness.
+
+.. autofunction:: getrandbytes
+.. autofunction:: getrandstr
+
+Object Tests
+============
+.. autofunction:: is_crypt_handler
+
+.. todo::
+
+    .. autofunction:: is_crypt_context
+
+Crypt Handler Helpers
+=====================
+The following functions are used by passlib to do input validation
+for many of the implemented password schemes:
+
+.. autofunction:: norm_rounds
+
+.. autofunction:: gen_salt(salt, charset=H64_CHARS)
+
+.. autofunction:: norm_salt(salt, min_chars, max_chars=None, charset=H64_CHARS, gen_charset=None, name=None)
+
+Submodules
+==========
+There are also a few sub modules which provide additional utility functions:
+
+.. toctree::
+
+    passlib.utils.des
+    passlib.utils.h64
+    passlib.utils.md4
+    passlib.utils.pbkdf2
+
+.. todo::
+
+    document this module...
+
+    passlib.utils.handlers