Algorithm Updates in WebCrypto

at a glance

Syntax

The update extends SubtleCrypto with four key-encapsulation methods (KEM support for ML-KEM), a public-key derivation helper, and a static feature-detection method. IDL from the WICG draft:

[SecureContext, Exposed=(Window,Worker)]
partial interface SubtleCrypto {
  Promise<EncapsulatedKey> encapsulateKey(
    AlgorithmIdentifier encapsulationAlgorithm,
    CryptoKey encapsulationKey,
    AlgorithmIdentifier sharedKeyAlgorithm,
    boolean extractable,
    sequence<KeyUsage> keyUsages
  );
  Promise<EncapsulatedBits> encapsulateBits(
    AlgorithmIdentifier encapsulationAlgorithm,
    CryptoKey encapsulationKey
  );

  Promise<CryptoKey> decapsulateKey(
    AlgorithmIdentifier decapsulationAlgorithm,
    CryptoKey decapsulationKey,
    BufferSource ciphertext,
    AlgorithmIdentifier sharedKeyAlgorithm,
    boolean extractable,
    sequence<KeyUsage> keyUsages
  );
  Promise<ArrayBuffer> decapsulateBits(
    AlgorithmIdentifier decapsulationAlgorithm,
    CryptoKey decapsulationKey,
    BufferSource ciphertext
  );

  Promise<CryptoKey> getPublicKey(
    CryptoKey key,
    sequence<KeyUsage> keyUsages
  );

  static boolean supports(DOMString operation,
                   AlgorithmIdentifier algorithm,
                   optional [EnforceRange] unsigned long? length = null);
  static boolean supports(DOMString operation,
                   AlgorithmIdentifier algorithm,
                   AlgorithmIdentifier additionalAlgorithm);
};

enum KeyFormat { "raw-public", "raw-private", "raw-seed", "raw-secret",
                 "raw", "spki", "pkcs8", "jwk" };

enum KeyUsage { "encrypt", "decrypt", "sign", "verify", "deriveKey", "deriveBits",
                "wrapKey", "unwrapKey",
                "encapsulateKey", "encapsulateBits",
                "decapsulateKey", "decapsulateBits" };

dictionary EncapsulatedKey {
  CryptoKey sharedKey;
  ArrayBuffer ciphertext;
};

dictionary EncapsulatedBits {
  ArrayBuffer sharedKey;
  ArrayBuffer ciphertext;
};

The draft also extends JsonWebKey with pub and priv fields (WICG §5, per RFC 9964) for the algorithms’ JWK representations.

Errors

The six methods (encapsulateKey, encapsulateBits, decapsulateKey, decapsulateBits, getPublicKey, and exportKey) fail in two different ways, and they are not interchangeable: a named DOMException that an implementer can catch by name, versus a promise rejection produced by algorithm normalization whose value is the normalization result itself and carries no name to catch. Every throw and rejection below is a step of the WICG — WebCrypto Modern Algorithms draft (the partial SubtleCrypto interface, §3.2); the W3C Web Cryptography API base Recommendation contributes none of these sites — they are all new draft algorithm steps.

Named DOMException sites — catchable by name

Twelve named throw sites across the five asynchronous methods. Each sentence is quoted verbatim from the draft.

Promise rejections from normalization — not catchable by name

Six sites return a promise rejected with the normalization result, not with a named DOMException. An implementer cannot catch these by name because the rejection value is the failed normalization result itself.

Because these rejections are returned (not thrown), the draft's throw-to-rejection convention does not apply to them — see the Lifecycle section.

supports() — no throw contract, and the one implied WebIDL TypeError

The static supports() method never throws: every failure path returns false. This is stated by the draft's own algorithm, not an inference:

Separate from that algorithm contract is a WebIDL binding-level TypeError implied by the IDL — not an algorithm step. The first overload declares optional [EnforceRange] unsigned long? length = null, so a length that is a non-integer or outside [0, 232−1] produces a WebIDL TypeError before the algorithm body runs. The draft's algorithm does not raise this — the [EnforceRange] extended attribute in the IDL does.

Lifecycle

For each of the six methods the contract records one of exactly two cases: the draft states the promise/parallel-task pattern (quoted below), or the draft does not state it (recorded as an absence, not composed and not “not-applicable”). The draft states the pattern identically in §3.2.1–§3.2.5; the four sentences are:

“Let realm be the relevant realm of this.”

“Let promise be a new Promise.”

“Return promise and perform the remaining steps in parallel.”

“Queue a global task on the crypto task source, given realm’s global object, to perform the remaining steps.”

And the draft converts any throw inside the parallel work into a promise rejection with this convention, stated verbatim in each of the same five methods:

“If the following steps or referenced procedures say to throw an error, queue a global task on the crypto task source, given realm’s global object, to reject promise with the returned error; and then terminate the algorithm.”

Per method, confirmed against the draft’s own text (presence of the five sentences checked in each §3.2.x body):

What the draft does not state: it has no dedicated lifecycle prose beyond the sentences above, and it assigns the two dictionary fields (sharedKey, ciphertext) no lifecycle of their own — they are populated by the encapsulate/decapsulate algorithms and have no independent “created when” step beyond being fields of the dictionaries named in §4. The draft also does not state any timing or ordering guarantee for the “Queue a global task … perform the remaining steps” step relative to the encapsulate/decapsulate operation other than what the quoted sentences say.

The new algorithm roster

Twelve algorithm families are registered — 37 registered names in total — each with its own operations section in the spec (key generation, import/export, and the operations below). All are optional to implement per the spec — use SubtleCrypto.supports() to detect them. The Reference column cites both the crypto-math standard and the WICG registration section that carries the web-facing grammar (registered name strings, WebIDL parameter dictionaries, JWK mappings).

Examples

// 1. Feature-detect first — the method and every algorithm are optional
const kemOK = SubtleCrypto.supports?.("encapsulateKey", "ML-KEM-768") ?? false;
if (!kemOK) throw new DOMException("ML-KEM-768 is unavailable", "NotSupportedError");

// 2. Recipient generates an ML-KEM key pair
const pair = await crypto.subtle.generateKey("ML-KEM-768", true, [
  "encapsulateKey", "decapsulateKey",
]);

// 3. Sender encapsulates a shared secret against the recipient public key
const { sharedKey, ciphertext } = await crypto.subtle.encapsulateKey(
  "ML-KEM-768", pair.publicKey, "AES-GCM", true, ["encrypt", "decrypt"],
);
// -> send { ciphertext } to the recipient; keep sharedKey local

// 4. Recipient decapsulates with the private key — same shared secret
const recovered = await crypto.subtle.decapsulateKey(
  "ML-KEM-768", pair.privateKey, ciphertext, "AES-GCM", true, ["encrypt", "decrypt"],
);

The three remaining methods — encapsulateBits, decapsulateBits, and getPublicKey — are not exercised by the snippet above. The short composed example below covers them. Like the example above, it is composed from the named sources, not copied from the draft, and the draft does not provide a JavaScript example for these members. It reuses pair (the ML-KEM key pair generated above) and uses only identifiers the draft or the example above already declare.

// encapsulateBits — the raw-bits form: no CryptoKey import of the shared secret
// sourceRef: https://wicg.github.io/webcrypto-modern-algos/#SubtleCrypto-method-encapsulateBits
const bits = await crypto.subtle.encapsulateBits("ML-KEM-768", pair.publicKey);
// bits.sharedKey → ArrayBuffer; bits.ciphertext → ArrayBuffer (send this)
// sourceRef: https://wicg.github.io/webcrypto-modern-algos/#x4-encapsulation-dictionaries

// decapsulateBits — recover the same raw bits on the recipient side
// sourceRef: https://wicg.github.io/webcrypto-modern-algos/#SubtleCrypto-method-decapsulateBits
const bitsRecovered = await crypto.subtle.decapsulateBits(
  "ML-KEM-768", pair.privateKey, bits.ciphertext,
);
// bitsRecovered → ArrayBuffer, equal to bits.sharedKey

// getPublicKey — recover the public half from a stored private key
// sourceRef: https://wicg.github.io/webcrypto-modern-algos/#SubtleCrypto-method-getPublicKey
const recoveredPublic = await crypto.subtle.getPublicKey(
  pair.privateKey, ["encapsulateKey"],
);

Browser compatibility

Cross-browser support is recorded in browser-compat-data (BCD) as of 2026-10-06; the earlier interim view built from ChromeStatus ship data is superseded (BCD carried no entries for these members as of 2026-07-24). BCD flags all six members experimental.

ChromeStatus (updated 2026-09-11) still records the feature as “Proposed” with no desktop ship milestone — it lags the shipped state BCD records; this page reports both rather than choosing.

Specifications

See also

• Origin trial documentation — WebCrypto Additional Algorithms
• blink-dev intent thread
• Chrome origin trials — registration
• Chrome Platform Showcase — Algorithm Updates in WebCrypto (also: capability matrix, ML-DSA signatures, ChaCha20-Poly1305, hybrid session key)