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.

HashForgeConfig is a dataclass that centralises every tunable parameter for Hash Forge’s supported algorithms in one object. Instead of scattering rounds=14 or iterations=200_000 keyword arguments across your codebase, you define all parameters once — from environment variables in production, a JSON file during integration testing, or a plain dict in unit tests — and pass the config object to HashManager.from_config() at startup.
Use HashForgeConfig.from_env() in production containers and HashForgeConfig.from_dict() in tests. This keeps security-sensitive parameters out of source code and makes test setups explicit without touching environment state.

​
Loading Configuration

​
From environment variables

HashForgeConfig.from_env() reads all recognised HASH_FORGE_* environment variables and falls back to library defaults for any that are not set. 
export HASH_FORGE_PBKDF2_ITERATIONS=200000
export HASH_FORGE_BCRYPT_ROUNDS=14
export HASH_FORGE_ARGON2_TIME_COST=4

from hash_forge.config import HashForgeConfig

config = HashForgeConfig.from_env()
# config.pbkdf2_iterations == 200000
# config.bcrypt_rounds      == 14
# config.argon2_time_cost   == 4
The prefix parameter defaults to "HASH_FORGE_" but can be customised: 
config = HashForgeConfig.from_env(prefix="MY_APP_HASH_")

​
From a JSON file

HashForgeConfig.from_json() reads a JSON file and maps its keys directly to dataclass fields. 
{
  "pbkdf2_iterations": 200000,
  "bcrypt_rounds": 14,
  "argon2_time_cost": 4,
  "argon2_memory_cost": 65536
}

from hash_forge.config import HashForgeConfig

config = HashForgeConfig.from_json("hashforge.json")

​
From a Python dict

HashForgeConfig.from_dict() accepts any plain dictionary. Keys map directly to dataclass fields; unrecognised keys raise a TypeError. 
from hash_forge.config import HashForgeConfig

config = HashForgeConfig.from_dict({
    "pbkdf2_iterations": 200_000,
    "bcrypt_rounds": 14,
})

​
Environment Variable Reference

VariableDefaultDescription
HASH_FORGE_PBKDF2_ITERATIONS150000PBKDF2 iteration count
HASH_FORGE_PBKDF2_SALT_LENGTH16Salt length in bytes
HASH_FORGE_BCRYPT_ROUNDS12BCrypt cost factor
HASH_FORGE_ARGON2_TIME_COST3Argon2 time cost
HASH_FORGE_ARGON2_MEMORY_COST65536Argon2 memory (KiB)
HASH_FORGE_ARGON2_PARALLELISM1Argon2 parallelism
HASH_FORGE_ARGON2_HASH_LEN32Argon2 output length
HASH_FORGE_SCRYPT_N32768Scrypt CPU/memory cost
HASH_FORGE_SCRYPT_R8Scrypt block size
HASH_FORGE_SCRYPT_P1Scrypt parallelism

​
Using Config with HashManager

Pass the config object and the algorithm names you want to HashManager.from_config(). The method reads the relevant fields from the config and passes them to each hasher’s constructor. 
from hash_forge import HashManager
from hash_forge.config import HashForgeConfig

config = HashForgeConfig.from_env()

# Create a manager with config-driven parameters
manager = HashManager.from_config(config, "argon2", "pbkdf2_sha256")

hashed = manager.hash("my_secure_password")
The algorithm order follows the same rule as from_algorithms: the first algorithm becomes the preferred hasher for new hashes.

​
Complete startup example

from hash_forge import HashManager
from hash_forge.config import HashForgeConfig

def create_hash_manager() -> HashManager:
    config = HashForgeConfig.from_env()
    return HashManager.from_config(config, "argon2", "pbkdf2_sha256", "bcrypt")

manager = create_hash_manager()

​
Exporting Configuration

​
to_dict()

config.to_dict() returns a plain dictionary containing every configuration field. Use it to inspect the current state of a config object, pass settings to another system, or serialise to a format other than JSON. 
from hash_forge.config import HashForgeConfig

config = HashForgeConfig(
    pbkdf2_iterations=200_000,
    bcrypt_rounds=14,
    argon2_time_cost=4,
)

data = config.to_dict()
print(data["pbkdf2_iterations"])  # 200000
print(data["bcrypt_rounds"])      # 14

​
to_json(path)

config.to_json() serialises the current configuration to a JSON file. Use this to capture a working configuration snapshot or to pre-generate config files for deployment. 
config = HashForgeConfig(
    pbkdf2_iterations=200_000,
    bcrypt_rounds=14,
    argon2_time_cost=4,
)

config.to_json("hashforge.json")
The resulting file can be loaded later with HashForgeConfig.from_json("hashforge.json").

​
get_hasher_config(algorithm)

config.get_hasher_config() returns a dictionary of constructor keyword arguments for the named algorithm. This is the same extraction that HashManager.from_config() performs internally, but you can call it directly when you need per-algorithm settings without creating a manager. 
from hash_forge.config import HashForgeConfig

config = HashForgeConfig(pbkdf2_iterations=200_000, bcrypt_rounds=14)

pbkdf2_cfg = config.get_hasher_config("pbkdf2_sha256")
# {'iterations': 200000, 'salt_length': 16}

bcrypt_cfg = config.get_hasher_config("bcrypt")
# {'rounds': 14}

argon2_cfg = config.get_hasher_config("argon2")
# {'time_cost': 3, 'memory_cost': 65536, 'parallelism': 1, 'hash_len': 32}

scrypt_cfg = config.get_hasher_config("scrypt")
# {'work_factor': 32768, 'block_size': 8, 'parallelism': 1}

​
Security Minimums

Hash Forge enforces minimum values for every security-sensitive parameter. Setting any value below its minimum raises InvalidHasherError when the hasher is instantiated.
ParameterMinimum
PBKDF2 iterations150,000
BCrypt rounds12
Argon2 time_cost2
Argon2 memory_cost32,768 KiB
Scrypt N16,384
Scrypt r8
Scrypt p1
Setting any parameter below its minimum will raise InvalidHasherError at hasher instantiation time. The error is raised immediately — before any hash or verify call — so misconfiguration is caught at startup rather than silently at runtime.

​
Example: minimum enforcement

from hash_forge.hashers import BCryptHasher
from hash_forge.exceptions import InvalidHasherError

try:
    hasher = BCryptHasher(rounds=8)  # below minimum of 12
except InvalidHasherError as e:
    print(e)
    # BCrypt rounds must be at least 12

Build docs developers (and LLMs) love

Get started for freeTalk to us