Skip to content
Tutorials Center
My learning

Topics

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.

NODE
const data = new TextEncoder().encode('hello');
const digest = await crypto.subtle.digest('SHA-256', data);
console.log(new Uint8Array(digest).length); // 32

Try it

Node.js Digest and HMAC

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.

Node.js AES-GCM and key derivation

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.

Node.js ECDSA signatures

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.
  • extractable is 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 usages array is enforced: a key made with ['encrypt'] cannot decrypt, and asking for a usage the algorithm does not support throws a SyntaxError.
  • 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 OperationError that does not say why.
  • ECDSA signatures are the raw r || s pair (64 bytes for P-256). The classic crypto.sign() produces DER by default, so signatures are not interchangeable without conversion.
  • Web Crypto has no streaming hash. For large files use crypto.createHash() from node:crypto.
  • Calls throw TypeError for wrong argument types, NotSupportedError for unknown algorithms or sizes, InvalidAccessError for misused keys and DataError for malformed key data.