Document CompositeMLDsa update to draft-08 breaking change (#49609)

Author: Copilot

docs/core/compatibility/10.0.md

@@ -61,6 +61,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 
 | Title | Type of change    | Introduced version |
 |-------|-------------------|--------------------|
+| [CompositeMLDsa updated to draft-08](cryptography/10.0/composite-mldsa-draft-08.md) | Behavioral change | 10.0.0 |
 | [CoseSigner.Key can be null](cryptography/10.0/cosesigner-key-null.md) | Behavioral/source incompatible change | Preview 7 |
 | [MLDsa and SlhDsa 'SecretKey' members renamed](cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md) | Source incompatible | RC 1 |
 | [OpenSSL cryptographic primitives aren't supported on macOS](cryptography/10.0/openssl-macos-unsupported.md) | Behavioral change | Preview 6 |

docs/core/compatibility/cryptography/10.0/composite-mldsa-draft-08.md

@@ -0,0 +1,45 @@
+---
+title: "Breaking change - CompositeMLDsa updated to draft-08"
+description: "Learn about the breaking change in .NET 10 where CompositeMLDsa was updated from draft-07 to draft-08 of the Composite ML-DSA for use in X.509 Public Key Infrastructure specification."
+ms.date: 11/04/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issue/48901
+---
+
+# CompositeMLDsa updated to draft-08
+
+<xref:System.Security.Cryptography.CompositeMLDsa> has moved from draft-07 to draft-08 of the [Composite ML-DSA for use in X.509 Public Key Infrastructure](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) specification. The draft-08 format is not compatible with the draft-07 signatures, and key export/import formats are also incompatible across the draft-07/draft-08 boundary. draft-08 and draft-09 are compatible.
+
+## Version introduced
+
+.NET 10 GA
+
+## Previous behavior
+
+In preview and RC releases of .NET 10, signatures were generated and validated according to draft-07 of Composite ML-DSA for use in X.509 Public Key Infrastructure.
+
+Public key and private key export and import used the format from draft-07 of Composite ML-DSA for use in X.509 Public Key Infrastructure.
+
+## New behavior
+
+Starting in the .NET 10 GA release, signatures are generated and validated according to draft-08 of Composite ML-DSA for use in X.509 Public Key Infrastructure.
+
+Public key and private key export and import use the format from draft-08 of Composite ML-DSA for use in X.509 Public Key Infrastructure.
+
+## Type of breaking change
+
+This change is a [behavioral change](../../categories.md#behavioral-change).
+
+## Reason for change
+
+This change was made to stay current with the underlying specification.
+
+## Recommended action
+
+The <xref:System.Security.Cryptography.CompositeMLDsa> class is marked as `[Experimental]`, partly because the specification isn't yet complete. Do not depend on this class in production.
+
+Discard any previously generated keys and signatures.
+
+## Affected APIs
+
+- <xref:System.Security.Cryptography.CompositeMLDsa?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -70,6 +70,8 @@ items:
                 href: core-libraries/10.0/ymm-embedded-rounding.md
           - name: Cryptography
             items:
+              - name: CompositeMLDsa updated to draft-08
+                href: cryptography/10.0/composite-mldsa-draft-08.md
               - name: CoseSigner.Key can be null
                 href: cryptography/10.0/cosesigner-key-null.md
               - name: Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE

docs/core/whats-new/dotnet-10/libraries.md

@@ -156,7 +156,7 @@ private static bool VerifyWithExternalMu(MLDsa verifyingKey, ReadOnlySpan<byte>
 
 #### Composite ML-DSA
 
-.NET 10 introduces new types to support [ietf-lamps-pq-composite-sigs](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) (currently at draft 7), including the <xref:System.Security.Cryptography.CompositeMLDsa> and <xref:System.Security.Cryptography.CompositeMLDsaAlgorithm> types, with implementation of the primitive methods for RSA variants.
+.NET 10 introduces new types to support [ietf-lamps-pq-composite-sigs](https://datatracker.ietf.org/doc/draft-ietf-lamps-pq-composite-sigs/) (at draft 8 as of .NET 10 GA), including the <xref:System.Security.Cryptography.CompositeMLDsa> and <xref:System.Security.Cryptography.CompositeMLDsaAlgorithm> types, with implementation of the primitive methods for RSA variants.
 
 ```csharp
 var algorithm = CompositeMLDsaAlgorithm.MLDsa65WithRSA4096Pss;