.. image:: https://img.shields.io/pypi/v/bcrypt.svg :target: https://pypi.org/project/bcrypt/ :alt: Latest Version
.. image:: https://github.com/pyca/bcrypt/workflows/CI/badge.svg?branch=main :target: https://github.com/pyca/bcrypt/actions?query=workflow%3ACI+branch%3Amain
Acceptable password hashing for your software and your servers (but you should really use argon2id or scrypt)
To install bcrypt, simply:
.. code:: console
$ pip install bcrypt
Note that bcrypt should build very easily on Linux provided you have a C compiler and a Rust compiler (the minimum supported Rust version is 1.56.0).
For Debian and Ubuntu, the following command will ensure that the required dependencies are installed:
.. code:: console
$ sudo apt-get install build-essential cargo
For Fedora and RHEL-derivatives, the following command will ensure that the required dependencies are installed:
.. code:: console
$ sudo yum install gcc cargo
For Alpine, the following command will ensure that the required dependencies are installed:
.. code:: console
$ apk add --update musl-dev gcc cargo
While bcrypt remains an acceptable 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.
manylinux wheels for PyPy 3.9.BCRYPT_ALLOW_RUST_163 environment variable.py37 and py39 wheels. This should resolve some errors
relating to initializing a module multiple times per process.kdf method.BCRYPT_ALLOW_RUST_163 environment variable)manylinux wheels.salt to checkpw could result in
a pyo3_runtime.PanicException. It now correctly raises a ValueError.bcrypt is now implemented in Rust. Users building from source will need
to have a Rust compiler available. Nothing will change for users downloading
wheels.manylinux2010 wheels. Users should upgrade to the latest
pip to ensure this doesn’t cause issues downloading wheels on their
platform. We now ship manylinux_2_28 wheels for users on new enough platforms.NUL bytes are now allowed in inputs.py.typed files in wheels so that mypy works.bcrypt with be 4.0 and it will require Rust at
compile time, for users building from source. There will be no additional
requirement for users who are installing from wheels. Users on most
platforms will be able to obtain a wheel by making sure they have an up to
date pip. The minimum supported Rust version will be 1.56.0.manylinux2010 wheels.
Going forward the minimum supported manylinux ABI for our wheels will be
manylinux2014. The vast majority of users will continue to receive
manylinux wheels provided they have an up to date pip.abi3 Windows wheels (requires pip >= 20).setuptools lower bound for PEP517 wheel building.manylinux1 wheels. Continuing to produce
them was a maintenance burden.abi3 wheels for Python 3. If you are not getting a
wheel on a compatible platform please upgrade your pip version.kdf.UserWarning when used with cffi 1.8.3.checkpw, a convenience method for verifying a password.$2y$ hash when you input a $2y$ salt.$2a hashes were vulnerable to a wraparound bug.bcrypt_pbkdf via the kdf function.gensalt.Password Hashing
Hashing and then later checking that a password matches the previous hashed
password is very simple:
.. code:: pycon
>>> 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 :(")
KDF
~~~
As of 3.0.0 ``bcrypt`` now offers a ``kdf`` function which does ``bcrypt_pbkdf``.
This KDF is used in OpenSSH's newer encrypted private key format.
.. code:: pycon
>>> 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):
.. code:: pycon
>>> 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 :(")
Adjustable Prefix
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 ``2a`` or
``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
bcrypt:
.. code:: pycon
>>> 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.
bcrypt follows the same security policy as cryptography_, if you
identify a vulnerability, we ask you to contact us privately.
.. _same security policy as cryptography: https://cryptography.io/en/latest/security.html
.. _standard library: https://docs.python.org/3/library/hashlib.html#hashlib.scrypt
.. _argon2_cffi: https://argon2-cffi.readthedocs.io
.. _cryptography: https://cryptography.io/en/latest/hazmat/primitives/key-derivation-functions/#cryptography.hazmat.primitives.kdf.scrypt.Scrypt
FAQs
Modern password hashing for your software and your servers
We found that bcrypt demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.