Proposal: Implement "Modern Algorithms in the Web Cryptography API" (WICG specification)

[panva]

The WICG is incubating a specification that adds post-quantum secure and modern cryptographic algorithms to the Web Cryptography API, much like X25519 was incubated before being merged into Web Cryptography: https://wicg.github.io/webcrypto-modern-algos/

Adoption is well underway:

• Node.js already ships support
• Cloudflare Workers PR is open
• Chrome intent to ship
• WebKit standards position
• Mozilla standards position
• Implementation status

The specification's Adoption Guidance section recommends the following implementation priorities:

1. ML-KEM (FIPS 203) — post-quantum key encapsulation mechanism. Combined with traditional key agreement it enables hybrid PQ/T key establishment as used in protocols like HPKE and its PQ and PQ/T algorithms. ML-KEM requires new SubtleCrypto methods: encapsulateKey, encapsulateBits, decapsulateKey, and decapsulateBits.
2. ML-DSA (FIPS 204) — post-quantum digital signature algorithm.
3. ChaCha20-Poly1305 (RFC 8439) — widely deployed AEAD cipher used across TLS, SSH, WireGuard, HPKE.
4. SHA-3 (FIPS 202) — SHA3-256, SHA3-384, SHA3-512 hash functions.
5. cSHAKE (NIST SP 800-185) — cSHAKE128, cSHAKE256 extendable-output functions used in post-quantum constructions including ML-KEM key derivation and hybrid KEM combiners. When invoked without customization parameters, cSHAKE produces output identical to SHAKE.
6. TurboSHAKE (RFC 9861) — TurboSHAKE128, TurboSHAKE256 XOFs based on round-reduced Keccak, roughly twice as fast as SHAKE.

The specification also introduces two important new SubtleCrypto methods that benefit all algorithms (including those already in Web Crypto):

• SubtleCrypto.supports(operation, algorithm) — synchronous feature detection for algorithm/operation support. This is critical for enabling progressive enhancement and graceful fallback as runtimes adopt these algorithms incrementally.
• SubtleCrypto.getPublicKey(key, keyUsages) — derives a public key from an asymmetric private key, simplifying key management and enabling protocols that commit the public key value to their outputs while accepting non-extractable private keys as input.

Web Platform Tests (WPTs) for the specified algorithms and operations are available and should be used to verify the implementation (it is okay to expect individual failures for unsupported features)

[robobun]

First slice in #29222:

• SHA-3 (SHA3-256/SHA3-384/SHA3-512) on crypto.subtle.digest.
• SubtleCrypto.supports(operation, algorithm) — a static on the interface object, per the WICG spec. Returns true for every algorithm/operation the underlying method would accept (including the wrapKey→encrypt / unwrapKey→decrypt fallback), false for unknown algorithms, unknown operations, and the modern-algos operations this slice does not yet implement (encapsulateKey/encapsulateBits/decapsulateKey/decapsulateBits/getPublicKey).
• SHA-3 is only wired as a top-level digest in this slice. It is explicitly rejected as a hash sub-algorithm for HMAC / RSA-PSS / RSA-OAEP / ECDSA until OpenSSLUtilities::digestAlgorithm, CryptoKeyHMAC::getKeyLengthFromHash, and the structured-clone tag table are extended — that gate will lift in a follow-up PR.

ML-KEM, ML-DSA, ChaCha20-Poly1305, SHAKE, cSHAKE, TurboSHAKE and getPublicKey() will follow in separate PRs referencing this issue.

[robobun]

Fixed in 0371039 on #29222 — supports is now a static on the SubtleCrypto constructor (SubtleCrypto.supports(op, alg)) rather than an instance method. Tests updated.

[robobun]

Latest commit ed341bc internalizes the full WPT sha3.tentative.https.any.js vector matrix (all 12 (SHA3-256/384/512 × empty/short/medium/long) digests, including the 87040-byte multi-block long input). The bytes are copied verbatim from the WPT file into test/regression/issue/29218.test.ts and asserted on every bun bd test run.

For supports.tentative.https.any.js, the existing SubtleCrypto.supports test block already covers every operation/algorithm pair the WPT exercises, plus the end-to-end invariant (supports()==true must not reject when the underlying method is called, supports()==false must reject with NotSupportedError). A proper WPT harness runner that can execute the upstream files unchanged is tracked separately under #19673 and will come as its own PR.

The red CI check on PR #29222 is unrelated to this slice — it is a pre-existing timing flake in test/bundler/bundler_defer.test.ts:646 (Bun.gc(true) + FinalizationRegistry callback counts), which has never been touched by this PR.

[robobun]

Thanks @panva! Happy this slice is good to go.

I scoped the next slice and want to post the plan here so it is on the record; picking it up in a fresh PR.

Scope for the next PR (referencing this issue):

• SHAKE128, SHAKE256 — XOFs on crypto.subtle.digest with a new {name, length} parameter dictionary (length in bits).
• cSHAKE128, cSHAKE256 — minimum form without functionName / customization, which (per your recommendation) means the same code path as SHAKE. The full cSHAKE prefix-absorption path can land in a separate PR.
• TurboSHAKE128, TurboSHAKE256 — round-reduced Keccak-p[1600, 12] with the default delimiter 0x1f. The configurable D suffix (RFC 9861) can come later.
• KangarooTwelve is deferred — you said "maybe" and it needs tree-hashing structure that does not drop into the current sponge; better as its own PR.

Implementation shape:

• Extend the Keccak-f[1600] code already in CryptoDigest.cpp by parameterising on round count (12 vs 24) and pad byte (0x06 vs 0x1f).
• Grow Sha3Context.buffer[144] to buffer[168] so SHAKE128's 168-byte rate fits (the exact overflow your bot flagged in this PR).
• Rewrite sha3Final to squeeze across multiple rate-sized blocks so XOFs with arbitrary length work, driven by a caller-supplied output byte count.
• Add a new CryptoAlgorithmShakeParams dictionary (WebIDL + C++) — this will be the first time the digest operation takes a non-trivial parameter object in Bun, so the Operations::Digest arm of normalizeCryptoAlgorithmParameters needs to pick the right params struct per algorithm.
• Wire six new CryptoAlgorithmIdentifier values, six new CryptoAlgorithm* subclasses, registry entries, and exhaustive-switch cases in AsymmetricKeyValue.cpp / SerializedScriptValue.cpp.

Rust:

Bun's main runtime does not currently link any Rust. There is some peripheral Rust tooling (verify-baseline-static, bun-native-plugin-rs), but pulling a crate like RustCrypto's sha3 into the main binary would mean standing up cargo build infra across every target (Linux/macOS/Windows × x64/aarch64 × baseline/ASan/musl) and wiring it into the link step — a much bigger project than the algorithm work itself. The C++ Keccak in this PR already covers SHA-3 and extends cleanly to SHAKE / TurboSHAKE / cSHAKE, so I will stay in C++ for this slice and leave the Rust dependency question to maintainers as a follow-up.

Tests:

I will internalise the WPT vector matrices from WebCryptoAPI/digest/shake.tentative.https.any.js and WebCryptoAPI/digest/turboshake.tentative.https.any.js the same way this PR did for sha3, and add the cSHAKE-with-empty-params subset of cshake.tentative.https.any.js.

[panva]

@robobun SHAKE128, SHAKE256 are not recognized algorithm identifiers, cSHAKE128 and cSHAKE256 are, and without optional arguments they just happen to behave as regular SHAKE which is the bare minimum we need to support

[robobun]

Correction to my earlier follow-up plan per @panva's clarification: there is no direct SHAKE128 / SHAKE256 algorithm in the WICG spec. cSHAKE with functionName and customization absent is equivalent to SHAKE, so the follow-up PR will register four identifiers — cSHAKE128, cSHAKE256, TurboSHAKE128, TurboSHAKE256 — not six. Callers who want SHAKE go through cSHAKE128 / cSHAKE256 with just {name, length}.

The underlying C++ work is unchanged (grow the sponge buffer to 168 bytes, parameterise Keccak on round count, multi-block squeeze for variable-length output, first-ever digest parameter dictionary). Still planning to stay in C++ rather than add a Rust crate.