[API Proposal]: MLKemCng and CNG identifiers

[vcsjones]

Background and motivation

As part of #113508, we will have an MLKemCng type, which is a Windows CNG type that allows MLKem to work with a CngKey.

We should also add the necessary CNG identifiers for algorithms, blob types, and algorithm groups, like we have for other algorithms.

API Proposal

namespace System.Security.Cryptography
{
    // New class in both Microsoft.Bcl.Cryptography and System.Security.Cryptography
    // No .NET Standard availability in M.B.C. Only netcoreapp and netfx.
+   [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
+   public sealed class MLKemCng : MLKem
+   {
+       [SupportedOSPlatformAttribute("windows")]
+       public MLKemCng(CngKey key);
+       public CngKey Key { get; }
+   }

    // New properties on existing type; System.Security.Cryptography only
    public sealed partial class CngAlgorithm
    {
+       [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
+       public static CngAlgorithm MLKem { get; }
    }

    // New properties on existing type; System.Security.Cryptography only
    public sealed partial class CngAlgorithmGroup
    {
+       [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
+       public static CngAlgorithmGroup MLKem { get; }
    }

    // New properties on existing type; System.Security.Cryptography only
    public sealed partial class CngKeyBlobFormat
    {
+       [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
+       public static CngKeyBlobFormat MLKemPrivateBlob { get; }

+       [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
+       public static CngKeyBlobFormat MLKemPrivateSeedBlob { get; }

+       [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
+       public static CngKeyBlobFormat MLKemPublicBlob { get; }
    }
}

API Usage

using CngKey myMLKemCngKey = CngKey.Open("uwu-ml-kem");

if (myMLKemCngKey.Algorithm != CngAlgorithm.MLKem || myMLKemCngKey.AlgorithmGroup != CngAlgorithmGroup.MLKem)
{
    throw new CryptographicException();
}

using MLKemCng kem = new MLKemCng(myMLKemCngKey);
kem.Encapsulate(out byte[] ciphertext, out byte[] sharedSecret);

Alternative Designs

As proposed, the Key property returns the interior CngKey instance that the algorithm instance is working on. It does not return a duplicate. This is consistent with what RSACng and ECDsaCng do.

We should consider if instead this should be a GetCngKey() method (not property) that returns a duplicated handle so the instance of the CngKey has an independent lifetime from the one that MLKemCng is using.

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-security, @bartonjs, @vcsjones
See info in area-owners.md if you want to be subscribed.

[bartonjs]

Video

• Based on the fact that kem.Key.Dispose() causes kem to behave as disposed, we moved the property to a method that creates distinct instances.

namespace System.Security.Cryptography
{
    // New class in both Microsoft.Bcl.Cryptography and System.Security.Cryptography
    // No .NET Standard availability in M.B.C. Only netcoreapp and netfx.
    [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
    public sealed class MLKemCng : MLKem
    {
        [SupportedOSPlatformAttribute("windows")]
        public MLKemCng(CngKey key);
        
        public CngKey GetKey();
    }

    // New properties on existing type; System.Security.Cryptography only
    public sealed partial class CngAlgorithm
    {
        [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
        public static CngAlgorithm MLKem { get; }
    }

    // New properties on existing type; System.Security.Cryptography only
    public sealed partial class CngAlgorithmGroup
    {
        [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
        public static CngAlgorithmGroup MLKem { get; }
    }

    // New properties on existing type; System.Security.Cryptography only
    public sealed partial class CngKeyBlobFormat
    {
        [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
        public static CngKeyBlobFormat MLKemPrivateBlob { get; }

        [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
        public static CngKeyBlobFormat MLKemPrivateSeedBlob { get; }

        [ExperimentalAttribute("SYSLIB5006", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
        public static CngKeyBlobFormat MLKemPublicBlob { get; }
    }
}