crypto — Cryptography

Secure hashing, HMACs, random data, UUIDs, and encryption in Node.js — the crypto built-in module.

What it is, in plain English: The crypto module provides cryptographic functionality in Node.js. Use crypto.randomBytes() for cryptographically secure random data. Use crypto.randomUUID() for UUIDs. createHash() creates MD5, SHA-1, SHA-256 hashes. createHmac() creates signed hashes for API authentication. For passwords specifically, use scrypt or bcrypt (from npm) — never plain SHA hashes.

Secure random data and hashing

Never use Math.random() for security. It's not cryptographically secure. Always use crypto.randomBytes() or crypto.randomUUID() for anything security-related.

Secure random data

import { randomBytes, randomUUID, randomInt } from "crypto";

// Random bytes (for tokens, salts, keys):
const token = randomBytes(32).toString("hex");   // 64-char hex string
const salt  = randomBytes(16).toString("base64"); // 24-char base64 string

console.log("Token:", token);  // "a3f8c2..."
console.log("Salt:",  salt);

// UUID — universally unique identifier (v4):
const id = randomUUID();
console.log("UUID:", id);  // "110e8400-e29b-41d4-a716-446655440000"

// Random integer in range [min, max):
const roll = randomInt(1, 7);  // dice: 1-6
console.log("Dice:", roll);

Hashing — one-way fingerprinting

import { createHash } from "crypto";

// SHA-256 hash of a string:
function sha256(data) {
  return createHash("sha256").update(data, "utf-8").digest("hex");
}

console.log(sha256("hello"));  // "2cf24dba..." (always same for same input)
console.log(sha256("hello"));  // same
console.log(sha256("Hello"));  // completely different — case sensitive!

// SHA-256 of a file:
import { readFileSync } from "fs";
const fileHash = createHash("sha256")
  .update(readFileSync("document.pdf"))
  .digest("hex");
// Use to verify file integrity (checksums)

// Common hash algorithms:
// sha256  — most common, 256-bit output ✓
// sha512  — stronger, 512-bit output ✓
// sha1    — deprecated, collision-prone ✗
// md5     — broken for security, ok for checksums ✗

HMAC — signed hashes for authentication

import { createHmac, timingSafeEqual } from "crypto";

// HMAC = Hash + Secret Key → verifiable signature
const SECRET  = process.env.WEBHOOK_SECRET ?? "my-secret";
const payload = JSON.stringify({ event: "push", repo: "codex" });

// Sign:
const signature = createHmac("sha256", SECRET)
  .update(payload)
  .digest("hex");

console.log("Signature:", signature);

// Verify (ALWAYS use timingSafeEqual — prevents timing attacks):
function verifyHMAC(received, payload, secret) {
  const expected = createHmac("sha256", secret).update(payload).digest("hex");
  const a = Buffer.from(received, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);  // constant-time comparison
}

console.log(verifyHMAC(signature, payload, SECRET));  // true

Try It Yourself

// crypto module — Node.js cryptography
// import { randomBytes, randomUUID, createHash, createHmac, timingSafeEqual } from "crypto";

// ─── RANDOM DATA ──────────────────────────────────────────────────────────────
// NEVER use Math.random() for security — it's not cryptographically secure!

// Secure random bytes:
// const bytes = randomBytes(32);
// console.log(bytes.toString("hex"));    // 64 hex chars
// console.log(bytes.toString("base64")); // 44 base64 chars

// Random UUID (version 4):
// console.log(randomUUID()); // "110e8400-e29b-41d4-a716-446655440000"

// Simulate (in browser without crypto module):
const mockUUID = () => "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, c => {
  const r = Math.random() * 16 | 0;
  return (c === "x" ? r : (r & 0x3 | 0x8)).toString(16);
});

// ─── HASHING ─────────────────────────────────────────────────────────────────
// Hashing is ONE-WAY — you can't recover the original from the hash

function sha256(data) {
  // Browser Web Crypto API equivalent:
  // const encoder = new TextEncoder();
  // const buffer = await crypto.subtle.digest("SHA-256", encoder.encode(data));
  // return Array.from(new Uint8Array(buffer)).map(b=>b.toString(16).padStart(2,"0")).join("");

// Simple demo (NOT a real hash — just for illustration):
  let hash = 5381;
  for (let i = 0; i < data.length; i++) hash = (hash * 33 ^ data.charCodeAt(i)) >>> 0;
  return hash.toString(16).padStart(8, "0");
}

console.log("sha256('hello'):", sha256("hello"));
console.log("sha256('hello'):", sha256("hello"));  // same input → same output
console.log("sha256('Hello'):", sha256("Hello"));  // different case → different hash
console.log("sha256('hello!'):", sha256("hello!")); // one char different → completely different

// ─── NODE.JS CODE PATTERNS ───────────────────────────────────────────────────
const CRYPTO_EXAMPLES = \`
// Random token (for password reset, API keys):
const token = randomBytes(32).toString("hex");  // 64-char hex string

// SHA-256 hash:
const hash = createHash("sha256").update("data").digest("hex");

// HMAC (signed hash — for webhooks, tokens):
const sig = createHmac("sha256", secretKey).update(payload).digest("hex");

// Verify HMAC safely (prevents timing attacks):
const isValid = timingSafeEqual(Buffer.from(received, "hex"), Buffer.from(expected, "hex"));

// UUID:
const id = randomUUID();  // "550e8400-e29b-41d4-a716-446655440000"

// Password hashing (use scrypt or bcrypt — NEVER plain sha256 for passwords):
const { key } = await scrypt(password, salt, 64);  // 64-byte key
\`;

console.log("Node.js crypto patterns:");
console.log(CRYPTO_EXAMPLES.trim());

Password hashing and symmetric encryption

Password hashing with scrypt

// NEVER store passwords as plain SHA hashes — use scrypt or bcrypt
// scrypt is built into Node.js (bcrypt requires npm install)

import { scrypt, randomBytes, timingSafeEqual } from "crypto";
import { promisify } from "util";
const scryptAsync = promisify(scrypt);

const SALT_LEN  = 32;
const KEY_LEN   = 64;

async function hashPassword(password) {
  const salt = randomBytes(SALT_LEN);
  const key  = await scryptAsync(password, salt, KEY_LEN);
  return `${salt.toString("hex")}:${key.toString("hex")}`;
}

async function verifyPassword(password, stored) {
  const [saltHex, keyHex] = stored.split(":");
  const salt = Buffer.from(saltHex, "hex");
  const key  = await scryptAsync(password, salt, KEY_LEN);
  return timingSafeEqual(key, Buffer.from(keyHex, "hex"));
}

const stored = await hashPassword("my_password");
console.log("Stored:", stored);
console.log("Valid:", await verifyPassword("my_password",  stored));  // true
console.log("Invalid:", await verifyPassword("wrong_pass", stored)); // false

AES-256-GCM symmetric encryption

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

const ALGORITHM = "aes-256-gcm";
const KEY_LEN   = 32;  // 256 bits

function encrypt(plaintext, key) {
  const iv         = randomBytes(12);  // 96-bit IV for GCM
  const cipher     = createCipheriv(ALGORITHM, key, iv);
  const encrypted  = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
  const authTag    = cipher.getAuthTag();  // GCM authentication tag
  return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted.toString("hex")}`;
}

function decrypt(ciphertext, key) {
  const [ivHex, tagHex, dataHex] = ciphertext.split(":");
  const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(ivHex, "hex"));
  decipher.setAuthTag(Buffer.from(tagHex, "hex"));
  return Buffer.concat([decipher.update(Buffer.from(dataHex, "hex")), decipher.final()]).toString("utf8");
}

const key       = randomBytes(KEY_LEN);
const encrypted = encrypt("Secret message", key);
const decrypted = decrypt(encrypted, key);
console.log("Encrypted:", encrypted);
console.log("Decrypted:", decrypted);  // "Secret message"

Web Crypto API compatibility and spec

// Node.js 15+ has webcrypto compatible API (browser-compatible):
const { subtle } = globalThis.crypto;  // or: import { webcrypto } from "crypto"

// SHA-256 via Web Crypto (browser AND Node.js):
async function sha256WebCrypto(data) {
  const encoded = new TextEncoder().encode(data);
  const buffer  = await subtle.digest("SHA-256", encoded);
  return Array.from(new Uint8Array(buffer))
    .map(b => b.toString(16).padStart(2, "0")).join("");
}

// AES-GCM key generation and encryption via Web Crypto:
const key = await subtle.generateKey({ name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);
const iv  = globalThis.crypto.getRandomValues(new Uint8Array(12));
const enc = await subtle.encrypt({ name: "AES-GCM", iv }, key,
  new TextEncoder().encode("secret"));

// Key derivation — PBKDF2 (for password-based keys):
const baseKey = await subtle.importKey("raw", new TextEncoder().encode(password),
  { name: "PBKDF2" }, false, ["deriveKey"]);
const derivedKey = await subtle.deriveKey(
  { name: "PBKDF2", salt, iterations: 100000, hash: "SHA-256" },
  baseKey, { name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]
);

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.