From 0aa766551d9655d93211325bd32f0fa9fc41b271 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 5 Aug 2025 23:36:11 +0000 Subject: [PATCH 1/5] Initial plan From aea4b35636b2ed60e466924849e3838ccf191dce Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 5 Aug 2025 23:43:26 +0000 Subject: [PATCH 2/5] Add breaking change documentation for CoseSigner.Key property Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/10.0.md | 1 + .../cryptography/10.0/cosesigner-key-null.md | 77 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 80 insertions(+) create mode 100644 docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 1b71ea787cc16..d667429dd913a 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -54,6 +54,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 may now 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 | diff --git a/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md b/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md new file mode 100644 index 0000000000000..555fd863de4b9 --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md @@ -0,0 +1,77 @@ +--- +title: "Breaking change - CoseSigner.Key may now be null" +description: "Learn about the breaking change in .NET 10 where CoseSigner.Key may now be null when backed by Post-Quantum Cryptography algorithms." +ms.date: 01/25/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/46999 +--- + +# CoseSigner.Key may now be null + +In .NET 10, the property may now return `null`. If `CoseSigner` is backed by an RSA or ECDSA key, then `CoseSigner.Key` continues to return the key and it's non-null. However, when `CoseSigner` is backed by a key that doesn't derive from `AsymmetricAlgorithm`, like `MLDsa` (a new Post-Quantum Cryptography (PQC) signing algorithm), `CoseSigner.Key` returns `null`. + +## Version introduced + +.NET 10 Preview 7 + +## Previous behavior + +`CoseSigner.Key` couldn't be `null`. It had type `AsymmetricAlgorithm`. + +```csharp +using RSA rsaKey = RSA.Create(); +CoseSigner signer = new CoseSigner(rsaKey, RSASignaturePadding.Pss, HashAlgorithmName.SHA512); +AsymmetricAlgorithm key = signer.Key; // key was never null +``` + +## New behavior + +`CoseSigner.Key` can be `null`. It now has type `AsymmetricAlgorithm?`. + +```csharp +using RSA rsaKey = RSA.Create(); + +CoseSigner signer = new CoseSigner(rsaKey, RSASignaturePadding.Pss, HashAlgorithmName.SHA512); +// signer.Key is rsaKey here + +// CoseKey is a new abstraction for all keys used in COSE +CoseKey coseKey = new CoseKey(rsaKey, RSASignaturePadding.Pss, HashAlgorithmName.SHA512); +signer = new CoseSigner(coseKey); +// signer.Key is rsaKey here + +using MLDsa mldsa = MLDsa.GenerateKey(MLDsaAlgorithm.MLDsa44); + +coseKey = new CoseKey(mldsa); +signer = new CoseSigner(coseKey); +// signer.Key is null here +``` + +## Type of breaking change + +This is both a [behavioral change](../../categories.md#behavioral-change) and [source compatibility](../../categories.md#source-compatibility) change. + +## Reason for change + +With the introduction of new signing algorithms such as ML-DSA, .NET has moved away from using `AsymmetricAlgorithm` as the universal base class for all asymmetric algorithms. Likewise, `CoseSigner` can now be constructed with a key that doesn't derive from `AsymmetricAlgorithm`. In this case `CoseSigner.Key` can't return an `AsymmetricAlgorithm` representing the underlying key and thus returns `null` instead. + +This change was introduced in . + +## Recommended action + +`CoseSigner.Key` can still be used, but callers should handle `null` values. + +```csharp +AsymmetricAlgorithm? key = signer.Key; +if (key != null) +{ + // Use the key for operations that require AsymmetricAlgorithm +} +else +{ + // Handle the case where the signer is backed by a non-AsymmetricAlgorithm key +} +``` + +## Affected APIs + +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index bef069b8a508c..f4f5b6ef7ee89 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -40,6 +40,8 @@ items: href: core-libraries/10.0/ymm-embedded-rounding.md - name: Cryptography items: + - name: CoseSigner.Key may now be null + 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: OpenSSL cryptographic primitives not supported on macOS From 07c5c79546bb44b2dadb1b6b639fa4fc4f7db6d7 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 6 Aug 2025 17:06:14 -0700 Subject: [PATCH 3/5] Apply suggestions from code review --- docs/core/compatibility/10.0.md | 2 +- .../cryptography/10.0/cosesigner-key-null.md | 38 +++++-------------- docs/core/compatibility/toc.yml | 2 +- 3 files changed, 11 insertions(+), 31 deletions(-) diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index d667429dd913a..17582a1f2029d 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -54,7 +54,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 may now be null](cryptography/10.0/cosesigner-key-null.md) | Behavioral/source incompatible change | Preview 7 | +| [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 | diff --git a/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md b/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md index 555fd863de4b9..29671dd34eb9a 100644 --- a/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md +++ b/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md @@ -6,9 +6,9 @@ ai-usage: ai-assisted ms.custom: https://github.com/dotnet/docs/issues/46999 --- -# CoseSigner.Key may now be null +# CoseSigner.Key can now be null -In .NET 10, the property may now return `null`. If `CoseSigner` is backed by an RSA or ECDSA key, then `CoseSigner.Key` continues to return the key and it's non-null. However, when `CoseSigner` is backed by a key that doesn't derive from `AsymmetricAlgorithm`, like `MLDsa` (a new Post-Quantum Cryptography (PQC) signing algorithm), `CoseSigner.Key` returns `null`. +In .NET 10, the property can now return `null`. If `CoseSigner` is backed by an RSA or ECDSA key, then `CoseSigner.Key` returns a non-null key. However, when `CoseSigner` is backed by a key that doesn't derive from , like `MLDsa` (a new Post-Quantum Cryptography (PQC) signing algorithm), `CoseSigner.Key` returns `null`. ## Version introduced @@ -18,59 +18,39 @@ In .NET 10, the . - ## Recommended action -`CoseSigner.Key` can still be used, but callers should handle `null` values. - -```csharp -AsymmetricAlgorithm? key = signer.Key; -if (key != null) -{ - // Use the key for operations that require AsymmetricAlgorithm -} -else -{ - // Handle the case where the signer is backed by a non-AsymmetricAlgorithm key -} -``` +It's still okay to use `CoseSigner.Key` but be sure to handle `null` values. ## Affected APIs diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index f4f5b6ef7ee89..c64edd63aa1f2 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -40,7 +40,7 @@ items: href: core-libraries/10.0/ymm-embedded-rounding.md - name: Cryptography items: - - name: CoseSigner.Key may now be null + - name: CoseSigner.Key can be null href: cryptography/10.0/cosesigner-key-null.md - name: Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE href: cryptography/10.0/version-override.md From be939c87d1d765f92c289922eaf8b4e10c5c731f Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 7 Aug 2025 13:18:33 -0700 Subject: [PATCH 4/5] Update date --- .../core/compatibility/cryptography/10.0/cosesigner-key-null.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md b/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md index 29671dd34eb9a..3fe177da39a3c 100644 --- a/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md +++ b/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md @@ -1,7 +1,7 @@ --- title: "Breaking change - CoseSigner.Key may now be null" description: "Learn about the breaking change in .NET 10 where CoseSigner.Key may now be null when backed by Post-Quantum Cryptography algorithms." -ms.date: 01/25/2025 +ms.date: 08/07/2025 ai-usage: ai-assisted ms.custom: https://github.com/dotnet/docs/issues/46999 --- From 34f373982d6c5acff9b3f3c816a675d0079f8f36 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 7 Aug 2025 19:36:51 -0700 Subject: [PATCH 5/5] Update docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md --- .../core/compatibility/cryptography/10.0/cosesigner-key-null.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md b/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md index 3fe177da39a3c..5895cb696d6e7 100644 --- a/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md +++ b/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md @@ -42,7 +42,7 @@ signer = new CoseSigner(coseKey); ## Type of breaking change -This is both a [behavioral change](../../categories.md#behavioral-change) but it can also affect [source compatibility](../../categories.md#source-compatibility). +This is a [behavioral change](../../categories.md#behavioral-change) but it can also affect [source compatibility](../../categories.md#source-compatibility). ## Reason for change