Checkpoint HPKE Seal and managed AEAD adapters

Add public Seal scaffolding, KDF info-length validation, an AES-GCM adapter, and unsupported-platform dispatch. This is an intentionally incomplete, non-building checkpoint; SealCore remains unimplemented.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 438fb068-aa8f-4969-9e8c-7065b52b74b5

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

@@ -285,6 +285,83 @@ public void ExportEncapsulationKey(Span<byte> destination)
         /// </remarks>
         protected abstract void ExportEncapsulationKeyCore(Span<byte> destination);
 
+        public void Seal(
+            ReadOnlySpan<byte> plaintext,
+            out byte[] encapsulatedSecret,
+            out byte[] ciphertext,
+            ReadOnlySpan<byte> associatedData = default,
+            ReadOnlySpan<byte> info = default)
+        {
+            ThrowIfInfoExceedsLimit(info);
+            ThrowIfDisposed();
+
+            byte[] ciphertextBuffer = new byte[Suite.GetCiphertextLength(plaintext.Length)];
+            byte[] encapsulatedSecretBuffer = new byte[Suite.EncapsulatedSecretSizeInBytes];
+
+            SealCore(plaintext, encapsulatedSecretBuffer, ciphertextBuffer, associatedData, info);
+
+            encapsulatedSecret = encapsulatedSecretBuffer;
+            ciphertext = ciphertextBuffer;
+        }
+
+        public void Seal(
+            byte[] plaintext,
+            out byte[] encapsulatedSecret,
+            out byte[] ciphertext,
+            byte[]? associatedData = null,
+            byte[]? info = null)
+        {
+            ArgumentNullException.ThrowIfNull(plaintext);
+            ThrowIfInfoExceedsLimit(info);
+            ThrowIfDisposed();
+
+            byte[] ciphertextBuffer = new byte[Suite.GetCiphertextLength(plaintext.Length)];
+            byte[] encapsulatedSecretBuffer = new byte[Suite.EncapsulatedSecretSizeInBytes];
+
+            // associatedData and info null's implicity convert to empty span.
+            SealCore(plaintext, encapsulatedSecretBuffer, ciphertextBuffer, associatedData, info);
+
+            encapsulatedSecret = encapsulatedSecretBuffer;
+            ciphertext = ciphertextBuffer;
+        }
+
+        public void Seal(
+            ReadOnlySpan<byte> plaintext,
+            Span<byte> encapsulatedSecret,
+            Span<byte> ciphertext,
+            ReadOnlySpan<byte> associatedData = default,
+            ReadOnlySpan<byte> info = default)
+        {
+            ThrowIfInfoExceedsLimit(info);
+            ThrowIfDisposed();
+
+            if (encapsulatedSecret.Length != Suite.EncapsulatedSecretSizeInBytes)
+            {
+                throw new ArgumentException(
+                    SR.Format(SR.Argument_DestinationImprecise, Suite.EncapsulatedSecretSizeInBytes),
+                    nameof(encapsulatedSecret));
+            }
+
+            int expectedCiphertextLength = Suite.GetCiphertextLength(plaintext.Length);
+
+            if (ciphertext.Length != expectedCiphertextLength)
+            {
+                throw new ArgumentException(
+                    SR.Format(SR.Argument_DestinationImprecise, expectedCiphertextLength),
+                    nameof(ciphertext));
+            }
+
+            SealCore(plaintext, encapsulatedSecret, ciphertext, associatedData, info);
+        }
+
+        protected abstract void SealCore(
+            ReadOnlySpan<byte> plaintext,
+            Span<byte> encapsulatedSecret,
+            Span<byte> ciphertext,
+            ReadOnlySpan<byte> associatedData,
+            ReadOnlySpan<byte> info);
+
+
         /// <summary>
         ///   Releases all resources used by the <see cref="Hpke" /> class.
         /// </summary>
@@ -318,6 +395,16 @@ private static void ThrowIfNotSupported(HpkeSuite suite)
             }
         }
 
+        private void ThrowIfInfoExceedsLimit(ReadOnlySpan<byte> info)
+        {
+            if (info.Length > Suite.KdfMetadata.MaximumInfoLength)
+            {
+                throw new ArgumentException(
+                    SR.Format(SR.Argument_HpkeKdfInfoLength, Suite.KdfMetadata.MaximumInfoLength),
+                    nameof(info));
+            }
+        }
+
         private void ThrowIfDisposed() => ObjectDisposedException.ThrowIf(_disposed, this);
     }
 }

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

@@ -9,28 +9,43 @@ internal sealed partial class HpkeKdfMetadata
         internal int Nh { get; }
         internal bool IsTwoStage { get; }
         internal string Name { get; }
+        internal int? MaximumInfoLength { get; }
 
         private HpkeKdfMetadata(HpkeKdf kdf, int nh, bool isTwoStage, string name)
         {
             Kdf = kdf;
             Nh = nh;
             IsTwoStage = isTwoStage;
             Name = name;
+
+            if (!IsTwoStage)
+            {
+                // One stage (SHAKE) uses a 16-bit integer to encode the info length. Practically that means the info is limited
+                // to 65,535. See CombineSecrets_OneStage. info is described as lengthPrefixed(info).
+                // > lengthPrefixed(x): The two-byte length of the byte string x, concatenated with x itself.
+                // > (lengthPrefixed(x) = concat(I2OSP(len(x), 2), x)) It is an error to call this function with an x
+                // > value that is more than 65535 bytes long.
+                // https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5
+                // We'll track that is the KDF having a maximum info length.
+                // Other KDFs have a maximum input length however they far exceed 32-bit integers which is limited by a
+                // Span's input limit.
+                MaximumInfoLength = ushort.MaxValue;
+            }
         }
 
         internal static HpkeKdfMetadata? Create(HpkeKdf kdf)
         {
             switch (kdf)
             {
+                // HKDF SHAs have limits on their info size, 2^61 - 91 and 2^125 - 155. Since this is well above
+                // A Span's possible length we'll treat it as unlimited.
                 // https://datatracker.ietf.org/doc/html/draft-ietf-hpke-hpke-04#section-7.2
                 case HpkeKdf.HKDF_SHA256:
                     return new HpkeKdfMetadata(kdf, nh: 32, isTwoStage: true, name: "HKDF-SHA256");
                 case HpkeKdf.HKDF_SHA384:
                     return new HpkeKdfMetadata(kdf, nh: 48, isTwoStage: true, name: "HKDF-SHA384");
                 case HpkeKdf.HKDF_SHA512:
                     return new HpkeKdfMetadata(kdf, nh: 64, isTwoStage: true, name: "HKDF-SHA512");
-
-                // https://datatracker.ietf.org/doc/html/draft-ietf-hpke-pq-05#section-5
                 case HpkeKdf.SHAKE128:
                     return new HpkeKdfMetadata(kdf, nh: 32, isTwoStage: false, name: "SHAKE128");
                 case HpkeKdf.SHAKE256:

src/libraries/System.Security.Cryptography/src/Resources/Strings.resx

@@ -147,6 +147,9 @@
   <data name="Argument_KemInvalidSeedLength" xml:space="preserve">
     <value>The specified private seed is not the correct length for the ML-KEM algorithm.</value>
   </data>
+  <data name="Argument_HpkeKdfInfoLength" xml:space="preserve">
+    <value>The specified info exceeds the maximum length of {0} bytes.</value>
+  </data>
   <data name="Argument_MLDsaMuInvalidLength" xml:space="preserve">
     <value>The specified mu value is not the correct length for the ML-DSA algorithm.</value>
   </data>

src/libraries/System.Security.Cryptography/src/System.Security.Cryptography.csproj

@@ -634,7 +634,6 @@
     <Compile Include="System\Security\Cryptography\HMACStatic.cs" />
     <Compile Include="System\Security\Cryptography\HpkeAeadMetadata.Managed.cs" />
     <Compile Include="System\Security\Cryptography\HpkeECDiffieHellmanKemAdapter.cs" />
-    <Compile Include="System\Security\Cryptography\HpkeImplementation.Managed.cs" />
     <Compile Include="System\Security\Cryptography\HpkeKdfMetadata.Managed.cs" />
     <Compile Include="System\Security\Cryptography\HpkeKemMetadata.Managed.cs" />
     <Compile Include="System\Security\Cryptography\HpkeManagedKemAdapter.cs" />
@@ -899,6 +898,7 @@
     <Compile Include="System\Security\Cryptography\HashProviderDispenser.Browser.cs" />
     <Compile Include="System\Security\Cryptography\HKDF.Managed.cs" />
     <Compile Include="System\Security\Cryptography\HMACHashProvider.Browser.Managed.cs" />
+    <Compile Include="System\Security\Cryptography\HpkeImplementation.Unsupported.cs" />
     <Compile Include="System\Security\Cryptography\LiteHash.Browser.cs" />
     <Compile Include="System\Security\Cryptography\LiteHash.Kmac.Unsupported.cs" />
     <Compile Include="System\Security\Cryptography\MLDsaOpenSsl.NotSupported.cs" />
@@ -2114,6 +2114,10 @@
     <Compile Include="System\Security\Cryptography\X509Certificates\X509Pal.Windows.X500DistinguishedName.cs" />
   </ItemGroup>
 
+  <ItemGroup Condition="'$(GeneratePlatformNotSupportedAssemblyMessage)' == '' and '$(TargetPlatformIdentifier)' != 'browser'">
+    <Compile Include="System\Security\Cryptography\HpkeImplementation.Managed.cs" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="$(LibrariesProjectRoot)System.Collections\src\System.Collections.csproj" />
     <ProjectReference Include="$(LibrariesProjectRoot)System.Collections.Concurrent\src\System.Collections.Concurrent.csproj" />

src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/HpkeImplementation.Managed.cs

@@ -1,15 +1,88 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Diagnostics;
+
+#pragma warning disable CA1416 // //TODO:HPKE Call is reachable on "unsupported platform" - deal with this messy daignostic later.
+
 namespace System.Security.Cryptography
 {
+    internal abstract class HpkeManagedAeadAdapter : IDisposable
+    {
+        internal static HpkeManagedAeadAdapter Create(HpkeSuite suite, ReadOnlySpan<byte> key)
+        {
+            Debug.Assert(suite.AeadMetadata.Nt == 16);
+
+            switch (suite.AeadAlgorithm)
+            {
+                case HpkeAead.AES_128_GCM:
+                case HpkeAead.AES_256_GCM:
+                    return new HpkeManagedAesAeadAdapter(suite, key);
+                case HpkeAead.ChaCha20Poly1305:
+                    throw new NotImplementedException();
+                default:
+                    Debug.Fail($"Unmapped AEAD adapter algorithm {suite.AeadAlgorithm}.");
+                    throw new CryptographicException();
+            }
+        }
+
+        internal abstract void Encrypt(
+            ReadOnlySpan<byte> plaintext,
+            ReadOnlySpan<byte> nonce,
+            ReadOnlySpan<byte> associatedData,
+            Span<byte> ciphertext,
+            Span<byte> tag);
+
+        internal abstract void Decrypt(
+            ReadOnlySpan<byte> ciphertext,
+            ReadOnlySpan<byte> nonce,
+            ReadOnlySpan<byte> associatedData,
+            ReadOnlySpan<byte> tag,
+            Span<byte> plaintext);
+
+        public abstract void Dispose();
+    }
+
+    internal sealed class HpkeManagedAesAeadAdapter : HpkeManagedAeadAdapter
+    {
+        private readonly AesGcm _aes;
+
+        internal HpkeManagedAesAeadAdapter(HpkeSuite suite, ReadOnlySpan<byte> key)
+        {
+            _aes = new AesGcm(key, suite.AeadMetadata.Nt);
+        }
+
+        internal override void Encrypt(
+            ReadOnlySpan<byte> plaintext,
+            ReadOnlySpan<byte> nonce,
+            ReadOnlySpan<byte> associatedData,
+            Span<byte> ciphertext,
+            Span<byte> tag)
+        {
+            _aes.Encrypt(nonce, plaintext, ciphertext, tag, associatedData);
+        }
+
+        internal override void Decrypt(
+            ReadOnlySpan<byte> ciphertext,
+            ReadOnlySpan<byte> nonce,
+            ReadOnlySpan<byte> associatedData,
+            ReadOnlySpan<byte> tag,
+            Span<byte> plaintext)
+        {
+            _aes.Decrypt(nonce, ciphertext, tag, plaintext, associatedData);
+        }
+
+
+        public override void Dispose() => _aes.Dispose();
+    }
+
     internal sealed class HpkeImplementation : Hpke
     {
-        private readonly HpkeManagedKemAdapter _adapter;
+        private readonly HpkeManagedKemAdapter _kemAdapter;
 
-        private HpkeImplementation(HpkeManagedKemAdapter adapter) : base(adapter.Suite)
+        private HpkeImplementation(HpkeSuite suite, HpkeManagedKemAdapter kemAdapter) : base(suite)
         {
-            _adapter = adapter;
+            _kemAdapter = kemAdapter;
         }
 
         internal static bool IsSupportedImpl(HpkeSuite suite) =>
@@ -24,7 +97,7 @@ internal static HpkeImplementation DeriveKeyImpl(HpkeSuite suite, ReadOnlySpan<b
             try
             {
                 adapter.DeriveKeyPair(ikm);
-                return new HpkeImplementation(adapter);
+                return new HpkeImplementation(suite, adapter);
             }
             catch
             {
@@ -40,7 +113,7 @@ internal static HpkeImplementation GenerateKeyImpl(HpkeSuite suite)
             try
             {
                 adapter.Generate();
-                return new HpkeImplementation(adapter);
+                return new HpkeImplementation(suite, adapter);
             }
             catch
             {
@@ -50,16 +123,26 @@ internal static HpkeImplementation GenerateKeyImpl(HpkeSuite suite)
         }
 
         protected override void ExportDecapsulationKeyCore(Span<byte> destination) =>
-            _adapter.ExportDecapsulationKey(destination);
+            _kemAdapter.ExportDecapsulationKey(destination);
 
         protected override void ExportEncapsulationKeyCore(Span<byte> destination) =>
-            _adapter.ExportEncapsulationKey(destination);
+            _kemAdapter.ExportEncapsulationKey(destination);
+
+        protected override void SealCore(
+            ReadOnlySpan<byte> plaintext,
+            Span<byte> encapsulatedSecret,
+            Span<byte> ciphertext,
+            ReadOnlySpan<byte> associatedData,
+            ReadOnlySpan<byte> info)
+        {
+            throw new NotImplementedException();
+        }
 
         protected override void Dispose(bool disposing)
         {
             if (disposing)
             {
-                _adapter.Dispose();
+                _kemAdapter.Dispose();
             }
 
             base.Dispose(disposing);

src/libraries/System.Security.Cryptography/src/System/Security/Cryptography/HpkeImplementation.Unsupported.cs

@@ -0,0 +1,71 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Diagnostics;
+
+namespace System.Security.Cryptography
+{
+    internal sealed class HpkeImplementation : Hpke
+    {
+        internal HpkeImplementation(HpkeSuite suite) : base(suite)
+        {
+        }
+
+        internal static bool IsSupportedImpl(HpkeSuite suite)
+        {
+            _ = suite;
+            return false;
+        }
+
+        internal static HpkeImplementation DeriveKeyImpl(HpkeSuite suite, ReadOnlySpan<byte> ikm)
+        {
+            _ = suite;
+            _ = ikm;
+            Debug.Fail("Platform validation should not permit this call.");
+            throw new CryptographicException();
+        }
+
+        internal static HpkeImplementation GenerateKeyImpl(HpkeSuite suite)
+        {
+            _ = suite;
+            Debug.Fail("Platform validation should not permit this call.");
+            throw new CryptographicException();
+        }
+
+        protected override void ExportDecapsulationKeyCore(Span<byte> destination)
+        {
+            _ = destination;
+            Debug.Fail("Platform validation should not permit this call.");
+            throw new CryptographicException();
+        }
+
+        protected override void ExportEncapsulationKeyCore(Span<byte> destination)
+        {
+            _ = destination;
+            Debug.Fail("Platform validation should not permit this call.");
+            throw new CryptographicException();
+        }
+
+        protected override void SealCore(
+            ReadOnlySpan<byte> plaintext,
+            Span<byte> encapsulatedSecret,
+            Span<byte> ciphertext,
+            ReadOnlySpan<byte> associatedData,
+            ReadOnlySpan<byte> info)
+        {
+            _ = plaintext;
+            _ = encapsulatedSecret;
+            _ = ciphertext;
+            _ = associatedData;
+            _ = info;
+            Debug.Fail("Platform validation should not permit this call.");
+            throw new CryptographicException();
+        }
+
+        protected override void Dispose(bool disposing)
+        {
+            Debug.Fail("Platform validation should not permit this call.");
+            throw new CryptographicException();
+        }
+    }
+}