Password Storage skill for Codex

Done well means: every stored credential is a slow, salted, memory-hard hash in a self-describing format; a stolen database alone does not let an attacker test guesses (pepper); and no user is left on a legacy hash, even ones who never log in again.

Inspect first

1. Read AGENTS.md for language, framework and migration tooling.
2. Find the hashing code and the column it writes:

rg -n -i "hash|bcrypt|argon|scrypt|pbkdf|md5|sha1|sha256|password_digest|set_password|check_password" -g '!*.lock' -g '!node_modules'

3. Profile what is actually stored. Export only the hash column (never plaintext emails alongside it) and classify it:

psql "$DATABASE_URL" -Atc "select password_hash from users" > /tmp/hashes.txt
python3 scripts/identify_hashes.py /tmp/hashes.txt

The script reports counts per scheme (argon2id, bcrypt with cost, PBKDF2 with iterations, Django and passlib formats, bare hex MD5/SHA-1/SHA-256, unknown) and exits 1 if any weak or unknown formats exist. Delete the export afterwards.

Algorithm and parameters

Use the first row your platform supports well. Parameters below are the OWASP Password Storage Cheat Sheet minimums; raise them until a single verify costs roughly 100-300 ms on production hardware under expected login load.

Algorithm	Minimum parameters	Notes
Argon2id	m=19456 KiB (19 MiB), t=2, p=1	Default choice. Alternative: m=47104 (46 MiB), t=1, p=1
scrypt	N=2^17, r=8, p=1	When Argon2 bindings are unavailable
bcrypt	cost 12 (never below 10)	Only uses the first 72 bytes; see below
PBKDF2-HMAC-SHA256	600,000 iterations	Only when FIPS-140 compliance demands it

Never: plain or salted SHA-*/MD5, encryption instead of hashing, a single global salt, or a home-built “hash N times” loop.

Reference implementations

Python (argon2-cffi; pip install argon2-cffi, needs network or an approved install):

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

ph = PasswordHasher(time_cost=2, memory_cost=19456, parallelism=1)

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

def verify_and_upgrade(user, pw: str) -> bool:
    try:
        ph.verify(user.password_hash, pw)
    except (VerifyMismatchError, InvalidHashError):
        return False
    if ph.check_needs_rehash(user.password_hash):
        user.password_hash = ph.hash(pw)
        user.save(update_fields=["password_hash"])
    return True

Node (argon2 package, native build):

import argon2 from "argon2";
const opts = { type: argon2.argon2id, memoryCost: 19456, timeCost: 2, parallelism: 1 };

export const hashPassword = (pw) => argon2.hash(pw, opts);
export async function verifyAndUpgrade(user, pw) {
  if (!(await argon2.verify(user.passwordHash, pw))) return false;
  if (argon2.needsRehash(user.passwordHash, opts)) {
    await users.update(user.id, { passwordHash: await argon2.hash(pw, opts) });
  }
  return true;
}

Framework defaults worth using instead of custom code:

Framework	Setting
Django	Put Argon2PasswordHasher first in PASSWORD_HASHERS (needs argon2-cffi); old hashers stay listed so they still verify and auto-upgrade
Spring Security	Argon2PasswordEncoder.defaultsForSpringSecurity_v5_8() inside a DelegatingPasswordEncoder
Rails	has_secure_password (bcrypt); set BCrypt::Engine.cost per environment
Laravel	HASH_DRIVER=argon2id in config/hashing.php; Hash::needsRehash()
ASP.NET Core Identity	PasswordHasherOptions.IterationCount (PBKDF2) - raise it; Identity rehashes on login
Go	golang.org/x/crypto/bcrypt, or x/crypto/argon2.IDKey with your own PHC-string encoding

Pepper

A pepper is a secret key applied to every password, stored outside the database (KMS, HSM, or a secrets manager injected as an environment variable). It turns a DB-only leak into an unusable one.

import hmac, hashlib, base64

def peppered(pw: str, pepper: bytes) -> str:
    mac = hmac.new(pepper, pw.encode("utf-8"), hashlib.sha256).digest()
    return base64.b64encode(mac).decode()   # base64 avoids NUL bytes and fits bcrypt's 72-byte limit

stored = ph.hash(peppered(pw, PEPPER_V1))

Rules:

• Store a pepper version alongside each hash (pepper_id column or a prefix) so you can rotate. Rotation happens on next login, like an algorithm upgrade.
• Losing the pepper locks out every user. Back it up with the same care as a root key.
• Never commit it, never log it, never put it in the same database or backup set.

bcrypt specifics

• Input beyond 72 bytes is ignored. A 100-character passphrase and its first 72 bytes are the same password. Prehash with HMAC-SHA256 and base64 as above when you must keep bcrypt and accept long passwords. Do not prehash to raw bytes: bcrypt stops at NUL.
• Some libraries (Go x/crypto/bcrypt since 2022, recent PHP) reject > 72 bytes with an error instead of truncating. Handle the error; do not let it become a 500 on sign-up.

Migrating legacy hashes

Two paths, used together:

1. Rehash on login (default). On a successful verify with the old scheme, hash with the new one and save. Simple, but users who never return stay weak.
2. Wrap now. For every legacy row, compute argon2id(legacy_hash) immediately and mark the row scheme = 'argon2id(md5)'. On login, compute the legacy hash of the input, verify through the wrapper, then replace with a plain Argon2id hash of the password. After the batch job, no weak hash exists at rest.

- [ ] Add scheme/version column (or rely on PHC prefixes) - zero-downtime migration
- [ ] Ship verify code that understands old, wrapped and new formats
- [ ] Batch-wrap legacy rows in chunks; log progress, not hashes
- [ ] Rehash-on-login replaces wrapped hashes over time
- [ ] After N months, expire remaining wrapped accounts to a forced reset (ask the user to confirm this policy)
- [ ] Remove legacy verify code once the count reaches zero

Run the batch-wrap against a staging copy first and confirm the user before running it on production data. For the schema change itself, see $zero-downtime-migrations.

Verification

• Unit test: hash, verify correct password, reject wrong password, needs_rehash is true for a hash made with lower parameters.
• Migration test: a fixture user with an MD5 hash logs in successfully and ends up with a $argon2id$ hash; a wrapped user does the same.
• Timing check: measure one verify on production-class hardware; keep it under about 300 ms and confirm login concurrency does not exhaust memory (19 MiB per concurrent verify adds up: 200 concurrent logins is ~3.8 GB).
• Re-run scripts/identify_hashes.py after migration: weak and unknown counts are zero.

Output template

## Password storage assessment
Current: <scheme counts from identify_hashes.py>
Target: Argon2id m=<> t=<> p=<>, pepper <yes/no, where held>
Migration: <rehash-on-login | wrap + rehash>, batch size <>, ETA <>
Measured verify time: <ms> on <hardware>
Open risks: <accounts still on legacy, pepper backup status>

Gotchas

• Comparing hashes with == in your own code leaks timing; library verify functions are constant-time, so always call them.
• Hashing on the client does not replace server hashing: the client hash becomes the password.
• Memory-hard parameters on small containers or Lambda can OOM under load; load-test login before raising m.
• Logging request bodies on the auth endpoint stores plaintext passwords. Check middleware and APM body capture.