From 7eaec7810ad6899aa8a9e70370a4181817fb6983 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 5 Sep 2025 16:27:40 +0000 Subject: [PATCH 1/3] Initial plan From 613200b82169b223e36f7ffb2a8aa370838b829a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 5 Sep 2025 16:35:42 +0000 Subject: [PATCH 2/3] Add breaking change documentation for MLDsa and SlhDsa SecretKey to PrivateKey rename Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 1 + .../mldsa-slhdsa-secretkey-to-privatekey.md | 70 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 73 insertions(+) create mode 100644 docs/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index b20300bcb804a..330c072263666 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -77,6 +77,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | 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 members renamed from using "SecretKey" to using "PrivateKey"](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 | diff --git a/docs/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md b/docs/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md new file mode 100644 index 0000000000000..8f7f181b0d4d9 --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md @@ -0,0 +1,70 @@ +--- +title: "Breaking change - MLDsa and SlhDsa members renamed from using 'SecretKey' to using 'PrivateKey'" +description: "Learn about the breaking change in .NET 10 where MLDsa and SlhDsa members were renamed from using 'SecretKey' to using 'PrivateKey'." +ms.date: 12/21/2024 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/47691 +--- + +# MLDsa and SlhDsa members renamed from using "SecretKey" to using "PrivateKey" + +In .NET 10, for the `[Experimental]` Post-Quantum Cryptography (PQC) classes and , method and property names involving the `sk` value from their respective specifications were renamed from using "SecretKey" to using "PrivateKey". + +## Version introduced + +.NET 10 RC 1 + +## Previous behavior + +In .NET 10 Preview 7, users could call methods like `ImportMLDsaSecretKey` or `ImportSlhDsaSecretKey`, and access properties like `SecretKeySizeInBytes`. + +```csharp +using System.Security.Cryptography; + +using MLDsa key = MLDsa.GenerateKey(MLDsaAlgorithm.MLDsa44); +int targetSize = key.Algorithm.SecretKeySizeInBytes; +byte[] output = new byte[targetSize]; +key.ExportMLDsaSecretKey(output); +``` + +## New behavior + +In .NET 10 RC 1, users should call methods like `ImportMLDsaPrivateKey` or `ImportSlhDsaPrivateKey`, and access properties like `PrivateKeySizeInBytes`. + +```csharp +using System.Security.Cryptography; + +using MLDsa key = MLDsa.GenerateKey(MLDsaAlgorithm.MLDsa44); +int targetSize = key.Algorithm.PrivateKeySizeInBytes; +byte[] output = new byte[targetSize]; +key.ExportMLDsaPrivateKey(output); +``` + +## 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 `ExportPkcs8PrivateKey`. + +## Recommended action + +Any compile breaks from this change can be resolved 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 + +- +- +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 2308812e76ac7..077c8318530fa 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -68,6 +68,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 members renamed from using "SecretKey" to using "PrivateKey" + 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 From 0f840df666a21aea9796e49d3dc1090939cf04b8 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Fri, 5 Sep 2025 19:33:26 -0700 Subject: [PATCH 3/3] human edits --- docs/core/compatibility/10.0.md | 22 +++++----- .../mldsa-slhdsa-secretkey-to-privatekey.md | 42 ++++++------------- docs/core/compatibility/toc.yml | 2 +- 3 files changed, 24 insertions(+), 42 deletions(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 330c072263666..67869a9b4439b 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -53,6 +53,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) @@ -72,17 +83,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 | -| [MLDsa and SlhDsa members renamed from using "SecretKey" to using "PrivateKey"](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 | - ## Interop | Title | Type of change | Introduced version | diff --git a/docs/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md b/docs/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md index 8f7f181b0d4d9..308900af099c6 100644 --- a/docs/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md +++ b/docs/core/compatibility/cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md @@ -1,14 +1,14 @@ --- -title: "Breaking change - MLDsa and SlhDsa members renamed from using 'SecretKey' to using 'PrivateKey'" +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: 12/21/2024 +ms.date: 09/05/2025 ai-usage: ai-assisted ms.custom: https://github.com/dotnet/docs/issues/47691 --- -# MLDsa and SlhDsa members renamed from using "SecretKey" to using "PrivateKey" +# MLDsa and SlhDsa 'SecretKey' members renamed -In .NET 10, for the `[Experimental]` Post-Quantum Cryptography (PQC) classes and , method and property names involving the `sk` value from their respective specifications were renamed from using "SecretKey" to using "PrivateKey". +Some methods and properties in the `[Experimental]` post-quantum cryptography (PQC) classes and have been renamed. APIs that involve the `sk` value from their respective specifications now have `PrivateKey` in their names instead of `SecretKey`. ## Version introduced @@ -16,29 +16,11 @@ In .NET 10, for the `[Experimental]` Post-Quantum Cryptography (PQC) classes . ## Recommended action -Any compile breaks from this change can be resolved by replacing instances of "SecretKey" with "PrivateKey" in the called member names: +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; @@ -62,9 +44,9 @@ byte[] output = new byte[targetSize]; ## Affected APIs -- -- +- +- - -- -- +- +- - diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 077c8318530fa..b9ab4277b8037 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -68,7 +68,7 @@ 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 members renamed from using "SecretKey" to using "PrivateKey" + - 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