diff options
author | Eli Collins <elic@assurancetechnologies.com> | 2013-12-26 10:50:07 -0500 |
---|---|---|
committer | Eli Collins <elic@assurancetechnologies.com> | 2013-12-26 10:50:07 -0500 |
commit | 0db4ea7949997265fcaae406a26070af86d4bb65 (patch) | |
tree | d2ddbef22b700f7e97075c15e9e94b700732955e /docs/lib/passlib.hash.bcrypt_sha256.rst | |
parent | 1fe99e524b5d6120b2994b94c2ed9ef2cb3437ad (diff) | |
download | passlib-0db4ea7949997265fcaae406a26070af86d4bb65.tar.gz |
added passlib.hash.bcrypt_sha256
* not too much trouble, and definitely needed.
after considering options, decided to use sha256 + base64.
* added note re: bcrypt password truncation
* HasBackend mixin -- changed to use _calc_checksum_backend()
as the attribute it patches, instead of _calc_checksum().
makes it easier to consolidate code common to all backends (e.g. bcrypt)
* test_60_secret_size: changed hardcoded exception list to a class flag
* added registry test to make sure all hashes are being tested
(with a few known exceptions)
* clarified names inside builtin bcrypt backend
* updated changelog
Diffstat (limited to 'docs/lib/passlib.hash.bcrypt_sha256.rst')
-rw-r--r-- | docs/lib/passlib.hash.bcrypt_sha256.rst | 71 |
1 files changed, 71 insertions, 0 deletions
diff --git a/docs/lib/passlib.hash.bcrypt_sha256.rst b/docs/lib/passlib.hash.bcrypt_sha256.rst new file mode 100644 index 0000000..22420db --- /dev/null +++ b/docs/lib/passlib.hash.bcrypt_sha256.rst @@ -0,0 +1,71 @@ +================================================================== +:class:`passlib.hash.bcrypt_sha256` - BCrypt+SHA256 +================================================================== + +.. versionadded:: 1.6.2 + +.. currentmodule:: passlib.hash + +BCrypt was developed to replace :class:`~passlib.hash.md5_crypt` for BSD systems. +It uses a modified version of the Blowfish stream cipher. +It does, however, truncate passwords to 72 bytes, and some other minor quirks +(see :ref:`BCrypt Password Truncation <bcrypt-password-truncation>` for details). +This class works around that issue by first running the password through SHA2-256. +This class can be used directly as follows:: + + >>> from passlib.hash import bcrypt_sha256 + + >>> # generate new salt, encrypt password + >>> h = bcrypt_sha256.encrypt("password") + >>> h + '$bcrypt-sha256$2a,12$LrmaIX5x4TRtAwEfwJZa1.$2ehnw6LvuIUTM0iz4iz9hTxv21B6KFO' + + >>> # the same, but with an explicit number of rounds + >>> bcrypt.encrypt("password", rounds=8) + '$bcrypt-sha256$2a,8$UE3dIZ.0I6XZtA/LdMrrle$Ag04/5zYu./12.OSqInXZnJ.WZoh1ua' + + >>> # verify password + >>> bcrypt.verify("password", h) + True + >>> bcrypt.verify("wrong", h) + False + +.. note:: + + 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 +========= +.. autoclass:: bcrypt_sha256() + +Format +====== +Bcrypt-SHA256 is compatible with the :ref:`modular-crypt-format`, and uses ``$bcrypt-sha256$`` as the identifying prefix +for all it's strings. +An example hash (of ``password``) is: + + ``$bcrypt-sha256$2a,12$LrmaIX5x4TRtAwEfwJZa1.$2ehnw6LvuIUTM0iz4iz9hTxv21B6KFO`` + +Bcrypt-SHA256 hashes have the format :samp:`$bcrypt-sha256${variant},{rounds}${salt}${checksum}`, where: + +* :samp:`{variant}` is the BCrypt variant in use (usually, as in this case, ``2a``). +* :samp:`{rounds}` is a cost parameter, encoded as decimal integer, + which determines the number of iterations used via :samp:`{iterations}=2**{rounds}` (rounds is 12 in the example). +* :samp:`{salt}` is a 22 character salt string, using the characters in the regexp range ``[./A-Za-z0-9]`` (``LrmaIX5x4TRtAwEfwJZa1.`` in the example). +* :samp:`{checksum}` is a 31 character checksum, using the same characters as the salt (``2ehnw6LvuIUTM0iz4iz9hTxv21B6KFO`` in the example). + +Algorithm +========= +The algorithm this hash uses is as follows: + +* first the password is encoded to ``UTF-8`` if not already encoded. +* then it's run through SHA2-256 to generate a 32 byte digest. +* this is encoded using base64, resulting in a 44-byte result + (including the trailing padding ``=``). For the example ``"password"``, + the output from this stage would be ``"XohImNooBHFR0OVvjcYpJ3NgPQ1qq73WKhHvch0VQtg="``. +* this base64 string is then passed on to the underlying bcrypt algorithm + as the new password to be hashed. See :doc:`passlib.hash.bcrypt` for details + on it's operation. |