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.
Cryptographic digest algorithms produce a fixed-length fingerprint of arbitrary input data. They are the right tool for data integrity checks, content addressing, MACs, and digital signatures — scenarios where you need to verify that data has not changed, not that a human chose a weak password. Because digest functions are designed to be fast, they offer no meaningful resistance to GPU-accelerated brute-force attacks when used to store passwords directly. Hash Forge exposes four active digest algorithms — Blake2, Blake3, SHA-3 256, and SHA-3 512 — alongside the legacy RIPEMD-160 and the deprecated Whirlpool, all using the same HashManager interface as the password hashers.
Digest algorithms are not suitable for password storage. They are fast by design, which means an attacker with access to the hash can test billions of guesses per second on commodity hardware. If you need to store passwords, use one of the memory-hard algorithms described in the Password Hashing guide instead. Blake2
Blake2 is a high-speed cryptographic hash function built into Python’s standard library via hashlib.blake2b. It supports optional keyed hashing (HMAC-like) through its key parameter, making it suitable for both unkeyed digests and message authentication codes. Hash Forge uses the canonical identifier blake2 and also accepts the legacy prefix blake2b for backward compatibility.
No extra installation required (uses Python’s hashlib).
Constructor parameters:
| Parameter | Type | Default | Description |
|---|
key | str | "" | Optional key for keyed hashing. Empty string disables keying. |
digest_size | int | 64 | Output digest size in bytes (1–64). |
from hash_forge import HashManager
from hash_forge.hashers import Blake2Hasher
# Unkeyed digest
hasher = Blake2Hasher()
hash_manager = HashManager(hasher)
hashed = hash_manager.hash("important document content")
is_valid = hash_manager.verify("important document content", hashed)
# Keyed digest (MAC)
hasher = Blake2Hasher(key="my_secret_key", digest_size=32)
hash_manager = HashManager(hasher)
hashed = hash_manager.hash("message to authenticate")
# Via quick_hash
hashed = HashManager.quick_hash("content", algorithm="blake2", key="secret_key")
blake2$<digest_size>$<hex>
digest_size is stored in the hash string so that verify() can reconstruct the exact digest parameters. Hashes with the legacy blake2b$ prefix are also accepted by can_handle() and verify().
Blake3
Blake3 is the successor to the Blake2 family, offering significantly faster hashing while maintaining strong security properties. Unlike Blake2, it has a fixed 256-bit (32-byte) output and no configurable parameters. Hash Forge requires the blake3 Python package.
Install the extra:
pip install "hash-forge[blake3]"
Blake3Hasher takes no configuration parameters.
Usage:
from hash_forge import HashManager
from hash_forge.hashers import Blake3Hasher
hasher = Blake3Hasher()
hash_manager = HashManager(hasher)
hashed = hash_manager.hash("file content to fingerprint")
is_valid = hash_manager.verify("file content to fingerprint", hashed)
# Via quick_hash
hashed = HashManager.quick_hash("content", algorithm="blake3")
blake3$ prefix directly. There are no additional stored parameters since Blake3 has no tunable cost axes.
SHA-3 256
SHA-3 256 is the 256-bit variant of the SHA-3 family (Keccak), standardised by NIST in FIPS 202. It is available in Python’s hashlib with no extra dependencies. Hash Forge salts each hash with a randomly generated salt to prevent pre-computation attacks when the input space is small or predictable.
No extra installation required (uses Python’s hashlib).
Constructor parameters:
| Parameter | Type | Default | Description |
|---|
salt_length | int | 16 | Number of random bytes used to generate the salt. |
from hash_forge import HashManager
from hash_forge.hashers import SHA3_256Hasher
hasher = SHA3_256Hasher()
hash_manager = HashManager(hasher)
hashed = hash_manager.hash("data to fingerprint")
is_valid = hash_manager.verify("data to fingerprint", hashed)
# Via quick_hash (no extra dependencies)
hashed = HashManager.quick_hash("data", algorithm="sha3_256")
verify() can reproduce the exact hash. Because SHA-3 has no tunable cost parameters, needs_rehash() always returns False.
SHA-3 512
SHA-3 512 is the 512-bit variant of the SHA-3 family. It is otherwise identical in behaviour and interface to SHA-3 256 — the only difference is the larger output digest and the use of the sha3_512 hashlib primitive internally.
No extra installation required (uses Python’s hashlib).
Constructor parameters:
| Parameter | Type | Default | Description |
|---|
salt_length | int | 16 | Number of random bytes used to generate the salt. |
from hash_forge import HashManager
from hash_forge.hashers import SHA3_512Hasher
hasher = SHA3_512Hasher()
hash_manager = HashManager(hasher)
hashed = hash_manager.hash("data to fingerprint")
is_valid = hash_manager.verify("data to fingerprint", hashed)
# Via quick_hash
hashed = HashManager.quick_hash("data", algorithm="sha3_512")
RIPEMD-160
RIPEMD-160 is a 160-bit cryptographic hash function developed in Europe in the mid-1990s. Hash Forge classifies it as legacy — it is available for verifying hashes produced by older systems but should not be used for new work. It requires the pycryptodome library via the [crypto] extra.
Install the extra:
pip install "hash-forge[crypto]"
Ripemd160Hasher takes no configuration parameters.
Usage:
from hash_forge import HashManager
from hash_forge.hashers import Ripemd160Hasher
hasher = Ripemd160Hasher()
hash_manager = HashManager(hasher)
hashed = hash_manager.hash("data")
is_valid = hash_manager.verify("data", hashed)
# Verifying a legacy hash with the old RIPEMD-160$ prefix
legacy_hash = "RIPEMD-160$<hex>"
is_valid = hash_manager.verify("data", legacy_hash)
RIPEMD-160$ prefix (with the hyphen and capital letters) is also accepted by can_handle() and verify() for backward compatibility. needs_rehash() returns True for hashes carrying the legacy prefix so they are automatically migrated to the canonical ripemd160$ format on next verification.
Whirlpool
Whirlpool is deprecated. The Hash Forge implementation is backed by SHA-512 (via pycryptodome), not a true Whirlpool implementation. WhirlpoolHasher raises a DeprecationWarning on every instantiation. New hashing is disabled by default and must be explicitly unlocked with allow_legacy_hashing=True. This hasher exists solely to verify old hashes stored by earlier versions of Hash Forge.
pip install "hash-forge[crypto]"
| Parameter | Type | Default | Description |
|---|
allow_legacy_verify | bool | True | Allow verification of existing whirlpool$ hashes. |
allow_legacy_hashing | bool | False | Allow creation of new whirlpool$ hashes. Disabled by default. |
allow_legacy_verify=False and allow_legacy_hashing=False simultaneously raises InvalidHasherError immediately, since the hasher would be entirely inert.
Usage — verification of old hashes only (recommended):
from hash_forge import HashManager
from hash_forge.hashers import WhirlpoolHasher, PBKDF2Sha256Hasher
import warnings
# Suppress the expected DeprecationWarning when working with legacy hashes
with warnings.catch_warnings():
warnings.simplefilter("ignore", DeprecationWarning)
whirlpool_hasher = WhirlpoolHasher(allow_legacy_verify=True, allow_legacy_hashing=False)
hash_manager = HashManager(
PBKDF2Sha256Hasher(), # preferred — used for all new hashes
whirlpool_hasher, # fallback — used only to verify old whirlpool hashes
)
# Verifying an old stored hash
is_valid = hash_manager.verify("old_password", old_whirlpool_hash)
# Rotate to a modern algorithm on next successful login
new_hash = hash_manager.rotate("old_password", old_whirlpool_hash)
if new_hash:
# Store new_hash — it is now pbkdf2_sha256
...
pycryptodome’s SHA-512 implementation (not a true Whirlpool digest). All verification is performed with hmac.compare_digest() to prevent timing attacks.