Add support for AEAD AES 128/256 GCM Ciphers (.NET 6.0 onward only) (#1369)

* Init AeadCipher

* Move AeadCipher to parent folder. Move EncryptBlock/DecryptBlock from SymmetricCipher to BlockCipher

* simplify parameter name

* Implement AesGcmCipher

* Update README

* Remove protected IV from AeadCipher; Set offset to outbound sequence just like other ciphers

* Rename associatedData to packetLengthField

* Use Span<byte> to avoid unnecessary allocations

* Use `Span` to improve performance when `IncrementCounter()`

* Add `IsAead` property to `CipherInfo`. Include packet length field and tag field in offset and length when call AesGcm's `Decrypt(...)` method. Do not determine HMAC if cipher is AesGcm during kex.

* Fix build

* Fix UT

* Check `AesGcm.IsSupported` before add to the `Encryptions` collection.
Guard AES-GCM with `NET6_0_OR_GREATER`.
Insert AES-GCM ciphers right after AES-CTR ciphers but before AES-CBC ciphers, which is similar with OpenSSH:
```
debug2: ciphers ctos: [email protected],aes128-ctr,aes192-ctr,aes256-ctr,[email protected],[email protected]
debug2: ciphers stoc: [email protected],aes128-ctr,aes192-ctr,aes256-ctr,[email protected],[email protected]
```
Although Dictionary's order is not defined, from observation, it is in the same order with add. Anyway that would be another topic.

* Suppress CA1859 "Use concrete types when possible for improved performance" for `ConnectionInfo.Encryptions`.
Test `Aes128Gcm` and `Aes256Gcm` only when `NET6_0_OR_GREATER`

* Update xml doc comments. Do not treat AesGcmCipher separately in Session.cs

* Fix build

* Fix build

* Update the comment as ChaCha20Poly1305 uses a separated key to encypt the packet length and the size it 4.

* Update src/Renci.SshNet/Security/Cryptography/Cipher.cs

Co-authored-by: Rob Hague <[email protected]>

* Make `AesGcmCipher` internal.
Assert offset when decrypt.

* Fix nullable error in build

* typos

---------

Co-authored-by: Rob Hague <[email protected]>

Author: scott-xu

README.md

@@ -50,6 +50,8 @@ the missing test once you figure things out.  🤓
 * aes128-cbc
 * aes192-cbc
 * aes256-cbc
+* aes128-gcm<span></span>@openssh.com (.NET 6 and higher)
+* aes256-gcm<span></span>@openssh.com (.NET 6 and higher)
 * blowfish-cbc
 * twofish-cbc
 * twofish192-cbc

src/Renci.SshNet/CipherInfo.cs

@@ -17,6 +17,14 @@ public class CipherInfo
         /// </value>
         public int KeySize { get; private set; }
 
+        /// <summary>
+        /// Gets a value indicating whether the cipher is AEAD (Authenticated Encryption with Associated data).
+        /// </summary>
+        /// <value>
+        /// <see langword="true"/> to indicate the cipher is AEAD, <see langword="false"/> to indicate the cipher is not AEAD.
+        /// </value>
+        public bool IsAead { get; private set; }
+
         /// <summary>
         /// Gets the cipher.
         /// </summary>
@@ -27,10 +35,12 @@ public class CipherInfo
         /// </summary>
         /// <param name="keySize">Size of the key.</param>
         /// <param name="cipher">The cipher.</param>
-        public CipherInfo(int keySize, Func<byte[], byte[], Cipher> cipher)
+        /// <param name="isAead"><see langword="true"/> to indicate the cipher is AEAD, <see langword="false"/> to indicate the cipher is not AEAD.</param>
+        public CipherInfo(int keySize, Func<byte[], byte[], Cipher> cipher, bool isAead = false)
         {
             KeySize = keySize;
             Cipher = (key, iv) => cipher(key.Take(KeySize / 8), iv);
+            IsAead = isAead;
         }
     }
 }

src/Renci.SshNet/ConnectionInfo.cs

@@ -55,7 +55,9 @@ public class ConnectionInfo : IConnectionInfoInternal
         /// <summary>
         /// Gets supported encryptions for this connection.
         /// </summary>
+#pragma warning disable CA1859 // Use concrete types when possible for improved performance
         public IDictionary<string, CipherInfo> Encryptions { get; private set; }
+#pragma warning restore CA1859 // Use concrete types when possible for improved performance
 
         /// <summary>
         /// Gets supported hash algorithms for this connection.
@@ -380,25 +382,30 @@ public ConnectionInfo(string host, int port, string username, ProxyTypes proxyTy
                     { "diffie-hellman-group1-sha1", () => new KeyExchangeDiffieHellmanGroup1Sha1() },
                 };
 
-            Encryptions = new Dictionary<string, CipherInfo>
-                {
-                    { "aes128-ctr", new CipherInfo(128, (key, iv) => new AesCipher(key, iv, AesCipherMode.CTR, pkcs7Padding: false)) },
-                    { "aes192-ctr", new CipherInfo(192, (key, iv) => new AesCipher(key, iv, AesCipherMode.CTR, pkcs7Padding: false)) },
-                    { "aes256-ctr", new CipherInfo(256, (key, iv) => new AesCipher(key, iv, AesCipherMode.CTR, pkcs7Padding: false)) },
-                    { "aes128-cbc", new CipherInfo(128, (key, iv) => new AesCipher(key, iv, AesCipherMode.CBC, pkcs7Padding: false)) },
-                    { "aes192-cbc", new CipherInfo(192, (key, iv) => new AesCipher(key, iv, AesCipherMode.CBC, pkcs7Padding: false)) },
-                    { "aes256-cbc", new CipherInfo(256, (key, iv) => new AesCipher(key, iv, AesCipherMode.CBC, pkcs7Padding: false)) },
-                    { "3des-cbc", new CipherInfo(192, (key, iv) => new TripleDesCipher(key, new CbcCipherMode(iv), padding: null)) },
-                    { "blowfish-cbc", new CipherInfo(128, (key, iv) => new BlowfishCipher(key, new CbcCipherMode(iv), padding: null)) },
-                    { "twofish-cbc", new CipherInfo(256, (key, iv) => new TwofishCipher(key, new CbcCipherMode(iv), padding: null)) },
-                    { "twofish192-cbc", new CipherInfo(192, (key, iv) => new TwofishCipher(key, new CbcCipherMode(iv), padding: null)) },
-                    { "twofish128-cbc", new CipherInfo(128, (key, iv) => new TwofishCipher(key, new CbcCipherMode(iv), padding: null)) },
-                    { "twofish256-cbc", new CipherInfo(256, (key, iv) => new TwofishCipher(key, new CbcCipherMode(iv), padding: null)) },
-                    { "arcfour", new CipherInfo(128, (key, iv) => new Arc4Cipher(key, dischargeFirstBytes: false)) },
-                    { "arcfour128", new CipherInfo(128, (key, iv) => new Arc4Cipher(key, dischargeFirstBytes: true)) },
-                    { "arcfour256", new CipherInfo(256, (key, iv) => new Arc4Cipher(key, dischargeFirstBytes: true)) },
-                    { "cast128-cbc", new CipherInfo(128, (key, iv) => new CastCipher(key, new CbcCipherMode(iv), padding: null)) },
-                };
+            Encryptions = new Dictionary<string, CipherInfo>();
+            Encryptions.Add("aes128-ctr", new CipherInfo(128, (key, iv) => new AesCipher(key, iv, AesCipherMode.CTR, pkcs7Padding: false)));
+            Encryptions.Add("aes192-ctr", new CipherInfo(192, (key, iv) => new AesCipher(key, iv, AesCipherMode.CTR, pkcs7Padding: false)));
+            Encryptions.Add("aes256-ctr", new CipherInfo(256, (key, iv) => new AesCipher(key, iv, AesCipherMode.CTR, pkcs7Padding: false)));
+#if NET6_0_OR_GREATER
+            if (AesGcm.IsSupported)
+            {
+                Encryptions.Add("[email protected]", new CipherInfo(128, (key, iv) => new AesGcmCipher(key, iv), isAead: true));
+                Encryptions.Add("[email protected]", new CipherInfo(256, (key, iv) => new AesGcmCipher(key, iv), isAead: true));
+            }
+#endif
+            Encryptions.Add("aes128-cbc", new CipherInfo(128, (key, iv) => new AesCipher(key, iv, AesCipherMode.CBC, pkcs7Padding: false)));
+            Encryptions.Add("aes192-cbc", new CipherInfo(192, (key, iv) => new AesCipher(key, iv, AesCipherMode.CBC, pkcs7Padding: false)));
+            Encryptions.Add("aes256-cbc", new CipherInfo(256, (key, iv) => new AesCipher(key, iv, AesCipherMode.CBC, pkcs7Padding: false)));
+            Encryptions.Add("3des-cbc", new CipherInfo(192, (key, iv) => new TripleDesCipher(key, new CbcCipherMode(iv), padding: null)));
+            Encryptions.Add("blowfish-cbc", new CipherInfo(128, (key, iv) => new BlowfishCipher(key, new CbcCipherMode(iv), padding: null)));
+            Encryptions.Add("twofish-cbc", new CipherInfo(256, (key, iv) => new TwofishCipher(key, new CbcCipherMode(iv), padding: null)));
+            Encryptions.Add("twofish192-cbc", new CipherInfo(192, (key, iv) => new TwofishCipher(key, new CbcCipherMode(iv), padding: null)));
+            Encryptions.Add("twofish128-cbc", new CipherInfo(128, (key, iv) => new TwofishCipher(key, new CbcCipherMode(iv), padding: null)));
+            Encryptions.Add("twofish256-cbc", new CipherInfo(256, (key, iv) => new TwofishCipher(key, new CbcCipherMode(iv), padding: null)));
+            Encryptions.Add("arcfour", new CipherInfo(128, (key, iv) => new Arc4Cipher(key, dischargeFirstBytes: false)));
+            Encryptions.Add("arcfour128", new CipherInfo(128, (key, iv) => new Arc4Cipher(key, dischargeFirstBytes: true)));
+            Encryptions.Add("arcfour256", new CipherInfo(256, (key, iv) => new Arc4Cipher(key, dischargeFirstBytes: true)));
+            Encryptions.Add("cast128-cbc", new CipherInfo(128, (key, iv) => new CastCipher(key, new CbcCipherMode(iv), padding: null)));
 
 #pragma warning disable IDE0200 // Remove unnecessary lambda expression; We want to prevent instantiating the HashAlgorithm objects.
             HmacAlgorithms = new Dictionary<string, HashInfo>

src/Renci.SshNet/Messages/Message.cs

@@ -37,7 +37,7 @@ protected override void WriteBytes(SshDataStream stream)
             base.WriteBytes(stream);
         }
 
-        internal byte[] GetPacket(byte paddingMultiplier, Compressor compressor, bool isEncryptThenMAC = false)
+        internal byte[] GetPacket(byte paddingMultiplier, Compressor compressor, bool excludePacketLengthFieldWhenPadding = false)
         {
             const int outboundPacketSequenceSize = 4;
 
@@ -78,9 +78,9 @@ internal byte[] GetPacket(byte paddingMultiplier, Compressor compressor, bool is
                     var packetLength = messageLength + 4 + 1;
 
                     // determine the padding length
-                    // in Encrypt-then-MAC mode, the length field is not encrypted, so we should keep it out of the
+                    // in Encrypt-then-MAC mode or AEAD, the length field is not encrypted, so we should keep it out of the
                     // padding length calculation
-                    var paddingLength = GetPaddingLength(paddingMultiplier, isEncryptThenMAC ? packetLength - 4 : packetLength);
+                    var paddingLength = GetPaddingLength(paddingMultiplier, excludePacketLengthFieldWhenPadding ? packetLength - 4 : packetLength);
 
                     // add padding bytes
                     var paddingBytes = new byte[paddingLength];
@@ -106,9 +106,9 @@ internal byte[] GetPacket(byte paddingMultiplier, Compressor compressor, bool is
                 var packetLength = messageLength + 4 + 1;
 
                 // determine the padding length
-                // in Encrypt-then-MAC mode, the length field is not encrypted, so we should keep it out of the
+                // in Encrypt-then-MAC mode or AEAD, the length field is not encrypted, so we should keep it out of the
                 // padding length calculation
-                var paddingLength = GetPaddingLength(paddingMultiplier, isEncryptThenMAC ? packetLength - 4 : packetLength);
+                var paddingLength = GetPaddingLength(paddingMultiplier, excludePacketLengthFieldWhenPadding ? packetLength - 4 : packetLength);
 
                 var packetDataLength = GetPacketDataLength(messageLength, paddingLength);
 

src/Renci.SshNet/Security/Cryptography/BlockCipher.cs

@@ -110,18 +110,6 @@ public override byte[] Encrypt(byte[] input, int offset, int length)
             return output;
         }
 
-        /// <summary>
-        /// Decrypts the specified data.
-        /// </summary>
-        /// <param name="input">The data.</param>
-        /// <returns>
-        /// The decrypted data.
-        /// </returns>
-        public override byte[] Decrypt(byte[] input)
-        {
-            return Decrypt(input, 0, input.Length);
-        }
-
         /// <summary>
         /// Decrypts the specified input.
         /// </summary>
@@ -167,5 +155,31 @@ public override byte[] Decrypt(byte[] input, int offset, int length)
 
             return output;
         }
+
+        /// <summary>
+        /// Encrypts the specified region of the input byte array and copies the encrypted data to the specified region of the output byte array.
+        /// </summary>
+        /// <param name="inputBuffer">The input data to encrypt.</param>
+        /// <param name="inputOffset">The offset into the input byte array from which to begin using data.</param>
+        /// <param name="inputCount">The number of bytes in the input byte array to use as data.</param>
+        /// <param name="outputBuffer">The output to which to write encrypted data.</param>
+        /// <param name="outputOffset">The offset into the output byte array from which to begin writing data.</param>
+        /// <returns>
+        /// The number of bytes encrypted.
+        /// </returns>
+        public abstract int EncryptBlock(byte[] inputBuffer, int inputOffset, int inputCount, byte[] outputBuffer, int outputOffset);
+
+        /// <summary>
+        /// Decrypts the specified region of the input byte array and copies the decrypted data to the specified region of the output byte array.
+        /// </summary>
+        /// <param name="inputBuffer">The input data to decrypt.</param>
+        /// <param name="inputOffset">The offset into the input byte array from which to begin using data.</param>
+        /// <param name="inputCount">The number of bytes in the input byte array to use as data.</param>
+        /// <param name="outputBuffer">The output to which to write decrypted data.</param>
+        /// <param name="outputOffset">The offset into the output byte array from which to begin writing data.</param>
+        /// <returns>
+        /// The number of bytes decrypted.
+        /// </returns>
+        public abstract int DecryptBlock(byte[] inputBuffer, int inputOffset, int inputCount, byte[] outputBuffer, int outputOffset);
     }
 }

src/Renci.SshNet/Security/Cryptography/Cipher.cs

@@ -13,6 +13,15 @@ public abstract class Cipher
         /// </value>
         public abstract byte MinimumSize { get; }
 
+        /// <summary>
+        /// Gets the size of the authentication tag for ciphers which implement Authenticated Encryption (AE).
+        /// </summary>
+        /// <returns>
+        /// When this <see cref="Cipher"/> implements Authenticated Encryption, the size, in bytes,
+        /// of the authentication tag included in the encrypted message.
+        /// </returns>
+        public virtual int TagSize { get; }
+
         /// <summary>
         /// Encrypts the specified input.
         /// </summary>
@@ -41,7 +50,10 @@ public byte[] Encrypt(byte[] input)
         /// <returns>
         /// The decrypted data.
         /// </returns>
-        public abstract byte[] Decrypt(byte[] input);
+        public byte[] Decrypt(byte[] input)
+        {
+            return Decrypt(input, 0, input.Length);
+        }
 
         /// <summary>
         /// Decrypts the specified input.

src/Renci.SshNet/Security/Cryptography/Ciphers/AesCipherMode.cs

@@ -5,22 +5,22 @@
     /// </summary>
     public enum AesCipherMode
     {
-        /// <summary>CBC Mode.</summary>
+        /// <summary>Cipher Block Chain Mode.</summary>
         CBC = 1,
 
-        /// <summary>ECB Mode.</summary>
+        /// <summary>Electronic Codebook Mode.</summary>
         ECB = 2,
 
-        /// <summary>OFB Mode.</summary>
+        /// <summary>Output Feedback Mode.</summary>
         OFB = 3,
 
-        /// <summary>CFB Mode.</summary>
+        /// <summary>Cipher Feedback Mode.</summary>
         CFB = 4,
 
-        /// <summary>CTS Mode.</summary>
+        /// <summary>Cipher Text Stealing Mode.</summary>
         CTS = 5,
 
-        /// <summary>CTR Mode.</summary>
+        /// <summary>Counter Mode.</summary>
         CTR = 6
     }
 }