Add breaking change documentation for CoseSigner.Key property

Co-authored-by: gewarren <[email protected]>

Author: Copilot

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 |

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 <xref:System.Security.Cryptography.Cose.CoseSigner.Key?displayProperty=fullName> 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 <https://github.com/dotnet/runtime/pull/115158>.
+
+## 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
+
+- <xref:System.Security.Cryptography.Cose.CoseSigner.Key?displayProperty=fullName>

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