Merge with stable

11 files changed, 203 insertions, 100 deletions

diff --git a/docs/_fragments/asa_verify_callout.rst b/docs/_fragments/asa_verify_callout.rst
new file mode 100644
index 0000000..46cfdb7
--- /dev/null
+++ b/docs/_fragments/asa_verify_callout.rst
@@ -0,0 +1,15 @@
+.. rst-class:: float-right without-title
+
+.. todo::
+
+    **Caveat Emptor**
+
+    Passlib's implementations of :class:`cisco_pix` and :class:`cisco_asa` both need verification.
+    For those with access to Cisco PIX and ASA systems, verifying Passlib's reference vectors
+    would be a great help (see :issue:`51`). In the mean time, there are no guarantees
+    that passlib correctly replicates the official implementation.
+
+    .. versionchanged:: 1.7.1
+
+        A number of :ref:`bugs <passlib-asa96-bug>` were fixed after expanding
+        the reference vectors, and testing against an ASA 9.6 system.
diff --git a/docs/conf.py b/docs/conf.py
index 7adac8b..6883743 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -63,7 +63,7 @@ extensions = [
     'cloud_sptheme.ext.index_styling',
 
     # inserts toc into right hand nav bar (ala old style python docs)
-    'cloud_sptheme.ext.relbar_toc',
+    'cloud_sptheme.ext.relbar_links',
 
     # add "issue" role
     'cloud_sptheme.ext.issue_tracker',
diff --git a/docs/history/1.7.rst b/docs/history/1.7.rst
index 60319dd..14e115f 100644
--- a/docs/history/1.7.rst
+++ b/docs/history/1.7.rst
@@ -2,21 +2,46 @@
 Passlib 1.7
 ===========
 
-**1.7.1** (NOT YET RELEASED)
-============================
+**1.7.1** (2017-1-30)
+=====================
 
-.. py:currentmodule:: passlib.ifc
+This release rolls up assorted bug & compatibility fixes since 1.7.0.
 
-* bugfix: :meth:`PasswordHash.hash` will now warn if passed any settings
+Bugfixes
+--------
+* .. py:currentmodule:: passlib.hash
+
+  :class:`cisco_asa` and :class:`cisco_pix`: Fixed a number of issues
+  which under :ref:`certain conditions <passlib-asa96-bug>`
+  caused prior releases to generate hashes that were unverifiable
+  on Cisco systems.
+
+* .. py:currentmodule:: passlib.ifc
+
+  :meth:`PasswordHash.hash` will now warn if passed any settings
   keywords.  This usage was deprecated in 1.7.0, but warning wasn't properly enabled.
   See :ref:`hash-configuring` for the preferred way to pass settings.
 
-* bugfix: setup.py: prevent erroneous version strings when run from an sdist.
+* **setup.py**: Don't append timestamp when run from an sdist.
+  This should fix some downstream build issues.
+
+* :mod:`!passlib.tests.test_totp`: Test suite now traps additional errors that :func:`datetime.utcfromtimestamp`
+  may throw under python 3, which should fix some test failures on architectures with rarer ILP sizes.
+  It also works around Python 3.6 bug `29100 <https://bugs.python.org/issue29100>`_.
+
+Deprecations
+------------
 
-* bugfix: TOTP tests: test setup now traps additional errors utcfromtimestamp()
-  may throw under python 3.
+* :class:`~passlib.context.CryptContext`: The ``harden_verify`` flag has been turned into a NOOP and deprecated.
+  It will be removed in passlib 1.8 along with the already-deprecated ``min_verify_time`` (:issue:`83`).
 
-* various documentation updates
+Other Changes
+-------------
+
+* :mod:`!passlib.tests.utils`: General truncation policy details were hammered out,
+  and additional hasher tests were added to enforce them.
+
+* **documentation**: Various updates & corrections.
 
 .. rst-class:: emphasize-children toc-always-open
 
@@ -92,12 +117,6 @@ New Features
       methods for dealing with hashes representing
       :ref:`disabled accounts <context-disabled-hashes>` (:issue:`45`).
 
-    * The :class:`~passlib.context.CryptContext` object now supports
-      a :ref:`harden_verify <context-harden-verify-option>` option,
-      allowing applications to introduce a delay in verification
-      to help prevent attackers discovering weak or missing hashes
-      through timing attacks.
-
     * All hashers which truncate passwords (e.g. :class:`~passlib.hash.bcrypt`
       and :class:`~passlib.hash.des_crypt`) can now be configured to raise
       a :exc:`~passlib.exc.PasswordTruncateError` when a overly-large password is provided.
@@ -304,8 +323,6 @@ Scheduled removal of features:
     * **[minor]** :mod:`passlib.context`: The ``min_verify_time`` keyword
       that was deprecated in release 1.6, is now completely ignored.
       Support will be removed entirely in release 1.8.
-      See the new :ref:`harden_verify <context-harden-verify-option>` keyword
-      that replaces it.
 
     * **[trivial]** :mod:`passlib.hash`: The internal :meth:`!PasswordHash.parse_rounds` method, deprecated in 1.6, has been removed.
 
diff --git a/docs/install.rst b/docs/install.rst
index 2c4ec6a..be11d5d 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -139,7 +139,7 @@ If you wish to generate your own copy of the documentation,
 you will need to:
 
 1. Install `Sphinx <http://sphinx.pocoo.org/>`_ (1.4 or newer)
-2. Install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_ (1.8 or newer).
+2. Install the `Cloud Sphinx Theme <http://packages.python.org/cloud_sptheme>`_ (1.8.2 or newer).
 3. Download the Passlib source
 4. From the Passlib source directory, run :samp:`python setup.py build_sphinx`.
 5. Once Sphinx completes its run, point a web browser to the file at :samp:`{SOURCE}/build/sphinx/html/index.html`
diff --git a/docs/lib/passlib.apache.rst b/docs/lib/passlib.apache.rst
index 4e81b09..969ead0 100644
--- a/docs/lib/passlib.apache.rst
+++ b/docs/lib/passlib.apache.rst
@@ -16,7 +16,7 @@ htpasswd and htdigest files; though the use of two helper classes.
 
 .. versionchanged:: 1.7
 
-    These classes will now preserve blank lines & "#" comments when updating
+    These classes will now preserve blank lines and "#" comments when updating
     htpasswd files; previous releases would throw a parse error.
 
 .. versionchanged:: 1.8
diff --git a/docs/lib/passlib.context.rst b/docs/lib/passlib.context.rst
index b1b6a86..5f2dd17 100644
--- a/docs/lib/passlib.context.rst
+++ b/docs/lib/passlib.context.rst
@@ -170,29 +170,14 @@ Options which directly affect the behavior of the CryptContext instance:
 
 ``harden_verify``
 
-    If set to ``true``, CryptContext will pause the first time :meth:`verify`
-    is called, in order to calculate the "average" time it would take
-    to verify a hash created using the default settings.
+    Companion to ``min_verify_time``, currently ignored.
 
-    Subsequent :meth:`verify` calls using will have their time padded
-    to this minimum time, in order to make it harder for an attacker
-    to guess which accounts have weak hashes.
-
-    Applications may also wish to call :meth:`~CryptContext.dummy_verify` for login
-    attempts where the user does not exist, in order to mask which
-    users accounts have valid hashes.
-
-    This option can be set to ``True`` or ``False`` (the default).
-
-    The default (may) be changed in a later 2.x release.
+    .. versionadded:: 1.7
 
-    .. warning::
+    .. deprecated:: 1.7.1
 
-        This feature is new, and adjustments may need to be made
-        to when (and how) the code calculates what the "minimum verification time"
-        is supposed to be.
-
-    .. versionadded:: 1.7
+        This option is ignored by 1.7.1, and will be removed in 1.8
+        along with ``min_verify_time``.
 
 .. _context-algorithm-options:
 
@@ -535,3 +520,9 @@ if any invalid-but-correctable values are encountered
 Other Helpers
 =============
 .. autoclass:: LazyCryptContext([schemes=None,] \*\*kwds [, onload=None])
+
+.. rst-class:: html-toggle
+
+The CryptPolicy Class (deprecated)
+==================================
+.. autoclass:: CryptPolicy
diff --git a/docs/lib/passlib.hash.cisco_asa.rst b/docs/lib/passlib.hash.cisco_asa.rst
index 3b9e757..5875214 100644
--- a/docs/lib/passlib.hash.cisco_asa.rst
+++ b/docs/lib/passlib.hash.cisco_asa.rst
@@ -1,7 +1,7 @@
 .. index:: Cisco; ASA hash
 
 ==================================================================
-:class:`passlib.hash.cisco_asa` - Cisco ASA hash
+:class:`passlib.hash.cisco_asa` - Cisco ASA MD5 hash
 ==================================================================
 
 .. include:: ../_fragments/insecure_hash_warning.rst
@@ -10,9 +10,11 @@
 
 .. versionadded:: 1.7
 
-The :class:`!cisco_asa` handler provides support for the 2005 revision of the older :class:`!cisco_pix` hash.
-The usage, functionality, and format is the same as for :class:`!cisco_pix`,
+.. include:: ../_fragments/asa_verify_callout.rst
 
-.. seealso::
+The :class:`!cisco_asa` class provides support for Cisco ASA "encrypted" hash format.
+This is a revision of the older :class:`!cisco_pix` hash;
+and the usage and format is the same.
 
-    :doc:`cisco_pix <passlib.hash.cisco_pix>` documentation page.
+**See the** :doc:`cisco_pix <passlib.hash.cisco_pix>` **documentation page**
+for combined details of both these classes.
diff --git a/docs/lib/passlib.hash.cisco_pix.rst b/docs/lib/passlib.hash.cisco_pix.rst
index 5b00b83..f9978f2 100644
--- a/docs/lib/passlib.hash.cisco_pix.rst
+++ b/docs/lib/passlib.hash.cisco_pix.rst
@@ -1,57 +1,57 @@
 .. index:: Cisco; PIX hash
 
 ==================================================================
-:class:`passlib.hash.cisco_pix` - Cisco PIX hash
+:class:`passlib.hash.cisco_pix` - Cisco PIX MD5 hash
 ==================================================================
 
+.. currentmodule:: passlib.hash
+
 .. include:: ../_fragments/insecure_hash_warning.rst
 
 .. versionadded:: 1.6
 
-.. todo::
-
-    Passlib currently lack a thorough set of test cases for the :class:`cisco_asa` hash
-    For people with access to such a system, verifying passlib's reference vectors
-    would be a great help (see :issue:`51`).
-    In the mean time, there are no guarantees that its behavior correctly replicates
-    the official implementation. *caveat emptor*.
-
-.. warning::
-
-    This class does not correctly handle hashes generated by
-    Pix/ASA 7.0 (2005) or newer; particularly for passwords 13 characters or more
-    (:issue:`51`). A new :class:`!cisco_asa` will be added in Passlib 1.7 to support these hashes.
+Overview
+========
+.. include:: ../_fragments/asa_verify_callout.rst
 
-.. currentmodule:: passlib.hash
+The :class:`cisco_asa` class implements the "encrypted" password hash algorithm commonly found on Cisco
+ASA systems. The companion :class:`cisco_pix` class
+implements the older variant found on Cisco PIX.
+Aside from internal differences, and slightly different limitations,
+the two hashes have the same format, and in some cases the same output.
 
-The :class:`cisco_pix` class implements the password hash algorithm commonly found on older Cisco
-PIX firewalls.  The :class:`cisco_asa` class implements a newer variant found Cisco ASA 7.0 and
-newer systems.  They can be used directly as follows::
+These classes can be used directly to generate or verify a hash for a specific
+user.  Specifying the user account name is required for this hash::
 
-    >>> from passlib.hash import cisco_pix as pix
+    >>> from passlib.hash import cisco_asa
 
     >>> # hash password using specified username
-    >>> hash = pix.hash("password", user="user")
+    >>> hash = cisco_asa.hash("password", user="user")
     >>> hash
     'A5XOy94YKDPXCo7U'
 
     >>> # verify correct password
-    >>> pix.verify("password", hash, user="user")
+    >>> cisco_asa.verify("password", hash, user="user")
     True
+
     >>> # verify correct password w/ wrong username
-    >>> pm.verify("password", hash, user="other")
+    >>> cisco_asa.verify("password", hash, user="other")
     False
+
     >>> # verify incorrect password
-    >>> pm.verify("letmein", hash, user="user")
+    >>> cisco_asa.verify("letmein", hash, user="user")
     False
 
+The main "enable" password can be hashes / verified just by omitting
+the ``user`` parameter, or setting ``user=""``::
+
     >>> # hash password without associated user account
-    >>> hash2 = pix.hash("password")
+    >>> hash2 = cisco_asa.hash("password")
     >>> hash2
     'NuLKvvWGg.x9HEKO'
 
     >>> # verify password without associated user account
-    >>> pix.verify("password", hash2)
+    >>> cisco_asa.verify("password", hash2)
     True
 
 .. seealso:: the generic :ref:`PasswordHash usage examples <password-hash-examples>`
@@ -66,8 +66,8 @@ Interface
 .. note::
 
     These hash algorithms have a context-sensitive peculiarity.
-    It takes in an optional username, used to salt the hash,
-    but with specific restrictions...
+    They take in an optional username to salt the hash,
+    but have specific restrictions...
 
     * The username *must* be provided in order to correctly hash passwords
       associated with a user account on the Cisco device.
@@ -80,15 +80,19 @@ Interface
 
 Format & Algorithm
 ==================
-Cisco PIX / ASA hashes consist of a 12 byte digest, encoded as a 16 character
+Cisco PIX & ASA hashes consist of a 12 byte digest, encoded as a 16 character
 :data:`HASH64 <passlib.utils.binary.h64>`-encoded string. An example
-hash (of ``"password"``) is ``"NuLKvvWGg.x9HEKO"``.
+hash (of ``"password"``, with user ``""``) is ``"NuLKvvWGg.x9HEKO"``.
 
 The PIX / ASA digests are calculated as follows:
 
-1. The password is encoded using an ``ASCII``-compatible encoding
-   (all known references are strict 7-bit ascii, and Passlib uses ``UTF-8``
-   to provide unicode support).
+1. The password is encoded using ``UTF-8`` (though entering non-ASCII
+   characters is subject to interface-specific issues, and may lead
+   to problems such as double-encoding).
+
+   If the result is greater than 16 bytes (for PIX), or 32 bytes (for ASA),
+   the password is not allowed -- it will be rejected when set,
+   and simplify not verify during authentication.
 
 2. If the hash is associated with a user account,
    append the first four bytes of the user account name
@@ -96,14 +100,18 @@ The PIX / ASA digests are calculated as follows:
    with a user account (e.g. it's the "enable" password),
    this step should be omitted.
 
+   If the user account is 1-3 bytes, it is repeated until all 4 bytes are filled
+   up (e.g. "usr" becomes "usru").
+
    For :class:`!cisco_asa`,
    this step is omitted if the password is 28 bytes or more.
 
-3. The password should be truncated to 16 bytes, or the right side NULL
-   padded to 16 bytes, as appropriate.
+3. The password+user string is truncated, or right-padded with NULLs,
+   until it's 16 bytes in size.
 
    For :class:`!cisco_asa`,
-   if the password is 13 or more bytes, the truncate/padding size is increased to 32 bytes.
+   if the password+user string is 16 or more bytes,
+   a padding size of 32 is used instead.
 
 4. Run the result of step 3 through MD5.
 
@@ -112,6 +120,10 @@ The PIX / ASA digests are calculated as follows:
 
 6. Encode the 12-byte result using :data:`HASH64 <passlib.utils.binary.h64>`.
 
+.. versionchanged:: 1.7.1
+
+    Updated to reflect current understanding of the algorithm.
+
 Security Issues
 ===============
 This algorithm is not suitable for *any* use besides manipulating existing
@@ -138,22 +150,44 @@ Cisco PIX hashes, due to the following flaws:
 
 Deviations
 ==========
-This implementation differs from the standard in one main way:
+This implementation tries to adhere to the canonical Cisco implementation,
+but without an official specification, there may be other unknown deviations.
+The following are known issues:
 
 * Unicode Policy:
 
-  The official Cisco PIX algorithm is primarily used with ``ascii`` passwords,
-  how it handles other characters is not known.
+  ASA documentation [#charset]_ indicates it uses UTF-8 encoding,
+  and Passlib does as well.  However, some ASA interfaces
+  have issues such as: ASDM may double-encode unicode characters,
+  and SSH connections may drop non-ASCII characters entirely.
+
+* How usernames are added is not entirely pinned down.  Under ASA, 3-character
+  usernames have their last character repeated to make a string of length 4.
+  It is currently assumed that a similar repetition would be applied to
+  usernames of 1-2 characters, and that this applies to PIX as well;
+  though neither assumption has been confirmed.
+
+* .. _passlib-asa96-bug:
 
-  In order to provide support for unicode strings,
-  Passlib will encode unicode passwords using ``utf-8``
-  before running them through this algorithm. If a different
-  encoding is desired by an application, the password should be encoded
-  before handing it to Passlib.
+  **Passlib 1.7.1 Bugfix**: Prior releases of Passlib had a number of issues
+  with their implementation of the PIX & ASA algorithms.   As of 1.7.1,
+  the reference vectors were greatly expanded, and then tested against
+  an ASA 9.6 system.  This revealed a number of errors in passlib's implementation,
+  which under the following conditions would create hashes that were
+  unverifiable on a Cisco system:
 
-* While this implementation agrees with all known references,
-  the actual algorithm has not been published by Cisco, so there may be other
-  unknown deviations.
+  - PIX and ASA: Usernames containing 1-3 characters were not appended correctly (step 2, above).
+
+  - ASA omits the user entirely (step 2, above) for passwords with >= 28 characters,
+    not >= 27.  Non-enable passwords of exactly 27 characters were previous hashed
+    incorrectly.
+
+  - ASA's padding size decision (step 3, above) is made after the user
+    has been appended, not before.  This caused prior releases to
+    incorrectly hash non-enable passwords of length 13-15.
+
+  Anyone relying on cisco_asa or cisco_pix should upgrade to Passlib 1.7.1 or newer
+  to avoid these issues.
 
 .. rubric:: Footnotes
 
@@ -166,3 +200,6 @@ This implementation differs from the standard in one main way:
 
 .. [#] Partial description of ASA algorithm - 
        `<https://github.com/stekershaw/asa-password-encrypt/blob/master/README.md>`_
+
+.. [#charset] Character set used by ASA 8.4 -
+       `<http://www.cisco.com/c/en/us/td/docs/security/asa/asa84/configuration/guide/asa_84_cli_config/ref_cli.html#Supported_Character_Sets>`_
diff --git a/docs/lib/passlib.hash.rst b/docs/lib/passlib.hash.rst
index 3211066..94580e8 100644
--- a/docs/lib/passlib.hash.rst
+++ b/docs/lib/passlib.hash.rst
@@ -238,20 +238,65 @@ no identifying markers, identifying them is pretty much context-dependant.
 
 Cisco Hashes
 ============
-The following hashes are used in various places on Cisco IOS and ASA devices:
+..
+    TODO:
+
+    What was/were IOS types 1, 2, 3, and 6? Don't see many references.
+    Think type 6 is a reversible encryption format ala type 7,
+    per https://supportforums.cisco.com/discussion/11733226/when-use-type-6-encrypted-or-type-7-encrypted
+
+
+**Cisco IOS**
+
+The following hashes are used in various places on Cisco IOS, and
+are usually referred to by a Cisco-assigned "type" code:
+
+.. rst-class:: hidden
 
 .. toctree::
     :maxdepth: 1
 
-    passlib.hash.cisco_pix
-    passlib.hash.cisco_asa
+    passlib.hash.cisco_type7
+
+* :doc:`passlib.hash.md5_crypt <passlib.hash.md5_crypt>` -- "Type 5" hashes are actually just the standard
+  Unix MD5-Crypt hash, the format is identical.
+
+* :doc:`passlib.hash.cisco_type7 <passlib.hash.cisco_type7>` -- "Type 7" isn't actually a hash,
+  but a reversible encoding designed to obscure passwords from idle view.
+
+* "Type 8" hashes are based on PBKDF2-HMAC-SHA256;
+  but not currently supported by passlib (:issue:`87`).
 
-* **Cisco "Type 5" hashes** - these are the same as :doc:`md5_crypt <passlib.hash.md5_crypt>`
+* "Type 9" hashes are based on scrypt;
+  but not currently supported by passlib (:issue:`87`).
+
+**Cisco PIX & ASA**
+
+Separately from this, Cisco PIX & ASA firewalls have their own hash formats,
+generally identified by the "format" parameter in the :samp:`username {user} password {hash} {format}` config line
+they occur in.  The following are known & handled by passlib:
+
+.. rst-class:: hidden
 
 .. toctree::
     :maxdepth: 1
 
-    passlib.hash.cisco_type7
+    passlib.hash.cisco_pix
+    passlib.hash.cisco_asa
+
+* :doc:`passlib.hash.cisco_pix <passlib.hash.cisco_pix>` -- PIX "encrypted" hashes
+  use a simple unsalted MD5-based algorithm.
+
+* :doc:`passlib.hash.cisco_asa <passlib.hash.cisco_asa>` -- ASA "encrypted" hashes
+  use a similar algorithm to PIX, with some minor improvements.
+
+* ASA "nt-encrypted" hashes
+  are the same as :class:`passlib.hash.nthash`,
+  except that they use base64 encoding rather than hexadecimal.
+
+* ASA 9.5 added support for "pbkdf2" hashes
+  (based on PBKDF2-HMAC-SHA512); which aren't currently supported
+  by passlib (:issue:`87`).
 
 .. _other-hashes:
 
diff --git a/docs/lib/passlib.hash.scrypt.rst b/docs/lib/passlib.hash.scrypt.rst
index 19751ca..5c3677c 100644
--- a/docs/lib/passlib.hash.scrypt.rst
+++ b/docs/lib/passlib.hash.scrypt.rst
@@ -55,7 +55,7 @@ Scrypt Backends
 
 This class will use the first available of two possible backends:
 
-1. The C-accelarated `scrypt <https://pypi.python.org/pypi/scrypt>`_ package, if installed.
+1. The C-accelerated `scrypt <https://pypi.python.org/pypi/scrypt>`_ package, if installed.
 2. A pure-python implementation of SCrypt, built into Passlib.
 
 .. warning::
diff --git a/docs/narr/context-tutorial.rst b/docs/narr/context-tutorial.rst
index 8e4cb7a..af093fa 100644
--- a/docs/narr/context-tutorial.rst
+++ b/docs/narr/context-tutorial.rst
@@ -371,7 +371,6 @@ If an existing hash below the minimum is tested, it will show up as needing reha
 Undocumented Features
 =====================
 
-.. todo:: Document usage of the :ref:`harden_verify <context-harden-verify-option>` option.
 .. todo:: Document usage of the :ref:`context-disabled-hashes` options.
 
 .. rst-class:: html-toggle
@@ -420,9 +419,6 @@ All of the documented :ref:`context-options` are allowed.
     admin__pbkdf2_sha1__min_rounds = 18000
     admin__pbkdf2_sha1__default_rounds = 20000
 
-    ; delay failed verify() calls to mask hashes with weak rounds
-    harden_verify = true
-
 Initializing the CryptContext
 -----------------------------
 Applications which choose to use a policy file will typically want