diff options
Diffstat (limited to 'docs/lib')
| -rw-r--r-- | docs/lib/passlib.hash.bcrypt.rst | 36 |
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>`_ |