various bcrypt improvements

* studied crypt_blowfish's 8bit bug
	- verified none of passlib's backends were affected
	- added recognition (but not support) for crypt_blowfish's $2x$ hash prefix
	- added support for crypt_blowfish's $2y$ hash prefix
	- note in docs about Passlib's current handling of crypt_blowfish 8bit issues.
* refactored bcrypt's salt-unused-bits repair code into Base64Engine.repair_unused(),
  making the code cleaner and more isolated. a bunch more tests.
* added bcrypt64 (bcrypt-base64 variant) to utils
* added LazyBase64Engine to reduce memory / startup time

1 files changed, 33 insertions, 3 deletions

diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
index 27027b4..11c1a25 100644
--- a/docs/lib/passlib.hash.bcrypt.rst
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -62,7 +62,9 @@ Bcrypt hashes have the format :samp:`$2a${rounds}${salt}{checksum}`, where:
 * :samp:`{salt}` is the 22 character salt string, using the characters in the regexp range ``[./A-Za-z0-9]`` (``GhvMmNVjRW29ulnudl.Lbu`` in the example).
 * :samp:`{checksum}` is the 31 character checksum, using the same characters as the salt (``AnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m`` in the example).
 
-BCrypt's algorithm is described in detail in it's specification document [#f1]_.
+While BCrypt's basic algorithm is described in it's design document [#f1]_,
+the OpenBSD implementation [#f2]_ is considered the canonical reference, even 
+though it differs from the design document in a few small ways.
 
 Deviations
 ==========
@@ -99,10 +101,38 @@ This implementation of bcrypt differs from others in a few ways:
   will reject all passwords if these padding bits are not set to 0.
   Due to a legacy issue with Passlib <= 1.5.2,
   Passlib instead prints a warning if it encounters hashes with any padding bits set,
-  and will then validate them correctly. 
+  and will then validate them correctly.
   (This behavior will eventually be deprecated and such hashes
   will throw a :exc:`ValueError` instead).
 
+* crypt_blowfish 2x/2y hashes
+
+  Pre-1.1 versions of the `crypt_blowfish <http://www.openwall.com/crypt/>`_
+  bcrypt implementation suffered from a serious flaw [#eight]_
+  in how they handled 8-bit passwords. The manner in which the flaw was fixed resulted
+  in two new bcrypt hash identifiers:
+
+  ``$2x$``, allowing sysadmins to mark ``$2a$`` hashes which potentially were
+  generated with the buggy algorithm. Passlib 1.6 recognizes, but does not
+  currently support generating or verifying these hashes.
+
+  ``$2y$``, the default for crypt_blowfish 1.1 and newer, indicates
+  the hash was generated with the canonical OpenBSD-compatible algorithm,
+  and should match *correctly* generated ``$2a$`` hashes. 
+  Passlib 1.6 can generate and verify these hashes.
+
+  As well, crypt_blowfish 1.2 modified the way it generates ``$2a$`` hashes,
+  so that passwords containing the byte value 0xFF are hashed in a manner
+  incompatible with either the buggy or canonical algorithms. Passlib
+  does not support this variant either, though it should rarely be needed.
+
 .. rubric:: Footnotes
 
-.. [#f1] `<http://www.usenix.org/event/usenix99/provos/provos_html/>`_ - the bcrypt format specification
+.. [#f1] the bcrypt format specification -
+         `<http://www.usenix.org/event/usenix99/provos/provos_html/>`_
+
+.. [#f2] the OpenBSD BCrypt source -
+         `<http://www.openbsd.org/cgi-bin/cvsweb/src/lib/libc/crypt/bcrypt.c>`_
+
+.. [#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>`_