From 96e56e1ca28fd28a89bc4033e951c529e98ece6d Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Thu, 23 Jul 2026 14:25:41 +0200 Subject: [PATCH 1/4] [workers] support for modern crypto algorithms --- .../webcrypto-modern-algorithms.md | 20 +++++++++++++++++++ .../docs/workers/runtime-apis/web-crypto.mdx | 14 +++++++++++++ 2 files changed, 34 insertions(+) create mode 100644 src/content/compatibility-flags/webcrypto-modern-algorithms.md diff --git a/src/content/compatibility-flags/webcrypto-modern-algorithms.md b/src/content/compatibility-flags/webcrypto-modern-algorithms.md new file mode 100644 index 00000000000..7dcd49bb723 --- /dev/null +++ b/src/content/compatibility-flags/webcrypto-modern-algorithms.md @@ -0,0 +1,20 @@ +--- +_build: + publishResources: false + render: never + list: never + +name: "Web Crypto modern algorithms" +sort_date: "2026-07-23" +experimental: true +enable_flag: "webcrypto_modern_algorithms" +--- + +Enables the Workers subset of the evolving [Modern Algorithms in the Web Cryptography API](https://wicg.github.io/webcrypto-modern-algos/) draft. This subset includes: + +* ML-KEM and ML-DSA. +* Key encapsulation and decapsulation methods. +* `getPublicKey()` and `SubtleCrypto.supports()`. +* JSON Web Keys (JWKs) with the `AKP` key type. + +Workers does not implement the full proposal. The API may change as the draft evolves. Refer to [Supported algorithms](/workers/runtime-apis/web-crypto/#supported-algorithms) for current support. diff --git a/src/content/docs/workers/runtime-apis/web-crypto.mdx b/src/content/docs/workers/runtime-apis/web-crypto.mdx index 9e3a0f0faaa..96f6a6a41d6 100644 --- a/src/content/docs/workers/runtime-apis/web-crypto.mdx +++ b/src/content/docs/workers/runtime-apis/web-crypto.mdx @@ -550,6 +550,20 @@ If a feature only implements the operation partially, details are listed. 3. MD5 is not part of the WebCrypto standard but is supported in Cloudflare Workers for interacting with legacy systems that require MD5. MD5 is considered a weak algorithm. Do not rely upon MD5 for security. +#### Modern algorithms + +The [`webcrypto_modern_algorithms` experimental compatibility flag](/workers/configuration/compatibility-flags/#web-crypto-modern-algorithms) enables a subset of the evolving [Modern Algorithms in the Web Cryptography API](https://wicg.github.io/webcrypto-modern-algos/) draft. + +| Algorithm | sign()
verify() | encapsulateKey()
encapsulateBits()
decapsulateKey()
decapsulateBits() | generateKey() | exportKey() | importKey() | +| :-------------------------------------------- | :------------------ | :-------------------------------------------------------------------------------- | :------------ | :---------- | :---------- | +| ML-DSA-44, ML-DSA-65, and ML-DSA-87 | ✓ | | ✓ | ✓ | ✓ | +| ML-KEM-768 and ML-KEM-1024 | | ✓ | ✓ | ✓ | ✓ | +| ML-KEM-512 | | ✘ | ✘ | ✘ | ✘ | + +The flag also adds `getPublicKey()` and `SubtleCrypto.supports()`. It supports JSON Web Keys (JWKs) with the `AKP` key type. + +Workers does not implement other algorithms from the draft. This API may change as the draft evolves. + *** ## Related resources From c823e67f509d2717aa9c7bc8e69f51bee1cc3f7a Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Thu, 23 Jul 2026 14:35:45 +0200 Subject: [PATCH 2/4] [workers] changelog item for modern crypto algorith, --- ...2026-07-23-webcrypto-modern-algorithms.mdx | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx diff --git a/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx b/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx new file mode 100644 index 00000000000..b6da60a2e61 --- /dev/null +++ b/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx @@ -0,0 +1,57 @@ +--- +title: Web Crypto adds experimental ML-KEM and ML-DSA support +description: The Workers runtime adds experimental post-quantum algorithms and key encapsulation methods through a compatibility flag. +products: + - workers +date: 2026-07-23 +--- + +import { TypeScriptExample, WranglerConfig } from "~/components"; + +The Workers Web Crypto API now supports ML-KEM-768, ML-KEM-1024, and all three ML-DSA parameter sets. ML-KEM establishes shared secrets, while ML-DSA signs and verifies data. + +The experimental API also adds key encapsulation and decapsulation methods, `getPublicKey()`, `SubtleCrypto.supports()`, and JSON Web Keys (JWKs) with the `AKP` key type. + +Enable the `webcrypto_modern_algorithms` compatibility flag to use these features: + + + +```toml +compatibility_date = "$today" +compatibility_flags = ["webcrypto_modern_algorithms"] +``` + + + +This example uses ML-KEM-768 to establish the same shared secret on both sides: + + + +```ts +const keyPair = await crypto.subtle.generateKey( + "ML-KEM-768", + false, + ["encapsulateBits", "decapsulateBits"], +); + +if (!("publicKey" in keyPair)) { + throw new Error("Expected an ML-KEM key pair"); +} + +const { sharedKey, ciphertext } = await crypto.subtle.encapsulateBits( + "ML-KEM-768", + keyPair.publicKey, +); + +const recoveredSharedKey = await crypto.subtle.decapsulateBits( + "ML-KEM-768", + keyPair.privateKey, + ciphertext, +); +``` + + + +Workers implements a subset of the evolving [Modern Algorithms in the Web Cryptography API](https://wicg.github.io/webcrypto-modern-algos/) draft. ML-KEM-512 and the draft's other algorithms are not supported. The API may change as the draft evolves. + +For current algorithm and operation support, refer to [Web Crypto supported algorithms](/workers/runtime-apis/web-crypto/#supported-algorithms). From ed4a15966964fda2ab35c3bf70fe73b1dd143a47 Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Thu, 23 Jul 2026 14:49:27 +0200 Subject: [PATCH 3/4] address review comment --- .../workers/2026-07-23-webcrypto-modern-algorithms.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx b/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx index b6da60a2e61..e446a9879b1 100644 --- a/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx +++ b/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx @@ -12,7 +12,7 @@ The Workers Web Crypto API now supports ML-KEM-768, ML-KEM-1024, and all three M The experimental API also adds key encapsulation and decapsulation methods, `getPublicKey()`, `SubtleCrypto.supports()`, and JSON Web Keys (JWKs) with the `AKP` key type. -Enable the `webcrypto_modern_algorithms` compatibility flag to use these features: +Turn on the `webcrypto_modern_algorithms` compatibility flag to use these features: From 23f4782149e213561fdda45ea037893d9274a3e3 Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Thu, 23 Jul 2026 18:23:36 +0200 Subject: [PATCH 4/4] wording is experimental -> opt-in --- .../workers/2026-07-23-webcrypto-modern-algorithms.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx b/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx index e446a9879b1..be35c601fec 100644 --- a/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx +++ b/src/content/changelog/workers/2026-07-23-webcrypto-modern-algorithms.mdx @@ -1,6 +1,6 @@ --- -title: Web Crypto adds experimental ML-KEM and ML-DSA support -description: The Workers runtime adds experimental post-quantum algorithms and key encapsulation methods through a compatibility flag. +title: Web Crypto adds ML-KEM and ML-DSA support +description: The Workers runtime adds opt-in post-quantum algorithms and key encapsulation methods through a compatibility flag. products: - workers date: 2026-07-23 @@ -10,7 +10,7 @@ import { TypeScriptExample, WranglerConfig } from "~/components"; The Workers Web Crypto API now supports ML-KEM-768, ML-KEM-1024, and all three ML-DSA parameter sets. ML-KEM establishes shared secrets, while ML-DSA signs and verifies data. -The experimental API also adds key encapsulation and decapsulation methods, `getPublicKey()`, `SubtleCrypto.supports()`, and JSON Web Keys (JWKs) with the `AKP` key type. +The opt-in API also adds key encapsulation and decapsulation methods, `getPublicKey()`, `SubtleCrypto.supports()`, and JSON Web Keys (JWKs) with the `AKP` key type. Turn on the `webcrypto_modern_algorithms` compatibility flag to use these features: