Seed in the skeleton of ML-DSA based on current prototyping

This seeds a lot of untested boilerplate code as non-public types in System.Security.Cryptography.

When we start work on ML-DSA, we can take this, make MLDsa and MLDsaAlgorithm public, start to write tests, and wire up an implementation. We can also take this and clone+customize it for the other PQC algorithms.

It does not define all span-vs-array overloads for all spanified members, just one candidate per method group.

As the PQC experiment needs to make it further before we can commit to the shape, it is both starting without API Review, and pre-emptively applying the Experimental attribute.

Author: bartonjs

docs/project/list-of-diagnostics.md

@@ -314,3 +314,4 @@ Diagnostic id values for experimental APIs must not be recycled, as that could s
 |  __`SYSLIB5003`__ |     .NET 9 |     TBD | `System.Runtime.Intrinsics.Arm.Sve` is experimental |
 |  __`SYSLIB5004`__ |     .NET 9 |     TBD | `X86Base.DivRem` is experimental since performance is not as optimized as `T.DivRem` |
 |  __`SYSLIB5005`__ |     .NET 9 |     TBD | `System.Formats.Nrbf` is experimental |
+|  __`SYSLIB5006`__ |    .NET 10 |     TBD | Types for Post-Quantum Cryptography (PQC) are experimental. |

src/libraries/Common/src/System/Experimentals.cs

@@ -30,6 +30,9 @@ internal static class Experimentals
 
         // System.Formats.Nrbf was experimental, do not reuse "SYSLIB5005"
 
+        // Types for Post-Quantum Cryptography (PQC) are experimental.
+        internal const string PostQuantumCryptographyDiagId = "SYSLIB5006";
+
         // When adding a new diagnostic ID, add it to the table in docs\project\list-of-diagnostics.md as well.
         // Keep new const identifiers above this comment.
     }

src/libraries/Common/src/System/Security/Cryptography/IImportExportShape.cs

@@ -0,0 +1,37 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace System.Security.Cryptography
+{
+#if DESIGNTIMEINTERFACES
+    internal interface IImportExportShape<TSelf> where TSelf : class, IImportExportShape<TSelf>
+    {
+        static abstract TSelf ImportSubjectPublicKeyInfo(ReadOnlySpan<byte> source);
+        static abstract TSelf ImportPkcs8PrivateKey(ReadOnlySpan<byte> source);
+        static abstract TSelf ImportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte> passwordBytes, ReadOnlySpan<byte> source);
+        static abstract TSelf ImportEncryptedPkcs8PrivateKey(ReadOnlySpan<char> password, ReadOnlySpan<byte> source);
+
+        static abstract TSelf ImportFromPem(ReadOnlySpan<char> source);
+        static abstract TSelf ImportFromEncryptedPem(ReadOnlySpan<char> source, ReadOnlySpan<char> password);
+        static abstract TSelf ImportFromEncryptedPem(ReadOnlySpan<char> source, ReadOnlySpan<byte> passwordBytes);
+
+        byte[] ExportSubjectPublicKeyInfo();
+        bool TryExportSubjectPublicKeyInfo(Span<byte> destination, out int bytesWritten);
+        string ExportSubjectPublicKeyInfoPem();
+
+        byte[] ExportPkcs8PrivateKey();
+        bool TryExportPkcs8PrivateKey(Span<byte> destination, out int bytesWritten);
+        string ExportPkcs8PrivateKeyPem();
+
+        byte[] ExportEncryptedPkcs8PrivateKey(ReadOnlySpan<char> password, PbeParameters pbeParameters);
+        bool TryExportEncryptedPkcs8PrivateKey(
+            ReadOnlySpan<char> password, PbeParameters pbeParameters, Span<byte> destination, out int bytesWritten);
+        string ExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<char> password, PbeParameters pbeParameters);
+
+        byte[] ExportEncryptedPkcs8PrivateKey(ReadOnlySpan<byte> passwordBytes, PbeParameters pbeParameters);
+        bool TryExportEncryptedPkcs8PrivateKey(
+            ReadOnlySpan<byte> passwordBytes, PbeParameters pbeParameters, Span<byte> destination, out int bytesWritten);
+        string ExportEncryptedPkcs8PrivateKeyPem(ReadOnlySpan<byte> passwordBytes, PbeParameters pbeParameters);
+    }
+#endif
+}

src/libraries/Common/src/System/Security/Cryptography/KeyFormatHelper.Encrypted.cs

@@ -12,6 +12,8 @@ namespace System.Security.Cryptography
 {
     internal static partial class KeyFormatHelper
     {
+        internal delegate TRet ReadOnlySpanFunc<TIn, TRet>(ReadOnlySpan<TIn> span);
+
         internal static unsafe void ReadEncryptedPkcs8<TRet>(
             string[] validOids,
             ReadOnlySpan<byte> source,
@@ -272,6 +274,68 @@ internal static ArraySegment<byte> DecryptPkcs8(
                 out bytesRead);
         }
 
+        internal static unsafe T DecryptPkcs8<T>(
+            ReadOnlySpan<char> password,
+            ReadOnlySpan<byte> source,
+            ReadOnlySpanFunc<byte, T> keyReader,
+            out int bytesRead)
+        {
+            fixed (byte* pointer = source)
+            {
+                using (PointerMemoryManager<byte> manager = new(pointer, source.Length))
+                {
+                    ArraySegment<byte> decrypted = DecryptPkcs8(password, manager.Memory, out bytesRead);
+
+                    try
+                    {
+                        AsnValueReader reader = new(decrypted, AsnEncodingRules.BER);
+                        reader.ReadEncodedValue();
+                        reader.ThrowIfNotEmpty();
+                        return keyReader(decrypted);
+                    }
+                    catch (AsnContentException e)
+                    {
+                        throw new CryptographicException(SR.Cryptography_Der_Invalid_Encoding, e);
+                    }
+                    finally
+                    {
+                        CryptoPool.Return(decrypted);
+                    }
+                }
+            }
+        }
+
+        internal static unsafe T DecryptPkcs8<T>(
+            ReadOnlySpan<byte> passwordBytes,
+            ReadOnlySpan<byte> source,
+            ReadOnlySpanFunc<byte, T> keyReader,
+            out int bytesRead)
+        {
+            fixed (byte* pointer = source)
+            {
+                using (PointerMemoryManager<byte> manager = new(pointer, source.Length))
+                {
+                    ArraySegment<byte> decrypted = KeyFormatHelper.DecryptPkcs8(passwordBytes, manager.Memory, out bytesRead);
+                    AsnValueReader reader = new(decrypted, AsnEncodingRules.BER);
+                    reader.ReadEncodedValue();
+
+                    try
+                    {
+                        reader.ThrowIfNotEmpty();
+                        return keyReader(decrypted);
+                    }
+                    catch (AsnContentException e)
+                    {
+                        throw new CryptographicException(SR.Cryptography_Der_Invalid_Encoding, e);
+                    }
+                    finally
+                    {
+                        CryptoPool.Return(decrypted);
+                    }
+                }
+            }
+        }
+
         private static ArraySegment<byte> DecryptPkcs8(
             ReadOnlySpan<char> inputPassword,
             ReadOnlySpan<byte> inputPasswordBytes,