Password Hashing

18 min read

Storing user passwords is the one place where “just hash it” is dangerous advice. A fast hash like SHA-256 is worse than useless for passwords because attackers can try billions of guesses per second. This page shows how to do it right in Rust with Argon2 (and bcrypt), and how it maps to the Node argon2/bcrypt packages you may already know.

Quick Overview

A password hash is a deliberately slow, salted, one-way transformation of a password that you store instead of the password itself. When a user logs in, you re-run the function on their attempt and compare. The defining feature of a good password hash is that it is memory-hard and tunably slow, so a stolen database is expensive to brute-force.

For a TypeScript/JavaScript developer, the mental model is almost identical to the npm argon2 package: you call a hash function that bakes a random salt into a self-describing string, and a verify function that reads the salt back out. In Rust this is built around the password-hash crate’s PasswordHasher and PasswordVerifier traits, with argon2 as the recommended implementation.

Note: This page is about password hashing specifically. For general-purpose cryptography (encryption, AEAD, MACs) see cryptography.md; for the random number sources used to make salts see secure-randomness.md.

TypeScript/JavaScript Example

A typical Node service using the native argon2 package (the recommended choice over bcryptjs today):

1
// npm install argon2
2
import argon2 from "argon2";
3

4
interface UserRecord {
5
  username: string;
6
  passwordHash: string; // store THIS, never the password
7
}
8

9
// Registration: hash the password for storage.
10
async function register(username: string, password: string): Promise<UserRecord> {
11
  // argon2.hash() defaults to Argon2id, generates a random salt,
12
  // and returns a self-describing PHC string.
13
  const passwordHash = await argon2.hash(password);
14
  return { username, passwordHash };
15
}
16

17
// Login: re-hash the attempt and compare in constant time.
18
async function verifyLogin(record: UserRecord, attempt: string): Promise<boolean> {
19
  // verify() reads the salt + parameters out of the stored hash.
20
  return argon2.verify(record.passwordHash, attempt);
21
}
22

23
const user = await register("alice", "s3cr3t-p@ssw0rd");
24
console.log(user.passwordHash);
25
// $argon2id$v=19$m=65536,t=3,p=4$8ykm3QdFyZnBmyrRKiy2MQ$y+Ds3M9MFMMBACIQHF/c2iZ5U5+oa8d2mS/nyuJ2Kt0
26

27
console.log(await verifyLogin(user, "s3cr3t-p@ssw0rd")); // true
28
console.log(await verifyLogin(user, "wrong")); // false

Key points:

argon2.hash(password) returns a PHC string that embeds the algorithm, version, parameters, salt, and digest.
You never store or manage the salt yourself — it travels inside the hash string.
argon2.verify(hash, attempt) returns a Promise<boolean>; it does the constant-time comparison internally.

Warning: Do not use Node’s built-in crypto.createHash("sha256") or md5 for passwords. Those are fast general-purpose hashes; the same warning applies to Rust’s sha2 crate. Password hashing needs a purpose-built, slow function.

Rust Equivalent

The same registration/login flow with the argon2 crate. Add the dependency first:

1
cargo add argon2 --features std

This pulls in argon2 = "0.5", which re-exports the password-hash crate (the traits, the salt type, and a CSPRNG-backed salt generator).

1
use argon2::{
2
    password_hash::{
3
        rand_core::OsRng, PasswordHash, PasswordHasher, PasswordVerifier, SaltString,
4
    },
5
    Argon2,
6
};
7

8
fn main() {
9
    let password = b"correct horse battery staple";
10

11
    // 1. Generate a random salt from the OS CSPRNG.
12
    let salt = SaltString::generate(&mut OsRng);
13

14
    // 2. Argon2::default() is Argon2id with current recommended parameters.
15
    let argon2 = Argon2::default();
16

17
    // 3. Hash into a self-describing PHC string (store THIS).
18
    let hash = argon2
19
        .hash_password(password, &salt)
20
        .expect("hashing failed")
21
        .to_string();
22
    println!("PHC string: {hash}");
23

24
    // 4. Verify: parse the stored string, then check the attempt.
25
    let parsed = PasswordHash::new(&hash).expect("invalid PHC string");
26
    let ok = Argon2::default()
27
        .verify_password(password, &parsed)
28
        .is_ok();
29
    println!("correct password verifies: {ok}");
30

31
    let wrong = Argon2::default()
32
        .verify_password(b"wrong password", &parsed)
33
        .is_ok();
34
    println!("wrong password verifies:   {wrong}");
35

36
    // 5. The same input hashed twice differs, because the salt is random.
37
    let salt2 = SaltString::generate(&mut OsRng);
38
    let hash2 = Argon2::default()
39
        .hash_password(password, &salt2)
40
        .unwrap()
41
        .to_string();
42
    println!("same input, hashes equal:  {}", hash == hash2);
43
}

Real output:

1
PHC string: $argon2id$v=19$m=19456,t=2,p=1$hOtbciLFrd1ihAGsRiEoIg$RN2Tf/CQZ8OcIaVfm3vz0q+bujmy5+/vxzMamQ3t4D0
2
correct password verifies: true
3
wrong password verifies:   false
4
same input, hashes equal:  false

Key points:

hash_password and verify_password come from the PasswordHasher / PasswordVerifier traits — you must bring them into scope with use.
The output is a PHC string, exactly like the Node argon2 package produces. It is a single String you put in one database column.
Passwords are passed as &[u8] (byte slices), not &str. Calling .as_bytes() on a String/&str is how you get there.

Detailed Explanation

Why slow + salted, line by line

A password hash defends against two distinct attacks, and each design choice targets one of them:

Salting defeats precomputation. A salt is a random value mixed into the hash so that two users with the same password get different hashes. Without it, an attacker uses a rainbow table (a precomputed map of hash → password) and cracks the whole database at once. SaltString::generate(&mut OsRng) draws ~16 bytes from the operating system CSPRNG. That is why our two-hashes-of-the-same-password check printed false.
Slowness defeats brute force. Argon2::default() is configured to take meaningful CPU and memory per hash. The PHC parameters m=19456,t=2,p=1 mean 19,456 KiB (19 MiB) of memory, 2 iterations, and 1 lane of parallelism. That is fast enough for a login request (single-digit milliseconds) but turns an attacker’s “billions of guesses per second” on a fast hash into a far smaller number on commodity hardware, and the 19 MiB memory cost specifically blunts GPU and ASIC cracking rigs.

Anatomy of the PHC string

1
$argon2id$v=19$m=19456,t=2,p=1$hOtbciLFrd1ihAGsRiEoIg$RN2Tf/CQZ8OcIaVfm3vz0q+bujmy5+/vxzMamQ3t4D0
2
 └─ algo ─┘└ver┘└──── params ────┘└──── salt (b64) ────┘└─────────── digest (b64) ───────────────┘

Because the salt and parameters are stored inside the string, verify_password can reproduce the exact computation. You never need a separate salt column, and you can change your global parameters later without breaking existing users — verify uses whatever is embedded in each stored hash.

`Argon2id` vs `Argon2i` vs `Argon2d`

Argon2 has three variants. Argon2::default() picks Argon2id, the hybrid that the OWASP Password Storage Cheat Sheet recommends for password storage — it resists both side-channel attacks (the i strength) and GPU/time-memory tradeoff attacks (the d strength). Unless you have a specific reason, use the default.

Tuning the cost parameters

Argon2::default() is a good baseline, but you may want to set parameters explicitly so they are visible and reviewable:

1
use argon2::{
2
    password_hash::{rand_core::OsRng, PasswordHasher, SaltString},
3
    Algorithm, Argon2, Params, Version,
4
};
5

6
fn main() {
7
    // m_cost = 19456 KiB (19 MiB), t_cost = 2 iterations, p_cost = 1 lane.
8
    // These are a current OWASP-recommended starting point.
9
    let params = Params::new(19_456, 2, 1, None).expect("invalid params");
10
    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);
11

12
    let salt = SaltString::generate(&mut OsRng);
13
    let hash = argon2
14
        .hash_password(b"hunter2", &salt)
15
        .expect("hash failed")
16
        .to_string();
17
    println!("{hash}");
18
}

Real output:

1
$argon2id$v=19$m=19456,t=2,p=1$nDrBHfbTwksob591a0f2XA$wqAf/QsgYOxUHbz/VRWJJs9dlmQt86VXYWmEvTfT5tg

Tip: Tune so that a single hash takes roughly 0.5–1 second on your production hardware, then back off if that hurts throughput. The right numbers depend on your CPU and how many logins per second you must serve. Benchmark; don’t cargo-cult a number.

The bcrypt alternative

bcrypt predates Argon2 and is still perfectly acceptable for password storage; it is what many existing systems use. The bcrypt crate has a simpler, function-style API:

1
cargo add bcrypt

1
use bcrypt::{hash, verify, DEFAULT_COST};
2

3
fn main() {
4
    let password = "correct horse battery staple";
5

6
    // hash() generates a random salt and embeds it in the output.
7
    let hashed = hash(password, DEFAULT_COST).expect("hashing failed");
8
    println!("bcrypt hash: {hashed}");
9
    println!("cost (DEFAULT_COST) = {DEFAULT_COST}");
10

11
    println!("correct verifies: {}", verify(password, &hashed).unwrap());
12
    println!("wrong verifies:   {}", verify("nope", &hashed).unwrap());
13
}

Real output:

1
bcrypt hash: $2b$12$Ttcq3h2TaM9ZeEWCGgiVge5yj33FaydsAeRyhyVQWoxTX/K5YW4Ru
2
cost (DEFAULT_COST) = 12
3
correct verifies: true
4
wrong verifies:   false

The $2b$12$... prefix is bcrypt’s own self-describing format: variant 2b, cost factor 12 (meaning 2^12 rounds), then salt+digest. The cost is the one knob — raise it as hardware gets faster.

Warning: bcrypt silently truncates passwords to 72 bytes. Anything past byte 72 is ignored, so a 100-character passphrase is no stronger than its first 72 bytes. Argon2 has no such limit. This is a real, frequently-overlooked footgun (demonstrated under Common Pitfalls).

Key Differences

Concern	TypeScript / Node	Rust
Recommended package	`argon2` (npm)	`argon2` crate
Default algorithm	Argon2id	Argon2id (`Argon2::default()`)
API shape	async functions `hash`/`verify`	trait methods `hash_password`/`verify_password` (synchronous)
Where the salt lives	inside the PHC string	inside the PHC string
Output type	`Promise<string>`	`Result<PasswordHash, Error>` → `.to_string()`
Password input	`string`	`&[u8]` (use `.as_bytes()`)
Comparison safety	constant-time inside `verify`	constant-time inside `verify_password`
CPU binding	native addon (libsodium-style)	pure Rust, no system libs

A few conceptual differences worth internalizing:

Synchronous, not async. Node’s argon2.hash returns a Promise because the native addon offloads work to a thread pool. The Rust argon2 crate is a plain synchronous CPU computation. In an async service (axum, tokio) you should wrap a hash call in tokio::task::spawn_blocking so the ~1 ms–1 s of CPU work does not stall the async runtime’s worker thread. See ../11-async for the blocking-vs-async distinction.
Traits, not free functions. hash_password lives on the PasswordHasher trait. If you forget the use, the method appears to not exist (see Common Pitfalls). This is Rust’s normal “methods come from traits in scope” rule — see ../09-generics-traits.
Errors are values. Node throws on a malformed hash; Rust returns Result. A failed verify is Err(...), not an exception, so you handle it with match/? like any other error handling.
No global state. There is no implicit “pepper” or process-wide config. Everything that affects a hash is either in the PHC string or in the Argon2 value you constructed.

Common Pitfalls

Forgetting to import the trait

The methods come from PasswordHasher / PasswordVerifier. Omit the use and the compiler says the method does not exist:

1
use argon2::{
2
    password_hash::{rand_core::OsRng, SaltString},
3
    Argon2,
4
};
5

6
fn main() {
7
    let salt = SaltString::generate(&mut OsRng);
8
    // does not compile (error[E0599]) — PasswordHasher trait not in scope
9
    let _hash = Argon2::default().hash_password(b"pw", &salt).unwrap();
10
}

Real compiler error (truncated):

1
error[E0599]: no method named `hash_password` found for struct `Argon2` in the current scope
2
   --> src/main.rs:9:35
3
    |
4
  9 |     let _hash = Argon2::default().hash_password(b"pw", &salt).unwrap();
5
    |                                   ^^^^^^^^^^^^^
6
...
7
    = help: items from traits can only be used if the trait is in scope
8
help: trait `PasswordHasher` which provides `hash_password` is implemented but not in scope; perhaps you want to import it
9
    |
10
  1 + use argon2::PasswordHasher;
11
    |

The fix is exactly what the compiler suggests: use argon2::PasswordHasher; (and PasswordVerifier for verifying).

Comparing hashes with `==` instead of verifying

A tempting but wrong instinct is to re-hash the attempt and compare strings:

1
// Logic bug, NOT a compile error — this will reject every correct password.
2
// let attempt_hash = Argon2::default()
3
//     .hash_password(attempt, &fresh_salt)?
4
//     .to_string();
5
// let ok = attempt_hash == stored_hash; // ALWAYS false: different random salts!

Because each hash uses a new random salt, two hashes of the same password never match by string equality — that is the whole point of salting. You must call verify_password, which re-uses the salt embedded in the stored hash and performs a constant-time digest comparison. String == would also leak timing information even if the salts matched.

Using a fast general-purpose hash

1
// Insecure for passwords (compiles fine, ships a vulnerability).
2
// use sha2::{Digest, Sha256};
3
// let digest = Sha256::digest(password); // GPU-crackable at billions/sec, no salt

SHA-256, SHA-512, and MD5 are designed to be fast, which is precisely the wrong property here. They are correct for file integrity and HMACs, never for passwords. Reach for argon2 (or bcrypt) instead.

bcrypt’s 72-byte truncation

1
use bcrypt::{hash, verify, DEFAULT_COST};
2

3
fn main() {
4
    let base = "a".repeat(72);
5
    let longer = format!("{base}EXTRA-IGNORED-BYTES");
6

7
    let h = hash(&base, DEFAULT_COST).unwrap();
8
    // Extra bytes past 72 are ignored, so a DIFFERENT password verifies.
9
    println!(
10
        "72-byte password verifies with +18 extra bytes: {}",
11
        verify(&longer, &h).unwrap()
12
    );
13
}

Real output:

1
72-byte password verifies with +18 extra bytes: true

If you must support long passphrases with bcrypt, pre-hash with SHA-256 and base64-encode before bcrypt — or simply use Argon2, which has no length limit.

Logging or returning the hash

A PHC string is not a secret you should display, but it is also not something to scatter through logs. Treat it like any credential material: do not log it, do not return it in API responses. For active in-memory secrets, see secrets-management.md.

Best Practices

Default to Argon2id. Use Argon2::default() (or explicit Algorithm::Argon2id) unless you are interoperating with an existing bcrypt store.
Never manage salts manually. Let SaltString::generate(&mut OsRng) and the PHC string handle it. A salt you generate with a non-CSPRNG (e.g. the default rand thread RNG without OsRng) is a bug — see secure-randomness.md.
Store the whole PHC string in one column. No separate salt/params columns. This makes parameter upgrades trivial.
Run hashing off the async executor. In tokio/axum services, wrap hash_password/verify_password in spawn_blocking so a slow hash does not block other requests.
Re-hash on login when parameters change. After a successful verify_password, check whether the stored hash used your current parameters; if not, transparently re-hash the just-verified plaintext and update the row. This lets you raise cost over time without forcing password resets.
Compare in constant time. Always go through verify_password (Argon2) or verify (bcrypt); never == on hashes or digests.
Pin and audit your dependencies. Password hashing is exactly the kind of code where a known-vulnerable transitive dependency matters — run cargo audit (see security-audit.md).
Cap input length before hashing. Reject absurdly long passwords (e.g. > 1 KiB) at the validation layer to avoid a denial-of-service where an attacker submits megabyte passwords to your slow hasher — see input-validation.md.

Real-World Example

A small, production-flavored auth module with a typed error enum. It models a users table row, hashes on registration, and verifies on login, returning a deliberately generic error so the response cannot distinguish “no such user” from “wrong password”.

1
cargo add argon2 --features std
2
cargo add thiserror

1
use argon2::{
2
    password_hash::{
3
        rand_core::OsRng, Error as PwHashError, PasswordHash, PasswordHasher,
4
        PasswordVerifier, SaltString,
5
    },
6
    Argon2,
7
};
8
use thiserror::Error;
9

10
#[derive(Debug, Error)]
11
enum AuthError {
12
    #[error("could not hash password")]
13
    Hash(#[source] PwHashError),
14
    #[error("stored credential is corrupt")]
15
    CorruptHash(#[source] PwHashError),
16
    #[error("invalid username or password")]
17
    BadCredentials,
18
}
19

20
/// Stand-in for a `users` table row.
21
struct UserRecord {
22
    username: String,
23
    password_hash: String, // the PHC string, safe to store in a DB column
24
}
25

26
/// Hash a new user's password for storage.
27
fn register(username: &str, password: &str) -> Result<UserRecord, AuthError> {
28
    let salt = SaltString::generate(&mut OsRng);
29
    let password_hash = Argon2::default()
30
        .hash_password(password.as_bytes(), &salt)
31
        .map_err(AuthError::Hash)?
32
        .to_string();
33

34
    Ok(UserRecord {
35
        username: username.to_owned(),
36
        password_hash,
37
    })
38
}
39

40
/// Check a login attempt against a stored record.
41
fn verify_login(record: &UserRecord, attempt: &str) -> Result<(), AuthError> {
42
    // A malformed stored hash is a server fault, distinct from a bad password.
43
    let parsed =
44
        PasswordHash::new(&record.password_hash).map_err(AuthError::CorruptHash)?;
45

46
    Argon2::default()
47
        .verify_password(attempt.as_bytes(), &parsed)
48
        // Collapse any verify failure into ONE generic error: never reveal which part failed.
49
        .map_err(|_| AuthError::BadCredentials)
50
}
51

52
fn main() {
53
    let user = register("alice", "s3cr3t-p@ssw0rd").expect("register failed");
54
    println!("stored for {}: {}", user.username, user.password_hash);
55

56
    match verify_login(&user, "s3cr3t-p@ssw0rd") {
57
        Ok(()) => println!("login ok"),
58
        Err(e) => println!("login failed: {e}"),
59
    }
60

61
    match verify_login(&user, "guess") {
62
        Ok(()) => println!("login ok"),
63
        Err(e) => println!("login failed: {e}"),
64
    }
65
}

Real output (PHC body redacted here for length; it is a full base64 salt+digest at runtime):

1
stored for alice: $argon2id$v=19$m=19456,t=2,p=1$<salt>$<digest>
2
login ok
3
login failed: invalid username or password

In a real service the UserRecord would come from a database — see ../17-database — and the register/verify_login calls would be wrapped in spawn_blocking inside your axum handlers (see ../16-web-apis). The generic BadCredentials error is intentional: returning the same message and status for unknown-user and wrong-password prevents username enumeration, and you should also keep the timing of both paths similar in production hardening (see ../28-production/README.md).

Note: This page presents argon2 = "0.5", bcrypt = "0.19", and thiserror = "2". The current stable toolchain is Rust 1.96.0 on the 2024 edition, which cargo new selects automatically. Always run cargo add <crate> to resolve the latest compatible versions rather than copying pins.

Exercises

Exercise 1: Round-trip a password

Difficulty: Easy

Objective: Get comfortable with the hash_password → store → verify_password cycle and confirm salting works.

Instructions: Write a program that hashes the password "hunter2" with Argon2::default() and a freshly generated salt, prints the PHC string, and then verifies both "hunter2" (should succeed) and "Hunter2" (should fail). As a final check, hash "hunter2" a second time and assert the two PHC strings are different. Fill in the /* ??? */ parts:

1
// The TypeScript you are translating:
2
import argon2 from "argon2";
3
const hash = await argon2.hash("hunter2");
4
console.log(await argon2.verify(hash, "hunter2")); // true
5
console.log(await argon2.verify(hash, "Hunter2")); // false

Solution

1
// cargo add argon2 --features std
2
use argon2::{
3
    password_hash::{
4
        rand_core::OsRng, PasswordHash, PasswordHasher, PasswordVerifier, SaltString,
5
    },
6
    Argon2,
7
};
8

9
fn main() {
10
    let salt = SaltString::generate(&mut OsRng);
11
    let hash = Argon2::default()
12
        .hash_password(b"hunter2", &salt)
13
        .unwrap()
14
        .to_string();
15
    println!("{hash}");
16

17
    let parsed = PasswordHash::new(&hash).unwrap();
18
    println!(
19
        "hunter2 -> {}",
20
        Argon2::default().verify_password(b"hunter2", &parsed).is_ok()
21
    );
22
    println!(
23
        "Hunter2 -> {}",
24
        Argon2::default().verify_password(b"Hunter2", &parsed).is_ok()
25
    );
26

27
    let salt2 = SaltString::generate(&mut OsRng);
28
    let hash2 = Argon2::default()
29
        .hash_password(b"hunter2", &salt2)
30
        .unwrap()
31
        .to_string();
32
    assert_ne!(hash, hash2, "random salts must produce different hashes");
33
    println!("two hashes differ: {}", hash != hash2);
34
}

Running this prints a PHC string, then hunter2 -> true, Hunter2 -> false, and two hashes differ: true.

Exercise 2: A reusable, parameter-aware hasher

Difficulty: Medium

Objective: Wrap Argon2 behind a small struct with explicit cost parameters and clean error handling.

Instructions: Define a Hasher struct that owns an Argon2<'static> configured with Params::new(19_456, 2, 1, None) and Algorithm::Argon2id. Give it two methods: hash(&self, password: &str) -> Result<String, argon2::password_hash::Error> and verify(&self, password: &str, stored: &str) -> Result<bool, argon2::password_hash::Error> (return Ok(true)/Ok(false) for match/mismatch, and propagate only structural errors such as a corrupt PHC string). Demonstrate it on "pa$$w0rd".

Solution

1
// cargo add argon2 --features std
2
use argon2::{
3
    password_hash::{
4
        rand_core::OsRng, Error, PasswordHash, PasswordHasher, PasswordVerifier,
5
        SaltString,
6
    },
7
    Algorithm, Argon2, Params, Version,
8
};
9

10
struct Hasher {
11
    inner: Argon2<'static>,
12
}
13

14
impl Hasher {
15
    fn new() -> Self {
16
        let params = Params::new(19_456, 2, 1, None).expect("valid params");
17
        Hasher {
18
            inner: Argon2::new(Algorithm::Argon2id, Version::V0x13, params),
19
        }
20
    }
21

22
    fn hash(&self, password: &str) -> Result<String, Error> {
23
        let salt = SaltString::generate(&mut OsRng);
24
        Ok(self
25
            .inner
26
            .hash_password(password.as_bytes(), &salt)?
27
            .to_string())
28
    }
29

30
    fn verify(&self, password: &str, stored: &str) -> Result<bool, Error> {
31
        // A bad PHC string is a real error; a wrong password is just `Ok(false)`.
32
        let parsed = PasswordHash::new(stored)?;
33
        match self.inner.verify_password(password.as_bytes(), &parsed) {
34
            Ok(()) => Ok(true),
35
            Err(Error::Password) => Ok(false),
36
            Err(e) => Err(e),
37
        }
38
    }
39
}
40

41
fn main() -> Result<(), Error> {
42
    let hasher = Hasher::new();
43
    let stored = hasher.hash("pa$$w0rd")?;
44
    println!("{stored}");
45
    println!("right: {}", hasher.verify("pa$$w0rd", &stored)?); // true
46
    println!("wrong: {}", hasher.verify("nope", &stored)?); // false
47
    Ok(())
48
}

The key idea is distinguishing a wrong password (Error::Password → Ok(false), a normal control-flow outcome) from a structural failure (a corrupt stored hash → propagated Err). This mirrors how you would surface a 401 vs a 500 in a web service.

Exercise 3: Detect outdated hashes for transparent rehashing

Difficulty: Hard

Objective: Implement the “upgrade cost over time” best practice: after a successful login, decide whether a stored hash used weaker-than-current parameters and should be re-hashed.

Instructions: Write needs_rehash(stored: &str, current: &Params) -> bool that parses the stored PHC string, reads its embedded Argon2 Params, and returns true if the stored memory cost (m_cost) or iteration count (t_cost) is lower than current’s. Use argon2::Params::try_from(&PasswordHash) to recover the parameters. Test it with a hash made at m=8,t=1 against a current policy of m=19_456,t=2.

Hint: Params::try_from(&password_hash) returns the parameters encoded in the PHC string. Compare .m_cost() and .t_cost().

Solution

1
// cargo add argon2 --features std
2
use argon2::{
3
    password_hash::{rand_core::OsRng, PasswordHash, PasswordHasher, SaltString},
4
    Algorithm, Argon2, Params, Version,
5
};
6

7
fn needs_rehash(stored: &str, current: &Params) -> bool {
8
    let parsed = match PasswordHash::new(stored) {
9
        Ok(p) => p,
10
        Err(_) => return true, // unparseable -> force a rehash on next login
11
    };
12
    match Params::try_from(&parsed) {
13
        Ok(used) => used.m_cost() < current.m_cost() || used.t_cost() < current.t_cost(),
14
        Err(_) => true,
15
    }
16
}
17

18
fn main() {
19
    // An old, weak hash: 8 KiB memory, 1 iteration.
20
    let weak_params = Params::new(8, 1, 1, None).unwrap();
21
    let weak = Argon2::new(Algorithm::Argon2id, Version::V0x13, weak_params)
22
        .hash_password(b"pw", &SaltString::generate(&mut OsRng))
23
        .unwrap()
24
        .to_string();
25

26
    // Current policy: 19 MiB memory, 2 iterations.
27
    let current = Params::new(19_456, 2, 1, None).unwrap();
28

29
    println!("weak hash needs rehash: {}", needs_rehash(&weak, &current)); // true
30

31
    // A hash made at current policy does NOT need a rehash.
32
    let strong = Argon2::new(Algorithm::Argon2id, Version::V0x13, current.clone())
33
        .hash_password(b"pw", &SaltString::generate(&mut OsRng))
34
        .unwrap()
35
        .to_string();
36
    println!("strong hash needs rehash: {}", needs_rehash(&strong, &current)); // false
37
}

In a real login handler you would call needs_rehash after a successful verify_password, and if it returns true, re-hash the plaintext you just verified (with current parameters) and update the database row — upgrading every active user’s security without a forced password reset.

Password Hashing

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Why slow + salted, line by line

Anatomy of the PHC string

Argon2id vs Argon2i vs Argon2d

Tuning the cost parameters

The bcrypt alternative

Key Differences

Common Pitfalls

Forgetting to import the trait

Comparing hashes with == instead of verifying

Using a fast general-purpose hash

bcrypt’s 72-byte truncation

Logging or returning the hash

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Round-trip a password

Exercise 2: A reusable, parameter-aware hasher

Exercise 3: Detect outdated hashes for transparent rehashing

`Argon2id` vs `Argon2i` vs `Argon2d`

Comparing hashes with `==` instead of verifying