PBKDF2Sha256Hasher and PBKDF2Sha1Hasher API Reference

PBKDF2Sha256Hasher and PBKDF2Sha1Hasher are password hashers built on Python’s stdlib hashlib.pbkdf2_hmac. They require no third-party packages, making them the lowest-friction option for environments where dependencies must be kept minimal. Both hashers produce a structured hash string that embeds the iteration count and salt, enabling safe round-trip verification and automatic detection of hashes that need rehashing as cost parameters are raised over time.

Import

from hash_forge.hashers import PBKDF2Sha256Hasher, PBKDF2Sha1Hasher

`PBKDF2Sha256Hasher`

The primary PBKDF2 hasher. Uses SHA-256 as the underlying pseudorandom function.

algorithm = 'pbkdf2_sha256'

Constructor

PBKDF2Sha256Hasher(iterations: int = 150_000, salt_length: int = 16)

iterations

int

default:"150000"

Number of PBKDF2 iterations. Higher values increase resistance to brute-force attacks at the cost of CPU time. Must be at least 150,000; raises InvalidHasherError if below this threshold.

salt_length

int

default:"16"

Number of random bytes used to generate the salt. The salt is hex-encoded before being embedded in the hash string.

Hash format

pbkdf2_sha256$<iterations>$<salt>$<hash>

All four fields are separated by $. The <salt> is a hex-encoded random byte sequence and <hash> is the hex-encoded PBKDF2-derived key.

Methods

`hash(string: str) -> str`

Hashes the given password string. A fresh random salt is generated on every call, so two calls with the same input produce different output.

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

Verifies a plain-text string against a previously produced hashed_string. Re-derives the PBKDF2 key using the salt and iteration count stored in the hash, then compares using hmac.compare_digest to prevent timing attacks.

`needs_rehash(hashed_string: str) -> bool`

Returns True when the iteration count embedded in hashed_string differs from the iterations value the hasher was constructed with. Use this after a successful verify call to decide whether to re-hash and store a fresh hash at the new iteration count.

`PBKDF2Sha1Hasher`

A subclass of PBKDF2Sha256Hasher that replaces the SHA-256 digest with SHA-1. The constructor signature and hash-format structure are identical; only the embedded algorithm token changes.

algorithm = 'pbkdf2_sha1'

Constructor

PBKDF2Sha1Hasher(iterations: int = 150_000, salt_length: int = 16)

iterations

int

default:"150000"

Number of PBKDF2 iterations. Same minimum and validation rules as PBKDF2Sha256Hasher.

salt_length

int

default:"16"

Number of random bytes used to generate the salt.

Hash format

pbkdf2_sha1$<iterations>$<salt>$<hash>

SHA-1 is a legacy digest algorithm. PBKDF2Sha1Hasher exists solely to verify hashes produced by older systems. Do not use it for new hashes — prefer PBKDF2Sha256Hasher or a memory-hard algorithm such as Argon2Hasher or ScryptHasher for new projects.

Code example

from hash_forge.hashers import PBKDF2Sha256Hasher

hasher = PBKDF2Sha256Hasher(iterations=200_000)
hashed = hasher.hash("my_password")
assert hasher.verify("my_password", hashed)
assert hasher.needs_rehash(hashed) == False

# Old hash with fewer iterations
old = PBKDF2Sha256Hasher(iterations=150_000).hash("my_password")
assert hasher.needs_rehash(old) == True

Core

Configuration & Policy

Hashers

Exceptions

PBKDF2Sha256Hasher and PBKDF2Sha1Hasher API Reference

Import