From a7afbe2e67a3cd74a095ae8e632daf50a61ba94f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 3 Aug 2026 17:41:55 +0000 Subject: [PATCH 1/7] Initial plan From 48ebea50662ce3e638dcb6d8e76885f3d654d075 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 3 Aug 2026 17:45:19 +0000 Subject: [PATCH 2/7] Add breaking change doc: Composite ML-DSA on Windows uses native implementation --- docs/core/compatibility/11.md | 1 + .../11/compositemldsa-windows-native.md | 54 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + .../security/cross-platform-cryptography.md | 24 +++++---- 4 files changed, 70 insertions(+), 11 deletions(-) create mode 100644 docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 369f0af6dd2a0..a7a842a4b9920 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -40,6 +40,7 @@ See [Breaking changes in ASP.NET Core 11](/aspnet/core/breaking-changes/11/overv | Title | Type of change | |----------------------------------------------------------------|-------------------| | [API obsoletions](cryptography/11/obsolete-apis.md) | Source incompatible | +| [Composite ML-DSA on Windows uses native implementation](cryptography/11/compositemldsa-windows-native.md) | Behavioral change | | [DSA removed from macOS](cryptography/11/dsa-removed-macos.md) | Behavioral change | ## Deployment diff --git a/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md b/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md new file mode 100644 index 0000000000000..7fed65bbcabb5 --- /dev/null +++ b/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md @@ -0,0 +1,54 @@ +--- +title: "Breaking change: Composite ML-DSA on Windows uses native implementation" +description: "Learn about the breaking change in .NET 11 where Composite ML-DSA on Windows uses the native Windows implementation, which supports fewer algorithms than the previous managed implementation." +ms.date: 08/03/2026 +ai-usage: ai-generated +--- + +# Composite ML-DSA on Windows uses native implementation + +Starting in .NET 11, on Windows uses the native Windows implementation of Composite ML-DSA instead of a managed implementation layered over ML-DSA, RSA, and ECDSA. Because Windows only implements a subset of the Composite ML-DSA parameter sets natively, this change reduces the number of Composite ML-DSA algorithms supported on Windows. + +## Version introduced + +.NET 11 Preview 7 + +## Previous behavior + +Previously, APIs on Windows worked for any composite algorithm as long as its underlying components (ML-DSA, RSA, and ECDSA) were supported. Algorithms that combine ML-DSA with EdDSA (Ed25519 or Ed448) always threw on Windows, because Windows doesn't support EdDSA. + +## New behavior + +Starting in .NET 11, APIs on Windows only support the composite algorithms that Windows implements natively in CNG. Windows currently implements native support for a subset of the Composite ML-DSA parameter sets that pair ML-DSA with ECDSA. All other composite algorithms, including every algorithm that pairs ML-DSA with RSA, now throw on Windows. + +For the current list of natively supported parameter sets, see the `cbParameterSet` field of the [`BCRYPT_PQDSA_KEY_BLOB`](/windows/win32/seccng/bcrypt/ns-bcrypt-bcrypt_pqdsa_key_blob#cbparameterset) structure. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +It's preferable to use the native implementation the operating system provides rather than a managed layer built on top of other primitives. Windows added native support for a subset of Composite ML-DSA parameter sets in recent Windows Insider Preview builds, and .NET now uses that native support when it's available. + +## Recommended action + +Before you use a specific Composite ML-DSA algorithm on Windows, call to check whether the algorithm is supported. If an algorithm isn't supported, choose a supported algorithm or handle the resulting . + +```csharp +if (CompositeMLDsa.IsAlgorithmSupported(CompositeMLDsaAlgorithm.MLDsa65WithECDsaP384)) +{ + using CompositeMLDsa mldsa = CompositeMLDsa.GenerateKey(CompositeMLDsaAlgorithm.MLDsa65WithECDsaP384); + // Use mldsa. +} +else +{ + // Fall back to another algorithm, or handle the lack of support. +} +``` + +This change doesn't affect the Composite ML-DSA certificate APIs. Those APIs continue to throw on Windows, as before. + +## Affected APIs + +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index ac20a3709ff70..0757c98bf088e 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -38,6 +38,8 @@ items: items: - name: API obsoletions href: cryptography/11/obsolete-apis.md + - name: Composite ML-DSA on Windows uses native implementation + href: cryptography/11/compositemldsa-windows-native.md - name: DSA removed from macOS href: cryptography/11/dsa-removed-macos.md - name: Deployment diff --git a/docs/standard/security/cross-platform-cryptography.md b/docs/standard/security/cross-platform-cryptography.md index 78c7f7564c417..b56af20edb28e 100644 --- a/docs/standard/security/cross-platform-cryptography.md +++ b/docs/standard/security/cross-platform-cryptography.md @@ -365,24 +365,26 @@ SLH-DSA has a pure and prehash variant (HashSLH-DSA). The following table reflec | Algorithm | Windows | Linux | Apple | Android | Browser | |----------------------------------------|-------------------------------|----------------|-------|---------|---------| -| MLDSA44-RSA2048-PSS-SHA256 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -| MLDSA44-RSA2048-PKCS15-SHA256 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA44-RSA2048-PSS-SHA256 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA44-RSA2048-PKCS15-SHA256 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | | MLDSA44-Ed25519-SHA512 | ❌ | ❌ | ❌ | ❌ | ❌ | | MLDSA44-ECDSA-P256-SHA256 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -| MLDSA65-RSA3072-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -| MLDSA65-RSA3072-PKCS15-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -| MLDSA65-RSA4096-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -| MLDSA65-RSA4096-PKCS15-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-RSA3072-PSS-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-RSA3072-PKCS15-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-RSA4096-PSS-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-RSA4096-PKCS15-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | | MLDSA65-ECDSA-P256-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | | MLDSA65-ECDSA-P384-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -| MLDSA65-ECDSA-brainpoolP256r1-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA65-ECDSA-brainpoolP256r1-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | | MLDSA65-Ed25519-SHA512 | ❌ | ❌ | ❌ | ❌ | ❌ | | MLDSA87-ECDSA-P384-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -| MLDSA87-ECDSA-brainpoolP384r1-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA87-ECDSA-brainpoolP384r1-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | | MLDSA87-Ed448-SHAKE256 | ❌ | ❌ | ❌ | ❌ | ❌ | -| MLDSA87-RSA3072-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -| MLDSA87-RSA4096-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -| MLDSA87-ECDSA-P521-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA87-RSA3072-PSS-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA87-RSA4096-PSS-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | +| MLDSA87-ECDSA-P521-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | + +Starting in .NET 11, Windows support for Composite ML-DSA uses the native Windows implementation, which only supports the algorithms marked "Windows 11 Insiders (Latest)" in the preceding table. For more information, see [Composite ML-DSA on Windows uses native implementation](../../core/compatibility/cryptography/11/compositemldsa-windows-native.md). #### Native interop composite ML-DSA From 751460f5d7f323a90e463b4fecf5f1f78d4e3153 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 3 Aug 2026 17:46:07 +0000 Subject: [PATCH 3/7] Add exact list of natively supported Composite ML-DSA algorithms on Windows --- .../11/compositemldsa-windows-native.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md b/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md index 7fed65bbcabb5..a3df5f4180812 100644 --- a/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md +++ b/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md @@ -15,13 +15,22 @@ Starting in .NET 11, on Windo ## Previous behavior -Previously, APIs on Windows worked for any composite algorithm as long as its underlying components (ML-DSA, RSA, and ECDSA) were supported. Algorithms that combine ML-DSA with EdDSA (Ed25519 or Ed448) always threw on Windows, because Windows doesn't support EdDSA. +Previously, APIs on Windows worked for any composite algorithm as long as its underlying components (ML-DSA, RSA, and ECDSA) were supported, including all the RSA-based composite algorithms. Algorithms that combine ML-DSA with EdDSA (Ed25519 or Ed448) always threw on Windows, because Windows doesn't support EdDSA. ## New behavior -Starting in .NET 11, APIs on Windows only support the composite algorithms that Windows implements natively in CNG. Windows currently implements native support for a subset of the Composite ML-DSA parameter sets that pair ML-DSA with ECDSA. All other composite algorithms, including every algorithm that pairs ML-DSA with RSA, now throw on Windows. +Starting in .NET 11, APIs on Windows only support the composite algorithms that Windows implements natively in CNG. Windows currently implements native support for exactly these four parameter sets, all of which pair ML-DSA with ECDSA: -For the current list of natively supported parameter sets, see the `cbParameterSet` field of the [`BCRYPT_PQDSA_KEY_BLOB`](/windows/win32/seccng/bcrypt/ns-bcrypt-bcrypt_pqdsa_key_blob#cbparameterset) structure. +| Windows parameter set | Composite ML-DSA algorithm | `CompositeMLDsaAlgorithm` member | +|---------------------------------|-----------------------------------|-----------------------------------| +| `44-ECDSA-P256-SHA256` | Composite ML-DSA-44 and ECDSA P256 | `MLDsa44WithECDsaP256` | +| `65-ECDSA-P256-SHA512` | Composite ML-DSA-65 and ECDSA P256 | `MLDsa65WithECDsaP256` | +| `65-ECDSA-P384-SHA512` | Composite ML-DSA-65 and ECDSA P384 | `MLDsa65WithECDsaP384` | +| `87-ECDSA-P384-SHA512` | Composite ML-DSA-87 and ECDSA P384 | `MLDsa87WithECDsaP384` | + +All other composite algorithms now throw on Windows. This includes every algorithm that pairs ML-DSA with RSA, which worked previously, and every algorithm that pairs ML-DSA with EdDSA (Ed25519 or Ed448), which already threw before this change. + +For more information, see the `cbParameterSet` field of the [`BCRYPT_PQDSA_KEY_BLOB`](/windows/win32/seccng/bcrypt/ns-bcrypt-bcrypt_pqdsa_key_blob#cbparameterset) structure. ## Type of breaking change From e9448350606c89801aa3239206b69a7b76e10131 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 3 Aug 2026 21:59:31 +0000 Subject: [PATCH 4/7] Update unsupported-apis.md and ms.date metadata per review feedback Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/unsupported-apis.md | 6 +++++- docs/standard/security/cross-platform-cryptography.md | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/core/compatibility/unsupported-apis.md b/docs/core/compatibility/unsupported-apis.md index 2b81b79994b76..5d0a99370547c 100644 --- a/docs/core/compatibility/unsupported-apis.md +++ b/docs/core/compatibility/unsupported-apis.md @@ -2,7 +2,7 @@ title: Unsupported APIs on .NET Core and .NET 5+ titleSuffix: "" description: Learn which .NET APIs always throw an exception on .NET Core and .NET 5 and later versions. -ms.date: 03/16/2026 +ms.date: 08/03/2026 ai-usage: ai-assisted --- # APIs that always throw exceptions on .NET (Core) @@ -246,6 +246,10 @@ This article organizes the affected APIs by namespace. | | Linux and macOS | | | Linux and macOS | | | Linux and macOS | +| \* | Windows, for algorithms not natively supported | +| \* | Windows, for algorithms not natively supported | +| \* | Windows, for algorithms not natively supported | +| \* | Windows, for algorithms not natively supported | | | All | | | Linux and macOS | | | Linux and macOS | diff --git a/docs/standard/security/cross-platform-cryptography.md b/docs/standard/security/cross-platform-cryptography.md index b56af20edb28e..01d9933cf345a 100644 --- a/docs/standard/security/cross-platform-cryptography.md +++ b/docs/standard/security/cross-platform-cryptography.md @@ -1,7 +1,7 @@ --- title: "Cross-platform cryptography" description: Learn about cryptographic capabilities on platforms supported by .NET. -ms.date: "11/04/2025" +ms.date: 08/03/2026 ms.subservice: standard-library helpviewer_keywords: - "cryptography, cross-platform" From 9d531ffc68e8fa5bab7127eb37193b2bdaaa90f6 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 3 Aug 2026 16:10:51 -0700 Subject: [PATCH 5/7] Add unsupported APIs for CompositeMLDsa in documentation --- docs/core/compatibility/unsupported-apis.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/core/compatibility/unsupported-apis.md b/docs/core/compatibility/unsupported-apis.md index 5d0a99370547c..ad71341e34ed8 100644 --- a/docs/core/compatibility/unsupported-apis.md +++ b/docs/core/compatibility/unsupported-apis.md @@ -247,9 +247,13 @@ This article organizes the affected APIs by namespace. | | Linux and macOS | | | Linux and macOS | | \* | Windows, for algorithms not natively supported | +| \* | Windows, for algorithms not natively supported | | \* | Windows, for algorithms not natively supported | +| \* | Windows, for algorithms not natively supported | | \* | Windows, for algorithms not natively supported | -| \* | Windows, for algorithms not natively supported | +| \* | Windows, for algorithms not natively supported | +| \* | Windows, for algorithms not natively supported | +| \* | Windows, for algorithms not natively supported | | | All | | | Linux and macOS | | | Linux and macOS | From abac2aa4bc3dc7680e862b3334c18b663b1b2061 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 3 Aug 2026 16:19:36 -0700 Subject: [PATCH 6/7] Apply suggestion from @gewarren --- .../cryptography/11/compositemldsa-windows-native.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md b/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md index a3df5f4180812..ea05b7b30d777 100644 --- a/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md +++ b/docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md @@ -42,7 +42,7 @@ It's preferable to use the native implementation the operating system provides r ## Recommended action -Before you use a specific Composite ML-DSA algorithm on Windows, call to check whether the algorithm is supported. If an algorithm isn't supported, choose a supported algorithm or handle the resulting . +Before you use a specific Composite ML-DSA algorithm on Windows, call to check whether the algorithm is supported. If an algorithm isn't supported, choose a supported algorithm or handle the resulting . ```csharp if (CompositeMLDsa.IsAlgorithmSupported(CompositeMLDsaAlgorithm.MLDsa65WithECDsaP384)) From ff1ddc42fb257a9e00000f52fd7e55983682ee49 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 5 Aug 2026 13:07:40 -0700 Subject: [PATCH 7/7] respond to feedback --- docs/core/compatibility/unsupported-apis.md | 6 +----- docs/standard/security/cross-platform-cryptography.md | 3 +-- 2 files changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/core/compatibility/unsupported-apis.md b/docs/core/compatibility/unsupported-apis.md index 5d0a99370547c..2b81b79994b76 100644 --- a/docs/core/compatibility/unsupported-apis.md +++ b/docs/core/compatibility/unsupported-apis.md @@ -2,7 +2,7 @@ title: Unsupported APIs on .NET Core and .NET 5+ titleSuffix: "" description: Learn which .NET APIs always throw an exception on .NET Core and .NET 5 and later versions. -ms.date: 08/03/2026 +ms.date: 03/16/2026 ai-usage: ai-assisted --- # APIs that always throw exceptions on .NET (Core) @@ -246,10 +246,6 @@ This article organizes the affected APIs by namespace. | | Linux and macOS | | | Linux and macOS | | | Linux and macOS | -| \* | Windows, for algorithms not natively supported | -| \* | Windows, for algorithms not natively supported | -| \* | Windows, for algorithms not natively supported | -| \* | Windows, for algorithms not natively supported | | | All | | | Linux and macOS | | | Linux and macOS | diff --git a/docs/standard/security/cross-platform-cryptography.md b/docs/standard/security/cross-platform-cryptography.md index 01d9933cf345a..88a62dbb43674 100644 --- a/docs/standard/security/cross-platform-cryptography.md +++ b/docs/standard/security/cross-platform-cryptography.md @@ -3,6 +3,7 @@ title: "Cross-platform cryptography" description: Learn about cryptographic capabilities on platforms supported by .NET. ms.date: 08/03/2026 ms.subservice: standard-library +ms.topic: reference helpviewer_keywords: - "cryptography, cross-platform" - "encryption, cross-platform" @@ -384,8 +385,6 @@ SLH-DSA has a pure and prehash variant (HashSLH-DSA). The following table reflec | MLDSA87-RSA4096-PSS-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | | MLDSA87-ECDSA-P521-SHA512 | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ | -Starting in .NET 11, Windows support for Composite ML-DSA uses the native Windows implementation, which only supports the algorithms marked "Windows 11 Insiders (Latest)" in the preceding table. For more information, see [Composite ML-DSA on Windows uses native implementation](../../core/compatibility/cryptography/11/compositemldsa-windows-native.md). - #### Native interop composite ML-DSA * : Not supported