Web APIsBaseline · Widely

Web Crypto API and SubtleCrypto

Mental Model

window.crypto.subtle delegates hashing, authenticated encryption, and key derivation to the browser's native C++ cryptographic library (BoringSSL, NSS, or CommonCrypto). Operations run off the main thread, require HTTPS, and can lock raw key material inside non-extractable CryptoKey objects.

Interactive Simulator

Client Hashing & Encryption: JS Crypto Polyfill vs SubtleCrypto

Lines of Code
Before
3
After
4
Reflows / Browser Cost
Before
Main-thread block
After
Native C++ thread
BeforePure-JS Crypto Library (crypto-js)
import CryptoJS from 'crypto-js';
const hash = CryptoJS.SHA256(largePayload).toString();
// Runs synchronously on main thread; key sits in JS heap
Lines: 3Reflows: Main-thread blockDependencies: ~45 kB min+gz

Blocks JS thread, ships 45 kB bundle, exposes raw key strings.

After (Native)Native crypto.subtle (AES-GCM / SHA-256)
const iv = crypto.getRandomValues(new Uint8Array(12));
const cipher = await crypto.subtle.encrypt(
  { name: 'AES-GCM', iv }, key, bytes
);
Lines: 4Reflows: Native C++ threadDependencies: 0 kB

Hardware-accelerated AES-NI/SHA off-thread; non-extractable keys.

Under the Hood

SubtleCrypto is a bank safe-deposit box with a slot in the door: you slide plaintext in, and ciphertext slides out, while the key inside can be marked extractable: false so even an XSS script cannot read the raw key bytes.

  1. Native Offload: Calls dispatch to an internal browser crypto thread pool, resolving Promises on the Event Loop without blocking frames.
  2. Non-Extractable Keys: Keys generated or imported with extractable: false can be stored in IndexedDB and used to sign or decrypt, yet exportKey() rejects.
  3. Hardware Acceleration: Engines route AES-GCM and SHA-256 to CPU AES-NI / ARMv8 crypto instructions.
JS
const key = await crypto.subtle.generateKey(
  { name: 'AES-GCM', length: 256 },
  false, // non-extractable: JS can never read raw key bytes
  ['encrypt', 'decrypt']
);
const iv = crypto.getRandomValues(new Uint8Array(12));
const ciphertext = await crypto.subtle.encrypt(
  { name: 'AES-GCM', iv },
  key,
  new TextEncoder().encode('sensitive-payload')
);

Problem Genealogy

  • 2010–2014 (JS Crypto Libraries): Pure-JS implementations shipped tens of kilobytes, stalled the UI thread, and suffered timing side-channels.
  • 2015 (W3C Web Crypto API): Standardized SubtleCrypto and crypto.getRandomValues() across engines.
  • 2024+ (Ed25519 & X25519): Modern curves landed in SubtleCrypto, retiring legacy RSA-OAEP boilerplate.

Production Pitfalls

Production Pitfall
  • Reusing an AES-GCM IV: Encrypting two messages with the same key and 12-byte iv destroys confidentiality and authentication; always call crypto.getRandomValues(new Uint8Array(12)) per message.
  • Missing window.isSecureContext: crypto.subtle is undefined on plain http:// staging URLs; test over HTTPS or localhost.
When Not to Use
  • When not to use SubtleCrypto: Never roll custom client-side password hashing to replace server-side Argon2id or TLS transport security.

Connections & Logical Next Steps

Web APIsWeb Crypto API and SubtleCrypto
What This Unlocks
Leaf concept

Mechanical Comparisons