DartSSH 2

To establish a basic SSH connection, use SSHClient with an SSHSocket. You must provide a username and an onPasswordRequest callback if using password authentication.

Note: SSHSocket.connect() uses native TCP sockets (dart:io) and is not available on Flutter Web or Dart Web. For web support, you must provide a custom SSHSocket implementation (e.g., using WebSockets).

void main() async {
  final client = SSHClient(
    await SSHSocket.connect('localhost', 22),
    username: '<username>',
    onPasswordRequest: () => '<password>',
  );
}

Since browsers cannot open TCP sockets, SSHSocket.connect() will fail on web runtimes. To use dartssh2 on Flutter Web or Dart Web, you must implement the SSHSocket interface using a transport the browser supports, such as a WebSocket connected to a proxy that bridges to your SSH endpoint.

Web Limitations:

• chacha20-poly1305@openssh.com is not available because the underlying library requires 64-bit integers not fully supported in the same way. AES-GCM or AES-CTR will be negotiated instead.
• SftpFile.downloadToRandomAccess is unavailable because it requires dart:io. Use SftpFile.downloadTo (which takes a sink) or SftpFile.read instead.

By default, dartssh2 uses modern, secure algorithms (e.g., ssh-ed25519 for host keys, curve25519-sha256 for KEX, and aes-gcm for ciphers).

If you are connecting to a legacy device (like an old router or NAS) that requires deprecated algorithms (e.g., diffie-hellman-group14-sha1 or ssh-rsa), you must explicitly pass them via the algorithms parameter in the SSHClient constructor using SSHAlgorithms.

void main() async {
  final client = SSHClient(
    await SSHSocket.connect('localhost', 22),
    username: '<username>',
    onPasswordRequest: () => '<password>',
    algorithms: const SSHAlgorithms(
      // Only do this for a server that supports nothing better.
      kex: [SSHKexType.dh14Sha1, SSHKexType.dh1Sha1],
    ),
  );

  // Use the client...
  await client.close();
}

To connect to a target server through a jump host (gateway), first establish an SSHClient to the jump server. Then, use jumpServer.forwardLocal(targetHost, targetPort) to create a tunnel, and use the resulting connection to initialize a second SSHClient targeting the destination.

final jumpServer = SSHClient(
  await SSHSocket.connect('<jump server>', 22),
  username: '...',
);

final targetClient = SSHClient(
  await jumpServer.forwardLocal('<target server>', 22),
  username: '...',
);

You can use DartSSH via a command-line interface. First, install the dartssh2_cli package globally using dart pub. Once installed, you can use the dartssh command in place of the standard ssh command, or dartsftp for SFTP operations.

# Install the `dartssh` command.
dart pub global activate dartssh2_cli

# Then use `dartssh` as regular `ssh` command.
dartssh user@example.com

# Example: execute a command on remote host.
dartssh user@example.com ls -al

# Example: connect to a non-standard port.
dartssh user@example.com:<port>

# Transfer files via SFTP.
dartsftp user@example.com

The library supports Strict Key Exchange, which is a countermeasure against the Terrapin attack (CVE-2023-48795).

When both the client and server advertise support for strict key exchange in their initial SSH_MSG_KEXINIT message:

1. The SSH_MSG_KEXINIT must be the very first packet of the connection (sequence number 0).
2. Certain optional transport messages—specifically SSH_MSG_IGNORE (2), SSH_MSG_UNIMPLEMENTED (3), and SSH_MSG_DEBUG (4)—are forbidden during the key exchange phase.

If a violation is detected (e.g., an unexpected message is received during the exchange), the library will throw an SSHHandshakeError and tear down the connection.

To prevent Man-in-the-Middle attacks, you should implement the onVerifyHostKey handler in SSHTransport. This handler is called when the host key is received during the handshake.

The handler must return a FutureOr<bool>:

• true: The key is valid; proceed with the connection.
• false: The key is invalid; the transport will reject the key and disconnect.

The fingerprint provided is an OpenSSH-style SHA256 fingerprint, UTF-8 encoded as SHA256:<base64>.

// Example of a verification handler
SSHHostkeyVerifyHandler myVerifier = (String type, Uint8List fingerprint) async {
  final fingerprintString = utf8.decode(fingerprint);
  if (fingerprintString == 'SHA256:expected_base64_fingerprint_here') {
    return true;
  }
  return false;
};

The SSHDynamicForward abstraction represents a local dynamic SOCKS5 forwarding server managed by an SSHClient. It allows you to bind a local port to act as a SOCKS proxy that tunnels traffic through the SSH connection.

Key properties:

• host: The local host/interface the SOCKS server is bound to.
• port: The local port the SOCKS server is listening on.
• isClosed: Indicates if the forwarder has been closed.

To stop the server and close all active connections, call close().