ML-KEM: SubjectPublicKeyInfo import and export

Author: vcsjones

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

@@ -3,6 +3,7 @@
 
 using System;
 using System.Diagnostics.CodeAnalysis;
+using System.Formats.Asn1;
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using System.Runtime.Versioning;
@@ -111,5 +112,18 @@ internal static int HashOidToByteLength(string hashOid)
                 _ => throw new CryptographicException(SR.Format(SR.Cryptography_UnknownHashAlgorithm, hashOid)),
             };
         }
+
+        internal static CryptographicException CreateAlgorithmUnknownException(AsnWriter encodedId)
+        {
+#if NET10_0_OR_GREATER
+            return encodedId.Encode(static encoded =>
+                new CryptographicException(
+                    SR.Format(SR.Cryptography_UnknownAlgorithmIdentifier, Convert.ToHexString(encoded))));
+#else
+            return new CryptographicException(
+                SR.Format(SR.Cryptography_UnknownAlgorithmIdentifier,
+                HexConverter.ToString(encodedId.Encode(), HexConverter.Casing.Upper)));
+#endif
+        }
     }
 }

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

@@ -6,6 +6,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Formats.Asn1;
 using System.Security.Cryptography.Asn1;
+using Internal.Cryptography;
 
 // The type being internal is making unused parameter warnings fire for
 // not-implemented methods. Suppress those warnings.
@@ -832,8 +833,7 @@ public static MLDsa ImportSubjectPublicKeyInfo(ReadOnlySpan<byte> source)
                         {
                             AsnWriter writer = new AsnWriter(AsnEncodingRules.DER);
                             spki.Algorithm.Encode(writer);
-                            ThrowAlgorithmUnknown(writer);
-                            Debug.Fail("Execution should have halted in the throw-helper.");
+                            throw Helpers.CreateAlgorithmUnknownException(writer);
                         }
 
                         return MLDsaImplementation.ImportPublicKey(info, spki.SubjectPublicKey.Span);
@@ -883,8 +883,7 @@ public static MLDsa ImportPkcs8PrivateKey(ReadOnlySpan<byte> source)
                         {
                             AsnWriter writer = new AsnWriter(AsnEncodingRules.DER);
                             pki.PrivateKeyAlgorithm.Encode(writer);
-                            ThrowAlgorithmUnknown(writer);
-                            Debug.Fail("Execution should have halted in the throw-helper.");
+                            throw Helpers.CreateAlgorithmUnknownException(writer);
                         }
 
                         return MLDsaImplementation.ImportPkcs8PrivateKeyValue(info, pki.PrivateKey.Span);
@@ -1366,19 +1365,6 @@ internal static void ThrowIfNotSupported()
             }
         }
 
-        [DoesNotReturn]
-        private static void ThrowAlgorithmUnknown(AsnWriter encodedId)
-        {
-#if NET9_0_OR_GREATER
-            throw encodedId.Encode(static encoded =>
-                new CryptographicException(
-                    SR.Format(SR.Cryptography_UnknownAlgorithmIdentifier, Convert.ToHexString(encoded))));
-#else
-            throw new CryptographicException(
-                SR.Format(SR.Cryptography_UnknownAlgorithmIdentifier, Convert.ToHexString(encodedId.Encode())));
-#endif
-        }
-
         [DoesNotReturn]
         private static ParameterSetInfo ThrowAlgorithmUnknown(string algorithmId)
         {

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

@@ -2,8 +2,13 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
+using System.Buffers;
+using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
+using System.Formats.Asn1;
 using System.Runtime.CompilerServices;
+using System.Security.Cryptography.Asn1;
+using Internal.Cryptography;
 
 namespace System.Security.Cryptography
 {
@@ -74,7 +79,7 @@ protected MLKem(MLKemAlgorithm algorithm)
         /// </exception>
         /// <exception cref="PlatformNotSupportedException">
         ///   The platform does not support ML-KEM. Callers can use the <see cref="IsSupported" /> property
-        ///   to determine if the platform supports MK-KEM.
+        ///   to determine if the platform supports ML-KEM.
         /// </exception>
         public static MLKem GenerateKey(MLKemAlgorithm algorithm)
         {
@@ -462,7 +467,7 @@ public byte[] ExportPrivateSeed()
         /// </exception>
         /// <exception cref="PlatformNotSupportedException">
         ///   The platform does not support ML-KEM. Callers can use the <see cref="IsSupported" /> property
-        ///   to determine if the platform supports MK-KEM.
+        ///   to determine if the platform supports ML-KEM.
         /// </exception>
         public static MLKem ImportPrivateSeed(MLKemAlgorithm algorithm, ReadOnlySpan<byte> source)
         {
@@ -495,7 +500,7 @@ public static MLKem ImportPrivateSeed(MLKemAlgorithm algorithm, ReadOnlySpan<byt
         /// </exception>
         /// <exception cref="PlatformNotSupportedException">
         ///   The platform does not support ML-KEM. Callers can use the <see cref="IsSupported" /> property
-        ///   to determine if the platform supports MK-KEM.
+        ///   to determine if the platform supports ML-KEM.
         /// </exception>
         public static MLKem ImportPrivateSeed(MLKemAlgorithm algorithm, byte[] source)
         {
@@ -521,7 +526,7 @@ public static MLKem ImportPrivateSeed(MLKemAlgorithm algorithm, byte[] source)
         /// </exception>
         /// <exception cref="PlatformNotSupportedException">
         ///   The platform does not support ML-KEM. Callers can use the <see cref="IsSupported" /> property
-        ///   to determine if the platform supports MK-KEM.
+        ///   to determine if the platform supports ML-KEM.
         /// </exception>
         public static MLKem ImportDecapsulationKey(MLKemAlgorithm algorithm, ReadOnlySpan<byte> source)
         {
@@ -553,7 +558,7 @@ public static MLKem ImportDecapsulationKey(MLKemAlgorithm algorithm, ReadOnlySpa
         /// </exception>
         /// <exception cref="PlatformNotSupportedException">
         ///   The platform does not support ML-KEM. Callers can use the <see cref="IsSupported" /> property
-        ///   to determine if the platform supports MK-KEM.
+        ///   to determine if the platform supports ML-KEM.
         /// </exception>
         public static MLKem ImportDecapsulationKey(MLKemAlgorithm algorithm, byte[] source)
         {
@@ -578,7 +583,7 @@ public static MLKem ImportDecapsulationKey(MLKemAlgorithm algorithm, byte[] sour
         /// </exception>
         /// <exception cref="PlatformNotSupportedException">
         ///   The platform does not support ML-KEM. Callers can use the <see cref="IsSupported" /> property
-        ///   to determine if the platform supports MK-KEM.
+        ///   to determine if the platform supports ML-KEM.
         /// </exception>
         public static MLKem ImportEncapsulationKey(MLKemAlgorithm algorithm, ReadOnlySpan<byte> source)
         {
@@ -610,7 +615,7 @@ public static MLKem ImportEncapsulationKey(MLKemAlgorithm algorithm, ReadOnlySpa
         /// </exception>
         /// <exception cref="PlatformNotSupportedException">
         ///   The platform does not support ML-KEM. Callers can use the <see cref="IsSupported" /> property
-        ///   to determine if the platform supports MK-KEM.
+        ///   to determine if the platform supports ML-KEM.
         /// </exception>
         public static MLKem ImportEncapsulationKey(MLKemAlgorithm algorithm, byte[] source)
         {
@@ -727,6 +732,119 @@ public byte[] ExportEncapsulationKey()
         /// </param>
         protected abstract void ExportEncapsulationKeyCore(Span<byte> destination);
 
+        /// <summary>
+        ///   Attempts to export the public-key portion of the current key in the X.509 SubjectPublicKeyInfo format
+        ///   into the provided buffer.
+        /// </summary>
+        /// <param name="destination">
+        ///   The buffer to receive the X.509 SubjectPublicKeyInfo value.
+        /// </param>
+        /// <param name="bytesWritten">
+        ///   When this method returns, contains the number of bytes written to the <paramref name="destination"/> buffer.
+        ///   This parameter is treated as uninitialized.
+        /// </param>
+        /// <returns>
+        ///   <see langword="true" /> if <paramref name="destination"/> was large enough to hold the result;
+        ///   otherwise, <see langword="false" />.
+        /// </returns>
+        /// <exception cref="ObjectDisposedException">
+        ///   This instance has been disposed.
+        /// </exception>
+        /// <exception cref="CryptographicException">
+        ///   An error occurred while exporting the key.
+        /// </exception>
+        public bool TryExportSubjectPublicKeyInfo(Span<byte> destination, out int bytesWritten)
+        {
+            ThrowIfDisposed();
+            return ExportSubjectPublicKeyInfoCore().TryEncode(destination, out bytesWritten);
+        }
+
+        /// <summary>
+        ///  Exports the public-key portion of the current key in the X.509 SubjectPublicKeyInfo format.
+        /// </summary>
+        /// <returns>
+        ///   A byte array containing the X.509 SubjectPublicKeyInfo representation of the public-key portion of this key.
+        /// </returns>
+        /// <exception cref="ObjectDisposedException">
+        ///   This instance has been disposed.
+        /// </exception>
+        /// <exception cref="CryptographicException">
+        ///   An error occurred while exporting the key.
+        /// </exception>
+        public byte[] ExportSubjectPublicKeyInfo()
+        {
+            ThrowIfDisposed();
+            return ExportSubjectPublicKeyInfoCore().Encode();
+        }
+
+        /// <summary>
+        ///  Imports an ML-KEM encapsulation key from an X.509 SubjectPublicKeyInfo structure.
+        /// </summary>
+        /// <param name="source">
+        ///  The bytes of an X.509 SubjectPublicKeyInfo structure in the ASN.1-DER encoding.
+        /// </param>
+        /// <returns>
+        ///   The imported key.
+        /// </returns>
+        /// <exception cref="CryptographicException">
+        ///   <para>
+        ///     The contents of <paramref name="source"/> do not represent an ASN.1-DER-encoded X.509 SubjectPublicKeyInfo structure.
+        ///   </para>
+        ///   <para>-or-</para>
+        ///   <para>
+        ///     The SubjectPublicKeyInfo value does not represent an ML-KEM key.
+        ///   </para>
+        ///   <para>-or-</para>
+        ///   <para>
+        ///     The algorithm-specific import failed.
+        ///   </para>
+        /// </exception>
+        /// <exception cref="PlatformNotSupportedException">
+        ///   The platform does not support ML-KEM. Callers can use the <see cref="IsSupported" /> property
+        ///   to determine if the platform supports ML-KEM.
+        /// </exception>
+        public static MLKem ImportSubjectPublicKeyInfo(ReadOnlySpan<byte> source)
+        {
+            ThrowIfNotSupported();
+
+            unsafe
+            {
+                fixed (byte* pointer = source)
+                {
+                    using (PointerMemoryManager<byte> manager = new(pointer, source.Length))
+                    {
+                        AsnValueReader reader = new(source, AsnEncodingRules.DER);
+                        SubjectPublicKeyInfoAsn.Decode(ref reader, manager.Memory, out SubjectPublicKeyInfoAsn spki);
+                        MLKemAlgorithm algorithm = MLKemAlgorithm.FromOid(spki.Algorithm.Algorithm) ??
+                            throw new CryptographicException(
+                                SR.Format(SR.Cryptography_UnknownAlgorithmIdentifier,
+                                spki.Algorithm.Algorithm));
+
+                        // draft-ietf-lamps-kyber-certificates-07:
+                        // The parameters field of the AlgorithmIdentifier for the ML-KEM public key MUST be absent.
+                        if (spki.Algorithm.Parameters.HasValue)
+                        {
+                            AsnWriter writer = new AsnWriter(AsnEncodingRules.DER);
+                            spki.Algorithm.Encode(writer);
+                            throw Helpers.CreateAlgorithmUnknownException(writer);
+                        }
+
+                        return MLKemImplementation.ImportEncapsulationKeyImpl(algorithm, spki.SubjectPublicKey.Span);
+                    }
+                }
+            }
+        }
+
+        /// <inheritdoc cref="ImportSubjectPublicKeyInfo(ReadOnlySpan{byte})" />
+        /// <exception cref="ArgumentNullException">
+        ///   <paramref name="source" /> is <see langword="null" />
+        /// </exception>
+        public static MLKem ImportSubjectPublicKeyInfo(byte[] source)
+        {
+            ThrowIfNull(source);
+            return ImportSubjectPublicKeyInfo(new ReadOnlySpan<byte>(source));
+        }
+
         /// <summary>
         ///  Releases all resources used by the <see cref="MLKem"/> class.
         /// </summary>
@@ -752,6 +870,40 @@ protected virtual void Dispose(bool disposing)
         {
         }
 
+        private AsnWriter ExportSubjectPublicKeyInfoCore()
+        {
+            int encapsulationKeySize = Algorithm.EncapsulationKeySizeInBytes;
+            byte[] encapsulationKeyBuffer = CryptoPool.Rent(encapsulationKeySize);
+            Memory<byte> encapsulationKey = encapsulationKeyBuffer.AsMemory(0, encapsulationKeySize);
+
+            try
+            {
+                ExportEncapsulationKeyCore(encapsulationKey.Span);
+
+                SubjectPublicKeyInfoAsn spki = new SubjectPublicKeyInfoAsn
+                {
+                    Algorithm = new AlgorithmIdentifierAsn
+                    {
+                        Algorithm = Algorithm.Oid,
+                        Parameters = default(ReadOnlyMemory<byte>?),
+                    },
+                    SubjectPublicKey = encapsulationKey,
+                };
+
+                // The ASN.1 overhead of a SubjectPublicKeyInfo encoding an encapsulation key is 22 bytes.
+                // Round it off to 32. This checked operation should never throw because the inputs are not
+                // user provided.
+                int capacity = checked(32 + encapsulationKeySize);
+                AsnWriter writer = new AsnWriter(AsnEncodingRules.DER, capacity);
+                spki.Encode(writer);
+                return writer;
+            }
+            finally
+            {
+                CryptoPool.Return(encapsulationKeyBuffer, clearSize: 0); // SPKI is public info, skip clear.
+            }
+        }
+
         private protected static void ThrowIfNotSupported()
         {
             if (!IsSupported)

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

@@ -18,12 +18,14 @@ private MLKemAlgorithm(
             string name,
             int encapsulationKeySizeInBytes,
             int decapsulationKeySizeInBytes,
-            int ciphertextSizeInBytes)
+            int ciphertextSizeInBytes,
+            string oid)
         {
             Name = name;
             EncapsulationKeySizeInBytes = encapsulationKeySizeInBytes;
             DecapsulationKeySizeInBytes = decapsulationKeySizeInBytes;
             CiphertextSizeInBytes = ciphertextSizeInBytes;
+            Oid = oid;
         }
 
         // Values are from NIST FIPS-203 table 3.
@@ -34,23 +36,23 @@ private MLKemAlgorithm(
         /// <value>
         ///   An ML-KEM algorithm identifier for the ML-KEM-512 algorithm.
         /// </value>
-        public static MLKemAlgorithm MLKem512 { get; } = new("ML-KEM-512", 800, 1632, 768);
+        public static MLKemAlgorithm MLKem512 { get; } = new("ML-KEM-512", 800, 1632, 768, Oids.MlKem512);
 
         /// <summary>
         ///   Gets an ML-KEM algorithm identifier for the ML-KEM-768 algorithm.
         /// </summary>
         /// <value>
         ///   An ML-KEM algorithm identifier for the ML-KEM-768 algorithm.
         /// </value>
-        public static MLKemAlgorithm MLKem768 { get; } = new("ML-KEM-768", 1184, 2400, 1088);
+        public static MLKemAlgorithm MLKem768 { get; } = new("ML-KEM-768", 1184, 2400, 1088, Oids.MlKem768);
 
         /// <summary>
         ///   Gets an ML-KEM algorithm identifier for the ML-KEM-1024 algorithm.
         /// </summary>
         /// <value>
         ///   An ML-KEM algorithm identifier for the ML-KEM-1024 algorithm.
         /// </value>
-        public static MLKemAlgorithm MLKem1024 { get; } = new("ML-KEM-1024", 1568, 3168, 1568);
+        public static MLKemAlgorithm MLKem1024 { get; } = new("ML-KEM-1024", 1568, 3168, 1568, Oids.MlKem1024);
 
         /// <summary>
         ///   Gets the name of the algorithm.
@@ -104,6 +106,8 @@ private MLKemAlgorithm(
         // size is needed, then it can be provided as input to the private constructor.
         public int PrivateSeedSizeInBytes { get; } = 64;
 
+        internal string Oid { get; }
+
         /// <summary>
         ///   Compares two <see cref="MLKemAlgorithm" /> objects.
         /// </summary>
@@ -155,5 +159,16 @@ private MLKemAlgorithm(
         {
             return !(left == right);
         }
+
+        internal static MLKemAlgorithm? FromOid(string? oid)
+        {
+            return oid switch
+            {
+                Oids.MlKem512 => MLKem512,
+                Oids.MlKem768 => MLKem768,
+                Oids.MlKem1024 => MLKem1024,
+                _ => null,
+            };
+        }
     }
 }

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

@@ -243,5 +243,13 @@ internal static partial class Oids
 
         // LDAP
         internal const string DomainComponent = "0.9.2342.19200300.100.1.25";
+
+        // ML-KEM
+        // id-alg-ml-kem-512
+        internal const string MlKem512 = "2.16.840.1.101.3.4.4.1";
+        // id-alg-ml-kem-768
+        internal const string MlKem768 = "2.16.840.1.101.3.4.4.2";
+        // id-alg-ml-kem-1024
+        internal const string MlKem1024 = "2.16.840.1.101.3.4.4.3";
     }
 }