Add breaking change documentation for MLDsa and SlhDsa SecretKey to PrivateKey rename (#48275)

Author: Copilot

docs/core/compatibility/10.0.md

@@ -55,6 +55,17 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 | [System.Linq.AsyncEnumerable included in core libraries](core-libraries/10.0/asyncenumerable.md) | Source incompatible | Preview 1 |
 | [YMM embedded rounding removed from AVX10.2](core-libraries/10.0/ymm-embedded-rounding.md) | Behavioral change | Preview 5 |
 
+## Cryptography
+
+| Title | Type of change    | Introduced version |
+|-------|-------------------|--------------------|
+| [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 |
+| [X500DistinguishedName validation is stricter](cryptography/10.0/x500distinguishedname-validation.md) | Behavioral change | Preview 1 |
+| [X509Certificate and PublicKey key parameters can be null](cryptography/10.0/x509-publickey-null.md) | Behavioral/source incompatible change | Preview 3 |
+| [Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE](cryptography/10.0/version-override.md) | Behavioral change | Preview 1 |
+
 ## Entity Framework Core
 
 [Breaking changes in EF Core 10](/ef/core/what-is-new/ef-core-10.0/breaking-changes)
@@ -74,16 +85,6 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
 |-------|-------------------|--------------------|
 | [Environment variable renamed to DOTNET_ICU_VERSION_OVERRIDE](globalization/10.0/version-override.md) | Behavioral change | Preview 1 |
 
-## Cryptography
-
-| Title | Type of change    | Introduced version |
-|-------|-------------------|--------------------|
-| [CoseSigner.Key can be null](cryptography/10.0/cosesigner-key-null.md) | Behavioral/source incompatible change | Preview 7 |
-| [OpenSSL cryptographic primitives aren't supported on macOS](cryptography/10.0/openssl-macos-unsupported.md) | Behavioral change | Preview 6 |
-| [X500DistinguishedName validation is stricter](cryptography/10.0/x500distinguishedname-validation.md) | Behavioral change | Preview 1 |
-| [X509Certificate and PublicKey key parameters can be null](cryptography/10.0/x509-publickey-null.md) | Behavioral/source incompatible change | Preview 3 |
-| [Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE](cryptography/10.0/version-override.md) | Behavioral change | Preview 1 |
-
 ## Interop
 
 | Title | Type of change    | Introduced version |

docs/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md

@@ -0,0 +1,52 @@
+---
+title: "Breaking change - MLDsa and SlhDsa 'SecretKey' members renamed"
+description: "Learn about the breaking change in .NET 10 where MLDsa and SlhDsa members were renamed from using 'SecretKey' to using 'PrivateKey'."
+ms.date: 09/05/2025
+ai-usage: ai-assisted
+ms.custom: https://github.com/dotnet/docs/issues/47691
+---
+
+# MLDsa and SlhDsa 'SecretKey' members renamed
+
+Some methods and properties in the `[Experimental]` post-quantum cryptography (PQC) classes <xref:System.Security.Cryptography.MLDsa?displayProperty=fullName> and <xref:System.Security.Cryptography.SlhDsa?displayProperty=fullName> have been renamed. APIs that involve the `sk` value from their respective specifications now have `PrivateKey` in their names instead of `SecretKey`.
+
+## Version introduced
+
+.NET 10 RC 1
+
+## Previous behavior
+
+Previously, you could call methods like `ImportMLDsaSecretKey` and `ImportSlhDsaSecretKey`, and you could access properties like `SecretKeySizeInBytes`.
+
+## New behavior
+
+Starting in .NET 10 RC 1, you must call methods like `ImportMLDsaPrivateKey` or `ImportSlhDsaPrivateKey`, and access properties like `PrivateKeySizeInBytes`.
+
+## Type of breaking change
+
+This change can affect [source compatibility](../../categories.md#source-compatibility).
+
+## Reason for change
+
+The change was made to align with existing asymmetric cryptography types in .NET and with related members such as <xref:System.Security.Cryptography.MLDsa.ExportPkcs8PrivateKey>.
+
+## Recommended action
+
+Resolve any compile breaks from this change by replacing instances of `SecretKey` with `PrivateKey` in the called member names:
+
+```diff
+-int targetSize = key.Algorithm.SecretKeySizeInBytes;
++int targetSize = key.Algorithm.PrivateKeySizeInBytes;
+byte[] output = new byte[targetSize];
+-key.ExportMLDsaSecretKey(output);
++key.ExportMLDsaPrivateKey(output);
+```
+
+## Affected APIs
+
+- <xref:System.Security.Cryptography.MLDsa.ImportMLDsaSecretKey*?displayProperty=fullName>
+- <xref:System.Security.Cryptography.MLDsa.ExportMLDsaSecretKey*?displayProperty=fullName>
+- <xref:System.Security.Cryptography.MLDsaAlgorithm.SecretKeySizeInBytes?displayProperty=fullName>
+- <xref:System.Security.Cryptography.SlhDsa.ImportSlhDsaSecretKey*?displayProperty=fullName>
+- <xref:System.Security.Cryptography.SlhDsa.ExportSlhDsaSecretKey*?displayProperty=fullName>
+- <xref:System.Security.Cryptography.SlhDsaAlgorithm.SecretKeySizeInBytes?displayProperty=fullName>

docs/core/compatibility/toc.yml

@@ -72,6 +72,8 @@ items:
                 href: cryptography/10.0/cosesigner-key-null.md
               - name: Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE
                 href: cryptography/10.0/version-override.md
+              - name: MLDsa and SlhDsa 'SecretKey' members renamed
+                href: cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md
               - name: OpenSSL cryptographic primitives not supported on macOS
                 href: cryptography/10.0/openssl-macos-unsupported.md
               - name: X500DistinguishedName validation is stricter