Hashing & Salting

The message is from a security researcher, not a customer. A file called users.csv is being passed around a forum, and its column names are yours. Somebody got a copy of the users table — through an injectable query, a public backup bucket, a laptop with a database dump on it — and the password column came with it. Whatever that column holds now belongs to someone with unlimited time and hardware of their own, and nothing you change on your servers today reaches their copy.

That is the day password storage is designed for: not the login form, which you control, but the breach, which you did not. If the column holds passwords as typed, the attacker has everything, and not only on your site. People reuse passwords, so your users’ email and bank accounts are now exposed through you.

Why not encrypt them

The obvious fix is to encrypt the column, and it fails for a structural reason rather than a mathematical one. Encryption is reversible by design: whoever holds the key gets every password back. Your login code needs that key, so it lives somewhere the application can read it — an environment variable, a config file, a secrets service. The attacker who copied the database usually came in through that same application or its backups, and the key tends to travel with the data.

A login never needs the password back. It only has to answer one question: is this the password chosen at signup? Run the password through a one-way function — a cryptographic hash such as SHA-256 — and store only the output, called the digest. At login, hash what was typed and compare digests. There is no key to steal and no way to run the function backwards. The only route from a digest to a password is to guess one, hash it, and see whether the digests match.

Why a fast hash fails anyway

That last sentence is the whole attack, and a plain hash makes it cheap in three ways. Identical passwords give identical digests: if Ada and Bob both chose letmein, both rows read 1c8b…, so the attacker knows they match before cracking anything, and cracking one cracks both. The digest of a password is also the same on every site that stores it this way, so attackers work in advance: hash millions of known passwords once, keep the pairs, and every unsalted breach becomes a lookup. Rainbow tables are a more compact form of the same idea. And SHA-256 is fast on purpose, because checksums and signatures need it to be; on graphics cards an attacker computes fast hashes by the billions per second.

This is a different job from the hash inside a hash table. A table’s hash only has to be quick and spread keys evenly; it does not need to be one-way, because nothing about a bucket number is secret. SHA-256 adds one-wayness. A password hash adds the property neither of them has: it is deliberately slow.

Salt: a different hash for every user

A salt is a random value, typically 16 bytes from a cryptographic random generator, created fresh for each user whenever they set a password. It is hashed together with the password and stored in the clear, right beside the result. It is not a secret. Its job is to give every user a different hash: with Ada’s salt mixed in, letmein gives one digest; with Bob’s, an unrelated one. That is why it must be unique. One salt shared by every user still gives equal passwords equal digests, and the attacker simply builds one table for it.

The scene runs the same two signups twice, against the same attacker: above, straight into SHA-256; below, with a salt drawn first. The badge on the attacker counts the lookups it makes in its precomputed table.

The attacker still has the salted rows, salts included. What is gone is everything that relied on two digests being comparable. Ada and Bob no longer look alike. A precomputed table is useless, because nobody could build one for salts that did not exist yet. And one guess no longer tests every account at once: letmein must be hashed with Ada’s salt, then again with Bob’s. The salt turns the attacker’s work from a cost per password into a cost per user.

What it does not change is the price of one guess. The attacker reads Bob’s salt from his row, hashes letmein with it, and compares: one SHA-256, as cheap as ever.

Slow on purpose

Password hashing functions go after that price. bcrypt, scrypt and Argon2id are the three to know, and all are slow by design, with a cost setting you choose. bcrypt’s work factor doubles the work with every step up; scrypt and Argon2id also demand a set amount of memory for every hash. That matters because graphics cards get their speed from thousands of cores side by side, each with little memory of its own, so a guess that needs many megabytes takes most of that parallelism away. For new code Argon2id is the usual first choice; scrypt and bcrypt remain sound.

Put numbers on the three designs, with round, illustrative figures rather than benchmarks: 1,000,000 users leak, and the attacker has 10 million likely passwords and hardware that computes a billion fast hashes a second.

• Unsalted SHA-256. Hash the list once and compare each digest against every row: 10 million hashes, a hundredth of a second, every user at once.
• Salted SHA-256. The list is hashed again for each salt: 10 million × 1,000,000 is 10¹³ hashes, or 10,000 seconds. Under three hours.
• Salted and slow. A cost that makes each hash 100,000 times the work of one SHA-256 turns a billion a second into 10,000. The same job takes 10⁹ seconds, about 32 years in all, or 17 minutes for each user, and every doubling of the cost doubles both figures.

Your server pays that price too, at every login, so the cost is set to what a login can afford and raised as hardware gets faster. And slow only slows guessing: letmein is near the top of every list and still falls in under a second. The defense for the worst passwords is refusing them at signup, checked against lists of passwords already seen in breaches.

A login repeats the signup: read the salt from the row, hash the attempt with it at the same cost, and compare with the stored hash in constant time. An ordinary equality check can stop at the first differing byte, so its timing hints at how much of a guess was right. Against a slow, salted hash that is hard to exploit, but the safe comparison costs nothing. You may also meet a pepper, a secret key mixed into every hash and kept outside the database. It helps only if it truly lives elsewhere, the condition that sank encryption, and it replaces none of the above.

Node ships scrypt in its standard library, so the whole scheme is a few lines:

import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto';

/** The cost. Doubling N doubles the time and the memory of every hash. */
const COST = { N: 2 ** 17, r: 8, p: 1, maxmem: 256 * 1024 * 1024 };

function derive(password: string, salt: Buffer): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    scrypt(password, salt, 32, COST, (error, key) =>
      error ? reject(error) : resolve(key),
    );
  });
}

async function hashPassword(password: string): Promise<string> {
  const salt = randomBytes(16); // new for every user, stored in the clear
  const hash = await derive(password, salt);
  return `${salt.toString('hex')}:${hash.toString('hex')}`;
}

async function verifyPassword(password: string, stored: string) {
  const [salt = '', hash = ''] = stored.split(':');
  const actual = await derive(password, Buffer.from(salt, 'hex'));
  return timingSafeEqual(actual, Buffer.from(hash, 'hex'));
}

The stored string is the salt and the hash, joined by a colon. It uses the callback form of scrypt because scryptSync would block the event loop for the whole of every hash. Real formats carry more: a bcrypt string starts with its version and cost, as in $2b$12$, and bcrypt and Argon2 libraries generate the salt for you. They store the cost because the cost will change. Raise N here and every existing user is locked out, because their hashes were made with the old one.

interface User {
  passwordHash: string;
}

/** Today's cost. Raise it, and every stored hash still verifies at its own. */
const CURRENT_N = 2 ** 17;

function derive(password: string, salt: Buffer, N: number): Promise<Buffer> {
  const cost = { N, r: 8, p: 1, maxmem: 256 * 1024 * 1024 };
  return new Promise((resolve, reject) => {
    scrypt(password, salt, 32, cost, (error, key) =>
      error ? reject(error) : resolve(key),
    );
  });
}

async function hashPassword(password: string, N = CURRENT_N) {
  const salt = randomBytes(16);
  const hash = await derive(password, salt, N);
  return `${N}:${salt.toString('hex')}:${hash.toString('hex')}`;
}

async function verifyPassword(password: string, stored: string) {
  const [cost = '', salt = '', hash = ''] = stored.split(':');
  const N = Number(cost);
  const actual = await derive(password, Buffer.from(salt, 'hex'), N);
  const ok = timingSafeEqual(actual, Buffer.from(hash, 'hex'));
  return { ok, needsRehash: ok && N < CURRENT_N };
}

async function logIn(user: User, password: string): Promise<boolean> {
  const { ok, needsRehash } = await verifyPassword(password, user.passwordHash);
  if (needsRehash) user.passwordHash = await hashPassword(password);
  return ok;
}

const user: User = { passwordHash: await hashPassword('letmein', 2 ** 14) };
console.log(user.passwordHash.split(':')[0]); // 16384
console.log(await logIn(user, 'letmein'), user.passwordHash.split(':')[0]);
// true 131072
console.log(await logIn(user, 'letmeout')); // false