bcrypt padding work:

* added changelog entry re: issue & fix
* bcrypt now warns about padding bits in digest as well
* bcrypt.normhash() now normalizes salt padding bits, digest padding bits, and rounds zero-padding
* hash_needs_update() will now flag unclean bcrypt hashes as needing an update
* UTs for hash_needs_update(), and digest padding bit handling

1 files changed, 13 insertions, 0 deletions

diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
index 2b9a22d..27027b4 100644
--- a/docs/lib/passlib.hash.bcrypt.rst
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -90,6 +90,19 @@ This implementation of bcrypt differs from others in a few ways:
   encoding is desired by an application, the password should be encoded
   before handing it to PassLib.
 
+* Padding Bits
+
+  BCrypt's base64 encoding results in the last character of the salt
+  encoding only 2 bits of data, the remaining 4 are "padding" bits.
+  Similarly, the last character of the digest contains 4 bits of data,
+  and 2 padding bits. Because of the way they are coded, many BCrypt implementations
+  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. 
+  (This behavior will eventually be deprecated and such hashes
+  will throw a :exc:`ValueError` instead).
+
 .. rubric:: Footnotes
 
 .. [#f1] `<http://www.usenix.org/event/usenix99/provos/provos_html/>`_ - the bcrypt format specification