Web Crypto API and SubtleCrypto
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.
Client Hashing & Encryption: JS Crypto Polyfill vs SubtleCrypto
import CryptoJS from 'crypto-js';
const hash = CryptoJS.SHA256(largePayload).toString();
// Runs synchronously on main thread; key sits in JS heapBlocks JS thread, ships 45 kB bundle, exposes raw key strings.
const iv = crypto.getRandomValues(new Uint8Array(12));
const cipher = await crypto.subtle.encrypt(
{ name: 'AES-GCM', iv }, key, bytes
);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.
- Native Offload: Calls dispatch to an internal browser crypto thread pool, resolving Promises on the Event Loop without blocking frames.
- Non-Extractable Keys: Keys generated or imported with
extractable: falsecan be stored in IndexedDB and used to sign or decrypt, yetexportKey()rejects. - Hardware Acceleration: Engines route AES-GCM and SHA-256 to CPU AES-NI / ARMv8 crypto instructions.
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
SubtleCryptoandcrypto.getRandomValues()across engines. - 2024+ (Ed25519 & X25519): Modern curves landed in
SubtleCrypto, retiring legacy RSA-OAEP boilerplate.
Production Pitfalls
- Reusing an AES-GCM IV: Encrypting two messages with the same key and 12-byte
ivdestroys confidentiality and authentication; always callcrypto.getRandomValues(new Uint8Array(12))per message. - Missing
window.isSecureContext:crypto.subtleisundefinedon plainhttp://staging URLs; test over HTTPS orlocalhost.
- 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
SubtleCrypto returns Promises that resolve on the microtask queue after native thread work.
Non-extractable CryptoKeys resist exfiltration even if an XSS payload executes in the page.
TypedArrays transfer raw buffers to workers for custom math, whereas crypto.subtle processes ArrayBuffers natively off-thread.
Mechanical Comparisons
TypedArrays transfer raw buffers to workers for custom math, whereas crypto.subtle processes ArrayBuffers natively off-thread.
Non-extractable CryptoKeys resist exfiltration even if an XSS payload executes in the page.