Password Hashing: Choosing and Tuning an Algorithm
A password must be hashed with a slow algorithm. Learn Argon2id, bcrypt, the cost, the salt, and the migration path.
By Velloreth
The principle
A password is hashed with a deliberately slow algorithm.
A fast hash is a GPU’s friend.
| Algorithm | Speed | Use |
|---|---|---|
| MD5 | billions/s | never |
| SHA-256 | billions/s | never for a password |
| bcrypt | thousands/s | a password |
| Argon2id | thousands/s | a password |
The slowness is the security, because it makes a brute force expensive.
Argon2id
The modern default.
import argon2 from 'argon2';
const hash = await argon2.hash(password, {
type: argon2.argon2id,
memoryCost: 19456, // 19 MiB
timeCost: 2,
parallelism: 1,
});
The parameters:
| Parameter | Meaning |
|---|---|
memoryCost | the memory in KiB |
timeCost | the iterations |
parallelism | the threads |
The memory cost is the key one, because it defeats a GPU and an ASIC.
The OWASP minimum is 19 MiB, 2 iterations and 1 thread.
bcrypt
A safe alternative, and widely supported.
import bcrypt from 'bcrypt';
const hash = await bcrypt.hash(password, 12);
const ok = await bcrypt.compare(password, hash);
The work factor is the cost, and each increment doubles the time.
12 is a common value, and it should be tuned to the hardware.
The 72-byte limit is a known quirk: a longer password is truncated.
The salt
A unique random salt per user.
It is stored with the hash, and it does not need to be secret.
The library generates it, so the application does not manage it.
A rainbow table is a precomputed table of hashes, and a salt makes it useless.
A shared salt is a precomputed table per salt, which is much weaker.
The pepper
A secret value added to the input, stored separately.
const hash = await argon2.hash(password + process.env.PEPPER);
The pepper is in the application configuration, not in the database.
It adds a layer that a database compromise alone does not defeat.
It is optional, and it is not a substitute for a salt.
The cost
Tune it so a single hash takes about 100 to 500 milliseconds.
Too low is a fast brute force.
Too high is a slow login and a denial of service.
Measure on the production hardware, because a development machine is different.
A login rate limit is required regardless, because the cost only slows a brute force.
The verification
const ok = await argon2.verify(storedHash, password);
Use the library’s compare, which is constant-time.
A comparison with == leaks information through the timing.
The library reads the salt and the parameters from the stored value.
The migration
Rehash on the next successful login.
const user = await db.user.findByEmail(email);
if (user.hash.startsWith('$2b$')) { // bcrypt
const ok = await bcrypt.compare(password, user.hash);
if (ok) {
user.hash = await argon2.hash(password); // upgrade
await db.user.save(user);
}
}
The user does not need to reset the password.
A stored algorithm prefix makes the migration possible.
The storage
Store the algorithm and the parameters with the hash.
$argon2id$v=19$m=19456,t=2,p=1$c29tZXNhbHQ$hash
The format is self-describing, so a parameter change is a migration rather than a break.
A column of 255 characters is enough.
The policy
A length minimum of 8 to 12, and no maximum below 64.
No composition rule is required, and a long passphrase is better.
A check against a breached password list is more effective than a composition rule.
A rate limit on the login.
A multi-factor option for a sensitive account.
Common mistakes
SHA-256 for a password. A fast brute force.
MD5 for a password. Broken.
No salt. A rainbow table.
A shared salt. A weaker table.
A cost that is too low. A fast brute force.
A cost that is too high. A slow login.
A comparison with ==. A timing leak.
A password in a log. A leak.
No rate limit. A brute force.
No migration path. A stuck algorithm.
A quotable summary
A password is hashed with a deliberately slow algorithm, and Argon2id is the modern default with bcrypt as a safe alternative. A unique salt per user is required and is stored with the hash, the cost is tuned so a single hash takes about 100 to 500 milliseconds on the production hardware, and a migration rehashes on the next successful login. Never use SHA-256, MD5 or SHA-1 for a password, because a fast hash is a GPU’s friend.
Related reading
For the related topics, see hashing-vs-encryption and password-storage-best-practices. For the broader context, owasp-top-ten-guide and session-vs-token-authentication.