Cryptography you actually need

Production cryptography is a handful of decisions made correctly and then hidden behind a good library. You do not need the maths; you need to know which tool does which job, which parameters matter and how keys are looked after. Each primitive answers a different question: is this the same data (hash), did someone with the key produce it (MAC), can only key holders read it (encryption), did this specific party produce it (signature), and how do two strangers agree a key (key exchange).

If you remember one rule: modern, boring, authenticated. The library should make the safe choice the easy choice. If you find yourself choosing an IV length or a padding mode, step back and use a higher-level API (libsodium, Tink, your cloud KMS).

A hash maps any input to a fixed-size digest; it is collision resistant (hard to find two inputs with the same digest) and preimage resistant (hard to go backwards). It has no key, so it proves nothing about who made the data. An attacker who changes a file can recompute its SHA-256. Hashes are for fingerprints, deduplication, content addressing and as building blocks.

Why MD5 and SHA-1 are on the "not" list: collisions are practical. Researchers used an MD5 collision to forge a rogue CA certificate in 2008, and the SHAttered attack produced two different PDFs with the same SHA-1 digest in 2017. If an attacker can get you to sign or allow-list one document and then swap in its twin, collision resistance is the whole game.

A MAC (message authentication code) mixes in a secret key, so only key holders can produce a valid tag. HMAC-SHA256 is the default: webhook signatures, signed cookies, CSRF tokens, internal request signing. Two mistakes recur in reviews: building a MAC as sha256(secret + message), which length-extension attacks break, and comparing tags with ===, which leaks how many leading bytes matched through timing.

import { createHmac, timingSafeEqual } from "node:crypto";

// Verify a webhook: header "X-Signature: t=1731600000,v1=<hex hmac>"
export function verifyWebhook(rawBody: Buffer, header: string, secret: Buffer, nowSec: number): boolean {
  const m = /^t=(\d{10}),v1=([0-9a-f]{64})$/.exec(header);
  if (!m) return false;
  const ts = Number(m[1]);
  if (Math.abs(nowSec - ts) > 300) return false;            // 5 minute window stops replays of old events
  const expected = createHmac("sha256", secret).update(m[1] + ".").update(rawBody).digest();
  const given = Buffer.from(m[2], "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

• Sign the raw bytes you received, not a re-serialised JSON object; key order and whitespace change between libraries.
• Include a timestamp inside the signed data and reject old ones, or an attacker can replay a captured request forever.
• timingSafeEqual throws on unequal lengths, so check the length first (as above) rather than letting an exception leak information or crash the handler.

Randomness is a primitive too

Session IDs, API keys, reset tokens, nonces and salts are only as strong as the generator behind them. Use the operating system CSPRNG (crypto.randomBytes, crypto.getRandomValues, secrets.token_urlsafe in Python) and take at least 128 bits for anything an attacker might guess. Math.random is a fast statistical generator whose internal state can be recovered from a handful of outputs, after which every future "random" token is predictable. Password reset links built from a timestamp or a user ID plus a counter fall to the same attack: the attacker requests a reset for themselves, sees the pattern and computes the victim's link.

Encryption without authentication tells you nothing about who produced the ciphertext or whether it was altered. Padding-oracle attacks against CBC, bit-flipping attacks that change role=user to role=admin in an encrypted cookie: both come from decrypting data that was never authenticated. AEAD (authenticated encryption with associated data) gives confidentiality and integrity in one call, and lets you bind unencrypted context, the associated data, into the tag.

import { createCipheriv, randomBytes } from "node:crypto";

const key = loadKeyFromKms();           // 32 bytes, never in source
const nonce = randomBytes(12);          // unique per message, never reused with the same key
const cipher = createCipheriv("aes-256-gcm", key, nonce);
cipher.setAAD(Buffer.from("tenant:42")); // bind context: ciphertext cannot be replayed for tenant 43
const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
const tag = cipher.getAuthTag();        // 16-byte MAC; decrypt MUST verify this before using data
store(Buffer.concat([nonce, tag, ct]));

Symmetric keys need both sides to share a secret in advance. Public key cryptography removes that. A signature is made with a private key and checked with the public key, so anyone can verify but only one party can sign: software releases, JWTs, certificates, audit log checkpoints. Ed25519 (RFC 8032) is the default for new systems: fast, small 64-byte signatures, deterministic, so a weak or repeated per-signature random value cannot leak the private key. That exact failure, a constant ECDSA nonce, exposed Sony's PlayStation 3 signing key in 2010.

import { generateKeyPairSync, sign, verify } from "node:crypto";

const { publicKey, privateKey } = generateKeyPairSync("ed25519");   // in production: KMS or HSM
const manifest = Buffer.from(JSON.stringify({ artefact: "academy-1.42.0.tgz", sha256: digestHex }));
const sig = sign(null, manifest, privateKey);   // Ed25519 takes no separate hash algorithm
const ok = verify(null, manifest, publicKey, sig);

Key exchange lets two parties agree a shared secret over a public channel. TLS 1.3 uses ephemeral X25519 (RFC 7748): both sides generate a fresh key pair per connection and throw it away afterwards, which gives forward secrecy. Stealing the server's long-term key later does not decrypt recorded traffic, because that key only signed the handshake. Static RSA key exchange had no such property and is gone from TLS 1.3.

Key exchange output is not a key you should use directly. HKDF (RFC 5869) turns a shared secret or master key into as many independent keys as you need, each labelled by an info string. Use it to derive per-tenant or per-purpose keys from one root so that the encryption key and the MAC key are never the same bytes.

import { hkdfSync } from "node:crypto";
// One master key from KMS, separate keys per purpose and tenant
const encKey = Buffer.from(hkdfSync("sha256", masterKey, salt, "academy/v1/enc/tenant:42", 32));
const macKey = Buffer.from(hkdfSync("sha256", masterKey, salt, "academy/v1/mac/tenant:42", 32));

Algorithms are rarely the weak point. Keys are: where they live, who can read them, how they rotate. The pattern every cloud KMS uses is envelope encryption.

1. A root key lives in an HSM or KMS and never leaves it.
2. For each object or tenant, generate a data encryption key (DEK), encrypt the data with it.
3. Encrypt the DEK with the root key (wrap it) and store the wrapped DEK next to the ciphertext.
4. To read: send the wrapped DEK to KMS, get the DEK back, decrypt locally. KMS logs every unwrap.
5. To rotate the root key: re-wrap DEKs, not re-encrypt terabytes. To revoke a tenant: delete its DEKs (crypto-shredding).

Put a key ID and algorithm identifier in every ciphertext header from day one. Without them, the first rotation or algorithm change becomes a migration crisis, because you cannot tell which key encrypted which record. The key rotation and crypto agility lesson covers formats and re-encryption strategies.

Fast hashes are the wrong tool for passwords because attackers compute billions per second on GPUs. Password hashing functions are deliberately slow and memory-hard: each guess costs real memory, which GPUs and ASICs have little of per core.

Argon2id  memory=64 MiB  iterations=3  parallelism=1   (~50-100 ms server-side)
bcrypt    cost=12                                       (legacy, 72-byte input limit)
Store: $argon2id$v=19$m=65536,t=3,p=1$<salt>$<hash>
Upgrade: on successful login, if params are weaker than current policy, rehash.

• The encoded string carries its own parameters and salt, so you can raise the cost later without a flag day.
• Add a server-side pepper from KMS so a database dump alone is not crackable.
• Check new passwords against breach corpora (k-anonymity API) instead of enforcing symbol rules.
• Rate limit by account and by IP, and alert on distributed low-and-slow attempts.