bunch of bcrypt updates, centered around the bsd wraparound bug.

bcrypt
------
* added support & UT for $2b$ hash format.
  not making it the default yet, for backward compat.

* large refactor of how bcrypt backends are loaded:
  instead of per-backend workarounds within each _calc_checksum_<backend>()
  function: now using runtime detection of specific capabilities & workarounds,
  that runs whenever set_backend() is called, combined with consolidated
  workaround code within _calc_checksum(), controlled by the flags
  set by set_backend().

  this detection now looks for:
    - the 8bit bug: throws a PasslibSecurityError
    - the wraparound bug: issues warning, sets flag enabling a workaround.
    - support for 2/2y/2b: if backend lacks support for particular variants,
      sets flag enabling workaround to add support.

* os_crypt backend now just issues error if it can't handle a password encoding;
  rather than trying fallbacks first -- edge case anyways, and likely
  to not have any fallbacks when it does happen. simplifies backend code.

* added UTs to make sure wraparound-vulnerable passwords are hashed correctly
  (as a 72char string, not a 1-3 char string that's repeated).

* internal blowfish code's ident parsing clarified.

other
-----
* added exc.PasslibSecurityError for fatal runtime errors.

* test framework: os_crypt backends no longer expected to use
  *any* backend as fallback, just ones with lower priority than os_crypt.

* test framework: crypt_stub() wrapper now subclasses the handler,
  so it can use an independant backend, instead of changing global
  backend for duration of call (made parallel testing hard)

docs
----
* added entry to bcrypt page, writing down wraparound bug details,
  and how passlib is handling it.

* all versions of pybcrypt & bcryptor seem to be vulnerable to wraparound bug.
  starting process of deprecating these backends: marked bcrypt backend
  as 'preferred' throughout the documentation.

4 files changed, 58 insertions, 17 deletions

diff --git a/docs/install.rst b/docs/install.rst
index 9407673..147cb60 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -31,8 +31,8 @@ Google App Engine is supported as well.
 
 Optional Libraries
 ==================
-* `bcrypt <https://pypi.python.org/pypi/bcrypt>`_ or
-  `py-bcrypt <https://pypi.python.org/pypi/py-bcrypt>`_ or
+* `bcrypt <https://pypi.python.org/pypi/bcrypt>`_ (preferred), or
+  `py-bcrypt <https://pypi.python.org/pypi/py-bcrypt>`_, or
   `bcryptor <https://bitbucket.org/ares/bcryptor/overview>`_
 
    If any of these packages are installed, they will be used to provide
diff --git a/docs/lib/passlib.exc.rst b/docs/lib/passlib.exc.rst
index 96be468..e30338a 100644
--- a/docs/lib/passlib.exc.rst
+++ b/docs/lib/passlib.exc.rst
@@ -17,6 +17,8 @@ Exceptions
 
 .. autoexception:: PasswordSizeError
 
+.. autoexception:: PasslibSecurityError
+
 Warnings
 ========
 .. autoexception:: PasslibWarning
diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
index 041a2bf..55566fa 100644
--- a/docs/lib/passlib.hash.bcrypt.rst
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -32,7 +32,6 @@ for new applications. This class can be used directly as follows::
 
     It is strongly recommended that you install
     `bcrypt <https://pypi.python.org/pypi/bcrypt>`_
-    or `py-bcrypt <https://pypi.python.org/pypi/py-bcrypt>`_
     when using this hash.
 
 .. seealso:: the generic :ref:`PasswordHash usage examples <password-hash-examples>`
@@ -46,23 +45,30 @@ Interface
 .. index::
     pair: environmental variable; PASSLIB_BUILTIN_BCRYPT
 
-.. note::
+Bcrypt Backends
+---------------
+
+This class will use the first available of five possible backends:
 
-    This class will use the first available of five possible backends:
+1. `bcrypt <https://pypi.python.org/pypi/bcrypt>`_, if installed.
+2. `py-bcrypt <https://pypi.python.org/pypi/py-bcrypt>`_, if installed.
+3. `bcryptor <https://bitbucket.org/ares/bcryptor/overview>`_, if installed.
+4. stdlib's :func:`crypt.crypt()`, if the host OS supports BCrypt
+   (primarily BSD-derived systems).
+5. A pure-python implementation of BCrypt, built into Passlib.
 
-    1. `bcrypt <https://pypi.python.org/pypi/bcrypt>`_, if installed.
-    2. `py-bcrypt <https://pypi.python.org/pypi/py-bcrypt>`_, if installed.
-    3. `bcryptor <https://bitbucket.org/ares/bcryptor/overview>`_, if installed.
-    4. stdlib's :func:`crypt.crypt()`, if the host OS supports BCrypt
-       (primarily BSD-derived systems).
-    5. A pure-python implementation of BCrypt, built into Passlib.
+If no backends are available, :meth:`encrypt` and :meth:`verify`
+will throw :exc:`~passlib.exc.MissingBackendError` when they are invoked.
+You can check which backend is in use by calling :meth:`!bcrypt.get_backend()`.
 
-    If no backends are available, :meth:`encrypt` and :meth:`verify`
-    will throw :exc:`~passlib.exc.MissingBackendError` when they are invoked.
-    You can check which backend is in use by calling :meth:`!bcrypt.get_backend()`.
+As of Passlib 1.6.3, a one-time check is peformed when the backend is first loaded,
+to detect the backend's capabilities & bugs.  If this check detects a fatal bug,
+a :exc:`~passlib.exc.PasslibSecurityError` will be raised.  This generally means
+you need to upgrade the external package being used as the backend
+(this will be detailed in the error message).
 
 .. warning::
-    The pure-python backend (#5) is disabled by default!
+    *The pure-python backend (#5) is disabled by default!*
 
     That backend is currently too slow to be usable given the number of rounds required
     for security. That said, if you have no other alternative and need to use it,
@@ -70,7 +76,7 @@ Interface
     before importing Passlib.
 
     What's "too slow"? Passlib's :ref:`rounds selection guidelines <rounds-selection-guidelines>`
-    currently require BCrypt be able to do >= 12 cost in <= 300ms. By this standard
+    currently require BCrypt be able to do at least 12 cost in under 300ms. By this standard
     the pure-python backend is 128x too slow under CPython 2.7, and 16x too slow under PyPy 1.8.
     (speedups are welcome!)
 
@@ -171,6 +177,37 @@ This implementation of bcrypt differs from others in a few ways:
   does not support this algorithmic variant either, though it should
   be *very* rarely encountered in practice.
 
+  .. versionchanged:: 1.6.3
+
+        Passlib will now detect, and refuse to use, any backend which is vulnerable
+        to this bug.
+
+* The 'BSD wraparound' bug
+
+  .. _bsd-wraparound-bug:
+
+  OpenBSD <= 5.4, and most bcrypt libraries derived from it's source,
+  are vulnerable to a 'wraparound' bug [#wraparound]_, where passwords larger
+  than 254 characters will be incorrectly hashed using only the first few
+  characters of the string, resulting in a severely weakened hash.
+
+  OpenBSD 5.5 `fixed <http://undeadly.org/cgi?action=article&sid=20140224132743>`_ this flaw,
+  and introduced the ``$2b$`` hash identifier to indicate the hash was generated with the correct
+  algorithm.
+
+  py-bcrypt <= 0.4 is known to be vulnerable to this, as well as the os_crypt
+  backend (if running on a vulnerable operating system).
+
+  Passlib 1.6.3 adds the following:
+
+  * Support for the ``$2b$`` hash format (though for backward compat it has not been made
+    the default yet).
+
+  * Detects if the active backend is vulnerable to the bug, issues a warning,
+    and enables a workaround so that vulnerable passwords will still be hashed correctly.
+    (This does mean that existing hashes suffering this vulnerability will no longer verify
+    using their correct password).
+
 .. rubric:: Footnotes
 
 .. [#f1] the bcrypt format specification -
@@ -181,3 +218,6 @@ This implementation of bcrypt differs from others in a few ways:
 
 .. [#eight] The flaw in pre-1.1 crypt_blowfish is described here -
             `CVE-2011-2483 <http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-2483>`_
+
+.. [#wraparound] The wraparound flaw is described here -
+            `<http://www.openwall.com/lists/oss-security/2012/01/02/4>`_
\ No newline at end of file
diff --git a/docs/lib/passlib.hash.bcrypt_sha256.rst b/docs/lib/passlib.hash.bcrypt_sha256.rst
index 22420db..255455f 100644
--- a/docs/lib/passlib.hash.bcrypt_sha256.rst
+++ b/docs/lib/passlib.hash.bcrypt_sha256.rst
@@ -34,7 +34,6 @@ This class can be used directly as follows::
 
     It is strongly recommended that you install
     `bcrypt <https://pypi.python.org/pypi/bcrypt>`_
-    or `py-bcrypt <https://pypi.python.org/pypi/py-bcrypt>`_
     when using this hash. See :doc:`passlib.hash.bcrypt` for more details.
 
 Interface