Add Aes256Gcm encryption with detached tags

src/Cryptography/Aes256Gcm.cs

@@ -89,6 +89,62 @@ internal override void CreateKey(
             keyHandle = SecureMemoryHandle.CreateFrom(seed);
         }
 
+        public void EncryptDetached(
+            Key key,
+            ReadOnlySpan<byte> nonce,
+            ReadOnlySpan<byte> associatedData,
+            ReadOnlySpan<byte> plaintext,
+            Span<byte> ciphertext,
+            Span<byte> authenticationTag)
+        {
+            if (key == null)
+            {
+                throw Error.ArgumentNull_Key(nameof(key));
+            }
+            if (key.Algorithm != this)
+            {
+                throw Error.Argument_KeyAlgorithmMismatch(nameof(key), nameof(key));
+            }
+            if (nonce.Length != NonceSize)
+            {
+                throw Error.Argument_NonceLength(nameof(nonce), NonceSize);
+            }
+            if (ciphertext.Length != plaintext.Length)
+            {
+                throw new ArgumentException();
+            }
+            if (ciphertext.Overlaps(plaintext, out int offset) && offset != 0)
+            {
+                throw Error.Argument_OverlapCiphertext(nameof(ciphertext));
+            }
+            if (authenticationTag.Length != TagSize)
+            {
+                throw new ArgumentException();
+            }
+
+            SecureMemoryHandle keyHandle = key.Handle;
+
+            Debug.Assert(keyHandle.Size == crypto_aead_aes256gcm_KEYBYTES);
+            Debug.Assert(nonce.Length == crypto_aead_aes256gcm_NPUBBYTES);
+            Debug.Assert(ciphertext.Length == plaintext.Length);
+            Debug.Assert(authenticationTag.Length == crypto_aead_aes256gcm_ABYTES);
+
+            int error = crypto_aead_aes256gcm_encrypt_detached(
+                ciphertext,
+                authenticationTag,
+                out ulong maclen,
+                plaintext,
+                (ulong)plaintext.Length,
+                associatedData,
+                (ulong)associatedData.Length,
+                IntPtr.Zero,
+                nonce,
+                keyHandle);
+
+            Debug.Assert(error == 0);
+            Debug.Assert((ulong)authenticationTag.Length == maclen);
+        }
+
         private protected override void EncryptCore(
             SecureMemoryHandle keyHandle,
             ReadOnlySpan<byte> nonce,
@@ -120,6 +176,58 @@ internal override int GetSeedSize()
             return crypto_aead_aes256gcm_KEYBYTES;
         }
 
+        public bool DecryptDetached(
+            Key key,
+            ReadOnlySpan<byte> nonce,
+            ReadOnlySpan<byte> associatedData,
+            ReadOnlySpan<byte> ciphertext,
+            ReadOnlySpan<byte> authenticationTag,
+            Span<byte> plaintext)
+        {
+            if (key == null)
+            {
+                throw Error.ArgumentNull_Key(nameof(key));
+            }
+            if (key.Algorithm != this)
+            {
+                throw Error.Argument_KeyAlgorithmMismatch(nameof(key), nameof(key));
+            }
+            if (nonce.Length != NonceSize || authenticationTag.Length != TagSize)
+            {
+                return false;
+            }
+            if (plaintext.Length != ciphertext.Length)
+            {
+                throw new ArgumentException();
+            }
+            if (plaintext.Overlaps(ciphertext, out int offset) && offset != 0)
+            {
+                throw Error.Argument_OverlapPlaintext(nameof(plaintext));
+            }
+
+            SecureMemoryHandle keyHandle = key.Handle;
+
+            Debug.Assert(keyHandle.Size == crypto_aead_aes256gcm_KEYBYTES);
+            Debug.Assert(nonce.Length == crypto_aead_aes256gcm_NPUBBYTES);
+            Debug.Assert(ciphertext.Length == plaintext.Length);
+            Debug.Assert(authenticationTag.Length == crypto_aead_aes256gcm_ABYTES);
+
+            int error = crypto_aead_aes256gcm_decrypt_detached(
+                plaintext,
+                IntPtr.Zero,
+                ciphertext,
+                (ulong)ciphertext.Length,
+                authenticationTag,
+                associatedData,
+                (ulong)associatedData.Length,
+                nonce,
+                keyHandle);
+
+            // libsodium clears plaintext if decryption fails
+
+            return error == 0;
+        }
+
         private protected override bool DecryptCore(
             SecureMemoryHandle keyHandle,
             ReadOnlySpan<byte> nonce,

src/Interop/Interop.Aead.Aes256Gcm.cs

@@ -28,6 +28,19 @@ internal static partial int crypto_aead_aes256gcm_decrypt(
             ReadOnlySpan<byte> npub,
             SecureMemoryHandle k);
 
+        [LibraryImport(Libraries.Libsodium)]
+        [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+        internal static partial int crypto_aead_aes256gcm_decrypt_detached(
+            Span<byte> m,
+            IntPtr nsec,
+            ReadOnlySpan<byte> c,
+            ulong clen,
+            ReadOnlySpan<byte> mac,
+            ReadOnlySpan<byte> ad,
+            ulong adlen,
+            ReadOnlySpan<byte> npub,
+            SecureMemoryHandle k);
+
         [LibraryImport(Libraries.Libsodium)]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         internal static partial int crypto_aead_aes256gcm_encrypt(
@@ -41,6 +54,20 @@ internal static partial int crypto_aead_aes256gcm_encrypt(
             ReadOnlySpan<byte> npub,
             SecureMemoryHandle k);
 
+        [LibraryImport(Libraries.Libsodium)]
+        [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+        internal static partial int crypto_aead_aes256gcm_encrypt_detached(
+            Span<byte> c,
+            Span<byte> mac,
+            out ulong maclen_p,
+            ReadOnlySpan<byte> m,
+            ulong mlen,
+            ReadOnlySpan<byte> ad,
+            ulong adlen,
+            IntPtr nsec,
+            ReadOnlySpan<byte> npub,
+            SecureMemoryHandle k);
+
         [LibraryImport(Libraries.Libsodium)]
         [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
         internal static partial int crypto_aead_aes256gcm_is_available();

src/Interop/Interop.yaml

@@ -46,7 +46,9 @@ Interop.Aead.Aes256Gcm.cs:
   functions:
   - crypto_aead_aes256gcm_abytes
   - crypto_aead_aes256gcm_decrypt (out ulong mlen_p, IntPtr nsec, SecureMemoryHandle k)
+  - crypto_aead_aes256gcm_decrypt_detached (IntPtr nsec, SecureMemoryHandle k)
   - crypto_aead_aes256gcm_encrypt (out ulong clen_p, IntPtr nsec, SecureMemoryHandle k)
+  - crypto_aead_aes256gcm_encrypt_detached (out ulong maclen_p, IntPtr nsec, SecureMemoryHandle k)
   - crypto_aead_aes256gcm_is_available
   - crypto_aead_aes256gcm_keybytes
   - crypto_aead_aes256gcm_npubbytes

tests/Algorithms/Aes256GcmTests.cs

@@ -52,5 +52,31 @@ public static void EncryptDecrypt(int length)
         }
 
         #endregion
+
+        #region Encrypt/Decrypt Detached
+
+        [Theory]
+        [MemberData(nameof(PlaintextLengths))]
+        public static void EncryptDecryptDetached(int length)
+        {
+            var a = AeadAlgorithm.Aes256Gcm;
+
+            using var k = new Key(a);
+            var n = Utilities.RandomBytes[..a.NonceSize];
+            var ad = Utilities.RandomBytes[..100];
+            var c = new byte[length];
+            var t = new byte[a.TagSize];
+
+            var expected = Utilities.RandomBytes[..length].ToArray();
+
+            a.EncryptDetached(k, n, ad, expected, c, t);
+
+            var actual = new byte[length];
+
+            Assert.True(a.DecryptDetached(k, n, ad, c, t, actual));
+            Assert.Equal(expected, actual);
+        }
+
+        #endregion
     }
 }