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..ea05b7b30d777 --- /dev/null +++ b/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, 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, 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 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 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 + +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..88a62dbb43674 100644 --- a/docs/standard/security/cross-platform-cryptography.md +++ b/docs/standard/security/cross-platform-cryptography.md @@ -1,8 +1,9 @@ --- 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 +ms.topic: reference helpviewer_keywords: - "cryptography, cross-platform" - "encryption, cross-platform" @@ -365,24 +366,24 @@ 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+ | ❌ | ❌ | ❌ | #### Native interop composite ML-DSA