Citadel

Remote port forwarding follows this lifecycle:

1. The Citadel client connects to the SSH server.
2. The client requests the server to listen on a specific port (the remote port).
3. When a client connects to that port on the remote server, the SSH server opens a forwarded-tcpip channel.
4. The Citadel client receives this connection via a closure and forwards it to a local host and port.
5. Data flows bidirectionally: remote client ↔ SSH tunnel ↔ local service.

Advanced Routing: You can inspect forwardedInfo.originatorAddress or forwardedInfo.listeningPort within the handler closure to implement custom routing logic, such as directing different connections to different local services.

To use Citadel, you must first establish a connection using SSHClient.connect(to:) with an SSHClientSettings object. You must provide a host, an authentication method (such as .passwordBased), and a hostKeyValidator.

Warning: Using .acceptAnything() for the hostKeyValidator is insecure and should only be used for testing/prototyping.

let settings = SSHClientSettings(
    host: "example.com",
    authenticationMethod: { .passwordBased(username: "joannis", password: "s3cr3t") },
    // Please use another validator if at all possible, it's insecure
    hostKeyValidator: .acceptAnything()
)
let client = try await SSHClient.connect(to: settings)

Citadel allows you to chain connections through a jump host. You first connect to the jump host using SSHClient.connect, and then call .jump(to:) on that client instance to reach the target host.

// 1. Connect to jump host
let jumpHostSettings = SSHClientSettings(
    host: "jump.example.com",
    authenticationMethod: .passwordBased(username: "joannis", password: "s3cr3t"),
    hostKeyValidator: .acceptAnything()
)
let jumpHostClient = try await SSHClient.connect(to: jumpHostSettings)

// 2. Jump to target host
let targetHostSettings = SSHClientSettings(
    host: "target.example.com",
    authenticationMethod: .passwordBased(username: "joannis", password: "s3cr3t"),
    hostKeyValidator: .acceptAnything()
)
let targetHostClient = try await jumpHostClient.jump(to: targetHostSettings)

To test the Citadel client, you can run a local SSH server using the provided Dockerfile.

1. Build the image: docker build --file ExampleServer.dockerfile --tag sshd-example .
2. Run the container, mapping host port 2323 to container port 22: docker run -p 2323:22 sshd-example

Once the Dockerized SSH server is running, you can execute the Swift client example to connect to the server and run a command using the Swift Package Manager.

swift run

Use SSHAlgorithms to manage and modify the cryptographic algorithms used for transport protection, key exchange, and public key/signature schemes. You can either replace the existing list of algorithms or add to them using the Modification enum.

Available modification types:

• .replace(with: [T]): Replaces the current list with the provided list.
• .add([T]): Appends the provided list to the current list.

SSHAlgorithms.all provides a pre-configured set of algorithms including AES128CTR, specific Diffie-Hellman groups, and RSA.

var algorithms = SSHAlgorithms()
algorithms.transportProtectionSchemes = .add([AES128CTR.self])
algorithms.keyExchangeAlgorithms = .replace(with: [DiffieHellmanGroup14Sha256.self])
// Use these algorithms when connecting

Address already in use

If the remote port is already bound, choose a different port or use 0 to let the server choose an available port.

Connection refused

Verify that:

1. Your local service is actually running.
2. The remote port forward was successfully established.
3. You are connecting to the correct remote host and port.

Permission denied for port < 1024

Binding to privileged ports (below 1024) usually requires root privileges on the remote server. Use a port number $\ge$ 1024.

To stream data into a process's stdin (interactive behavior), use the withPTY method. This requires providing a PseudoTerminalRequest which defines terminal characteristics like dimensions and modes.

try await client.withPTY(
    SSHChannelRequestEvent.PseudoTerminalRequest(
        wantReply: true,
        term: "xterm",
        terminalCharacterWidth: 80,
        terminalRowHeight: 24,
        terminalPixelWidth: 0,
        terminalPixelHeight: 0,
        terminalModes: .init([.ECHO: 1])
    )
) { ttyOutput, ttyStdinWriter in
    // ...do something...
}