passlib.hash.bcrypt - BCrypt

BCrypt was developed to replace md5_crypt for BSD systems. It uses a modified version of the Blowfish stream cipher. Featuring a large salt and variable number of rounds, it’s currently the default password hash for many systems (notably BSD), and has no known weaknesses. It is one of the three hashes Passlib recommends for new applications. This class can be used directly as follows:

>>> from passlib.hash import bcrypt

>>> # generate new salt, encrypt password
>>> h = bcrypt.encrypt("password")
>>> h
'$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy'

>>> # the same, but with an explicit number of rounds
>>> bcrypt.encrypt("password", rounds=8)
'$2a$08$8wmNsdCH.M21f.LSBSnYjQrZ9l1EmtBc9uNPGL.9l75YE8D8FlnZC'

>>> # verify password
>>> bcrypt.verify("password", h)
True
>>> bcrypt.verify("wrong", h)
False

Note

It is strongly recommended that you install py-bcrypt when using this hash.

See also

the generic PasswordHash usage examples

Interface

class passlib.hash.bcrypt

This class implements the BCrypt password hash, and follows the Password Hash Interface.

It supports a fixed-length salt, and a variable number of rounds.

The encrypt() and genconfig() methods accept the following optional keywords:

Parameters:

• salt (str) – Optional salt string. If not specified, one will be autogenerated (this is recommended). If specified, it must be 22 characters, drawn from the regexp range [./0-9A-Za-z].
• rounds (int) – Optional number of rounds to use. Defaults to 12, must be between 4 and 31, inclusive. This value is logarithmic, the actual number of iterations used will be 2**rounds – increasing the rounds by +1 will double the amount of time taken.
• ident (str) –

  Specifies which version of the BCrypt algorithm will be used when creating a new hash. Typically this option is not needed, as the default ("2a") is usually the correct choice. If specified, it must be one of the following:

  • "2" - the first revision of BCrypt, which suffers from a minor security flaw and is generally not used anymore.
  • "2a" - latest revision of the official BCrypt algorithm, and the current default.
  • "2y" - format specific to the crypt_blowfish BCrypt implementation, identical to "2a" in all but name.
• relaxed (bool) –

  By default, providing an invalid value for one of the other keywords will result in a ValueError. If relaxed=True, and the error can be corrected, a PasslibHashWarning will be issued instead. Correctable errors include rounds that are too small or too large, and salt strings that are too long.

  New in version 1.6.

Changed in version 1.6: This class now supports "2y" hashes, and recognizes (but does not support) the broken "2x" hashes. (see the crypt_blowfish bug for details).

Changed in version 1.6: Added a pure-python backend.

Note

This class will use the first available of four possible backends:

1. py-bcrypt, if installed.
2. bcryptor, if installed.
3. stdlib’s crypt.crypt(), if the host OS supports BCrypt (primarily BSD-derived systems).
4. A pure-python implementation of BCrypt, built into Passlib.

If no backends are available, encrypt() and verify() will throw MissingBackendError when they are invoked. You can check which backend is in use by calling bcrypt.get_backend().

Warning

The pure-python backend (#4) is disabled by default!

That backend is currently too slow to be usuable given the number of rounds required for security. That said, if you have no other alternative and need to use it, set the environmental variable PASSLIB_BUILTIN_BCRYPT="enabled" before importing Passlib.

What’s “too slow”? Passlib’s rounds selection guidelines currently require BCrypt be able to do >= 12 cost in <= 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!)

Format & Algorithm

Bcrypt is compatible with the Modular Crypt Format, and uses $2$ and $2a$ as the identifying prefix for all it’s strings ($2$ is seen only for legacy hashes which used an older version of Bcrypt). An example hash (of password) is:

$2a$12$GhvMmNVjRW29ulnudl.LbuAnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m

Bcrypt hashes have the format $2a$rounds$saltchecksum, where:

• rounds is a cost parameter, encoded as 2 zero-padded decimal digits, which determines the number of iterations used via iterations=2**rounds (rounds is 12 in the example).
• salt is a 22 character salt string, using the characters in the regexp range [./A-Za-z0-9] (GhvMmNVjRW29ulnudl.Lbu in the example).
• checksum is a 31 character checksum, using the same characters as the salt (AnUtN/LRfe1JsBm1Xu6LE3059z5Tr8m in the example).

While BCrypt’s basic algorithm is described in it’s design document [1], the OpenBSD implementation [2] is considered the canonical reference, even though it differs from the design document in a few small ways.

Deviations

This implementation of bcrypt differs from others in a few ways:

• Restricted salt string character set:

  BCrypt does not specify what the behavior should be when passed a salt string outside of the regexp range [./A-Za-z0-9]. In order to avoid this situtation, Passlib strictly limits salts to the allowed character set, and will throw a ValueError if an invalid salt character is encountered.

• Unicode Policy:

  The underlying algorithm takes in a password specified as a series of non-null bytes, and does not specify what encoding should be used; though a us-ascii compatible encoding is implied by nearly all implementations of bcrypt as well as all known reference hashes.

  In order to provide support for unicode strings, Passlib will encode unicode passwords using utf-8 before running them through bcrypt. If a different 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 will print a warning if it encounters hashes with any padding bits set, and then validate the hash as if the padding bits were cleared. (This behavior will eventually be deprecated and such hashes will throw a ValueError instead).

• The crypt_blowfish 8-bit bug

  Pre-1.1 versions of the crypt_blowfish bcrypt implementation suffered from a serious flaw [3] in how they handled 8-bit passwords. The manner in which the flaw was fixed resulted in crypt_blowfish adding support for two new BCrypt hash identifiers:

  $2x$, allowing sysadmins to mark any $2a$ hashes which were potentially 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 algorithmic variant either, though it should be very rarely encountered in practice.

Footnotes

[1]	the bcrypt format specification - http://www.usenix.org/event/usenix99/provos/provos_html/

[2]	the OpenBSD BCrypt source - http://www.openbsd.org/cgi-bin/cvsweb/src/lib/libc/crypt/bcrypt.c

[3]	The flaw in pre-1.1 crypt_blowfish is described here - CVE-2011-2483