BCrypt was developed to replace md5_crypt for BSD systems.It uses a modified version of the Blowfish stream cipher. Featuringa large salt and variable number of rounds, it’s currently the defaultpassword hash for many systems (notably BSD), and has no known weaknesses.It is one of the four hashes Passlib recommendsfor new applications. This class can be used directly as follows:
>>> from passlib.hash import bcrypt>>> # generate new salt, hash password>>> h = bcrypt.hash("password")>>> h'$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy'>>> # the same, but with an explicit number of rounds>>> bcrypt.using(rounds=13).hash("password")'$2b$13$HMQTprwhaUwmir.g.ZYoXuRJhtsbra4uj.qJPHrKsX5nGlhpts0jm'>>> # verify password>>> bcrypt.verify("password", h)True>>> bcrypt.verify("wrong", h)False
Note
It is strongly recommended that you installbcryptwhen 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 PasswordHash API.
It supports a fixed-length salt, and a variable number of rounds.
The using() method accepts the following optional keywords:
See Also[New research] How tough is bcrypt to crack? And can it keep passwords safe?How Tough Is Bcrypt To Crack? Can It Keep Passwords Safe? - Spiceworksbcrypt is just obsolete – this was to find a *successor* to it. yescrypt, one of...How to hash passwords using bcrypt in Node.jsParameters: - 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 (
"2b"
) 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"
- some implementations suffered from rare security flaws, replaced by 2b."2y"
- format specific to the crypt_blowfish BCrypt implementation,identical to"2b"
in all but name."2b"
- latest revision of the official BCrypt algorithm, current default.
- truncate_error (bool) –
By default, BCrypt will silently truncate passwords larger than 72 bytes.Setting
truncate_error=True
will cause hash()to raise a PasswordTruncateError instead.New in version 1.7.
- relaxed (bool) –
By default, providing an invalid value for one of the otherkeywords will result in a
ValueError
. Ifrelaxed=True
,and the error can be corrected, a PasslibHashWarningwill be issued instead. Correctable errors includerounds
that are too small or too large, andsalt
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 bugfor details).Changed in version 1.6: Added a pure-python backend.
Changed in version 1.6.3: Added support for
"2b"
variant.Changed in version 1.7: Now defaults to
"2b"
variant.- 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
Bcrypt Backends¶
Warning
Support for py-bcrypt
and bcryptor
will be dropped in Passlib 1.8,as these libraries are unmaintained.
This class will use the first available of five possible backends:
- bcrypt, if installed.
- py-bcrypt, if installed (DEPRECATED)
- bcryptor, if installed (DEPRECATED).
- stdlib’s
crypt.crypt()
, if the host OS supports BCrypt(primarily BSD-derived systems). - A pure-python implementation of BCrypt, built into Passlib.
If no backends are available, hash()
and verify()
will throw MissingBackendError when they are invoked.You can check which backend is in use by calling bcrypt.get_backend()
.
As of Passlib 1.6.3, a one-time check is peformed when the backend is first loaded,to detect the backend’s capabilities & bugs. If this check detects a fatal bug,a PasslibSecurityError will be raised. This generally meansyou need to upgrade the external package being used as the backend(this will be detailed in the error message).
Warning
The pure-python backend (#5) is disabled by default!
That backend is currently too slow to be usable given the number of rounds requiredfor 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 guidelinescurrently require BCrypt be able to do at least 12 cost in under 300ms. By this standardthe 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 a number of identifyingprefixes: $2$
, $2a$
, $2x$
, $2y$
, and $2b$
. Each prefix indicatesa different revision of the BCrypt algorithm; and all but the $2b$
identifier areconsidered deprecated.
An example hash (of password
) is:
$2b$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 viaiterations=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).Note that due to padding bits within the encoding, the last character should always be one of[.Oeu]
:under some bcrypt implementations, other final characters may result in false negatives when verifying.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 its design document [1],the OpenBSD implementation [2] is considered the canonical reference, eventhough it differs from the design document in a few small ways.
Security Issues¶
Password Truncation.
While not a security issue per-se, bcrypt does have one major limitation:password are truncated on the first NULL byte (if any),and only the first 72 bytes of a password are hashed… all the rest are ignored.Furthermore, bytes 55-72 are not fully mixed into the resulting hash (citation needed!).To work around both these issues, many applications first run the password through a messagedigest such as (HMAC-) SHA2-256. Passlib offers the premade passlib.hash.bcrypt_sha256 - BCrypt+SHA256to take care of this issue.
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 whenpassed a salt string outside of the regexp range
[./A-Za-z0-9]
.In order to avoid this situation, Passlib strictly limits salts to theallowed character set, and will throw aValueError
if an invalidsalt character is encountered.Unicode Policy:
The underlying algorithm takes in a password specifiedas a series of non-null bytes, and does not specify what encodingshould be used; though a
us-ascii
compatible encodingis implied by nearly all implementations of bcryptas 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 differentencoding is desired by an application, the password should be encodedbefore handing it to Passlib.Padding Bits
BCrypt’s base64 encoding results in the last character of the saltencoding 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 implementationswill 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 hasheswill throw a
ValueError
instead).The crypt_blowfish 8-bit bug
Pre-1.1 versions of the crypt_blowfishbcrypt implementation suffered from a serious flaw [3]in how they handled 8-bit passwords. The manner in which the flaw was fixed resultedin crypt_blowfish adding support for two new BCrypt hash identifiers:
$2x$
, allowing sysadmins to mark any$2a$
hashes which were potentiallygenerated with the buggy algorithm. Passlib 1.6 recognizes (but does notcurrently support generating or verifying) these hashes.$2y$
, the default for crypt_blowfish 1.1-1.2, indicatesthe 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 mannerincompatible with either the buggy or canonical algorithms. Passlibdoes not support this algorithmic variant either, though it shouldbe very rarely encountered in practice.(crypt_blowfish 1.3 switched to the
$2b$
standard as the default)Changed in version 1.6.3: Passlib will now throw a PasslibSecurityError if an attempt ismade to use any backend which is vulnerable to this bug.
The ‘BSD wraparound’ bug
OpenBSD <= 5.4, and most bcrypt libraries derived from it’s source,are vulnerable to a ‘wraparound’ bug [4], where passwords largerthan 254 characters will be incorrectly hashed using only the first fewcharacters of the string, resulting in a severely weakened hash.
OpenBSD 5.5 fixed this flaw,and introduced the
$2b$
hash identifier to indicate the hash was generated with the correctalgorithm.py-bcrypt <= 0.4 is known to be vulnerable to this, as well as the os_cryptbackend (if running on a vulnerable operating system).
Passlib 1.6.3 adds the following:
- Support for the
$2b$
hash format (though for backward compat it has not been madethe default yet). - Detects if the active backend is vulnerable to the bug, issues a warning,and enables a workaround so that vulnerable passwords will still be hashed correctly.(This does mean that existing hashes suffering this vulnerability will no longer verifyusing their correct password).
- Support for the
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 |
[4] | The wraparound flaw is described here -http://www.openwall.com/lists/oss-security/2012/01/02/4 |