Merge pull request #155 from TerminalStudio/feat/issue-26-aead-groundwork

feat: start AEAD support with AES-GCM groundwork

Author: vicajilau

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## [2.17.0] - yyyy-mm-dd
 - Improved Web/WASM compatibility by updating `SSHSocket` conditional imports so web runtimes consistently use the web socket shim and avoid incorrect native socket selection [#88]. Thanks [@vicajilau].
 - Added local dynamic forwarding (`SSHClient.forwardDynamic`) with SOCKS5 `NO AUTH` + `CONNECT`, including configurable handshake/connect timeouts and connection limits.
+- Added AES-GCM (`aes128-gcm@openssh.com`, `aes256-gcm@openssh.com`) AEAD groundwork in transport and cipher negotiation; currently opt-in (not enabled by default yet). `chacha20-poly1305@openssh.com` remains pending [#26]. Thanks [@vicajilau].
 
 ## [2.16.0] - 2026-03-24
 - **BREAKING**: Changed `SSHChannelController.sendEnv()` from `void` to `Future<bool>` to properly await environment variable setup responses and avoid race conditions with PTY requests [#102]. Thanks [@itzhoujun] and [@vicajilau].
@@ -208,6 +209,7 @@
 [#124]: https://github.com/TerminalStudio/dartssh2/issues/124
 [#95]: https://github.com/TerminalStudio/dartssh2/issues/95
 [#88]: https://github.com/TerminalStudio/dartssh2/issues/88
+[#26]: https://github.com/TerminalStudio/dartssh2/issues/26
 [#139]: https://github.com/TerminalStudio/dartssh2/pull/139
 [#132]: https://github.com/TerminalStudio/dartssh2/pull/132
 [#133]: https://github.com/TerminalStudio/dartssh2/pull/133

README.md

@@ -625,9 +625,39 @@ void main() async {
 - `diffie-hellman-group1-sha1 `
 
 **Cipher**: 
+- `aes[128|256]-gcm@openssh.com`
 - `aes[128|192|256]-ctr`
 - `aes[128|192|256]-cbc`
 
+AES-GCM is currently available as opt-in via `SSHAlgorithms(cipher: ...)`, and is not enabled in the default cipher preference list yet.
+
+Example (opt-in AES-GCM with explicit fallback ciphers):
+
+```dart
+void main() async {
+  final client = SSHClient(
+    await SSHSocket.connect('localhost', 22),
+    username: '<username>',
+    onPasswordRequest: () => '<password>',
+    algorithms: const SSHAlgorithms(
+      cipher: [
+        SSHCipherType.aes256gcm,
+        SSHCipherType.aes128gcm,
+        SSHCipherType.aes256ctr,
+        SSHCipherType.aes128ctr,
+        SSHCipherType.aes256cbc,
+        SSHCipherType.aes128cbc,
+      ],
+    ),
+  );
+
+  // Use the client...
+  client.close();
+}
+```
+
+`chacha20-poly1305@openssh.com` is not supported yet.
+
 **Integrity**: 
 - `hmac-md5`
 - `hmac-sha1`

lib/src/algorithm/ssh_cipher_type.dart

@@ -5,6 +5,8 @@ import 'package:pointycastle/export.dart';
 
 class SSHCipherType extends SSHAlgorithm {
   static const values = [
+    aes128gcm,
+    aes256gcm,
     aes128cbc,
     aes192cbc,
     aes256cbc,
@@ -31,6 +33,24 @@ class SSHCipherType extends SSHAlgorithm {
     cipherFactory: _aesCtrFactory,
   );
 
+  static const aes128gcm = SSHCipherType._(
+    name: 'aes128-gcm@openssh.com',
+    keySize: 16,
+    isAead: true,
+    ivSize: 12,
+    blockSize: 16,
+    aeadTagSize: 16,
+  );
+
+  static const aes256gcm = SSHCipherType._(
+    name: 'aes256-gcm@openssh.com',
+    keySize: 32,
+    isAead: true,
+    ivSize: 12,
+    blockSize: 16,
+    aeadTagSize: 16,
+  );
+
   static const aes128cbc = SSHCipherType._(
     name: 'aes128-cbc',
     keySize: 16,
@@ -61,7 +81,11 @@ class SSHCipherType extends SSHAlgorithm {
   const SSHCipherType._({
     required this.name,
     required this.keySize,
-    required this.cipherFactory,
+    this.cipherFactory,
+    this.isAead = false,
+    this.aeadTagSize = 0,
+    this.ivSize = 16,
+    this.blockSize = 16,
   });
 
   /// The name of the algorithm. For example, `"aes256-ctr`"`.
@@ -70,17 +94,29 @@ class SSHCipherType extends SSHAlgorithm {
 
   final int keySize;
 
-  final int ivSize = 16;
+  /// Indicates whether this cipher is an AEAD mode (e.g. AES-GCM).
+  final bool isAead;
 
-  final int blockSize = 16;
+  /// Authentication tag size for AEAD ciphers.
+  final int aeadTagSize;
 
-  final BlockCipher Function() cipherFactory;
+  final int ivSize;
+
+  final int blockSize;
+
+  final BlockCipher Function()? cipherFactory;
 
   BlockCipher createCipher(
     Uint8List key,
     Uint8List iv, {
     required bool forEncryption,
   }) {
+    if (isAead) {
+      throw UnsupportedError(
+        'AEAD ciphers are packet-level and do not expose BlockCipher',
+      );
+    }
+
     if (key.length != keySize) {
       throw ArgumentError.value(key, 'key', 'Key must be $keySize bytes long');
     }
@@ -89,7 +125,11 @@ class SSHCipherType extends SSHAlgorithm {
       throw ArgumentError.value(iv, 'iv', 'IV must be $ivSize bytes long');
     }
 
-    final cipher = cipherFactory();
+    final factory = cipherFactory;
+    if (factory == null) {
+      throw StateError('No block cipher factory configured for $name');
+    }
+    final cipher = factory();
     cipher.init(forEncryption, ParametersWithIV(KeyParameter(key), iv));
     return cipher;
   }