Skip to main content

Password hashing

The Suite's OIDC provider stores passwords as PBKDF2-HMAC-SHA256 hashes. The stored value contains its own parameters:

pbkdf2$sha256$<iterations>$<salt_base64>$<hash_base64>

New hashes use a cryptographically random 16-byte salt, a 32-byte derived key, and 100,000 iterations. The password itself is never stored.

Why the work factor is 100,000​

This policy was selected for the former Cloudflare Workers runtime. Production and test now run on Oracle Node servers; the Workers derivation and 10 ms limits below are historical constraints, not limits of the current VM. The policy has not been changed as part of the hosting migration. The OWASP Password Storage Cheat Sheet recommends 600,000 iterations for PBKDF2-HMAC-SHA256. The former Workers runtime refused any single derivation above 100,000 with NotSupportedError, while the Workers Free plan allows 10 ms of CPU per HTTP invocation.

The disposable Worker in scripts/bench/ measured a 100,000-iteration derivation at approximately 3.5 ms on Cloudflare's edge. One derivation completed successfully; two or more in the same request were terminated with Cloudflare error 1102. Local wrangler dev did not enforce either limit, which is why local timings are not accepted as evidence for changing this setting.

The declared margin is therefore one derivation per request. The provider accepts this weaker-than-OWASP setting because it has five to ten users, administrator-issued random temporary passwords, and a login rate limiter that must run before password verification. The provider must not be cut over until that ordering is implemented by #30.

Verification and upgrades​

lib/oidc/password-hashing.ts parses the stored parameters, derives the candidate key through WebCrypto, and compares the fixed-width keys with the runtime's timing-safe comparison. Malformed or unsupported values fail authentication instead of becoming server errors.

After a successful verification, a hash with a lower iteration count is replaced with a new current-policy hash. Failed passwords are never re-hashed. The login caller is responsible for storing the returned replacement before it completes the successful sign-in.

Raising the work factor or changing the algorithm requires a benchmark on the Oracle test VM first, including verification plus rehashing an older password. Measure latency and memory under concurrent sign-ins before changing policy.