argon2

stable

Password hashing and verification using Argon2id, the winner of the Password Hashing Competition.

use plugin argon2::{hash_password, verify_password, hash_with_params, …}

/ filter jk navigate Esc clear

Functions (7)

hash_password Hash a password with default params
verify_password Verify a password against a stored hash
hash_with_params Hash with custom time/memory/parallelism
generate_salt Generate a random base64 salt string
hash_with_salt Hash a password with a specific salt
extract_params Parse algorithm parameters from a hash
needs_rehash Check if a hash needs upgrading

Overview

The argon2 plugin provides password hashing and verification built on Argon2id, the memory-hard algorithm that won the Password Hashing Competition. Every hash is returned as a self-contained PHC string (e.g. $argon2id$v=19$m=65536,t=3,p=4$...) that bundles the algorithm, version, tuning parameters, salt, and digest — so you store a single string and never manage salts separately. Use it whenever you need to store user credentials securely, verify logins, or migrate older hashes to stronger settings over time.

The core concept is stateless: each call configures Argon2id internally and works purely from the strings you pass in. hash_password and verify_password cover the common case, while hash_with_params, extract_params, and needs_rehash let you tune cost factors and gradually upgrade stored hashes.

Common patterns

use plugin argon2::{hash_password, verify_password}

// Signup: store the PHC string in your database
let stored = hash_password("hunter2")

// Login: compare the attempt against the stored hash
if verify_password("hunter2", stored) {
  print("login ok")
} else {
  print("invalid credentials")
}

Transparent hash upgrade on login — re-hash with stronger params when the old hash is weaker than your current policy:

use plugin argon2::{verify_password, needs_rehash, hash_with_params}

// Policy: 3 iterations, 64 MiB memory, 4 threads
let stored = hash_with_params("password", 1, 65536, 1)

if verify_password("password", stored) {
  if needs_rehash(stored, 3, 65536, 4) {
    let upgraded = hash_with_params("password", 3, 65536, 4)
    print("re-hashed with stronger params: {upgraded}")
  }
}

Audit a stored hash to see exactly how it was tuned:

use plugin argon2::{hash_password, extract_params}

let hash = hash_password("example")
let params = extract_params(hash)
print("algorithm: {params["algorithm"]}")
print("memory: {params["memory"]} KiB, iterations: {params["iterations"]}")

hash_password(password) → string

Hash a password with default params

Hashes a password using Argon2id with default parameters and a randomly generated salt. Returns a PHC string (e.g. $argon2id$v=19$m=65536,t=3,p=4$...). Store this string directly — it includes the salt and parameters.

use plugin argon2::{hash_password, verify_password}

let hash = hash_password("hunter2")
print(hash)

let ok = verify_password("hunter2", hash)
print(ok)

Because the salt is random, hashing the same password twice yields two different PHC strings — yet both verify against the original password:

use plugin argon2::{hash_password, verify_password}

let a = hash_password("repeat")
let b = hash_password("repeat")
print(a == b)                      // false — different salts
print(verify_password("repeat", a)) // true
print(verify_password("repeat", b)) // true

verify_password(password, hash) → bool

Verify a password against a stored hash

Verifies password against a PHC hash string produced by any of the hash_* functions. Returns true if the password matches, false otherwise. Never errors on wrong password.

use plugin argon2::{hash_password, verify_password}

let stored = hash_password("secret123")

print(verify_password("secret123", stored))
print(verify_password("wrong", stored))

hash_with_params(password, time_cost, memory_cost, parallelism) → string

Hash with custom time/memory/parallelism

Hashes a password with explicit Argon2id parameters. time_cost is the number of iterations, memory_cost is memory in KiB, and parallelism is the thread count. Use higher values for stronger security at the cost of speed.

use plugin argon2::{hash_with_params, verify_password}

// High-security settings: 4 iterations, 128 MiB memory, 4 threads
let hash = hash_with_params("my-password", 4, 131072, 4)
print(verify_password("my-password", hash))

Lighter settings trade strength for speed — useful in tests or low-risk contexts:

use plugin argon2::{hash_with_params, extract_params}

// 1 iteration, 32 MiB memory, 1 thread
let hash = hash_with_params("token", 1, 32768, 1)
let p = extract_params(hash)
print("memory: {p["memory"]}, iterations: {p["iterations"]}")

generate_salt() → string

Generate a random base64 salt string

Generates a cryptographically random base64-encoded salt string, suitable for use with hash_with_salt.

use plugin argon2::{generate_salt, hash_with_salt}

let salt = generate_salt()
let hash = hash_with_salt("password", salt)
print(hash)

hash_with_salt(password, salt) → string

Hash a password with a specific salt

Hashes password using Argon2id with default parameters and the provided base64 salt string. Use this when you need deterministic hashing (e.g. testing or migration).

use plugin argon2::{generate_salt, hash_with_salt, verify_password}

let salt = generate_salt()
let hash = hash_with_salt("p@ssw0rd", salt)
print(verify_password("p@ssw0rd", hash))

extract_params(hash) → table

Parse algorithm parameters from a hash

Parses a PHC hash string and returns a table with algorithm, version, memory, iterations, parallelism, and salt fields. Useful for auditing stored hashes.

use plugin argon2::{hash_password, extract_params}

let hash = hash_password("example")
let params = extract_params(hash)
print("algorithm: {params["algorithm"]}")
print("memory: {params["memory"]} KiB")
print("iterations: {params["iterations"]}")

needs_rehash(hash, time_cost, memory_cost, parallelism) → bool

Check if a hash needs upgrading

Returns true if the stored hash was created with parameters that differ from the provided targets. Use this during login to upgrade weak hashes to stronger settings without forcing a password reset.

use plugin argon2::{hash_with_params, needs_rehash, hash_password}

let old_hash = hash_with_params("password", 1, 65536, 1)
let upgrade_needed = needs_rehash(old_hash, 3, 65536, 4)
print(upgrade_needed)

// On login: if needs_rehash returns true, re-hash with new params
let current_hash = hash_password("password")
print(needs_rehash(current_hash, 3, 65536, 4))

A hash created with the same target parameters does not need rehashing:

use plugin argon2::{hash_with_params, needs_rehash}

let hash = hash_with_params("password", 3, 65536, 4)
print(needs_rehash(hash, 3, 65536, 4)) // false — already matches policy

View source code