Node.js Reference ยท Web APIs in Node.js
Node.js crypto.subtle (Web Crypto API)
Reference for crypto.subtle in Node.js: digest, HMAC, AES-GCM, key generation, import and export with the promise-based Web Crypto API, plus common mistakes.
crypto.subtle is the SubtleCrypto object of the Web Crypto API. It offers hashing, message authentication, symmetric and asymmetric encryption, signatures and key derivation through promise-based methods, with the same interface that browsers provide. Code written against it runs unchanged in browsers, Deno and Node.js.
The global crypto object has subtle, getRandomValues() and randomUUID(). Keys are opaque CryptoKey objects: you create or import them, choose which operations they allow, and decide whether they can be exported. For the Node-specific API see crypto.createHash() and friends; the algorithm list is on Web Crypto algorithms.
const data = new TextEncoder().encode('hello'); const digest = await crypto.subtle.digest('SHA-256', data); // ArrayBuffer
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.
Syntax
crypto.subtle.digest(algorithm, data) // Promise<ArrayBuffer> crypto.subtle.generateKey(algorithm, extractable, usages) // Promise<CryptoKey | CryptoKeyPair> crypto.subtle.importKey(format, keyData, algorithm, extractable, usages) crypto.subtle.exportKey(format, key) crypto.subtle.encrypt(algorithm, key, data) crypto.subtle.decrypt(algorithm, key, data) crypto.subtle.sign(algorithm, key, data) crypto.subtle.verify(algorithm, key, signature, data) crypto.subtle.deriveBits(algorithm, baseKey, length) crypto.subtle.deriveKey(algorithm, baseKey, derivedKeyType, extractable, usages) crypto.subtle.wrapKey(format, key, wrappingKey, wrapAlgorithm) crypto.subtle.unwrapKey(format, wrapped, unwrappingKey, unwrapAlgorithm, unwrappedKeyAlgorithm, extractable, usages)
| Name | Description |
|---|---|
algorithm |
A name string or an object with name and algorithm parameters, such as { name: 'AES-GCM', iv }. |
data |
An ArrayBuffer, typed array or DataView. Strings are not accepted: encode them first. |
format |
'raw', 'pkcs8', 'spki' or 'jwk', depending on the key type. |
extractable |
If false, exportKey() rejects. Set it to false for keys you never need to read back. |
usages |
Array of allowed operations: 'encrypt', 'decrypt', 'sign', 'verify', 'deriveKey', 'deriveBits', 'wrapKey', 'unwrapKey'. |
Returns: every method returns a promise.
Errors: the promise rejects with a DOMException such as OperationError (decryption or authentication failed), InvalidAccessError (the key does not allow that usage), NotSupportedError (unknown algorithm) or DataError (bad key data). A wrong argument type rejects with a TypeError.
Usage notes
- Everything is asynchronous. Use
awaitor.then(). There are no synchronous forms; for those use thenode:cryptofunctions. - Strings must be encoded. Use
TextEncoderto get bytes andTextDecoderto turn results back into text. Hex and Base64 conversion is not built in;Bufferdoes it in one call. - AES-GCM needs a unique IV for every message under the same key. Reusing one destroys its security. A random 12-byte IV is the usual choice. Store the IV beside the ciphertext; it is not secret.
- AES-GCM appends the authentication tag to the ciphertext. Altered data makes
decrypt()reject instead of returning garbage. - Usages are enforced. A key created for
['encrypt']cannot decrypt. - Available everywhere in Node 24 as the global
crypto.import { webcrypto } from 'node:crypto'returns the same object, andwebcrypto.subtleequalscrypto.subtle. - Not every algorithm exists in every runtime. Check the algorithm page before relying on newer algorithms such as Ed25519 or X25519 outside Node.