Digestif (digestif v0.1.0)

Copy Markdown

Password hashing with secure defaults and a small public API.

The common case is deliberately three functions:

hash = Digestif.hash("correct horse battery staple")
true = Digestif.verify?("correct horse battery staple", hash)
false = Digestif.needs_rehash?(hash)

Argon2id with 32 MiB of memory, two iterations, and one lane is the default. Select a different primary hasher or declare legacy hashers in application configuration:

config :digestif,
  hasher: {Digestif.Argon2id, []},
  legacy_hashers: [{Digestif.PBKDF2, []}]

verify?/2 dispatches only to the configured primary hasher and explicit legacy hashers. A successful legacy verification is therefore visible to needs_rehash?/1, allowing the application to replace the stored hash.

Authentication libraries and applications with several independent hashing policies can use the explicit {module, options} API in Digestif.Hasher rather than global application configuration.

Summary

Functions

hash(value)

Hashes a value with the configured primary hasher.

needs_rehash?(encoded_hash)

Returns whether a stored hash should be replaced by the primary hasher.

verify?(value, encoded_hash)

Returns whether a value matches a stored hash.

Functions

hash(value)

@spec hash(String.t()) :: String.t()

Hashes a value with the configured primary hasher.

Work factors come from application configuration so hashing and verification share one resource budget. Invalid configuration and backend failures raise rather than returning an unusable hash.

needs_rehash?(encoded_hash)

@spec needs_rehash?(String.t()) :: boolean()

Returns whether a stored hash should be replaced by the primary hasher.

Call this after successful verification. Hashes belonging to an explicit legacy hasher always return true; primary hashes defer to that adapter's work-factor policy.

verify?(value, encoded_hash)

@spec verify?(String.t(), String.t()) :: boolean()

Returns whether a value matches a stored hash.

Only the configured primary and legacy hashers are considered. Foreign, unknown, malformed, and over-budget hashes fail closed as false.