diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 1b71ea787cc16..17582a1f2029d 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 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 new file mode 100644 index 0000000000000..5895cb696d6e7 --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/cosesigner-key-null.md @@ -0,0 +1,57 @@ +--- +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: 08/07/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/46999 +--- + +# CoseSigner.Key can now be 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 + +.NET 10 Preview 7 + +## Previous behavior + +`CoseSigner.Key` couldn't be `null`. It had type `AsymmetricAlgorithm`. + +## New behavior + +`CoseSigner.Key` can be `null`. Its type is `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 a [behavioral change](../../categories.md#behavioral-change) but it can also affect [source compatibility](../../categories.md#source-compatibility). + +## 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. + +## Recommended action + +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 bef069b8a508c..c64edd63aa1f2 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 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 - name: OpenSSL cryptographic primitives not supported on macOS