[Breaking change]: MLDsa and SlhDsa members renamed from using "SecretKey" to using "PrivateKey"

[bartonjs]

Description

For the [Experimental] Post-Quantum Cryptography (PQC) classes MLDsa and SlhDsa, the classes were originally built using "SecretKey" in method and property names involving the sk value from their respective specifications.

During their final pass through the API Review process, we shifted to using "PrivateKey" to be better aligned with existing asymmetric cryptography types and with related members (such as ExportPkcs8PrivateKey).

Version

.NET 10 RC 1

Previous behavior

Users of .NET 10 Preview 7 integrating with the MLDsa or SlhDsa classes could call ImportMLDsaSecretKey or ImportSlhDsaSecretKey, or similar.

New behavior

Users of .NET 10 RC1 integrating with the MLDsa or SlhDsa classes should instead call ImportMLDsaPrivateKey or ImportSlhDsaPrivateKey, or similar.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

Alignment with the rest of the asymmetric algorithms

Recommended action

Any compile breaks from this change will be solved by replacing instances of "SecretKey" with "PrivateKey" in the called member name:

-int targetSize = key.Algorithm.SecretKeySizeInBytes;
+int targetSize = key.Algorithm.PrivateKeySizeInBytes;
byte[] output = new byte[targetSize];
-key.ExportMLDsaSecretKey(output);
+key.ExportMLDsaPrivateKey(output);

Feature area

Cryptography

Affected APIs

• System.Security.Cryptography.MLDsa.ImportMLDsaSecretKey (all overloads)
• System.Security.Cryptography.MLDsa.ExportMLDsaSecretKey (all overloads)
• System.Security.Cryptography.MLDsaAlgorithm.SecretKeySizeInBytes
• System.Security.Cryptography.SlhDsa.ImportSlhDsaSecretKey (all overloads)
• System.Security.Cryptography.SlhDsa.ExportSlhDsaSecretKey (all overloads)
• System.Security.Cryptography.SlhDsaAlgorithm.SecretKeySizeInBytes

[bartonjs]

@gewarren These types are marked as [Experimental], they're new in .NET 10, and I don't think there's a lot of usage.

But since both renames took multiple rounds of cleanup within dotnet/runtime, it seemed like a breaking change notice wouldn't go amiss.