Skip to content

Hashing

David Ciulla edited this page Nov 7, 2026 · 1 revision

Hashing

Laravex provides one-way password hashing through Laravex.Hashing.Hash. Passwords are hashed with PBKDF2-HMAC-SHA256 — a deliberately slow key-derivation function that resists brute-force and GPU attacks.

Never use Laravex.Encryption.Crypt for passwords. Crypt is reversible (AES-256-GCM); Hash is not. See Encryption.

Configuration

Control the PBKDF2 work factor via BCRYPT_ROUNDS in .env (the name is intentionally Laravel-compatible):

BCRYPT_ROUNDS=12

The environment variable is multiplied by 1 000 to get the actual PBKDF2 iteration count (default 12 × 1000 = 12 000). Increase this value on more powerful hardware:

BCRYPT_ROUNDS=14   # 14 000 iterations

Hashing a Password

hashed = Laravex.Hashing.Hash.make("secret-password")
# => "pbkdf2:12000:<salt_hex>:<hash_hex>"

A fresh 16-byte salt is generated via :crypto.strong_rand_bytes/1 for every call, so the same password always produces a different stored value.

Verifying a Password

Laravex.Hashing.Hash.check("secret-password", hashed)
# => true | false

check/2 reconstructs the hash using the salt and iteration count embedded in the stored value, then compares it in constant time using :crypto.hash_equals/2 to prevent timing attacks. It handles both the current four-part format and a legacy three-part format (iterations inferred from env).

Checking If a Hash Needs Rehashing

When you increase BCRYPT_ROUNDS, existing hashes are out of date. Check this on login and transparently rehash:

if Laravex.Hashing.Hash.needs_rehash?(user.password) do
  new_hash = Laravex.Hashing.Hash.make(plain_password)
  model.save(%{user | password: new_hash})
end

needs_rehash?/1 returns true when the iteration count embedded in the hash does not match the current BCRYPT_ROUNDS × 1000. The Authentication guard calls this automatically via Guard.attempt/2 — you only need it in custom authentication flows.

Hash Format

Hashes are stored as plain text strings:

pbkdf2:<iterations>:<salt_hex>:<hash_hex>
Field Example
Algorithm pbkdf2
Iterations 12000
Salt 32 lowercase hex chars (16 bytes)
Hash 64 lowercase hex chars (32 bytes)

A legacy format (hashed:<payload>) is also recognized by check/2 for backward compatibility, though new hashes are never produced in that format.

Automatic Hashing via Casts

If you define a :hashed cast on an Eloquex model field, the value is automatically hashed when assigned and before persisting — you never handle the raw hash manually:

defmodule App.Models.User do
  use Laravex.Eloquex.Model, table: "users"

  def casts do
    %{password: :hashed}
  end
end
# Plain text in → hash stored automatically
App.Models.User.create(%{"name" => "Alice", "password" => "secret"})

See Eloquex-Mutators for full details on casts.

See Also

  • Encryption — Reversible AES-256-GCM encryption
  • Authentication — The session guard that calls Hash.check/2 on login
  • Passwords — The password reset broker that calls Hash.make/1

Clone this wiki locally