Digestif.Argon2id (digestif v0.1.0)

Copy Markdown

Argon2id password hashing backed by the required argon2_elixir dependency.

This is Digestif's default adapter. Digestif.PBKDF2 remains available for compatibility and environments with a specific PBKDF2 requirement.

The defaults are m_cost: 15, t_cost: 2, and parallelism: 1. argon2_elixir expresses m_cost as the base-2 exponent of kibibytes, so 15 uses 32 MiB. This is the smallest supported power-of-two memory setting above OWASP's 19 MiB minimum, and the validator enforces it as the floor (m_cost >= 15, t_cost >= 2). Benchmark production hardware before raising these values; for fast test fixtures use a deliberately cheap custom test hasher rather than tuning the real algorithm down. The configurable bounds are m_cost 15..21, t_cost 2..16, and parallelism 1..8; salt and tag are the conventional 16 and 32 bytes and are not configurable.

Stored hashes are held to a verification budget rather than to the encoding's theoretical limits: by default a stored hash may not request more memory, passes, or lanes than the configured hashing costs, so a hostile, imported, or corrupted value can never make one verification more expensive than a login the host already pays for. Hosts that must keep verifying stronger imported hashes raise the budget explicitly:

{Digestif.Argon2id,
 m_cost: 15, verification_budget: [m_cost: 19, t_cost: 4]}

Each budget dimension defaults to its configured cost and may not fall below it (every hash this configuration mints must stay verifiable).

Trust boundary

Stored hashes are application-controlled database values, not untrusted network input. This adapter is a minimal resource preflight, defence in depth for corrupted, imported, or unexpectedly modified values: it bounds the total encoded length before any other work, extracts only the cost parameters for the budget decision, and hands everything else to argon2_elixir, which owns complete format parsing and cryptographic validation. The preflight is not a general parser or sanitizer for adversarial cryptographic encodings; anything it rejects fails closed after the configured dummy work, and malformed values below its ceilings are the backend's to reject.

Summary

Functions

Returns whether a stored Argon2id hash is weaker than the configured parameters. Hashes beyond the verification budget report true as well: they cannot verify under this configuration at all.

Functions

needs_rehash?(encoded_hash, options \\ [])

Returns whether a stored Argon2id hash is weaker than the configured parameters. Hashes beyond the verification budget report true as well: they cannot verify under this configuration at all.