Storing passwords: Argon2id, salts, peppers and rehashing

HOW IT FITS TOGETHER

KEY TERMS

Hashing, not encryption

Verification only needs to answer "does this input produce the stored value", so nothing should be able to recover the password. Encryption is reversible by design; the key is on the same servers, in the same backups, and in the same breach.

Slow, memory-hard hashes

Argon2id, scrypt and bcrypt make each guess cost CPU time, and Argon2id and scrypt also RAM, which is what GPUs and ASICs lack per core. OWASP's Argon2id minimum is 19 MiB, 2 iterations, parallelism 1; argon2-cffi defaults to RFC 9106's 64 MiB, t=3, p=4 profile and PHP to 64 MiB, t=4, p=1, both stronger. Budget memory x concurrent logins.

Salts

A unique random value per hash (16 bytes is standard), stored in the clear inside the encoded hash. It defeats precomputed tables and forces the attacker to attack each user separately. Modern libraries generate it for you; never supply your own or reuse one.

Peppers

A secret shared by all hashes, kept in a secrets manager or HSM, never in the database. It helps only when the database leaks without the application secrets. Argon2 accepts it as the secret (K) input; with bcrypt, OWASP's suggestion is HMAC-SHA-384 with the pepper, base64-encoded, before hashing. Rotating it requires a password reset, so version it.

Rehash on login

Store algorithm and parameters with each hash (PHC string or a {id} prefix). After a successful verify, if the hash is older than current policy, hash the plaintext again and save it. For dormant accounts on a broken scheme, wrap the old hash (argon2id(md5)) now and replace it on next login, or expire the password.

Breached-password checks

Credential stuffing uses passwords leaked elsewhere, which no hash strength stops. HIBP Pwned Passwords takes only the first 5 hex characters of the SHA-1 (k-anonymity) and returns roughly 800 matching suffixes with counts; Add-Padding: true hides the true response size. Check at signup and password change.

Prefer passkeys

A passkey leaves your server with only a public key, so there is nothing to crack, stuff or phish. Offer passkeys first and keep passwords as a fallback; then the fallback and the account recovery path become the parts to harden.

IN YOUR STACK

import * as argon2 from "argon2";

// OWASP minimum; raise memoryCost while p99 login latency allows.
const PARAMS = { type: argon2.argon2id, memoryCost: 19_456, timeCost: 2, parallelism: 1 } as const;
const PEPPER = Buffer.from(process.env.PASSWORD_PEPPER_V1!, "base64"); // from a secrets manager
const DUMMY_HASH = await argon2.hash("timing-equalizer", { ...PARAMS, secret: PEPPER });

export const hashPassword = (password: string) =>
  argon2.hash(password, { ...PARAMS, secret: PEPPER });

export async function verifyLogin(email: string, password: string) {
  const user = await db.users.findByEmail(email);
  // Always run one verify so unknown emails take as long as wrong passwords.
  const ok = await argon2.verify(user?.passwordHash ?? DUMMY_HASH, password, { secret: PEPPER });
  if (!user || !ok) return null;

  if (argon2.needsRehash(user.passwordHash, PARAMS)) {
    await db.users.update(user.id, { passwordHash: await hashPassword(password) });
  }
  return user;
}

from argon2 import PasswordHasher
from argon2.exceptions import InvalidHashError, VerificationError

# Defaults: Argon2id, RFC 9106 low-memory profile (64 MiB, t=3, p=4), above OWASP's minimum.
ph = PasswordHasher()
DUMMY_HASH = ph.hash("timing-equalizer")


def hash_password(password: str) -> str:
    return ph.hash(password)


def verify_login(email: str, password: str):
    user = users.find_by_email(email)
    try:
        ph.verify(user.password_hash if user else DUMMY_HASH, password)
    except (VerificationError, InvalidHashError):  # VerifyMismatchError is a VerificationError
        return None
    if user is None:
        return None
    if ph.check_needs_rehash(user.password_hash):
        users.update(user.id, password_hash=ph.hash(password))
    return user

import (
	"crypto/rand"
	"crypto/subtle"
	"encoding/base64"
	"fmt"
	"golang.org/x/crypto/argon2"
)

const memoryKiB, iterations, threads, keyLen = 19 * 1024, 2, 1, 32
var b64 = base64.RawStdEncoding

func Hash(password string) string {
	salt := make([]byte, 16)
	rand.Read(salt) // never returns an error since Go 1.24
	key := argon2.IDKey([]byte(password), salt, iterations, memoryKiB, threads, keyLen)
	return fmt.Sprintf("$argon2id$v=%d$m=%d,t=%d,p=%d$%s$%s", argon2.Version,
		memoryKiB, iterations, threads, b64.EncodeToString(salt), b64.EncodeToString(key))
}

// p is parsed from the stored PHC string by your decodePHC helper.
func Verify(password string, p PHC) (ok, needsRehash bool) {
	got := argon2.IDKey([]byte(password), p.Salt, p.T, p.M, p.P, uint32(len(p.Key)))
	ok = subtle.ConstantTimeCompare(got, p.Key) == 1
	return ok, ok && (p.M < memoryKiB || p.T < iterations)
}

import java.util.Map;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.crypto.argon2.Argon2PasswordEncoder;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.DelegatingPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;

@Configuration
class PasswordConfig {
  @Bean
  PasswordEncoder passwordEncoder() {
    // saltLength, hashLength, parallelism, memory (KiB), iterations: OWASP minimum.
    var argon2 = new Argon2PasswordEncoder(16, 32, 1, 19_456, 2);
    Map<String, PasswordEncoder> encoders = Map.of(
        "argon2@owasp", argon2,
        "bcrypt", new BCryptPasswordEncoder(12)); // existing {bcrypt} hashes keep working
    return new DelegatingPasswordEncoder("argon2@owasp", encoders);
  }
}
// New hashes are stored as {argon2@owasp}$argon2id$... With a UserDetailsPasswordService
// bean, a successful login re-encodes any hash whose {id} differs from the current one.

<?php
const PASSWORD_OPTIONS = ['memory_cost' => 19456, 'time_cost' => 2, 'threads' => 1];
// A precomputed Argon2id hash of a random string, used when the email is unknown.
const DUMMY_HASH = '$argon2id$v=19$m=19456,t=2,p=1$...';

function hash_password(string $password): string {
    return password_hash($password, PASSWORD_ARGON2ID, PASSWORD_OPTIONS);
}

function verify_login(PDO $db, string $email, string $password): ?array {
    $stmt = $db->prepare('SELECT id, password_hash FROM users WHERE email = ?');
    $stmt->execute([$email]);
    $user = $stmt->fetch(PDO::FETCH_ASSOC) ?: null;
    $hash = $user['password_hash'] ?? DUMMY_HASH;

    if (!password_verify($password, $hash) || $user === null) {
        return null;
    }
    // True for old bcrypt ($2y$) hashes too, so this migrates them on login.
    if (password_needs_rehash($hash, PASSWORD_ARGON2ID, PASSWORD_OPTIONS)) {
        $db->prepare('UPDATE users SET password_hash = ? WHERE id = ?')
           ->execute([hash_password($password), $user['id']]);
    }
    return $user;
}

import { createHash } from "node:crypto";

export async function breachCount(password: string): Promise<number> {
  const sha1 = createHash("sha1").update(password, "utf8").digest("hex").toUpperCase();
  const prefix = sha1.slice(0, 5); // the only part that leaves your server
  const suffix = sha1.slice(5);

  const res = await fetch(`https://api.pwnedpasswords.com/range/${prefix}`, {
    headers: { "Add-Padding": "true", "User-Agent": "example-app-password-check" },
    signal: AbortSignal.timeout(2_000),
  });
  if (!res.ok) throw new Error(`Pwned Passwords returned ${res.status}`);

  for (const line of (await res.text()).split("\n")) {
    const [candidate, count] = line.trim().split(":");
    if (candidate === suffix) return Number(count); // padding rows have count 0
  }
  return 0;
}

// At signup and password change, never at login:
// if ((await breachCount(newPassword).catch(() => 0)) > 0) reject("Found in a known breach");

WHEN TO REACH FOR WHAT

WHERE IT BITES

• Hashing with SHA-256 or MD5, even salted and iterated a few times. Fast hashes fall to GPU cracking within hours for most real passwords.
• Pre-hashing for bcrypt with raw SHA output: the binary digest can contain NUL bytes that truncate the input, and an unkeyed pre-hash enables password shucking against other leaked SHA databases.
• Returning early for unknown emails. The missing hash computation makes account enumeration a timing measurement.
• Choosing parameters without load testing. 64 MiB per hash times a burst of 200 logins is 12.8 GiB; attackers can turn the login endpoint into a memory DoS.
• Storing the pepper in the same database or config table as the hashes, or rotating it without a version id and forcing every user into a reset.
• Never rehashing. Parameters chosen in 2018 stay in your database forever unless verify-time upgrades and expiry of dormant accounts move them forward.

WHEN IT BREAKS IN PRODUCTION

• The login endpoint is hammered with leaked passwords
• Passwords, tokens, or personal data show up in logs

SOURCES

• OWASP Password Storage Cheat Sheet (opens in new tab)Checked 2026-11-06
• Have I Been Pwned: API v3 (Pwned Passwords) (opens in new tab)Checked 2026-11-06
• argon2-cffi: API reference (opens in new tab)Checked 2026-11-06
• Go: golang.org/x/crypto/argon2 (opens in new tab)Checked 2026-11-06
• Spring Security: Password Storage (opens in new tab)Checked 2026-11-06
• PHP manual: password_hash (opens in new tab)Checked 2026-11-06