Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Zozi96/hash-forge/llms.txt

Use this file to discover all available pages before exploring further.

BCryptSha256Hasher and BCryptHasher are adaptive password hashers that use the bcrypt algorithm. The cost parameter (rounds) controls hashing time exponentially, making it straightforward to increase security as hardware improves. BCryptSha256Hasher adds a SHA-256 pre-digest step to safely handle passwords longer than bcrypt’s native 72-byte limit, while BCryptHasher passes the password directly to bcrypt without any pre-processing.

​
Installation

The bcrypt package is required. Install it via the bcrypt extra: 
pip install "hash-forge[bcrypt]"

​
Import

from hash_forge.hashers import BCryptHasher, BCryptSha256Hasher

​
BCryptSha256Hasher

The recommended bcrypt hasher. Before calling bcrypt it hex-encodes the SHA-256 digest of the password, ensuring that arbitrarily long passwords are handled safely and deterministically. 
algorithm = 'bcrypt_sha256'

​
Constructor

BCryptSha256Hasher(rounds: int = 12)
​
rounds
int
default:"12"
The bcrypt cost factor. The number of bcrypt iterations is 2 ** rounds. Must be at least 12; raises InvalidHasherError for lower values.

​
Hash format

bcrypt_sha256$<version>$<rounds>$<bcrypt_hash>
The prefix bcrypt_sha256 is prepended to the raw bcrypt output (which itself encodes version, rounds, salt, and hash separated by $).

​
Methods

​
hash(string: str) -> str

Pre-digests the password with SHA-256 (hex-encoded), then hashes the result with bcrypt using a freshly generated salt.

​
verify(string: str, hashed_string: str) -> bool

Applies the same SHA-256 pre-digest to string and delegates to bcrypt.checkpw for constant-time comparison.

​
needs_rehash(hashed_string: str) -> bool

Returns True when the rounds value embedded in hashed_string differs from the rounds the hasher was constructed with.

​
BCryptHasher

A subclass of BCryptSha256Hasher with digest = None. The password is passed to bcrypt without any pre-digest. 
algorithm = 'bcrypt'

​
Constructor

BCryptHasher(rounds: int = 12)
​
rounds
int
default:"12"
The bcrypt cost factor. Must be at least 12; raises InvalidHasherError for lower values.

​
Hash format

bcrypt$<version>$<rounds>$<bcrypt_hash>
bcrypt silently truncates passwords longer than 72 bytes. If a user’s password exceeds this length, bcrypt will hash only the first 72 bytes — two different passwords that share the same first 72 bytes will produce the same hash. Use BCryptSha256Hasher for all user-facing APIs to avoid this issue.

​
Code examples

from hash_forge.hashers import BCryptSha256Hasher, BCryptHasher

# Recommended: SHA-256 pre-digest handles long passwords safely
sha256_hasher = BCryptSha256Hasher(rounds=12)
hashed = sha256_hasher.hash("super_secure_password")
assert sha256_hasher.verify("super_secure_password", hashed)
assert sha256_hasher.needs_rehash(hashed) == False

# Increase cost and detect old hashes
strong_hasher = BCryptSha256Hasher(rounds=14)
assert strong_hasher.needs_rehash(hashed) == True

# Plain bcrypt — no pre-digest
bcrypt_hasher = BCryptHasher(rounds=12)
plain_hashed = bcrypt_hasher.hash("short_password")
assert bcrypt_hasher.verify("short_password", plain_hashed)

Build docs developers (and LLMs) love

Get started for freeTalk to us