Node.js Reference ยท crypto
Web Crypto algorithms in Node.js
How the Web Crypto API (crypto.subtle) works in Node.js: digest, AES-GCM encrypt, HMAC and ECDSA signing, key derivation, CryptoKey objects and algorithm names.
Node.js ships the standard Web Crypto API next to its classic node:crypto functions. It is available as crypto.subtle (a global crypto object exists, no import needed) or as webcrypto.subtle from node:crypto. The API is promise based, works on ArrayBuffers and typed arrays, and uses the same algorithm names in browsers, Deno and Node, so code you write once runs in all of them.
Every operation takes an algorithm description, either a string such as 'SHA-256' or an object such as { name: 'AES-GCM', iv }, and most take a CryptoKey. A CryptoKey is an opaque handle: it records which algorithm it belongs to, whether it can be exported, and which operations (usages) it may perform.
const data = new TextEncoder().encode('hello'); const digest = await crypto.subtle.digest('SHA-256', data); console.log(new Uint8Array(digest).length); // 32
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Algorithms and the methods that accept them
| Algorithm name | Purpose | Methods |
|---|---|---|
SHA-1, SHA-256, SHA-384, SHA-512 |
Hashing | digest() |
HMAC |
Keyed message authentication | generateKey, importKey, sign, verify |
AES-GCM, AES-CBC, AES-CTR |
Symmetric encryption | generateKey, importKey, encrypt, decrypt, wrapKey, unwrapKey |
AES-KW |
Key wrapping | wrapKey, unwrapKey |
RSASSA-PKCS1-v1_5, RSA-PSS |
RSA signatures | generateKey, sign, verify |
RSA-OAEP |
RSA encryption | generateKey, encrypt, decrypt |
ECDSA |
Elliptic-curve signatures (P-256, P-384, P-521) | generateKey, sign, verify |
ECDH, X25519 |
Key agreement | deriveBits, deriveKey |
Ed25519 |
EdDSA signatures | generateKey, sign, verify |
PBKDF2, HKDF |
Key derivation | importKey then deriveBits, deriveKey |
Which algorithms exist depends on the Node version; newer additions such as Ed25519, X25519, SHA-3 digests and ChaCha20-Poly1305 arrived in recent releases. Check by trying the call and catching NotSupportedError.
Usage notes
- Methods return promises and run the heavy work off the main thread where OpenSSL allows it.
digest()of a small buffer is fast, but PBKDF2 with a high iteration count is deliberately slow. extractableis fixed when a key is created. A non-extractable key can still be used but never read back, which is the point of the API.- The
usagesarray is enforced: a key made with['encrypt']cannot decrypt, and asking for a usage the algorithm does not support throws aSyntaxError. - AES-GCM needs a unique IV (12 bytes recommended) for every message under one key. Reusing an IV breaks its security. Generate it with
crypto.getRandomValues(new Uint8Array(12))and store it next to the ciphertext. - The AES-GCM result is the ciphertext with the 16-byte tag appended; decryption failures are a generic
OperationErrorthat does not say why. - ECDSA signatures are the raw
r || spair (64 bytes for P-256). The classiccrypto.sign()produces DER by default, so signatures are not interchangeable without conversion. - Web Crypto has no streaming hash. For large files use
crypto.createHash()fromnode:crypto. - Calls throw
TypeErrorfor wrong argument types,NotSupportedErrorfor unknown algorithms or sizes,InvalidAccessErrorfor misused keys andDataErrorfor malformed key data.