Good password hashing for your software and your servers
To install bcrypt, simply:
$ pip install bcrypt
Note that bcrypt should build very easily on Linux provided you have a C compiler, headers for Python (if you're not using pypy), and headers for the libffi libraries available on your system.
For Debian and Ubuntu, the following command will ensure that the required dependencies are installed:
$ sudo apt-get install build-essential libffi-dev python-dev
For Fedora and RHEL-derivatives, the following command will ensure that the required dependencies are installed:
$ sudo yum install gcc libffi-devel python-devel
For Alpine, the following command will ensure that the required dependencies are installed:
$ apk add --update musl-dev gcc libffi-dev
While bcrypt remains a good choice for password storage depending on your specific use case you may also want to consider using scrypt (either via standard library or cryptography) or argon2id via argon2_cffi.
- Added typehints for library functions.
- Dropped support for Python versions less than 3.6 (2.7, 3.4, 3.5).
abi3Windows wheels (requires pip >= 20).
- Set a
setuptoolslower bound for PEP517 wheel building.
- We no longer distribute 32-bit
manylinux1wheels. Continuing to produce them was a maintenance burden.
- Added support for compilation on Haiku.
- Added support for compilation on AIX.
- Dropped Python 2.6 and 3.3 support.
- Switched to using
abi3wheels for Python 3. If you are not getting a wheel on a compatible platform please upgrade your
- Fixed compilation with mingw and on illumos.
- Fixed a compilation issue on Solaris.
- Added a warning when using too few rounds with
- Fixed a compile issue affecting big endian platforms.
- Fixed invalid escape sequence warnings on Python 3.6.
- Fixed building in non-UTF8 environments on Python 2.
- Resolved a
UserWarningwhen used with
- Added support for
checkpw, a convenience method for verifying a password.
- Ensure that you get a
$2y$hash when you input a
- Fixed a regression where
$2ahashes were vulnerable to a wraparound bug.
- Fixed compilation under Alpine Linux.
- Switched the C backend to code obtained from the OpenBSD project rather than openwall.
- Added support for
- Added support for an adjustible prefix when calling
- Switched to CFFI 1.0+
Hashing and then later checking that a password matches the previous hashed password is very simple:
>>> import bcrypt >>> password = b"super secret password" >>> # Hash a password for the first time, with a randomly-generated salt >>> hashed = bcrypt.hashpw(password, bcrypt.gensalt()) >>> # Check that an unhashed password matches one that has previously been >>> # hashed >>> if bcrypt.checkpw(password, hashed): ... print("It Matches!") ... else: ... print("It Does not Match :(")
As of 3.0.0
bcrypt now offers a
kdf function which does
This KDF is used in OpenSSH's newer encrypted private key format.
>>> import bcrypt >>> key = bcrypt.kdf( ... password=b'password', ... salt=b'salt', ... desired_key_bytes=32, ... rounds=100)
Adjustable Work Factor
One of bcrypt's features is an adjustable logarithmic work factor. To adjust
the work factor merely pass the desired number of rounds to
bcrypt.gensalt(rounds=12) which defaults to 12):
>>> import bcrypt >>> password = b"super secret password" >>> # Hash a password for the first time, with a certain number of rounds >>> hashed = bcrypt.hashpw(password, bcrypt.gensalt(14)) >>> # Check that a unhashed password matches one that has previously been >>> # hashed >>> if bcrypt.checkpw(password, hashed): ... print("It Matches!") ... else: ... print("It Does not Match :(")
Another one of bcrypt's features is an adjustable prefix to let you define what
libraries you'll remain compatible with. To adjust this, pass either
2b (the default) to
bcrypt.gensalt(prefix=b"2b") as a bytes object.
As of 3.0.0 the
$2y$ prefix is still supported in
hashpw but deprecated.
Maximum Password Length
The bcrypt algorithm only handles passwords up to 72 characters, any characters
beyond that are ignored. To work around this, a common approach is to hash a
password with a cryptographic hash (such as
sha256) and then base64
encode it to prevent NULL byte problems before hashing the result with
>>> password = b"an incredibly long password" * 10 >>> hashed = bcrypt.hashpw( ... base64.b64encode(hashlib.sha256(password).digest()), ... bcrypt.gensalt() ... )
This library should be compatible with py-bcrypt and it will run on Python 3.6+, and PyPy 3.
This library uses code from OpenBSD.
bcrypt follows the same security policy as cryptography, if you
identify a vulnerability, we ask you to contact us privately.