feat(secrets): AES-256-GCM envelope cipher with AAD binding

2026-07-15 16:34:46 -04:00
parent 16b32257f5
commit b784c7117f
4 changed files with 321 additions and 1 deletions
@@ -0,0 +1,109 @@
+using System.Text;
+using ZB.MOM.WW.Secrets.Abstractions;
+using ZB.MOM.WW.Secrets.Crypto;
+using ZB.MOM.WW.Secrets.Tests.Fakes;
+
+namespace ZB.MOM.WW.Secrets.Tests.Crypto;
+
+public class AesGcmEnvelopeCipherTests
+{
+    [Fact]
+    public void RoundTrips()
+    {
+        var provider = new FakeMasterKeyProvider("k1");
+        var cipher = new AesGcmEnvelopeCipher(provider);
+        var name = new SecretName("sql/foo");
+
+        StoredSecret row = cipher.Encrypt(name, "hunter2", SecretContentType.Text);
+
+        Assert.Equal("k1", row.KekId);
+        // Ciphertext must not leak the plaintext in the clear.
+        byte[] plaintextBytes = Encoding.UTF8.GetBytes("hunter2");
+        Assert.False(Contains(row.Ciphertext, plaintextBytes));
+
+        string decrypted = cipher.Decrypt(row);
+        Assert.Equal("hunter2", decrypted);
+    }
+
+    [Fact]
+    public void TamperedCiphertextThrows()
+    {
+        var provider = new FakeMasterKeyProvider("k1");
+        var cipher = new AesGcmEnvelopeCipher(provider);
+        var name = new SecretName("sql/foo");
+
+        StoredSecret row = cipher.Encrypt(name, "hunter2", SecretContentType.Text);
+        row.Ciphertext[0] ^= 0xFF;
+
+        Assert.Throws<SecretDecryptionException>(() => cipher.Decrypt(row));
+    }
+
+    [Fact]
+    public void AadBindingRejectsRenamedRow()
+    {
+        var provider = new FakeMasterKeyProvider("k1");
+        var cipher = new AesGcmEnvelopeCipher(provider);
+
+        StoredSecret row = cipher.Encrypt(new SecretName("sql/foo"), "hunter2", SecretContentType.Text);
+        var renamed = row with { Name = new SecretName("sql/bar") };
+
+        Assert.Throws<SecretDecryptionException>(() => cipher.Decrypt(renamed));
+    }
+
+    [Fact]
+    public void WrongKekThrows()
+    {
+        // Both providers report KekId "k1" but hold different random key bytes.
+        var providerA = new FakeMasterKeyProvider("k1");
+        var providerB = new FakeMasterKeyProvider("k1");
+        var cipherA = new AesGcmEnvelopeCipher(providerA);
+        var cipherB = new AesGcmEnvelopeCipher(providerB);
+
+        StoredSecret row = cipherA.Encrypt(new SecretName("sql/foo"), "hunter2", SecretContentType.Text);
+
+        // Matching KekId string but wrong key material must still fail closed (unwrap tag mismatch).
+        Assert.Throws<SecretDecryptionException>(() => cipherB.Decrypt(row));
+    }
+
+    [Fact]
+    public void UnknownKekIdThrows()
+    {
+        var providerK1 = new FakeMasterKeyProvider("k1");
+        var providerK2 = new FakeMasterKeyProvider("k2");
+        var cipherK1 = new AesGcmEnvelopeCipher(providerK1);
+        var cipherK2 = new AesGcmEnvelopeCipher(providerK2);
+
+        StoredSecret row = cipherK1.Encrypt(new SecretName("sql/foo"), "hunter2", SecretContentType.Text);
+
+        var ex = Assert.Throws<SecretDecryptionException>(() => cipherK2.Decrypt(row));
+        Assert.Contains("unknown KEK", ex.Message, StringComparison.Ordinal);
+    }
+
+    private static bool Contains(byte[] haystack, byte[] needle)
+    {
+        if (needle.Length == 0 || haystack.Length < needle.Length)
+        {
+            return false;
+        }
+
+        for (int i = 0; i <= haystack.Length - needle.Length; i++)
+        {
+            bool match = true;
+            for (int j = 0; j < needle.Length; j++)
+            {
+                if (haystack[i + j] != needle[j])
+                {
+                    match = false;
+                    break;
+                }
+            }
+
+            if (match)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}
@@ -0,0 +1,45 @@
+using System.Security.Cryptography;
+using ZB.MOM.WW.Secrets.Abstractions;
+
+namespace ZB.MOM.WW.Secrets.Tests.Fakes;
+
+/// <summary>
+/// A hand-written <see cref="IMasterKeyProvider"/> test double (the family does not use Moq).
+/// Generates a random 32-byte master key once at construction and returns it stably, alongside
+/// a caller-supplied <see cref="KekId"/>. Two instances with the same <see cref="KekId"/> string
+/// still hold different key bytes, which lets a test prove that a matching KEK id but wrong key
+/// material fails closed.
+/// </summary>
+public sealed class FakeMasterKeyProvider : IMasterKeyProvider
+{
+    private readonly byte[] _key;
+
+    /// <summary>
+    /// Creates a provider with a freshly generated random 32-byte master key and the given
+    /// <paramref name="kekId"/>.
+    /// </summary>
+    /// <param name="kekId">The stable, non-secret key identifier this provider reports.</param>
+    public FakeMasterKeyProvider(string kekId = "k1")
+    {
+        KekId = kekId;
+        _key = RandomNumberGenerator.GetBytes(32);
+    }
+
+    /// <summary>
+    /// Creates a provider that reuses an explicit 32-byte key. Use this to build a second
+    /// provider with the same key bytes as another (or, by omitting it, a different random key).
+    /// </summary>
+    /// <param name="kekId">The stable, non-secret key identifier this provider reports.</param>
+    /// <param name="key">The exact 32-byte master key material to use.</param>
+    public FakeMasterKeyProvider(string kekId, byte[] key)
+    {
+        KekId = kekId;
+        _key = (byte[])key.Clone();
+    }
+
+    /// <inheritdoc />
+    public string KekId { get; }
+
+    /// <inheritdoc />
+    public ReadOnlyMemory<byte> GetMasterKey() => _key;
+}