Document breaking change: Composite ML-DSA on Windows uses native implementation in .NET 11

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

docs/core/compatibility/cryptography/11/compositemldsa-windows-native.md

@@ -0,0 +1,63 @@
+---
+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, <xref:System.Security.Cryptography.CompositeMLDsa> 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, <xref:System.Security.Cryptography.CompositeMLDsa> 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 <xref:System.PlatformNotSupportedException> on Windows, because Windows doesn't support EdDSA.
+
+## New behavior
+
+Starting in .NET 11, <xref:System.Security.Cryptography.CompositeMLDsa> 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:
+
+| 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 <xref:System.PlatformNotSupportedException> 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 <xref:System.PlatformNotSupportedException> 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
+
+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 <xref:System.Security.Cryptography.CompositeMLDsa.IsAlgorithmSupported*> to check whether the algorithm is supported. If an algorithm isn't supported, choose a supported algorithm or handle the resulting <xref:System.PlatformNotSupportedException>.
+
+```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 <xref:System.PlatformNotSupportedException> on Windows, as before.
+
+## Affected APIs
+
+- <xref:System.Security.Cryptography.CompositeMLDsa?displayProperty=fullName>

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

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,14 @@ This article organizes the affected APIs by namespace.
 | <xref:System.Security.Cryptography.CngKeyCreationParameters?displayProperty=nameWithType> | Linux and macOS |
 | <xref:System.Security.Cryptography.CngProvider?displayProperty=nameWithType> | Linux and macOS |
 | <xref:System.Security.Cryptography.CngUIPolicy?displayProperty=nameWithType> | Linux and macOS |
+| <xref:System.Security.Cryptography.CompositeMLDsa.GenerateKey*?displayProperty=nameWithType>\* | Windows, for algorithms not natively supported |
+| <xref:System.Security.Cryptography.CompositeMLDsa.ImportCompositeMLDsaPrivateKey*?displayProperty=nameWithType>\* | Windows, for algorithms not natively supported |
+| <xref:System.Security.Cryptography.CompositeMLDsa.ImportCompositeMLDsaPublicKey*?displayProperty=nameWithType>\* | Windows, for algorithms not natively supported |
+| <xref:System.Security.Cryptography.CompositeMLDsa.ImportFromEncryptedPem*?displayProperty=nameWithType>\* | Windows, for algorithms not natively supported |
+| <xref:System.Security.Cryptography.CompositeMLDsa.ImportFromPem*?displayProperty=nameWithType>\* | Windows, for algorithms not natively supported |
+| <xref:System.Security.Cryptography.CompositeMLDsa.ImportEncryptedPkcs8PrivateKey*?displayProperty=nameWithType>\* | Windows, for algorithms not natively supported |
+| <xref:System.Security.Cryptography.CompositeMLDsa.ImportPkcs8PrivateKey*?displayProperty=nameWithType>\* | Windows, for algorithms not natively supported |
+| <xref:System.Security.Cryptography.CompositeMLDsa.ImportSubjectPublicKeyInfo*?displayProperty=nameWithType>\* | Windows, for algorithms not natively supported |
 | <xref:System.Security.Cryptography.CryptoConfig.EncodeOID(System.String)?displayProperty=nameWithType> | All |
 | <xref:System.Security.Cryptography.CspKeyContainerInfo.%23ctor*> | Linux and macOS |
 | <xref:System.Security.Cryptography.CspKeyContainerInfo.Accessible?displayProperty=nameWithType> | Linux and macOS |

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"
@@ -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