Web Crypto API#

History
VersionChanges
v23.5.0, v22.13.0

Algorithms Ed25519 and X25519 are now stable.

v19.0.0

No longer experimental except for the Ed25519, Ed448, X25519, and X448 algorithms.

v20.0.0, v18.17.0

Arguments are now coerced and validated as per their WebIDL definitions like in other Web Crypto API implementations.

v18.4.0, v16.17.0

Removed proprietary 'node.keyObject' import/export format.

v18.4.0, v16.17.0

Removed proprietary 'NODE-DSA', 'NODE-DH', and 'NODE-SCRYPT' algorithms.

v18.4.0, v16.17.0

Added 'Ed25519', 'Ed448', 'X25519', and 'X448' algorithms.

v18.4.0, v16.17.0

Removed proprietary 'NODE-ED25519' and 'NODE-ED448' algorithms.

v18.4.0, v16.17.0

Removed proprietary 'NODE-X25519' and 'NODE-X448' named curves from the 'ECDH' algorithm.

Stability: 2 - Stable

Node.js provides an implementation of the standard Web Crypto API.

Use globalThis.crypto or require('node:crypto').webcrypto to access this module.

const { subtle } = globalThis.crypto;

(async function() {

  const key = await subtle.generateKey({
    name: 'HMAC',
    hash: 'SHA-256',
    length: 256,
  }, true, ['sign', 'verify']);

  const enc = new TextEncoder();
  const message = enc.encode('I love cupcakes');

  const digest = await subtle.sign({
    name: 'HMAC',
  }, key, message);

})();

Examples#

Generating keys#

The <SubtleCrypto> class can be used to generate symmetric (secret) keys or asymmetric key pairs (public key and private key).

AES keys#
const { subtle } = globalThis.crypto;

async function generateAesKey(length = 256) {
  const key = await subtle.generateKey({
    name: 'AES-CBC',
    length,
  }, true, ['encrypt', 'decrypt']);

  return key;
}
ECDSA key pairs#
const { subtle } = globalThis.crypto;

async function generateEcKey(namedCurve = 'P-521') {
  const {
    publicKey,
    privateKey,
  } = await subtle.generateKey({
    name: 'ECDSA',
    namedCurve,
  }, true, ['sign', 'verify']);

  return { publicKey, privateKey };
}
Ed25519/X25519 key pairs#
const { subtle } = globalThis.crypto;

async function generateEd25519Key() {
  return subtle.generateKey({
    name: 'Ed25519',
  }, true, ['sign', 'verify']);
}

async function generateX25519Key() {
  return subtle.generateKey({
    name: 'X25519',
  }, true, ['deriveKey']);
}
HMAC keys#
const { subtle } = globalThis.crypto;

async function generateHmacKey(hash = 'SHA-256') {
  const key = await subtle.generateKey({
    name: 'HMAC',
    hash,
  },