The Web Crypto API

Use platform cryptography, not clever code

Web Crypto is the browser and Node runtime interface to audited cryptographic primitives. It works with typed arrays, bytes from TextEncoder, and promises from Promises and async/await. Use it when a frontend needs secure random values, digests, HMACs, encryption, signatures, or key import/export. Do not design your own cryptography.

Practical connections: CSRF, cookies & tokens uses random tokens and PKCE hashes; supply-chain security uses Subresource Integrity hashes; IndexedDB can store non-extractable keys; and Web Storage is where keys and long-lived bearer tokens should usually not go.

Randomness is the first place frontend code often goes wrong. Math.random() is fine for animations and sampling demos, but it is not cryptographically secure and must never create tokens, password reset links, CSRF secrets, PKCE verifiers, encryption keys, or IDs attackers can guess. Use crypto.getRandomValues for bytes and crypto.randomUUID() for RFC 4122 version 4 UUIDs.

1function bytesToHex(bytes) {2  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");3}4 5function randomToken(byteLength = 16, cryptoImpl = crypto) {6  const bytes = new Uint8Array(byteLength);7  cryptoImpl.getRandomValues(bytes);8  return bytesToHex(bytes);9}10 11const fixedCrypto = {12  getRandomValues(bytes) {13    bytes.set([0xde, 0xad, 0xbe, 0xef].slice(0, bytes.length));14    return bytes;15  },16};17 18console.log(randomToken(4, fixedCrypto));19console.log(randomToken(16).length);20console.log("differs every run");

The first printed token uses an injected fixed source so tests can prove the formatter. The 16-byte token length and real token value differ every run when the default crypto source fills the array. The important property is unpredictability, not a pretty format.

1const uuid = crypto.randomUUID();2const v4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;3console.log(v4.test(uuid));4console.log(uuid.slice(14, 15));5console.log("differs every run");

A UUID v4 has a 4 in the version position and 8, 9, a, or b in the variant position. The value itself differs every run, so tests validate it with a regex instead of comparing one literal string.

1console.log("65536 bytes", crypto.getRandomValues(new Uint8Array(65536)).length);2try {3  crypto.getRandomValues(new Uint8Array(65537));4} catch (error) {5  console.log(error.name);6  console.log(error.message);7}

A common mistake is sample % max. If the random range is not evenly divisible by max, some results get one extra source value. For a 32-bit sample and max = 10, residues 0 through 5 would happen one extra time. Rejection sampling discards the tiny tail so every accepted result has the same count.

1function randomInt(max, source = crypto) {Run2  const range = 0x100000000;3  const limit = Math.floor(range / max) * max;4  const sample = new Uint32Array(1);5  do {6    source.getRandomValues(sample);7  } while (sample[0] >= limit);8  return sample[0] % max;9}10 11const fake = {12  getRandomValues(array) {13    array[0] = array[0] === 0 ? 4294967294 : 8;14    return array;15  },16};17 18console.log(randomInt(10, fake));

Hash functions are deterministic, one-way, and fixed length. SHA-256 returns 32 bytes no matter how large the input is. To hash text, encode it to bytes, await crypto.subtle.digest, then choose a display format such as hex. You already saw those byte-to-text display formats in Text encoding & Base64.

1async function sha256Hex(message) {2  const bytes = new TextEncoder().encode(message);3  const digest = await crypto.subtle.digest("SHA-256", bytes);4  return [...new Uint8Array(digest)]5    .map((byte) => byte.toString(16).padStart(2, "0"))6    .join("");7}8 9sha256Hex("abc").then(console.log);

The known SHA-256 test vector for "abc" is ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad. If your helper prints anything else, the bytes or hex conversion are wrong.

1async function sha256Hex(message) {2  const bytes = new TextEncoder().encode(message);3  const digest = await crypto.subtle.digest("SHA-256", bytes);4  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");5}

Hashes are useful for integrity checks such as Subresource Integrity, cache keys, and comparing content without storing the content itself. They are not encryption and cannot be reversed.

A plain hash says “these bytes match.” It does not say who created the digest. HMAC adds a shared secret key, so a receiver can verify the message came from someone who knows the secret and that the message was not changed. Webhooks often use this pattern.

1async function hmacHex(message, secret) {2  const encoder = new TextEncoder();3  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);4  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(message));5  return [...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, "0")).join("");6}7 8async function verifyHmac(message, secret, hex) {9  const encoder = new TextEncoder();10  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);11  const signature = Uint8Array.from(hex.match(/../g), (pair) => parseInt(pair, 16));12  return crypto.subtle.verify("HMAC", key, signature, encoder.encode(message));13}14 15(async () => {16  const message = "The quick brown fox jumps over the lazy dog";17  const signature = await hmacHex(message, "key");18  console.log(signature);19  console.log(await verifyHmac(message, "key", signature));20  console.log(await verifyHmac(message + "!", "key", signature));21})();

Passwords are different. Do not store SHA-256(password). SHA-256 is intentionally fast, which helps attackers guess billions of candidates. Prefer server-side password hashing libraries using Argon2id, bcrypt, or scrypt. Web Crypto has PBKDF2 and HKDF; when PBKDF2-HMAC-SHA-256 is required, current OWASP guidance is about 600,000 iterations or more for new applications. The next snippet uses only 1,000 iterations so the browser demo finishes quickly.

1async function deriveDemoKey(password, salt, iterations = 1000) {2  const encoder = new TextEncoder();3  const baseKey = await crypto.subtle.importKey("raw", encoder.encode(password), "PBKDF2", false, ["deriveBits"]);4  const bits = await crypto.subtle.deriveBits(5    { name: "PBKDF2", hash: "SHA-256", salt: encoder.encode(salt), iterations },6    baseKey,7    256,8  );9  return [...new Uint8Array(bits)].map((byte) => byte.toString(16).padStart(2, "0")).join("");10}11 12deriveDemoKey("correct horse battery staple", "demo-salt", 1000).then((hex) => {13  console.log(hex);14  console.log("demo iterations only");15});

AES-GCM is the Web Crypto workhorse for symmetric encryption. It uses one shared key to encrypt and decrypt, a 12-byte IV for each message, and an authentication tag that travels with the ciphertext. Reusing an IV with the same key can reveal data and break authentication. Store the IV beside the ciphertext; it is not secret, it just must be unique for that key.

1async function aesGcmDemo() {2  const keyBytes = new Uint8Array([...Array(32).keys()]);Run3  const iv = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]);4  const key = await crypto.subtle.importKey("raw", keyBytes, "AES-GCM", false, ["encrypt", "decrypt"]);5  const encoded = new TextEncoder().encode("meet at noon");6  const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoded);7  const plaintext = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ciphertext);8  const hex = [...new Uint8Array(ciphertext)].map((byte) => byte.toString(16).padStart(2, "0")).join("");9  console.log(hex);10  console.log(new TextDecoder().decode(plaintext));11}12 13aesGcmDemo();

1async function encryptMessage(text) {2  const key = await crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);3  const iv = crypto.getRandomValues(new Uint8Array(12));4  const ciphertext = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, new TextEncoder().encode(text));5  return { key, iv, ciphertext: new Uint8Array(ciphertext) };6}7 8async function decryptMessage(record) {9  const bytes = await crypto.subtle.decrypt({ name: "AES-GCM", iv: record.iv }, record.key, record.ciphertext);10  return new TextDecoder().decode(bytes);11}

When the last byte is tampered, Web Crypto rejects decrypt with OperationError. That rejection is the security feature: do not catch it and continue as if you had trustworthy text. For asymmetric encryption, RSA-OAEP can encrypt small secrets such as a random AES key, while ECDH derives a shared secret that you feed into a KDF. In modern systems, asymmetric crypto usually protects or agrees on symmetric keys; AES-GCM protects the bulk data.

Encryption hides content. Signing proves a holder of the private key approved the message. The message can still be public. Web Crypto widely supports ECDSA with P-256. Chrome 154 and Node 22.23.1 also support Ed25519, but production code should feature-detect because support is newer across the platform.

1async function supportsEd25519() {2  try {3    const pair = await crypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]);4    const message = new TextEncoder().encode("hello");5    const signature = await crypto.subtle.sign({ name: "Ed25519" }, pair.privateKey, message);6    const ok = await crypto.subtle.verify({ name: "Ed25519" }, pair.publicKey, signature, message);7    return ok && signature.byteLength === 64;8  } catch {9    return false;10  }11}12 13async function ecdsaDemo() {14  const message = new TextEncoder().encode("ship release 42");15  const pair = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);16  const signature = await crypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, pair.privateKey, message);17  console.log(await supportsEd25519());18  console.log(await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, pair.publicKey, signature, message));19  console.log(await crypto.subtle.verify({ name: "ECDSA", hash: "SHA-256" }, pair.publicKey, signature, new TextEncoder().encode("ship release 43")));20}21 22ecdsaDemo();

Signatures are how package manifests, update feeds, and authorization statements can be checked without sharing a symmetric secret. They do not hide the message. If the message is confidential, encrypt it separately and verify both confidentiality and authenticity.

Web Crypto does not hand you raw bytes by default. It hands you CryptoKey objects with type, extractable, algorithm, and usages. Those properties are part of the security boundary: a key meant only for verify cannot sign, and a non-extractable key cannot be exported as raw bytes.

1async function inspectKeys() {2  const aesKey = await crypto.subtle.generateKey({ name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"]);3  console.log(aesKey.type + " " + aesKey.extractable + " " + aesKey.usages.join(","));4  console.log((await crypto.subtle.exportKey("raw", aesKey)).byteLength);5  console.log((await crypto.subtle.exportKey("jwk", aesKey)).kty);6 7  const pair = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);8  console.log((await crypto.subtle.exportKey("spki", pair.publicKey)).byteLength > 0);9  console.log((await crypto.subtle.exportKey("pkcs8", pair.privateKey)).byteLength > 0);10}11 12inspectKeys();

Non-extractable keys can still be stored by the browser. IndexedDB can persist a CryptoKey object without exposing its raw bytes, which is safer than putting key material in localStorage. The fragment below is intentionally not runnable in the lesson editor because real IndexedDB setup needs a database wrapper and application-specific lifecycle decisions.

1async function makeStoredKey() {2  const key = await crypto.subtle.generateKey(3    { name: "AES-GCM", length: 256 },4    false,5    ["encrypt", "decrypt"],6  );7  // Store the non-extractable CryptoKey object itself, not raw key bytes.8  const db = await openIndexedDbSomewhere();9  await db.put("keys", key, "message-key");10  return key.extractable;11}

If you do export key material, know the format: raw for symmetric bytes, jwk for JSON Web Keys, spki for public keys, and pkcs8 for private keys. Private key export should be rare, encrypted at rest, and handled outside ordinary page scripts whenever possible.

What not to do

• Do not roll your own crypto. Compose audited primitives and protocols instead.
• Do not use ECB mode. Web Crypto does not expose AES-ECB; use authenticated modes such as AES-GCM.
• Do not reuse AES-GCM IVs with the same key. Generate a fresh 12-byte IV per message.
• Do not store keys in localStorage. XSS can read it. Prefer non-extractable keys in IndexedDB or server-side keys.
• Do not confuse encoding, hashing, encryption, and signing. Each answers a different security question.

Key takeaways

• Use crypto.getRandomValues and crypto.randomUUID for security-sensitive randomness; never use Math.random for secrets.
• crypto.subtle is promise-based and works on bytes, so encode text before hashing, signing, or encrypting.
• SHA-256 is deterministic, one-way, and fixed length. HMAC adds a shared secret; PBKDF2 slows derivation but frontend demos use low iterations only for speed.
• AES-GCM needs a fresh 12-byte IV for each message with the same key, and tampering must reject.
• CryptoKey metadata, extractability, usages, and import/export formats are part of key management.
• Keep keys out of script-readable storage; consider non-extractable keys in IndexedDB or server-side key management.

Final definition: Web Crypto gives JavaScript audited primitives for random bytes, hashes, authentication, encryption, signatures, derivation, and keys. Your job is to choose the right primitive, feed it bytes, and respect the key and nonce rules.

Up next: Measuring performance, where the focus shifts from keeping users safe to proving which code is actually slow.