Cryptography

A practical cryptography guide for engineers who need to implement encryption, hashing, signing, and key management correctly. This skill covers the seven most common cryptographic tasks with production-ready TypeScript/Node.js code, opinionated algorithm choices, and a clear anti-patterns table. Designed for engineers who understand the basics but need confident, safe defaults.

---

When to use this skill

Trigger this skill when the user:

• Hashes or stores passwords (bcrypt, argon2, any hashing question)
• Encrypts or decrypts data at rest or in transit (AES, RSA, envelope encryption)
• Implements JWT signing, verification, or refresh token flows
• Configures TLS certificates on servers, proxies, or mutual TLS
• Implements HMAC signatures for webhooks or API request signing
• Designs or implements a key rotation strategy
• Generates cryptographically secure random tokens, IDs, or salts
• Chooses between symmetric vs asymmetric, hashing vs encryption, or any algorithm

Do NOT trigger this skill for:

• General security posture or authentication/authorization flows - use the backend-engineering security reference instead
• Building a custom cryptographic algorithm, cipher, or protocol - that is always wrong; redirect the user immediately

---

Key principles

1. Never invent your own crypto primitives - Do not implement block ciphers, hash functions, key derivation, or signature schemes. The gap between "looks correct" and "is correct" is where attackers live. Use audited libraries (Node.js crypto, bcrypt, jose, argon2) that encode decades of research.

2. Use the highest-level API available - If a library has a hashPassword() function, use it over constructing the primitive manually. High-level APIs embed safe defaults. Low-level APIs require you to know every parameter that matters.

3. Rotate keys regularly and plan for it upfront - Key rotation is not an afterthought. Envelope encryption makes rotation cheap: re-encrypt only the data key, not the data. Design systems with rotation in mind before writing the first line of code.

4. Hash passwords with bcrypt or argon2 - never MD5 or SHA* - MD5 and SHA-family hashes are fast by design. Fast hashes mean fast brute force. Password hashing needs to be slow. Argon2id is the current standard. bcrypt with cost 12+ is the safe fallback.

5. TLS 1.3 is the minimum - Disable TLS 1.0 and 1.1 everywhere. They have known attacks (BEAST, POODLE). TLS 1.2 is acceptable only as a fallback for legacy clients. TLS 1.3 removes the broken cipher suites entirely and has mandatory forward secrecy.

---

Core concepts

Symmetric vs asymmetric encryption - Symmetric uses one key for both encrypt and decrypt (AES). Fast, suitable for bulk data. The hard problem is securely sharing the key. Asymmetric uses a key pair: public key encrypts, private key decrypts (RSA, ECDH). Slower, but solves the key distribution problem. In practice, use asymmetric to exchange a symmetric key, then use symmetric for the actual data (this is what TLS does).

Hashing vs encryption - Hashing is one-way: you can verify but not reverse. Encryption is two-way: you can recover the original with the key. Use hashing for passwords (you verify, never recover). Use encryption for data you need to read back (PII, configuration secrets).

Digital signatures - Asymmetric operation where the private key signs and the public key verifies. Proves authenticity (this came from the private key holder) and integrity (data was not modified). Used in JWTs (RS256, ES256), code signing, and document verification.

Key derivation functions (KDF) - Transform a low-entropy input (password) into a high-entropy key using a slow, memory-hard algorithm. PBKDF2, bcrypt, scrypt, and Argon2 are KDFs. Do not use raw SHA-256 to derive a key from a password.

Envelope encryption - The pattern for production key management. Encrypt data with a data encryption key (DEK). Encrypt the DEK with a key encryption key (KEK) stored in a KMS. Store the encrypted DEK alongside the ciphertext. To rotate: ask KMS to re-wrap the DEK with the new KEK. The data itself never needs re-encryption.

---

Common tasks

Hash passwords with bcrypt / argon2

Use argon2 (preferred) or bcrypt (widely supported). Never use crypto.createHash for passwords.

import argon2 from 'argon2';

// Hash a password
export async function hashPassword(password: string): Promise<string> {
  return argon2.hash(password, {
    type: argon2.argon2id,
    memoryCost: 65536,   // 64 MB
    timeCost: 3,
    parallelism: 1,
  });
}

// Verify a password
export async function verifyPassword(hash: string, password: string): Promise<boolean> {
  return argon2.verify(hash, password);
}

// bcrypt fallback (cost 12+ required in production)
import bcrypt from 'bcrypt';

const SALT_ROUNDS = 12;

export async function hashPassword(password: string): Promise<string> {
  return bcrypt.hash(password, SALT_ROUNDS);
}

export async function verifyPassword(hash: string, password: string): Promise<boolean> {
  return bcrypt.compare(password, hash);
}

Always use argon2.verify / bcrypt.compare for comparison - they are constant-time. Never use === to compare hashes.

---

Encrypt data with AES-256-GCM

AES-256-GCM is authenticated encryption: it provides both confidentiality and integrity. Always use GCM mode, not CBC (CBC requires a separate MAC and is error-prone).

import { randomBytes, createCipheriv, createDecipheriv } from 'crypto';

const ALGORITHM = 'aes-256-gcm';
const KEY_LENGTH = 32; // 256 bits
const IV_LENGTH = 12;  // 96 bits - recommended for GCM
const TAG_LENGTH = 16; // 128 bits

export function encrypt(plaintext: string, key: Buffer): {
  ciphertext: string;
  iv: string;
  tag: string;
} {
  const iv = randomBytes(IV_LENGTH);
  const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: TAG_LENGTH });

  const encrypted = Buffer.concat([
    cipher.update(plaintext, 'utf8'),
    cipher.final(),
  ]);

  return {
    ciphertext: encrypted.toString('base64'),
    iv: iv.toString('base64'),
    tag: cipher.getAuthTag().toString('base64'),
  };
}

export function decrypt(
  ciphertext: string,
  iv: string,
  tag: string,
  key: Buffer
): string {
  const decipher = createDecipheriv(
    ALGORITHM,
    key,
    Buffer.from(iv, 'base64'),
    { authTagLength: TAG_LENGTH }
  );

  decipher.setAuthTag(Buffer.from(tag, 'base64'));

  return Buffer.concat([
    decipher.update(Buffer.from(ciphertext, 'base64')),
    decipher.final(),
  ]).toString('utf8');
}

// Generate a key (store in KMS, never hardcode)
export function generateKey(): Buffer {
  return randomBytes(KEY_LENGTH);
}

Never reuse an IV with the same key. Generate a fresh random IV for every encryption operation and store it alongside the ciphertext.

---

Implement JWT signing and verification

Use the jose library. It enforces algorithm allowlisting, handles key rotation via JWKS, and is actively maintained.

import { SignJWT, jwtVerify, generateKeyPair } from 'jose';

// Generate a key pair once (store private key in secrets manager)
export async function generateJwtKeys() {
  return generateKeyPair('ES256'); // prefer ES256 over RS256 - smaller, faster
}

// Sign a JWT
export async function signToken(
  payload: Record<string, unknown>,
  privateKey: CryptoKey
): Promise<string> {
  return new SignJWT(payload)
    .setProtectedHeader({ alg: 'ES256' })
    .setIssuedAt()
    .setExpirationTime('15m')      // short-lived access tokens
    .setIssuer('https://your-api.example.com')
    .setAudience('https://your-api.example.com')
    .sign(privateKey);
}

// Verify a JWT
export async function verifyToken(
  token: string,
  publicKey: CryptoKey
): Promise<Record<string, unknown>> {
  const { payload } = await jwtVerify(token, publicKey, {
    issuer: 'https://your-api.example.com',
    audience: 'https://your-api.example.com',
    algorithms: ['ES256'], // explicit allowlist - never omit this
  });
  return payload as Record<string, unknown>;
}

Always specify an algorithms allowlist in jwtVerify. The historic alg: "none" bypass happened because libraries trusted the header blindly.

---

Configure TLS certificates

For Node.js HTTPS servers, enforce TLS 1.3 and remove weak cipher suites.

import https from 'https';
import fs from 'fs';

const server = https.createServer(
  {
    key: fs.readFileSync('/etc/ssl/private/server.key'),
    cert: fs.readFileSync('/etc/ssl/certs/server.crt'),
    ca: fs.readFileSync('/etc/ssl/certs/ca.crt'), // optional: chain file

    minVersion: 'TLSv1.3',
    // If TLSv1.2 is required for legacy clients:
    // minVersion: 'TLSv1.2',
    // ciphers: [
    //   'TLS_AES_256_GCM_SHA384',
    //   'TLS_CHACHA20_POLY1305_SHA256',
    //   'ECDHE-RSA-AES256-GCM-SHA384',
    // ].join(':'),

    honorCipherOrder: true,
  },
  app
);

For certificate rotation without downtime, use Let's Encrypt with certbot and configure auto-renewal. Point your server at the live symlink (/etc/letsencrypt/live/<domain>/). On renewal, reload the process (SIGHUP for nginx; graceful restart for Node).

Mutual TLS (mTLS) for service-to-service: add requestCert: true and rejectUnauthorized: true to require client certificates.

---

Implement HMAC for webhook verification

Webhooks deliver signed payloads. HMAC-SHA256 lets receivers verify authenticity without asymmetric keys.

import { createHmac, timingSafeEqual } from 'crypto';

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET!;
const TIMESTAMP_TOLERANCE_SECONDS = 300; // 5 minutes - prevent replay attacks

export function signWebhookPayload(payload: string, timestamp: number): string {
  const message = `${timestamp}.${payload}`;
  return createHmac('sha256', WEBHOOK_SECRET).update(message).digest('hex');
}

export function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: number
): boolean {
  // Reject stale requests
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > TIMESTAMP_TOLERANCE_SECONDS) {
    return false;
  }

  const expected = signWebhookPayload(payload, timestamp);
  const expectedBuf = Buffer.from(expected, 'hex');
  const receivedBuf = Buffer.from(signature, 'hex');

  // Buffers must be equal length for timingSafeEqual
  if (expectedBuf.length !== receivedBuf.length) {
    return false;
  }

  return timingSafeEqual(expectedBuf, receivedBuf);
}

Always use timingSafeEqual for signature comparison. String === is vulnerable to timing attacks that leak whether the prefix matched.

---

Set up key rotation strategy

Envelope encryption makes rotation low-risk and incremental.

// Pseudo-implementation showing the envelope encryption + rotation pattern
interface EncryptedRecord {
  ciphertext: string;
  iv: string;
  tag: string;
  encryptedDek: string;  // DEK wrapped by KEK from KMS
  keyVersion: string;    // which KEK version was used
}

// Encryption: generate a fresh DEK per record (or per session)
async function encryptWithEnvelope(plaintext: string, kmsClient: KMSClient): Promise<EncryptedRecord> {
  const dek = generateKey(); // random 256-bit DEK
  const { ciphertext, iv, tag } = encrypt(plaintext, dek);

  // KMS wraps (encrypts) the DEK - the DEK never leaves your process in plaintext
  const { encryptedDek, keyVersion } = await kmsClient.encryptKey(dek);
  dek.fill(0); // zero out DEK from memory immediately after use

  return { ciphertext, iv, tag, encryptedDek, keyVersion };
}

// Key rotation: re-wrap the DEK with the new KEK version, no data re-encryption needed
async function rotateKey(record: EncryptedRecord, kmsClient: KMSClient): Promise<EncryptedRecord> {
  const dek = await kmsClient.decryptKey(record.encryptedDek, record.keyVersion);
  const { encryptedDek, keyVersion } = await kmsClient.encryptKey(dek, 'latest');
  dek.fill(0);
  return { ...record, encryptedDek, keyVersion };
}

Rotation strategy: when a new KEK version is available, re-wrap DEKs lazily on access or proactively in a background job. Retire old KEK versions only after all DEKs have been re-wrapped.

---

Generate secure random tokens

For session IDs, API keys, password reset tokens, and CSRF tokens, use crypto.randomBytes. Do not use Math.random.

import { randomBytes } from 'crypto';

// URL-safe base64 token (default 32 bytes = 256 bits)
export function generateToken(bytes = 32): string {
  return randomBytes(bytes).toString('base64url');
}

// Hex token (for systems that require hex)
export function generateHexToken(bytes = 32): string {
  return randomBytes(bytes).toString('hex');
}

// Numeric OTP (e.g., 6-digit)
export function generateOtp(digits = 6): string {
  const max = 10 ** digits;
  const value = Number(randomBytes(4).readUInt32BE(0)) % max;
  return value.toString().padStart(digits, '0');
}

32 bytes (256 bits) is the minimum for tokens used as secret keys or long-lived credentials. 16 bytes (128 bits) is acceptable for CSRF tokens where the attack surface is limited.

---

Anti-patterns

Anti-pattern	Why it is dangerous	What to do instead
MD5 or SHA-256 for passwords	Fast hashes enable brute force at billions of attempts/sec	Use argon2id or bcrypt (cost >= 12)
Reusing an IV/nonce with the same key	Catastrophically breaks GCM confidentiality and integrity	Generate a fresh randomBytes(12) IV for every encrypt call
alg: "none" in JWT or omitting algorithm allowlist	Allows token forgery by stripping the signature	Always pass algorithms: ['ES256'] (or your chosen alg) to jwtVerify
Comparing signatures with ===	String comparison short-circuits, leaking timing information	Use crypto.timingSafeEqual for all secret/signature comparisons
Math.random() for tokens or keys	Predictable PRNG, not suitable for security-sensitive values	Use crypto.randomBytes()
Encrypting passwords instead of hashing	Encrypted passwords are recoverable if the key leaks	Hash passwords; never encrypt them

---

Gotchas

1. IV reuse with AES-256-GCM is catastrophically insecure - Reusing an IV (nonce) with the same key in GCM mode allows an attacker to recover the plaintext and the authentication key. This is not a theoretical risk - it is a known attack. Generate a fresh randomBytes(12) IV for every single encrypt call without exception.

2. alg: "none" JWT bypass via missing algorithm allowlist - If you call jwtVerify without passing an explicit algorithms allowlist, some library versions accept a token with alg: "none" in the header, bypassing signature verification entirely. Always pass algorithms: ['ES256'] (or your chosen algorithm) to every verification call.

3. Timing attacks on signature comparison - Using === or .equals() to compare HMAC signatures or password hashes leaks timing information: the comparison short-circuits as soon as it finds a mismatch, revealing how many prefix bytes matched. Always use crypto.timingSafeEqual() for any security-sensitive comparison.

4. bcrypt silently truncates passwords at 72 bytes - bcrypt only processes the first 72 bytes of a password. A user with a 100-byte password gets the same hash as if they used the first 72 bytes. This is not a bug per se, but it means bcrypt does not protect extremely long passwords. Pre-hash with SHA-256 before bcrypt if you need to support passwords beyond 72 bytes.

5. Storing the DEK in plaintext next to the ciphertext - Envelope encryption only works if the data encryption key (DEK) is itself encrypted by a KMS-managed key. Storing an unencrypted DEK in the same database column as the ciphertext provides zero additional security over not encrypting at all.

---

References

• references/algorithm-guide.md - when to use which algorithm: AES vs RSA vs ECDH, SHA-256 vs Argon2, ES256 vs RS256, and cipher mode comparisons

Load the references file only when deeper algorithm selection guidance is needed. It is detailed and will consume additional context.