Merge from defaultironpython-support-dev

9 files changed, 157 insertions, 113 deletions

diff --git a/docs/lib/passlib.apache.rst b/docs/lib/passlib.apache.rst
index 731baed..8649e62 100644
--- a/docs/lib/passlib.apache.rst
+++ b/docs/lib/passlib.apache.rst
@@ -8,6 +8,13 @@
 This module provides utilities for reading and writing Apache's
 htpasswd and htdigest files; though the use of two helper classes.
 
+.. versionchanged:: 1.6
+    The api for this module was updated to be more flexible,
+    and to have (hopefully) less confusing method names.
+    The old method and keyword names are supported but deprecated, and
+    will be removed in Passlib 1.8.
+    No more backwards-incompatible changes are currently planned.
+
 .. index:: apache; htpasswd
 
 Htpasswd Files
@@ -17,34 +24,34 @@ A quick summary of it's usage::
 
     >>> from passlib.apache import HtpasswdFile
 
-    >>> #when creating a new file, set to autoload=False, add entries, and save.
-    >>> ht = HtpasswdFile("test.htpasswd", autoload=False)
-    >>> ht.update("someuser", "really secret password")
+    >>> # when creating a new file, set to new=True, add entries, and save.
+    >>> ht = HtpasswdFile("test.htpasswd", new=True)
+    >>> ht.set_password("someuser", "really secret password")
     >>> ht.save()
 
-    >>> #loading an existing file to update a password
+    >>> # loading an existing file to update a password
     >>> ht = HtpasswdFile("test.htpasswd")
-    >>> ht.update("someuser", "new secret password")
+    >>> ht.set_password("someuser", "new secret password")
     >>> ht.save()
 
-    >>> #examining file, verifying user's password
+    >>> # examining file, verifying user's password
     >>> ht = HtpasswdFile("test.htpasswd")
     >>> ht.users()
     [ "someuser" ]
-    >>> ht.verify("someuser", "wrong password")
+    >>> ht.check_password("someuser", "wrong password")
     False
-    >>> ht.verify("someuser", "new secret password")
+    >>> ht.check_password("someuser", "new secret password")
     True
 
-    >>> #making in-memory changes and exporting to string
+    >>> # making in-memory changes and exporting to string
     >>> ht = HtpasswdFile()
-    >>> ht.update("someuser", "mypass")
-    >>> ht.update("someuser", "anotherpass")
+    >>> ht.set_password("someuser", "mypass")
+    >>> ht.set_password("someuser", "anotherpass")
     >>> print ht.to_string()
     someuser:$apr1$T4f7D9ly$EobZDROnHblCNPCtrgh5i/
     anotheruser:$apr1$vBdPWvh1$GrhfbyGvN/7HalW5cS9XB1
 
-.. autoclass:: HtpasswdFile(path, default=None, autoload=True)
+.. autoclass:: HtpasswdFile(path=None, new=False, autosave=False, ...)
 
 .. index:: apache; htdigest
 
@@ -53,7 +60,7 @@ Htdigest Files
 The :class:`!HtdigestFile` class allows management of htdigest files
 in a similar fashion to :class:`HtpasswdFile`.
 
-.. autoclass:: HtdigestFile(path, autoload=True)
+.. autoclass:: HtdigestFile(path, default_realm=None, new=False, autosave=False, ...)
 
 .. rubric:: Footnotes
 
diff --git a/docs/lib/passlib.context-interface.rst b/docs/lib/passlib.context-interface.rst
index 8331992..a760d06 100644
--- a/docs/lib/passlib.context-interface.rst
+++ b/docs/lib/passlib.context-interface.rst
@@ -8,8 +8,7 @@
 
 .. currentmodule:: passlib.context
 
-This details all the constructors and methods provided by :class:`!CryptContext`
-and :class:`!CryptPolicy`.
+This details all the constructors and methods provided by :class:`!CryptContext`.
 
 .. seealso::
 
@@ -19,12 +18,14 @@ and :class:`!CryptPolicy`.
 
 The Context Object
 ==================
-.. autoclass:: CryptContext(schemes=None, policy=<default policy>, \*\*kwds)
-
-The Policy Object
-=================
-.. autoclass:: CryptPolicy(\*\*kwds)
+.. autoclass:: CryptContext(schemes=None, \*\*kwds)
 
 Other Helpers
 =============
-.. autoclass:: LazyCryptContext([schemes=None,] **kwds [, create_policy=None])
+.. autoclass:: LazyCryptContext([schemes=None,] \*\*kwds [, onload=None])
+
+.. rst-class:: html-toggle
+
+(deprecated) The CryptPolicy Class
+==================================
+.. autoclass:: CryptPolicy
diff --git a/docs/lib/passlib.context-options.rst b/docs/lib/passlib.context-options.rst
index 4f0bcbe..ece9033 100644
--- a/docs/lib/passlib.context-options.rst
+++ b/docs/lib/passlib.context-options.rst
@@ -9,9 +9,13 @@
 .. currentmodule:: passlib.context
 
 The :class:`CryptContext` accepts a number of keyword options.
-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:
+These can be provided to any of the CryptContext constructor methods,
+as well as the :meth:`CryptContext.update` method, or any configuration
+string or INI file passed to :meth:`CryptContext.load`.
+
+The options are divided into two categories: "context options", which directly
+affect the :class:`!CryptContext` object itself; and "hash options", which
+affect the behavior of a particular password hashing scheme.
 
 .. seealso::
 
@@ -21,8 +25,7 @@ which affect the context treats a particular type of hash:
 
 Context Options
 ===============
-The following keyword options are accepted by both the :class:`CryptContext`
-and :class:`CryptPolicy` constructors, and directly affect the behavior
+The following keyword options directly affect the behavior
 of the :class:`!CryptContext` instance itself:
 
 ``schemes``
@@ -41,15 +44,14 @@ of the :class:`!CryptContext` instance itself:
 ``deprecated``
 
     List of handler names which should be considered deprecated by the CryptContext.
-    This should be a subset of the names of the handlers listed in schemes.
-    This is optional, if not specified, no handlers will be considered deprecated.
+    This should be a subset of the names of the handlers listed in *schemes*.
+    This is optional, and if not specified, no handlers will be considered deprecated.
 
-    For use in INI files, this may also be specified as a single comma-separated string
+    For INI files, this may also be specified as a single comma-separated string
     of handler names.
 
-    This is primarily used by :meth:`CryptContext.hash_needs_update` and
-    :meth:`CryptPolicy.handler_is_deprecated`. If the application does not use
-    these methods, this option can be ignored.
+    This is primarily used by :meth:`CryptContext.hash_needs_update`.
+    If the application does not use this method, this option can be ignored.
 
     Example: ``deprecated=["des_crypt"]``.
 
@@ -77,25 +79,22 @@ of the :class:`!CryptContext` instance itself:
 
     For symmetry with the format of the hash option keywords (below),
     all of the above context option keywords may also be specified
-    using the format :samp:`context__{option}` (note double underscores),
-    or :samp:`context.{option}` within INI files.
+    using the format :samp:`context__{option}` (note double underscores).
 
 .. note::
 
     To override context options for a particular :ref:`user category <user-categories>`,
-    use the format :samp:`{category}__context__{option}`,
-    or :samp:`{category}.context.{option}` within an INI file.
+    use the format :samp:`{category}__context__{option}`.
 
 Hash Options
 ============
-The following keyword options are accepted by both the :class:`CryptContext`
-and :class:`CryptPolicy` constructors, and affect how a :class:`!CryptContext` instance
-treats hashes belonging to a particular hash scheme, as identified by the hash's handler name.
+The following keyword option affect how a :class:`!CryptContext` instance
+treats hashes belonging to a particular hash scheme,
+as identified by the scheme's name.
 
 All hash option keywords should be specified using the format :samp:`{hash}__{option}`
 (note double underscores); where :samp:`{hash}` is the name of the hash's handler,
 and :samp:`{option}` is the name of the specific options being set.
-Within INI files, this may be specified using the alternate format :samp:`{hash}.{option}`.
 
 :samp:`{hash}__default_rounds`
 
@@ -111,11 +110,9 @@ Within INI files, this may be specified using the alternate format :samp:`{hash}
     to have a rounds value random chosen from the range :samp:`{default_rounds} +/- {vary_rounds}`.
 
     This may be specified as an integer value, or as a string containing an integer
-    with a percent suffix (eg: ``"10%"``). if specified as a percent,
+    with a percent suffix (eg: ``"10%"``). If specified as a percent,
     the amount varied will be calculated as a percentage of the :samp:`{default_rounds}` value.
 
-    The default Passlib policy sets this to ``"10%"``.
-
     .. note::
 
         If this is specified as a percentage, and the hash algorithm
@@ -172,6 +169,11 @@ Within INI files, this may be specified using the alternate format :samp:`{hash}
         It is recommended to set this for all hashes via ``all__passprep``,
         instead of settings it per algorithm.
 
+    .. note::
+
+        Due to a missing :mod:`!stringprep` module, this feature
+        is not available on Jython.
+
 :samp:`{hash}__{setting}`
 
     Any other option values, which match the name of a parameter listed
@@ -217,48 +219,61 @@ of the category string it wants to use, and add an additional separator to the k
     the need to use a different hash for a particular category
     can instead be acheived by overridden the ``default`` context option.
 
-Sample Policy File
+Sample Config File
 ==================
-A sample policy file:
+A sample config file:
 
 .. code-block:: ini
 
     [passlib]
-    #configure what schemes the context supports (note the "context." prefix is implied for these keys)
+    # configure what schemes the context supports
+    # (note that the "context__" prefix is implied for these keys)
     schemes = md5_crypt, sha512_crypt, bcrypt
     deprecated = md5_crypt
     default = sha512_crypt
 
-    #set some common options for all schemes
-    all.vary_rounds = 10%%
-        ; NOTE the '%' above has to be escaped due to configparser interpolation
+    # set some common options for all schemes
+    # (this particular setting causes the rounds value to be varied
+    # +/- 10% for each encrypt call)
+    all__vary_rounds = 0.1
 
-    #setup some hash-specific defaults
-    sha512_crypt.min_rounds = 40000
-    bcrypt.min_rounds = 10
+    # setup some hash-specific defaults
+    sha512_crypt__min_rounds = 40000
+    bcrypt__min_rounds = 10
 
-    #create a "admin" category, which uses bcrypt by default, and has stronger hashes
-    admin.context.default = bcrypt
-    admin.sha512_crypt.min_rounds = 100000
-    admin.bcrypt.min_rounds = 13
+    # create an "admin" category which uses bcrypt by default,
+    #  and has stronger default cost
+    admin__context__default = bcrypt
+    admin__sha512_crypt__min_rounds = 100000
+    admin__bcrypt__min_rounds = 13
 
-And the equivalent as a set of python keyword options::
+This can be turned into a :class:`!CryptContext` via :meth:`CryptContext.from_path`,
+or loaded into an existing object via :meth:`CryptContext.load`.
+
+And the equivalent of the above, as a set of Python keyword options::
 
     dict(
-        #configure what schemes the context supports (note the "context." prefix is implied for these keys)
+        # configure what schemes the context supports
+        # (note the "context__" prefix is implied for these keys)
         schemes = ["md5_crypt", "sha512_crypt", "bcrypt" ],
         deprecated = ["md5_crypt"],
         default = "sha512_crypt",
 
-        #set some common options for all schemes
-        all__vary_rounds = "10%",
+        # set some common options for all schemes
+        # (this particular setting causes the rounds value to be varied
+        # +/- 10% for each encrypt call)
+        all__vary_rounds = 0.1,
 
-        #setup some hash-specific defaults
+        # setup some hash-specific defaults
         sha512_crypt__min_rounds = 40000,
         bcrypt__min_rounds = 10,
 
-        #create a "admin" category, which uses bcrypt by default, and has stronger hashes
-        admin__context__default = bcrypt
-        admin__sha512_crypt__min_rounds = 100000
-        admin__bcrypt__min_rounds = 13
+        # create a "admin" category which uses bcrypt by default,
+        # and has stronger default cost
+        admin__context__default = bcrypt,
+        admin__sha512_crypt__min_rounds = 100000,
+        admin__bcrypt__min_rounds = 13,
     )
+
+This can be turned into a :class:`CryptContext` via the class constructor,
+or loaded into an existing object via :meth:`CryptContext.load`.
diff --git a/docs/lib/passlib.context-usage.rst b/docs/lib/passlib.context-usage.rst
index 9832203..4d897d4 100644
--- a/docs/lib/passlib.context-usage.rst
+++ b/docs/lib/passlib.context-usage.rst
@@ -77,28 +77,39 @@ copy; using the :meth:`CryptContext.replace` method to create
 a mutated copy of the original object::
 
     >>> from passlib.apps import ldap_context
-    >>> pwd_context = ldap_context.replace(default="ldap_md5_crypt")
+    >>> pwd_context = ldap_context.copy(default="ldap_md5_crypt")
     >>> pwd_context.encrypt("somepass")
     '{CRYPT}$1$Cw7t4sbP$dwRgCMc67mOwwus9m33z71'
 
 Examining a CryptContext Instance
 =================================
 All configuration options for a :class:`!CryptContext` instance
-are stored in a :class:`!CryptPolicy` instance accessible through
-the :attr:`CryptContext.policy` attribute::
+are accessible through various methods of the object:
 
     >>> from passlib.context import CryptContext
     >>> myctx = CryptContext([ "md5_crypt", "des_crypt" ], deprecated="des_crypt")
 
-    >>> #get a list of schemes recognized in this context:
-    >>> myctx.policy.schemes()
+    >>> # get a list of schemes recognized in this context:
+    >>> myctx.schemes()
     [ 'md5-crypt', 'bcrypt' ]
 
-    >>> #get the default handler class :
-    >>> myctx.policy.get_handler()
+    >>> # get the default handler object:
+    >>> myctx.handler("default")
     <class 'passlib.handlers.md5_crypt.md5_crypt'>
 
-See the :class:`CryptPolicy` class for more details on it's interface.
+    >>> # the results of a CryptContext object can be serialized as a dict,
+    >>> # suitable for passing to CryptContext's class constructor.
+    >>> myctx.to_dict()
+    {'schemes': ['md5_crypt, 'des_crypt'], 'deprecated': 'des_crypt'}
+
+    >>> # or serialized to an INI-style string, suitable for passing to
+    >>> # CryptContext's from_string() method.
+    >>> print myctx.to_string()
+    [passlib]
+    schemes = md5_crypt, des_crypt
+    deprecated = des_crypt
+
+See the :class:`CryptContext` reference for more details on it's interface.
 
 Full Integration Example
 ========================
@@ -123,31 +134,32 @@ applications with advanced policy requirements may want to create a hash policy
 
     [passlib]
 
-    ;setup the context to support pbkdf2_sha1, along with legacy md5_crypt hashes:
+    ; 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)
+    ; flag md5_crypt as deprecated
+    ; (existing md5_crypt hashes will be flagged as needs-updating)
     deprecated = md5_crypt
 
-    ;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%%
-        ; NOTE the '%' above has to be doubled due to configparser interpolation
-
-    ;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
+    ; 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 % of the default (in this case,
+    ; 20000 +/- 10% or 2000).
+    pbkdf2_sha1__default_rounds = 20000
+    pbkdf2_sha1__vary_rounds = 0.1
+
+    ; 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
 
 Initializing the CryptContext
 -----------------------------
@@ -172,7 +184,6 @@ the configuration once the application starts:
         #
 
         from myapp.model.security import user_pwd_context
-        from passlib.context import CryptPolicy
 
         def myapp_startup():
 
@@ -180,10 +191,13 @@ the configuration once the application starts:
             # ... other code ...
             #
 
-            # vars:
-            #   policy_path - path to policy file defined in previous step
             #
-            user_pwd_context.policy = CryptPolicy.from_path(policy_path)
+            # load configuration from some application-specified path.
+            # the load() method also supports loading from a string,
+            # or from dictionary, and other options.
+            #
+            ##user_pwd_context.load(policy_config_string)
+            user_pwd_context.load_path(policy_config_path)
 
             #
             #if you want to reconfigure the context without restarting the application,
diff --git a/docs/lib/passlib.ext.django.rst b/docs/lib/passlib.ext.django.rst
index 225642e..d797e23 100644
--- a/docs/lib/passlib.ext.django.rst
+++ b/docs/lib/passlib.ext.django.rst
@@ -73,7 +73,7 @@ you may set the following options in django ``settings.py``:
    * ``"disabled"``, in which case this app will do nothing when Django is loaded.
 
    * A multiline configuration string suitable for passing to
-     :meth:`passlib.context.CryptPolicy.from_string`.
+     :meth:`passlib.context.CryptContext.from_string`.
      It is *strongly* recommended to use a configuration which will support
      the existing Django hashes
      (see :data:`~passlib.ext.django.utils.STOCK_CTX`).
diff --git a/docs/lib/passlib.hash.bsdi_crypt.rst b/docs/lib/passlib.hash.bsdi_crypt.rst
index 99e7231..8a1b9af 100644
--- a/docs/lib/passlib.hash.bsdi_crypt.rst
+++ b/docs/lib/passlib.hash.bsdi_crypt.rst
@@ -18,19 +18,19 @@ This class can be used directly as follows::
     >>> from passlib.hash import bsdi_crypt as bc
 
     >>> bc.encrypt("password") #generate new salt, encrypt password
-    '_cD..Bf/46u7tr9IAJ6M'
+    '_7C/.Bf/4gZk10RYRs4Y'
 
-    >>> bc.encrypt("password", rounds=10000) #same, but with explict number of rounds
-    '_EQ0.amG/Pp5b0hIpggo'
+    >>> bc.encrypt("password", rounds=10001) #same, but with explict number of rounds
+    '_FQ0.amG/zwCMip7DnBk'
 
-    >>> bc.identify('_cD..Bf/46u7tr9IAJ6M') #check if hash is recognized
+    >>> bc.identify('_7C/.Bf/4gZk10RYRs4Y') #check if hash is recognized
     True
     >>> bc.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31') #check if some other hash is recognized
     False
 
-    >>> bc.verify("password", '_cD..Bf/46u7tr9IAJ6M') #verify correct password
+    >>> bc.verify("password", '_7C/.Bf/4gZk10RYRs4Y') #verify correct password
     True
-    >>> bc.verify("secret", '_cD..Bf/46u7tr9IAJ6M') #verify incorrect password
+    >>> bc.verify("secret", '_7C/.Bf/4gZk10RYRs4Y') #verify incorrect password
     False
 
 Interface
@@ -110,11 +110,16 @@ BSDi Crypt should not be considered sufficiently secure, for a number of reasons
 * The fact that it only uses the lower 7 bits of each byte of the password
   restricts the keyspace which needs to be searched.
 
-.. note::
+* Additionally, even *rounds* values are slightly weaker still,
+  as they may reveal the hash used one of the weak DES keys [#weak]_.
+  This information could theoretically allow an attacker to perform a
+  brute-force attack on a reduced keyspace and against only 1-2 rounds of DES.
+  (This issue is mitagated by the fact that few passwords are both valid *and*
+  result in a weak key).
 
-    This algorithm is none-the-less stronger than des-crypt itself,
-    since it supports variable rounds, a larger salt size,
-    and uses all bytes of the password.
+This algorithm is none-the-less stronger than :class:`!des_crypt` itself,
+since it supports variable rounds, a larger salt size,
+and uses all the bytes of the password.
 
 Deviations
 ==========
@@ -138,3 +143,5 @@ This implementation of bsdi-crypt differs from others in one way:
 
 .. [#] Another source describing algorithm -
        `<http://ftp.lava.net/cgi-bin/bsdi-man?proto=1.1&query=crypt&msection=3&apropos=0>`_
+
+.. [#weak] DES weak keys - `<https://en.wikipedia.org/wiki/Weak_key#Weak_keys_in_DES>`_
diff --git a/docs/lib/passlib.hosts.rst b/docs/lib/passlib.hosts.rst
index 5ca13db..85514e8 100644
--- a/docs/lib/passlib.hosts.rst
+++ b/docs/lib/passlib.hosts.rst
@@ -52,7 +52,7 @@ for the following Unix variants:
     All of the above contexts include the :class:`~passlib.hash.unix_disabled` handler
     as a final fallback. This special handler treats all strings as invalid passwords,
     particularly the common strings ``!`` and ``*`` which are used to indicate
-    that an account has been disabled [#shadow]_. 
+    that an account has been disabled [#shadow]_.
 
 A quick usage example, using the :data:`!linux_context` instance::
 
@@ -81,7 +81,7 @@ Current Host OS
     The main differences between this object and :func:`!crypt`:
 
     * this object provides introspection about *which* schemes
-      are available on a given system (via ``host_context.policy.schemes()``).
+      are available on a given system (via ``host_context.schemes()``).
     * it defaults to the strongest algorithm available,
       automatically configured to an appropriate strength
       for encrypting new passwords.
diff --git a/docs/lib/passlib.utils.des.rst b/docs/lib/passlib.utils.des.rst
index 674f934..ea09506 100644
--- a/docs/lib/passlib.utils.des.rst
+++ b/docs/lib/passlib.utils.des.rst
@@ -18,4 +18,4 @@ since they are designed primarily for use in password hash algorithms
 
 .. autofunction:: expand_des_key
 .. autofunction:: des_encrypt_block
-.. autofunction:: mdes_encrypt_int_block
+.. autofunction:: des_encrypt_int_block
diff --git a/docs/lib/passlib.utils.rst b/docs/lib/passlib.utils.rst
index afd27de..060d420 100644
--- a/docs/lib/passlib.utils.rst
+++ b/docs/lib/passlib.utils.rst
@@ -3,7 +3,7 @@
 =============================================
 
 .. module:: passlib.utils
-    :synopsis: helper functions for implementing password hashes
+    :synopsis: internal helpers for implementing password hashes
 
 This module contains a number of utility functions used by passlib
 to implement the builtin handlers, and other code within passlib.