docs: various updates

* updated new_application_quickstart to account for Argon2
* added doc page for passlib.crypto

10 files changed, 249 insertions, 123 deletions

diff --git a/CHANGES b/CHANGES
index dac93e9..4d4668a 100644
--- a/CHANGES
+++ b/CHANGES
@@ -26,145 +26,195 @@ Release History
 
     * Get :mod:`passlib.apache` context profiles finished & committed.
 
+Overview
+--------
+
+    *Welcome to Passlib 1.7!*
+
+    This release includes a number of new features, as well as cleans up
+    some long-standing design issues, and contains a number of internal
+    improvements as part of the roadmap towards passlib 2.0.
+
+    *Highlights include:*
+
+    * Support for :class:`~passlib.hash.argon2` and :class:`~passlib.hash.scrypt`
+
+    * The misnamed :meth:`~passlib.ifc.PasswordHash.encrypt` is deprecated, new code should
+      now call :meth:`~passlib.ifc.PasswordHash.hash` instead.  This is part of a much
+      larger project to clean up passlib's password hashing API.
+
+    * Experimental TOTP (two factor authentication) helpers in the :mod:`passlib.totp` module.
+
+    * Large speedup of the internal PBKDF2 routines.
+
 Requirements
 ------------
 
    * **Passlib now requires Python 2.6, 2.7, or >= 3.3**.
-     Support for Python versions 2.5 and 3.0 - 3.2 have been dropped.
+     Support for Python versions 2.5 and 3.0 through 3.2 have been dropped.
      Support for PyPy 1.x has also been dropped.
 
    * The :mod:`passlib.ext.django` extension now requires Django 1.8 or better.
      Django 1.7 and earlier are no longer supported.
 
-Major Changes
--------------
+New Hashes
+----------
+    * :class:`~passlib.hash.argon2` -- Support for the Argon2 password hash (:issue:`69`).
+
+    * :class:`~passlib.hash.scrypt` -- New password hash format which uses
+      the SCrypt KDF (:issue:`8`).
+
+    * Added :class:`~passlib.hash.cisco_asa` which provides (tentative)
+      support for Cisco ASA 7.0 and newer hashes (:issue:`51`).
+
+New Features
+------------
     * New :mod:`passlib.totp` module provides full support for TOTP & HOTP tokens
       on both client and server side. Contains both low-level primitives, and high-level
       helpers for persisting and tracking client state.
 
-    * New :mod:`passlib.pwd` module added to aid in password generation
-      and strength measurement (with contributions from Thomas Waldmann).
-
-    * Added :class:`~passlib.hash.cisco_asa` which provides (tentative)
-      support for Cisco ASA 7.0 and newer hashes.
+    * New :mod:`passlib.pwd` module added to aid in password generation.
 
     * The :func:`~passlib.crypto.digest.pbkdf2_hmac` function and all PBKDF2-based
       hashes have been sped up by ~20% compared to Passlib 1.6. Furthermore,
       it will now use `fastpbk2 <https://pypi.python.org/pypi/fastpbkdf2>`_
       or :func:`hashlib.pbkdf2_hmac` when available, for an even greater speedup.
 
+Bugfixes
+--------
     * Passlib will now detect and work around the fatal concurrency bug
       in py-bcrypt 0.2 and earlier (a :exc:`~passlib.exc.PasslibSecurityWarning`
       will also be issued). Nevertheless, users are *strongly* encouraged
       to upgrade to py-bcrypt 0.3 or another bcrypt library if you are using
       the :doc:`bcrypt </lib/passlib.hash.bcrypt>` hash.
 
-    * :class:`~passlib.hash.scrypt` -- New password hash format which uses
-      the SCrypt KDF (:issue:`8`).
-
-    * :class:`~passlib.hash.argon2` -- Support for the Argon2 password hash (:issue:`69`).
-
     * The :mod:`passlib.apache` htpasswd helpers now preserve blank lines and comments,
       rather than choking on them (:issue:`73`).
 
-Minor Internal Changes
-----------------------
-    * The shared :class:`!PasswordHash` unittests now check all hash handlers for
-      basic thread-safety (motivated by the pybcrypt 0.2 concurrency bug).
-
-    * Most of passlib's internal cryptography helpers have been moved from
-      :mod:`!passlib.utils` to :mod:`passlib.crypto`, and the APIs refactored.
-      This allowed unification of various hash management routines,
-      some speed ups to the HMAC and PBKDF2 primitives, and opens up the architecture
-      to support more optional backend libraries.
-
-      Compatibility wrappers will be kept in place at the old location until Passlib 2.0.
-
+Other Changes
+-------------
     * The majority of CryptContext's internal rounds handling & migration code has been
       moved to the password hashes themselves, via the new :meth:`~passlib.ifc.PasswordHash.using`
-      and :meth:`~passlib.ifc.PasswordHash.needs_update` methods.  This allows much more flexibility
+      and :meth:`~passlib.ifc.PasswordHash.needs_update` methods.
+
+      This allows much more flexibility
       when using a hash directly, rather than via CryptContext, as well making it easier for
       CryptContext to support hash-specific parameters.
 
-    * :func:`~passlib.utils.consteq` is now an alias for stdlib's :func:`hmac.compare_digest`
-      under python 3.3 and up.
+    * [minor] The shared :class:`!PasswordHash` unittests now check all hash handlers for
+      basic thread-safety (motivated by the pybcrypt 0.2 concurrency bug).
 
-    * M2Crypto no longer used to accelerate pbkdf2-hmac-sha1; applications which need this
-      should use the `fastpbkdf2 <https://pypi.python.org/pypi/fastpbkdf2>`_ backend instead.
+    * [trivial] :func:`~passlib.utils.consteq` is now an alias for stdlib's :func:`hmac.compare_digest`
+      under python 3.3 and up.
 
 Deprecations
 ------------
-    Passlib 1.7 has undergone a large number of deprecations, as part of a long range plan
-    to restructure and simplify both the API and the internals of Passlib 2.0.  There will be
-    at least one more major release (1.8 or 1.9) before Passlib 2.0 is released.
-
-    * The :class:`~passlib.ifc.PasswordHash` API (used by all hashes in passlib),
-      has had a number of cleanups made:
-
-        * :meth:`!encrypt` has been renamed to :meth:`~passlib.ifc.PasswordHash.hash`,
-          to clarify that it's performing one-way hashing rather than encryption.
-          A compatibility alias will remain in place until Passlib 2.0.
-          This should fix the longstanding :issue:`21`.
-
-        * The little-used methods :meth:`~passlib.ifc.PasswordHash.genhash` and
-          :meth:`~passlib.ifc.PasswordHash.genconfig` have been deprecated.
-          Compatibility aliases will remain in place until Passlib 2.0.
-
-        * Settings options like ``rounds`` and ``salt_size`` should no longer be passed to
-          :meth:`!hash`. Instead, callers should use the new :meth:`~passlib.ifc.PasswordHash.using`
-          method: for example, ``sha256_crypt.hash("secret", rounds=12345)`` should now be
-          ``sha256_crypt.using(rounds=12345).hash("secret")``.  Support for the old method
-          will be removed in Passlib 2.0.
-
-    * The :class:`~passlib.context.CryptContext` object has a number of cleanups made:
-
-        * :meth:`!encrypt` was renamed to :meth:`!hash` to match the
-          :class:`~passlib.ifc.PasswordHash` API changes listed above.
-
-        * The ``vary_rounds`` option has been deprecated,
-          and will be removed in Passlib 2.0.  It provided very little security benefit,
-          and was judged not worth the additional code complexity it requires.
-
-        * The special wildcard ``all`` scheme name
-          has been deprecated, and will be removed in Passlib 2.0.  The only legitimate use
-          was to support ``vary_rounds``, which itself will be removed in 2.0.
+As part of a long-range plan to restructure and simplify both the API and the internals of Passlib,
+a number of methods have been deprecated & replaced.  The eventually goal is a large cleanup
+and overhaul as part of Passlib 2.0. There will be at least one more major release (1.8 or 1.9)
+before Passlib 2.0 is released.
+
+Password Hash API
+.................
+Towards that end, the :class:`~passlib.ifc.PasswordHash` API (used by all hashes in passlib),
+has had a number of changes made:
+
+    * [major] The :class:`!PasswordHash` method :meth:`!encrypt`
+      has been renamed to :meth:`~passlib.ifc.PasswordHash.hash`,
+      to clarify that it's performing one-way hashing rather than reversiable encryption.
+      A compatibility alias will remain in place until Passlib 2.0.
+      This should fix the longstanding :issue:`21`.
+
+    * [major] Settings explicit configuration options like ``rounds`` and ``salt_size``
+      should no longer be passed to :meth:`!hash` (née :meth:`encrypt`).  Instead, callers
+      should use the new :meth:`~passlib.ifc.PasswordHash.using`
+      method, which generates a new hasher with a customized configuration.
+
+      For example, ``sha256_crypt.encrypt("secret", rounds=12345)`` should now be
+      ``sha256_crypt.using(rounds=12345).hash("secret")``.  Support for the old syntax
+      will be removed in Passlib 2.0.
+
+    * [minor] The little-used :class:`!PasswordHash` methods :meth:`~passlib.ifc.PasswordHash.genhash` and
+      :meth:`~passlib.ifc.PasswordHash.genconfig` have been deprecated.
+      Compatibility aliases will remain in place until Passlib 2.0,
+      at which point they will be removed entirely.
+
+Crypt Context API
+.................
+Applications which use passlib's :class:`~passlib.context.CryptContext` should not be
+greatly affected by this release; only one major deprecation was made:
+
+    * [major] The :meth:`!encrypt` method was renamed to :meth:`!hash` to match the
+      :class:`~passlib.ifc.PasswordHash` API changes listed above.
+      The old method will remain around until Passlib 2.0.
+
+A few internal options in have been deprecated:
+
+    * [minor] The ``vary_rounds`` option has been deprecated,
+      and will be removed in Passlib 2.0.  It provided very little security benefit,
+      and was judged not worth the additional code complexity it requires.
+
+    * [minor] The special wildcard ``all`` scheme name
+      has been deprecated, and will be removed in Passlib 2.0.  The only legitimate use
+      was to support ``vary_rounds``, which itself will be removed in 2.0.
+
+Other Deprecations
+..................
+A few other assorted deprecations have been made:
 
     * The :func:`~passlib.utils.generate_secret` function has been deprecated
       in favor of the new :mod:`passlib.pwd` module, and the old function will be removed
       in Passlib 2.0.
 
-    * :class:`passlib.utils.handlers.HasManyBackends` internal API changed:
+    * Most of passlib's internal cryptography helpers have been moved from
+      :mod:`passlib.utils` to :mod:`passlib.crypto`, and the APIs refactored.
+      This allowed unification of various hash management routines,
+      some speed ups to the HMAC and PBKDF2 primitives, and opens up the architecture
+      to support more optional backend libraries.
+
+      Compatibility wrappers will be kept in place at the old location until Passlib 2.0.
 
-      Applications implementing a custom handler with multiple backends
-      should now provide :samp:`_load_backend_{name}` classmethod for each backend.
-      This is simpler, more flexible, and more explicit than the
-      previous (1.6 and earlier) API, which required a :samp:`_has_backend_{name}`
-      class property and a :samp:`_calc_checksum_{name}` method.
+    * Some deprecations and internal changes have been made to the :mod:`passlib.utils.handlers`
+      module, which provides the common framework Passlib uses to implement hashers.
 
-      Support for the older API is deprecated, and will it be removed in Passlib 2.0.
+      .. warning::
+
+          Developers who are using :mod:`!passlib.utils.handlers` directly are strongly encouraged
+          to contact the Passlib message board.  It is likely breaking changes will occur in the
+          Passlib 1.8 / 1.9 releases.
 
 Backwards Incompatibilities
 ---------------------------
-    * :func:`passlib.utils.pbkdf2.pbkdf2` no longer supports custom PRF callables.
-      this was an unused feature, and prevented some useful optimizations.
+Changes in existing behavior:
 
-    * The :ref:`min_verify_time <context-min-verify-time-option>` keyword
+    * [moderate] New hashes generated by :class:`~passlib.apache.HtpasswdFile` now use the strongest
+      algorithm available on the host, rather than one that is guaranteed to be portable.
+      Applications can explicitly set ``default_scheme="portable"`` to retain the old behavior.
+
+    * [minor] M2Crypto no longer used to accelerate pbkdf2-hmac-sha1; applications relying on this
+      to speed up :class:`~passlib.hash.pbkdf2_sha1` should install
+      `fastpbkdf2 <https://pypi.python.org/pypi/fastpbkdf2>`_.
+
+Scheduled removal of features:
+
+    * [minor] The :ref:`min_verify_time <context-min-verify-time-option>` keyword
       that was deprecated in release 1.6, is now completely ignored.
       It was never very useful, and now complicates the internal code needlessly.
       It will be removed entirely in release 1.8.
 
-    * New hashes generated by :class:`~passlib.apache.HtpasswdFile` now use the strongest
-      algorithm available on the host, rather than one that is guaranteed to be portable.
-      Applications can explicitly set ``default_scheme="portable"`` to retain the old behavior.
+    * [trivial] The internal :meth:`!PasswordHash.parse_rounds` method, deprecated in 1.6, has been removed.
 
-    * The little-used method :meth:`~passlib.ifc.PasswordHash.genconfig`
+Minor incompatibilities:
+
+    * [minor] The little-used method :meth:`~passlib.ifc.PasswordHash.genconfig`
       will now always return a valid hash, rather than a truncated configuration
       hash or ``None``.
 
-    * The little-used method :meth:`~passlib.ifc.PasswordHash.genhash` no longer accepts
+    * [minor] The little-used method :meth:`~passlib.ifc.PasswordHash.genhash` no longer accepts
       ``None`` as a config argument.
 
-    * The internal :meth:`!PasswordHash.parse_rounds` method, deprecated in 1.6, has been removed.
+    * [trivial] :func:`passlib.utils.pbkdf2.pbkdf2` no longer supports custom PRF callables.
+      this was an unused feature, and prevented some useful optimizations.
 
 **1.6.6** (NOT YET RELEASED)
 ============================
diff --git a/docs/contents.rst b/docs/contents.rst
index 3ad2ced..309d7cb 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -26,6 +26,7 @@ Table Of Contents
     lib/passlib.exc
     lib/passlib.registry
     lib/passlib.utils
+    lib/passlib.crypto
 
     modular_crypt_format
 
diff --git a/docs/install.rst b/docs/install.rst
index bbecd04..5231e8b 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -64,7 +64,7 @@ Optional Libraries
    If installed, this will be used to provider support for the :class:`~passlib.hash.scrypt`
    hash algorithm.  If not installed, a MUCH slower builtin reference implementation will be used.
 
-.. versiochanged:: 1.7
+.. versionchanged:: 1.7
 
     Added fastpbkdf2, cryptography, argon2_cffi, argon2pure, and scrypt support.
     Removed M2Crypto support.
diff --git a/docs/lib/passlib.crypto.digest.rst b/docs/lib/passlib.crypto.digest.rst
index 5af4cd1..942f11d 100644
--- a/docs/lib/passlib.crypto.digest.rst
+++ b/docs/lib/passlib.crypto.digest.rst
@@ -24,10 +24,11 @@ Hash Functions
     as well as offered through :func:`hashlib.new`.
     It will also fallback to passlib's builtin MD4 implementation if one is not natively available.
 
-HMAC Functions
-==============
+..
+    HMAC Functions
+    ==============
 
-.. autofunction:: compile_hmac
+    .. autofunction:: compile_hmac
 
 PKCS#5 Key Derivation Functions
 ===============================
diff --git a/docs/lib/passlib.crypto.rst b/docs/lib/passlib.crypto.rst
new file mode 100644
index 0000000..5d4a2c1
--- /dev/null
+++ b/docs/lib/passlib.crypto.rst
@@ -0,0 +1,18 @@
+======================================================
+:mod:`passlib.crypto` - Cryptographic Helper Functions
+======================================================
+
+.. module:: passlib.crypto
+    :synopsis: internal cryptographic helpers for implementing password hashes
+
+This module is primarily used as an internal support module.
+It contains cryptography utility functions used by Passlib.
+However, end-user applications may find some of the functions useful.
+
+It contains the following submodules:
+
+.. toctree::
+    :maxdepth: 1
+
+    passlib.crypto.digest
+    passlib.crypto.des
diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst
index 0064820..ff82c4f 100644
--- a/docs/lib/passlib.hash.pbkdf2_digest.rst
+++ b/docs/lib/passlib.hash.pbkdf2_digest.rst
@@ -19,7 +19,7 @@ Though the original PBKDF2 specification uses the SHA-1 message digest,
 it is not vulnerable to any of the known weaknesses of SHA-1 [#hmac-sha1]_,
 and can be safely used. However, for those still concerned, SHA-256 and SHA-512
 versions are offered as well.
-PBKDF2-SHA512 is one of the three hashes Passlib
+PBKDF2-SHA512 is one of the four hashes Passlib
 :ref:`recommends <recommended-hashes>` for new applications.
 
 All of these classes can be used directly as follows::
diff --git a/docs/lib/passlib.hash.scrypt.rst b/docs/lib/passlib.hash.scrypt.rst
index a908b75..3224a34 100644
--- a/docs/lib/passlib.hash.scrypt.rst
+++ b/docs/lib/passlib.hash.scrypt.rst
@@ -97,8 +97,17 @@ See `<http://www.tarsnap.com/scrypt.html>`_ for the canonical description of the
 
 Security Issues
 ===============
-See the warning at the top of this page about the tradeoff between memory usage
-and security that comes as part of altering scrypt's rounds parameter.
+`SCrypt <http://www.tarsnap.com/scrypt.html>`_ is the first in a class of "memory-hard"
+key derivation functions. Initially, it looked very promising as a replacement for BCrypt,
+PBKDF2, and SHA512-Crypt.  However, the fact that it's ``N`` parameter controls both
+time *and* memory cost means the two cannot be varied completely independantly.  This
+eventually proved to be problematic, as ``N`` values required for even BCrypt levels of security
+resulting in memory requirements that were unacceptable on most production systems.
+
+.. seealso::
+
+   :class:`~passlib.hash.argon2`, a next generation memory-hard KDF designed as the
+   successor to SCrypt.
 
 .. rubric:: Footnotes
 
diff --git a/docs/lib/passlib.hash.sha256_crypt.rst b/docs/lib/passlib.hash.sha256_crypt.rst
index aca2f9a..adc5557 100644
--- a/docs/lib/passlib.hash.sha256_crypt.rst
+++ b/docs/lib/passlib.hash.sha256_crypt.rst
@@ -11,7 +11,7 @@ The design involves repeated composition of the underlying digest algorithm,
 using various arbitrary permutations of inputs.
 SHA-512 / SHA-256 Crypt are currently the default password hash for many systems
 (notably Linux), and have no known weaknesses.
-SHA-256 Crypt is one of the three hashes Passlib :ref:`recommends <recommended-hashes>`
+SHA-256 Crypt is one of the four hashes Passlib :ref:`recommends <recommended-hashes>`
 for new applications.
 This class can be used directly as follows::
 
diff --git a/docs/lib/passlib.utils.rst b/docs/lib/passlib.utils.rst
index ef6432d..fc08f13 100644
--- a/docs/lib/passlib.utils.rst
+++ b/docs/lib/passlib.utils.rst
@@ -217,8 +217,6 @@ There are also a few sub modules which provide additional utility functions:
     passlib.utils.handlers
     passlib.utils.des
     passlib.utils.pbkdf2
-    passlib.crypto.digest
-    passlib.crypto.des
 
 ..
     passlib.utils.compat
diff --git a/docs/new_app_quickstart.rst b/docs/new_app_quickstart.rst
index 6f157bb..508a385 100644
--- a/docs/new_app_quickstart.rst
+++ b/docs/new_app_quickstart.rst
@@ -48,33 +48,53 @@ If you'd like to set up a configuration that's right for your
 application, the first thing to do is choose a password hashing scheme.
 Passlib contains a large number of schemes, but most of them
 should only be used when a specific format is explicitly required.
-For new applications, there are really only three choices [#choices]_:
 
+The Options
+-----------
+There are currently four good choices [#choices]_ for secure hashing:
+
+    * :class:`~passlib.hash.argon2`
     * :class:`~passlib.hash.bcrypt`
     * :class:`~passlib.hash.sha512_crypt`
-    * :class:`~passlib.hash.pbkdf2_sha512`
+    * :class:`~passlib.hash.pbkdf2_sha256` / :class:`~passlib.hash.pbkdf2_sha512`
 
-All three password hashes share the following properties:
+All four hashes share the following properties:
 
     * no known vulnerabilities.
     * based on documented & widely reviewed algorithms.
-    * basic algorithm has seen heavy scrutiny
-      and use for at least 10 years.
     * public-domain or BSD-licensed reference implementations available.
-    * in use across a number of OSes and/or a wide variety of applications.
     * variable rounds for configuring flexible cpu cost on a per-hash basis.
     * at least 96 bits of salt.
+    * basic algorithm has seen heavy scrutiny and use for at least 10 years
+      (except for Argon2, from is from circa 2013).
+    * in use across a number of OSes and/or a wide variety of applications.
 
-The following comparison should help you choose which hash is
-most appropriate for your application; if in doubt,
-any of these is a good choice, though PBKDF2 is probably the best
-for portability.
+Argon2 is much younger than the others, but has seen heavy scrunity,
+and was purpose-designed for password hashing.  In the near future, it stands likely to
+become *THE* recommended standard.
 
 .. rst-class:: html-toggle
 
 Detailed Comparison of Choices
 ------------------------------
 
+Argon2
+......
+:class:`~passlib.hash.argon2` is the newest of the four recommended hashes.
+It was selected as the winner of the `2013 Password Hashing Competition <https://password-hashing.net/>`_,
+and draws on the design and lessons from BCrypt, PBKDF2, and SCrypt.  Despite
+being much newer than the others, it has seen heavy scrutiny.  Since the Argon2 project
+had the foresight to provide not just a reference implementation, but a standard
+hash encoding format, these hashes should be reliably interoperatable across all implementations.
+
+Issues: In it's default configuration, Argon2 uses more memory than the other hashes
+(However, this is one of it's hallmarks as a "memory hard" hashing algorithm, and contributes to it's security.
+Furthermore the exact amount used is configurable).  It's only main drawback is that as of 2016-6-20
+it's only 3 years old.  It's seen only a few minor adjustments since 2013,
+but as it is just now gaining widespread use, the next few years are the period in which it will
+likely either prove itself, or be found wanting.  It's for this reason,
+any cryptographic algorithm less than a decade old is generally considered "young" :)
+
 BCrypt
 ......
 :class:`~passlib.hash.bcrypt`
@@ -91,13 +111,9 @@ this matter of concern is what motivated the development of SHA512-Crypt.
 As well, its rounds parameter is logarithmically scaled,
 making it hard to fine-tune the amount of time taken to verify passwords;
 which can be an issue for applications that handle a large number
-of simultaneous logon attempts (e.g. web apps).
-
-.. note::
-
-    For BCrypt support on non-BSD systems,
-    Passlib requires the C-extension provided by the
-    `bcrypt <https://pypi.python.org/pypi/bcrypt>`_ package.
+of simultaneous logon attempts (e.g. web apps). Finally, BCrypt only hashes
+the first 72 characters of a password, and will silently truncate longer ones
+(Passlib's non-standard :class:`~passlib.hash.bcrypt_sha256` works around this last issue).
 
 SHA512-Crypt
 ............
@@ -121,8 +137,11 @@ version for use in a pre-computed or brute-force search.
 However, this design also hampers analysis of the algorithm
 for future flaws.
 
-*While this algorithm is still considered secure, it has fallen slightly out of favor
-in comparison to bcrypt & pbkdf2, due to it's non-standard construction.*
+While this algorithm is still considered secure, it has fallen out of favor
+in comparison to bcrypt & pbkdf2, due to it's non-standard construction.
+
+Furthermore, when compared to Argon2 and BCrypt,
+SHA512-Crypt and PBKDF2 have proven more susceptible to cracking using modern GPU-based techniques.
 
 .. index:: Google App Engine; recommended hash algorithm
 
@@ -158,21 +177,51 @@ in recent years; mainly hampered by the fact that there is no
 standard format for encoding password hashes using this algorithm
 (which is why Passlib has its own :ref:`custom format <mcf-pbkdf2-format>`).
 
-.. note::
+Furthermore, when compared to Argon2 and BCrypt, PBKDF2 has proven more susceptible to cracking
+using modern GPU-based techniques.
+
+Making Descision
+----------------
+For new applications, this decision comes down to a couple of questions:
+
+1. Does the hash need to be natively supported by your operating system's :func:`!crypt` api,
+   in order to allow inter-operation with third-party applications on the host?
+
+   * If so, the right choice is either :class:`~passlib.hash.bcrypt` for BSD variants,
+     or :class:`~passlib.hash.sha512_crypt` for Linux; since these are natively supported.
+
+   * If not, continue...
+
+2. Does your hosting prevent you from installing C extensions?
+
+   * If yes, you probably want to use :class:`~passlib.hash.pbkdf2_sha256` / :class:`~passlib.hash.pbkdf2_sha512`;
+     This is currently the option with the fastest pure-python backend.
+
+   * If they allow C extensions, continue...
+
+3. Do you want to use the latest, greatest, and don't mind increased memory usage
+   per hash?
+
+   * :class:`~passlib.hash.argon2` is a next-generation hashing algorithm,
+     attempting to become the new standard.  It's design has been being slightly tweaked
+     since 2013, but will quite likely become *the* standard in the next few years.
+     You'll need to install the `argon2_cffi  <https://pypi.python.org/pypi/argon2_cffi>`_
+     support library.
+
+   * If you want something secure, but battle tested, continue...
+
+4. The top two choices left are :class:`~passlib.hash.bcrypt` and :class:`~passlib.hash.pbkdf2_sha256`.
 
-    Passlib strongly suggests installing
-    the external M2Crypto package to speed up PBKDF2 calculations,
-    though this is not required.
+   Both have advantages, and their respective rough edges;
+   though currently the balance is in favor of :class:`~passlib.hash.bcrypt`
+   (pbkdf2 can be cracked somewhat more efficiently).
 
-.. index:: SCrypt; status of
+   * If choosing bcrypt, we strongly recommend installing the `bcrypt <https://pypi.python.org/pypi/bcrypt>`_
+     support library on non-BSD operating systems.
 
-What about SCrypt?
-..................
-`SCrypt <http://www.tarsnap.com/scrypt.html>`_ is the first in a class of "memory-hard"
-key derivation functions.  Passlib supports hashing passwords with SCrypt via the
-:class:`~passlib.hash.scrypt` password hash.  However, it is not currently recommended for use
-unless you know what you're doing, as selection of an appropriate secure set of rounds parameters
-is very dependant on your serve load, and may frequently not be possible.
+   * If choosing pbkdf2, especially on python2 < 2.7.8 and python 3 < 3.4,
+     you will probably want to install `fastpbk2 <https://pypi.python.org/pypi/fastpbkdf2>`_
+     support library.
 
 Creating and Using a CryptContext
 =================================
@@ -200,7 +249,7 @@ Insert the following code into your application::
         # set the number of rounds that should be used...
         # (appropriate values may vary for different schemes,
         # and the amount of time you wish it to take)
-        pbkdf2_sha256__default_rounds = 29000,
+        pbkdf2_sha256__rounds = 29000,
         )
 
 To start using your CryptContext, import the context you created wherever it's needed::