Add ML-KEM and ML-DSA WebCrypto support by thibmeu · Pull Request #6872 · cloudflare/workerd

thibmeu · 2026-07-09T14:00:45Z

This adds the first opt-in slice of modern WebCrypto:

ML-KEM and ML-DSA support
encapsulate/decapsulate helpers
getPublicKey() and SubtleCrypto.supports()
JWK import/export
Tentative tests

It also adds webcrypto_modern_algorithms flag and gates the new API behind it.

Deferred from the original PR (#6403) SHA3/cSHAKE/TurboSHAKE and ChaCha20-Poly1305

Given the code is simply taken out from @panva 's PR, they are still credited as co-author

This first PR should facilitate review and support of other (relevant) algorithms defined in https://wicg.github.io/webcrypto-modern-algos/

I have read the CLA Document and I hereby sign the CLA

Assisted-by: Codex:gpt-5 Signed-off-by: Filip Skokan <panva.ip@gmail.com>

Keep ML-KEM, ML-DSA, helper APIs, and JWK support. Defer SHA3, ChaCha20-Poly1305, and aws-lc Rust deps. Co-authored-by: Filip Skokan <panva.ip@gmail.com>

github-actions · 2026-07-09T14:01:40Z

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

thibmeu · 2026-07-09T14:36:13Z

recheck

thibmeu · 2026-07-09T15:07:34Z

I have read the CLA Document and I hereby sign the CLA

thibmeu · 2026-07-09T15:07:47Z

recheck

codecov-commenter · 2026-07-09T16:03:51Z

Codecov Report

❌ Patch coverage is 13.19703% with 1401 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.51%. Comparing base (99057e4) to head (0e1b3c4).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/workerd/api/crypto/mlkem.c++	0.00%	502 Missing ⚠️
src/workerd/api/crypto/mldsa.c++	19.55%	397 Missing and 35 partials ⚠️
src/workerd/api/crypto/crypto.c++	18.94%	355 Missing and 43 partials ⚠️
src/workerd/api/crypto/keys.c++	0.00%	22 Missing ⚠️
src/workerd/api/crypto/impl.h	14.28%	10 Missing and 8 partials ⚠️
src/workerd/api/crypto/rsa.c++	0.00%	12 Missing ⚠️
src/workerd/api/crypto/ec.c++	0.00%	7 Missing and 2 partials ⚠️
src/workerd/api/crypto/aes.c++	0.00%	2 Missing and 2 partials ⚠️
src/workerd/api/crypto/digest.c++	0.00%	1 Missing and 1 partial ⚠️
src/workerd/api/crypto/hkdf.c++	0.00%	1 Missing ⚠️
... and 1 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6872      +/-   ##
==========================================
- Coverage   67.21%   66.51%   -0.70%     
==========================================
  Files         424      426       +2     
  Lines      121180   122759    +1579     
  Branches    20175    20552     +377     
==========================================
+ Hits        81447    81653     +206     
- Misses      27663    28958    +1295     
- Partials    12070    12148      +78

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

bwesterb

⚠️ I only fully reviewed the ML-DSA & ML-KEM specific bits.

The ML-DSA & ML-KEM bits look good except for a potential ML-DSA JWT import issue.

Other than that, there are some optional improvements:

We're wasting memory by keeping both public key and public key bytes in memory. We only need (seed and parsed private key) or parsed public key. Other values can be derived cheaply.
There is some marshaling/parsing going on, where direct clone or private-to-public-key functions are available.

I did not fully review the non ML-DSA/ML-KEM specific bits, but I did spot a few things:

The supports() function doesn't seem to be implemented correctly. Found one problem with checking length for deriveKey in case of ECDH. Do we need to implement supports() anyway for this PR?
Looks like we're inadvertently disabling some existing test cases.
We might want to make the compatibility flag ML-KEM/ML-DSA specific, or just enable by default.

Question for someone more versed in V8:

Sometimes parsed public and private keys are put on the stack. These can be somewhat large—the largest is the parsed ML-DSA-87 private key at 32kB. Would that lead to issues?

bwesterb · 2026-07-10T08:39:58Z

  # frameworks when running tests that require the inspector to be functional, and not by end users.
+
+  webCryptoModernAlgorithms @181 :Bool
+      $compatEnableFlag("webcrypto_modern_algorithms")


Non-blocking: Given it's a subset, maybe that should be reflected in the name webcrypto_pq.

i thought about it. i feel that having one flag is already plenty. probably a decision for @jasnell

bwesterb · 2026-07-10T08:42:12Z

+
+  webCryptoModernAlgorithms @181 :Bool
+      $compatEnableFlag("webcrypto_modern_algorithms")
+      $experimental;


Reminder for me to get back here and discuss whether this should be enabled by default. The question depends on how obvious the API implemented is.

bwesterb · 2026-07-10T09:27:08Z

+  JSG_REQUIRE(
+      keyType == KeyType::PRIVATE, DOMInvalidAccessError, "getPublicKey requires a private key.");
+
+  // Extract the public key by serializing/deserializing through SPKI DER.


When moving to a more recent BoringSSL, you can move to this

// EVP_PKEY_copy_public returns a newly-allocated `EVP_PKEY` that contains only // [the public key] OPENSSL_EXPORT EVP_PKEY *EVP_PKEY_copy_public(const EVP_PKEY *pkey);

that avoids the silly roundtrip.

probably a future ticket. not sure how this is being tracked by workers team. again, defering to @jasnell here

By the way, given the scope of the change, I think it'd be fine to enable by default.

that'd make thing even easier to be fair. let's see what James sugtgest. it might even be behind node_compat

bwesterb · 2026-07-10T10:08:25Z

+          case SubtleOperation::DERIVE_KEY:
+            return false;
+
+          case SubtleOperation::DERIVE_BITS: {


Interestingly, the behavior of supports for deriveBits isn't very clear in the draft spec.

i've added a comment as to why it now returns 528, as well as a test

issue on the specification repository WICG/webcrypto-modern-algos#74

bwesterb · 2026-07-10T11:02:13Z

+
+  // Public key data (present for both public and private keys)
+  kj::Maybe<typename P::PublicKey> publicKey;
+  kj::Array<kj::byte> publicKeyBytes;


No need to fix this now, but want to mention that we're wasting bytes.

Keeping around publicKeyBytes doesn't make a lot of sense. Generating it from a PublicKey or a PrivateKey is cheap. For equality testing we can use MLDSAxx_public_keys_equal.

Similarly, it's cheap to compute a PublicKey from a PrivateKey.

Ideally we keep around seed and PrivateKey for a private key and PublicKey for a public key. In the future BoringSSL might keep the seed around in the private key, but today they don't.

no actioned in the latest commit. feels like a nit indeed. i wonder what other engines do

bwesterb · 2026-07-10T11:10:51Z

+
+  // Private key data (present only for private keys)
+  kj::Maybe<kj::Array<kj::byte>> seed;
+  kj::Maybe<typename P::PrivateKey> privateKey;


Same as for ML-DSA. For private keys we only need seed and PrivateKey. For public keys we only need PublicKey. The others are cheap to derive, and there is a mlkem_public_keys_equal for public key comparisson.

bwesterb · 2026-07-10T11:33:20Z

+      auto pkBytes = kj::heapArray<kj::byte>(CBB_data(cbb.get()), CBB_len(cbb.get()));
+
+      // If pub field is present, verify it matches
+      KJ_IF_SOME(pubField, jwk.pub) {


Just want to flag that the spec requires the pub key to be present and matching. That's a mistake of the spec: having a public key in there as well only causes trouble. It doesn't help with performance, as the public key is essentially recomputed anyway.

@thibmeu might be worth following up

do you feel that's something the spec should not mandate? happy to open an issue and follow up

i could imagine some horror stories loading a private key and not actually signing the right thing, and that's one guardrail. but that alsoe means more storage

* throw if alg is not normalised * Validate JWK key_ops. * Use publicFromPrivate() in getPublicKey() * Zeroize * Added missing-alg ML-DSA JWK rejection test * ECDH P-521 supports("deriveBits", ..., 528) behavior

panva and others added 3 commits July 9, 2026 15:10

implement a subset of "Modern Algorithms in the Web Cryptography API"

59954ce

Assisted-by: Codex:gpt-5 Signed-off-by: Filip Skokan <panva.ip@gmail.com>

Scope modern crypto subset

7bcba93

Keep ML-KEM, ML-DSA, helper APIs, and JWK support. Defer SHA3, ChaCha20-Poly1305, and aws-lc Rust deps. Co-authored-by: Filip Skokan <panva.ip@gmail.com>

Gate modern WebCrypto algorithms

3ca1c5f

thibmeu requested review from a team as code owners July 9, 2026 14:00

thibmeu requested a review from edmundhung July 9, 2026 14:00

thibmeu mentioned this pull request Jul 9, 2026

implement a subset of "Modern Algorithms in the Web Cryptography API" #6403

Open

Fix modern crypto buffer imports

aa10a91

thibmeu added 2 commits July 9, 2026 16:46

Trigger CI

1c2cb5f

Fix encapsulated key imports

df831b4

github-actions Bot added a commit that referenced this pull request Jul 9, 2026

@thibmeu has signed the CLA in #6872

6be5d08

thibmeu added 2 commits July 9, 2026 17:22

Update experimental crypto types

f4e298e

Fix crypto extras lint

139a8da

bwesterb approved these changes Jul 10, 2026

View reviewed changes

bwesterb reviewed Jul 10, 2026

View reviewed changes

Comment thread src/workerd/api/crypto/mldsa.c++ Outdated

bwesterb reviewed Jul 10, 2026

View reviewed changes

Comment thread src/workerd/api/crypto/mldsa.c++ Outdated

bwesterb reviewed Jul 10, 2026

View reviewed changes

Comment thread src/workerd/api/crypto/mldsa.c++

Comment thread src/workerd/api/crypto/mlkem.c++

bwesterb reviewed Jul 10, 2026

View reviewed changes

Comment thread src/workerd/api/crypto/mldsa.c++

thibmeu added 3 commits July 10, 2026 15:55

Address @bwesterb comments

6dffb02

* throw if alg is not normalised * Validate JWK key_ops. * Use publicFromPrivate() in getPublicKey() * Zeroize * Added missing-alg ML-DSA JWK rejection test * ECDH P-521 supports("deriveBits", ..., 528) behavior

Tighten modern crypto supports

89fa6e7

Restore digest input order

0e1b3c4

Uh oh!

Conversation

thibmeu commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thibmeu commented Jul 9, 2026

Uh oh!

thibmeu commented Jul 9, 2026

Uh oh!

thibmeu commented Jul 9, 2026

Uh oh!

codecov-commenter commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

bwesterb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

thibmeu commented Jul 9, 2026 •

edited

Loading

github-actions Bot commented Jul 9, 2026 •

edited

Loading

codecov-commenter commented Jul 9, 2026 •

edited

Loading