passlib.apps work

=================
* renamed passlib.servers -> passlib.apps
* added custom_app_context, for quickly adding hashes to new apps
* documented module

9 files changed, 134 insertions, 64 deletions

diff --git a/docs/lib/passlib.apache.rst b/docs/lib/passlib.apache.rst
index b9728a9..0826246 100644
--- a/docs/lib/passlib.apache.rst
+++ b/docs/lib/passlib.apache.rst
@@ -3,6 +3,7 @@
 =============================================
 
 .. module:: passlib.apache
+    :synopsis: reading/writing htpasswd & htdigest files
 
 This module provides utilities for reading and writing Apache's
 htpasswd and htdigest files; though the use of two helper classes.
diff --git a/docs/lib/passlib.apps.rst b/docs/lib/passlib.apps.rst
new file mode 100644
index 0000000..8b7e422
--- /dev/null
+++ b/docs/lib/passlib.apps.rst
@@ -0,0 +1,108 @@
+==================================================================
+:mod:`passlib.apps` - Helpers for various applications
+==================================================================
+
+.. module:: passlib.apps
+    :synopsis: encrypting & verifying passwords used in sql servers and other applications
+
+This lists a number of :class:`!CryptContext` instances that are predefined
+by PassLib for easily handling the multiple formats used by various applications.
+(For details about how to *use* a :class:`!CryptContext` instance,
+see the documentation for the :class:`CryptContext` class itself).
+
+.. _quickstart-custom-applications:
+
+Custom Applications
+===================
+.. object:: custom_app_context
+
+    This :class:`!CryptContext` object is provided for new python applications
+    to quickly and easily add password hashing support.
+    It offers:
+
+    * Support for :class:`~passlib.hash.sha256_crypt` and :class:`~passlib.hash.sha512_crypt`
+    * Defaults to SHA256-Crypt under 32 bit systems; SHA512-Crypt under 64 bit systems.
+    * Comes pre-configured with strong rounds settings.
+
+    For applications which want to quickly add a password hash,
+    all they need to do is the following::
+
+        >>> #import the context under an app-specific name (so it can easily be replaced later)
+        >>> from passlib.apps import custom_app_context as pwd_context
+
+        >>> #encrypting a password...
+        >>> hash = pwd_context.encrypt("somepass")
+
+        >>> #verifying a password...
+        >>> ok = pwd_context.verify("somepass", hash)
+
+        >>> #[optional] encrypting a password for an admin account - uses stronger settings
+        >>> hash = pwd_context.encrypt("somepass", category="admin")
+
+    For applications which started using this preset, but whose needs
+    have grown beyond it, it is recommended to create your own CryptContext
+    instance; the configuration used to create this object can be a good starting point.
+
+LDAP
+====
+.. object:: ldap_context
+
+    This object provides a pre-configured :class:`!CryptContext` instance
+    for handling LDAPv2 password hashes. It recognizes all
+    the formats in the :doc:`ldap_digests listing <passlib.hash.ldap_digests>`.
+
+    It defaults to using the ``{SSHA}`` password hash.
+    For times when there should be another default, using code such as the following::
+
+        >>> from passlib.apps import ldap_context
+        >>> ldap_context = ldap_context.replace(default="ldap_salted_md5")
+
+        >>> #the new context object will now default to {SMD5}:
+        >>> ldap_context.encrypt("password")
+        '{SMD5}T9f89F591P3fFh1jz/YtW4aWD5s='
+
+    .. warning::
+
+        PassLib does not currently support the ``{CRYPT}`` password hash method.
+
+MySQL
+=====
+This module provides two pre-configured :class:`!CryptContext` instances
+for handling MySQL user passwords:
+
+.. object:: mysql_context
+
+    This object should recognize the new :class:`~passlib.hash.mysql41` hashes,
+    as well as any legacy :class:`~passlib.hash.mysql323` hashes.
+
+    It defaults to mysql41 when generating new hashes.
+
+    This should be used with MySQL version 4.1 and newer.
+
+.. object:: mysql3_context
+
+    This object is for use with older MySQL deploys which only recognize
+    the :class:`~passlib.hash.mysql323` hash.
+
+    This should be used only with MySQL version 3.2.3 - 4.0.
+
+PostgreSQL
+==========
+.. object:: postgres_context
+
+    This object should recognize password hashes stores in PostgreSQL's ``pg_shadow`` table;
+    which are all assumed to follow the :class:`~passlib.hash.postgres_md5` format.
+
+    Note that the username must be provided whenever encrypting or verifying a postgres hash::
+
+        >>> from passlib.apps import postgres_context
+
+        >>> #encrypting a password...
+        >>> postgres_context.encrypt("somepass", user="dbadmin")
+        'md578ed0f0ab2be0386645c1b74282917e7'
+
+        >>> #verifying a password...
+        >>> postgres_context.verify("somepass", 'md578ed0f0ab2be0386645c1b74282917e7', user="dbadmin")
+        True
+        >>> postgres_context.verify("wrongpass", 'md578ed0f0ab2be0386645c1b74282917e7', user="dbadmin")
+        False
diff --git a/docs/lib/passlib.hash.mysql323.rst b/docs/lib/passlib.hash.mysql323.rst
index a28dda0..a94d197 100644
--- a/docs/lib/passlib.hash.mysql323.rst
+++ b/docs/lib/passlib.hash.mysql323.rst
@@ -19,7 +19,7 @@ hash algorithm was introduced (see :class:`~passlib.hash.mysql41`).
 
 Usage
 =====
-Users will most likely find the frontends provided by :mod:`passlib.servers`
+Users will most likely find the frontends provided by :mod:`passlib.apps`
 to be more useful than accessing this class directly.
 That aside, this class can be used as follows::
 
diff --git a/docs/lib/passlib.hash.mysql41.rst b/docs/lib/passlib.hash.mysql41.rst
index 745d1d1..eaaf89e 100644
--- a/docs/lib/passlib.hash.mysql41.rst
+++ b/docs/lib/passlib.hash.mysql41.rst
@@ -18,7 +18,7 @@ used by MySQL, and is still in active use under MySQL 5.
 
 Usage
 =====
-Users will most likely find the frontends provided by :mod:`passlib.servers`
+Users will most likely find the frontends provided by :mod:`passlib.apps`
 to be more useful than accessing this class directly.
 That aside, this class can be used in the same manner
 as :class:`~passlib.hash.mysql323`.
diff --git a/docs/lib/passlib.hash.oracle11.rst b/docs/lib/passlib.hash.oracle11.rst
index 9dc0c8b..84e6ee6 100644
--- a/docs/lib/passlib.hash.oracle11.rst
+++ b/docs/lib/passlib.hash.oracle11.rst
@@ -42,15 +42,19 @@ Interface
 
 Format & Algorithm
 ==================
-An example oracle11 hash (of the string ``password``)
-is ``'S:4143053633E59B4992A8EA17D2FF542C9EDEB335C886EED9C80450C1B4E6'``.
+An example oracle11 hash (of the string ``password``) is:
+
+    ``'S:4143053633E59B4992A8EA17D2FF542C9EDEB335C886EED9C80450C1B4E6'``
 
 An oracle11 hash string has the format :samp:`S:{checksum}{salt}`, where:
 
 * ``S:`` is the prefix used to identify oracle11 hashes
   (as distinct from oracle10 hashes, which have no constant prefix).
 * :samp:`{checksum}` is 40 hexidecimal characters;
-  encoding a 160-bit checksum (``4143053633E59B4992A8EA17D2FF542C9EDEB335`` in the example).
+  encoding a 160-bit checksum.
+
+  (``4143053633E59B4992A8EA17D2FF542C9EDEB335`` in the example)
+
 * :samp:`{salt}` is 20 hexidecimal characters;
   providing a 80-bit salt (``C886EED9C80450C1B4E6`` in the example).
 
diff --git a/docs/lib/passlib.hash.postgres_md5.rst b/docs/lib/passlib.hash.postgres_md5.rst
index d42e258..a04f8b5 100644
--- a/docs/lib/passlib.hash.postgres_md5.rst
+++ b/docs/lib/passlib.hash.postgres_md5.rst
@@ -15,7 +15,7 @@ prior to this PostgreSQL stored it's password in plain text.
 
 Usage
 =====
-Users will most likely find the frontend provided by :mod:`passlib.servers`
+Users will most likely find the frontend provided by :mod:`passlib.apps`
 to be more useful than accessing this class directly.
 That aside, this class can be used directly as follows::
 
diff --git a/docs/lib/passlib.servers.rst b/docs/lib/passlib.servers.rst
deleted file mode 100644
index fe98265..0000000
--- a/docs/lib/passlib.servers.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-==================================================================
-:mod:`passlib.servers` - Contexts for SQL Database & Other Servers
-==================================================================
-
-.. module:: passlib.servers
-    :synopsis: frontend for encrypting & verifying passwords used in various sql databases
-
-PostgreSQL
-==========
-This module provides a single pre-configured :class:`CryptContext` instance
-which should be capable of recognizing passwords in modern postgres systems:
-
-.. object:: postgres_context
-
-    This object should recognize password hashes stores in postgres' pg_shadow table.
-    it can recognize :class:`~passlib.hash.postgres_md5` hashes,
-    as well as plaintext hashes.
-    It defaults to postgres_md5 when generating new hashes.
-
-    note that the username must be provided whenever encrypting or verifying a postgres hash.
-
-MySQL
-=====
-This module provides two pre-configured :class:`CryptContext` instances
-for handling MySQL user passwords:
-
-.. object:: mysql_context
-
-    This object should recognize the new :class:`~passlib.hash.mysql41` hashes,
-    as well as any legacy :class:`~passlib.hash.mysql323` hashes.
-    It defaults to mysql41 when generating new hashes.
-
-    This should be used for all mysql versions from 4.1 onward.
-
-.. object:: mysql3_context
-
-    This object is for use with older MySQL deploys which only recognize
-    the :class:`~passlib.hash.mysql323` hash.
-
-    This should be used only for mysql version 3 systems.
-
-LDAP
-====
-This module provides a pre-configured :class:`!CryptContext` instance
-for handling LDAPv2 password hashes:
-
-.. object:: ldap_context
-
-    This object is for use when reading LDAP password hashes.
-
-.. warning::
-
-    PassLib does not currently support the ``{CRYPT}`` password hash method.
diff --git a/docs/overview.rst b/docs/overview.rst
index c9ce82a..bfcdb4e 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -63,7 +63,7 @@ in order to get users started quickly:
 * The :mod:`passlib.apache` module contains classes
   for managing htpasswd and htdigest files.
 
-* The :mod:`passlib.servers` module contains pre-configured
+* The :mod:`passlib.apps` module contains pre-configured
   instances for managing hashes used by postgres, mysql, and ldap.
 
 * The :mod:`passlib.hosts` module contains pre-configured
@@ -74,7 +74,7 @@ in order to get users started quickly:
 
     For new applications which just need drop-in support for some manner
     of password encryption, so they can secure store passwords
-    and then forget about it, they should see :data:`passlib.servers.custom_app_context`.
+    and then forget about it, they should see :data:`passlib.apps.custom_app_context`.
 
 A quick example of how a password context can be used::
 
diff --git a/passlib/servers.py b/passlib/apps.py
index ef5ee12..f7feeb9 100644
--- a/passlib/servers.py
+++ b/passlib/apps.py
@@ -1,4 +1,4 @@
-"""passlib.servers"""
+"""passlib.apps"""
 #=========================================================
 #imports
 #=========================================================
@@ -25,18 +25,28 @@ __all__ = [
 _is32 = platform.architecture()[0] == '32bit'
 
 custom_app_context = CryptContext(
+    #choose some reasonbly strong schemes
     schemes=["sha512_crypt", "sha256_crypt"],
+
+    #set some useful global options
+    min_verify_time = .125,
+    all__vary_rounds = "10%",
     default="sha256_crypt" if _is32 else "sha512_crypt",
+
+    #set a good starting point for rounds selection
     sha512_crypt__default_rounds = 40000,
     sha256_crypt__default_rounds = 40000,
-    all__vary_rounds = "10%",
+
+    #if the admin user category is selected, make a much stronger hash,
+    admin__sha512_crypt__default_rounds = 80000,
+    admin__sha256_crypt__default_rounds = 80000,
     )
 
 #=========================================================
 #ldap
 #=========================================================
 #TODO: support ldap_crypt
-ldap_context = CryptContext(["ldap_salted_sha1", "ldap_salted_md5", "ldap_sha1", "ldap_md5", "ldap_cleartext" ])
+ldap_context = CryptContext(["ldap_salted_sha1", "ldap_salted_md5", "ldap_sha1", "ldap_md5", "ldap_plaintext" ])
 
 #=========================================================
 #mysql