Build1 publisher2 min readPublished
Cloudflare Workers adds ML-KEM and ML-DSA to Web Crypto behind an opt-in flag
Cloudflare Workers adds five ML-KEM and ML-DSA parameter sets to Web Crypto behind the webcrypto_modern_algorithms flag. Developers can now test post-quantum code against primitives built into the runtime, but they still have to build the protocols on top.
The Engineer · Build desk
Drafted by a language model from the sources cited here and checked against its claim ledger before publication. How we use AISend a correction
What happened
- Alongside the algorithms, Workers adds encapsulateBits, decapsulateBits, encapsulateKey, decapsulateKey, getPublicKey, SubtleCrypto.supports, and JWK import and export.
- The algorithms are defined in the Modern Algorithms in the Web Cryptography API draft, a community group report.
- Until now, a Workers developer wanting post-quantum primitives had to bundle a JavaScript or WebAssembly implementation, or could not build the protocol on Web Crypto at all.
- Cloudflare's worked example signs JWTs with ML-DSA through panva/jose, a library that maps the ML-DSA algorithms to Web Crypto.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- constraint Anything long-lived built on the flag targets a draft that can still change, so production code that depends on these exact calls risks rework until the specification settles.
- decision Maintainers who ship their own ML-KEM or ML-DSA code for Workers now have to decide whether to detect the runtime version and call it instead.
- capability With RFC 9964 defining ML-DSA in JOSE, a Worker can sign and verify post-quantum tokens using only runtime calls, once its library maps to them.
Calling encapsulateBits with an ML-KEM-768 public key returns a sharedKey and a ciphertext [8]. The private-key holder passes that ciphertext to decapsulateBits and gets the same secret back [8]. Cloudflare's snippet names the result sameSharedKey. For a KEM, that equality is the whole acceptance test [8]. Nothing has been encrypted yet [9]. According to the post, a protocol such as HPKE feeds the shared material into a key schedule and then into an AEAD such as AES-GCM [9].
ML-DSA follows the pattern of Ed25519 or ECDSA: generate a key pair, sign bytes, verify bytes [10]. "These examples are deliberately small. They are not protocols," Cloudflare wrote [11].
Cloudflare's case for putting the primitives in the runtime is about who maintains them. Bundled crypto, the post says, leaves each implementer to pick and maintain an implementation, and the application grows with the code it carries [7]. The same work is then repeated in every downstream library [7]. The post also says the ecosystem has to move to post-quantum algorithms sooner than expected, and that developers need the primitives now to test and improve their integrations [16].
The protocol work happens a layer above these calls. OpenSSH added mlkem768x25519 in 2024 [12]. At the IETF, HPKE has a draft for post-quantum and hybrid KEMs, and there is an adopted draft for JWE using PQ and PQ/T HPKE [13]. The Workers additions are the ML-KEM and ML-DSA parameter sets themselves [2]. I'd expect anyone who wants a hybrid KEM on Workers today to write the combination in their own code.
Cloudflare says the flag is there because the specification is still moving [4]. The post is plain about scope: "They do not provide a full migration path, but rather building blocks that can be used to validate your integration" [5]. I think Cloudflare got the order right. The method names come from the community group draft [1], and making the APIs opt-in [4] lets the runtime follow that draft without changing behaviour for code that never turned the flag on. In my context, the native calls belong in test and staging, checked against whatever implementation the application ships today. The bundled code stays in production until the draft stops changing.
What to watch
- Revisions to the Modern Algorithms in the Web Cryptography API draft that rename or reshape the encapsulate and decapsulate calls Workers now exposes.
- Cloudflare making ML-KEM and ML-DSA available without the webcrypto_modern_algorithms flag, a sign it treats the API shape as settled.
- The IETF HPKE draft for post-quantum and hybrid KEMs reaching RFC, giving Workers code a standard protocol to build on these primitives.