PuTTY SSH Proxy (Jump Host) Architecture Note

Requirements

When a target SSH server is not directly reachable from the client network, PuTTY must facilitate a connection through an intermediate server. The system requirements for this feature include:

• Establishing an initial SSH connection to an intermediate (proxy) host.
• Using that connection as a transport layer for a second SSH session to the final destination.
• Maintaining strict separation between proxy authentication credentials and target authentication credentials.
• Providing distinct error reporting for each hop to allow precise network diagnostics.

Minimal Suitable Design

PuTTY implements proxy support by nesting two SSH protocol instances. Rather than creating a new networking stack, it reuses the existing SSH transport implementation in two stages:

1. The Proxy Hop: PuTTY opens a standard SSH connection to the proxy host using the credentials configured in the Proxy pane. This session is treated as a raw data pipe (similar to a TCP socket).
2. The Target Hop: Once the proxy session is established, PuTTY initiates a second SSH protocol instance. The data for this second session is encapsulated within the encrypted tunnel of the first session, effectively using the proxy's stdin/stdout as the transport medium.

This design allows the entire operation to occur within a single PuTTY process without requiring external scripts or ProxyCommand binaries.

Trust and Data Boundaries

The architecture maintains a clear security boundary between the intermediate hop and the final destination:

• Credential Isolation: Proxy authentication secrets (passwords or private keys) are used only to establish the first hop. Unless Agent forwarding is explicitly enabled in the SSH → Auth pane, these keys are never exposed to the target host.
• End-to-End Encryption: Target authentication secrets are encrypted by the inner SSH session. The proxy host sees only encrypted traffic and cannot intercept the credentials used to access the final server.
• Host Key Validation: PuTTY performs two separate host key checks. The proxy's host key is validated against the local known-hosts store first; only after the proxy is verified does PuTTY validate the target host's key.

Operational Checks

To verify the proxy configuration is functioning as intended, perform the following checks:

• Reachability: Ensure the proxy host is reachable on port 22. A failure here typically results in a Network error: Connection timed out dialog.
• Event Log Audit: Access the Event Log via the system menu. A successful proxy connection will show distinct entries: first, Opening connection to [proxy], and subsequently, Opening connection to [target].
• Authentication Sequence: Attempt a connection with an incorrect proxy password. PuTTY should surface a proxy authentication error and terminate before ever attempting to contact the target host.

Failure Modes

Failures are categorized by the hop where they occur:

Failure Point	Symptom	Root Cause
Proxy Hop	Connection timeout or Host Key Warning	Proxy server down or MITM attack on proxy.
Proxy Auth	Proxy authentication failure dialog	Invalid proxy credentials.
Target Hop	Network error after proxy login	Proxy cannot reach target or target SSH service is down.
Target Auth	Standard SSH login failure	Invalid target credentials.

Conditions That Would Change the Design

The current SSH-over-SSH design is optimized for jump hosts. A redesign would be necessary if the following requirements emerged:

• Non-SSH Proxying: If support for SOCKS5 or HTTP CONNECT proxies became a primary requirement, the transport layer would need a generic proxy abstraction rather than a nested SSH implementation.
• Performance Constraints: If the overhead of double-encryption (two layers of SSH) caused significant latency, the design might shift toward a single-connection model using TCP forwarding (similar to ssh -W).
• Certificate-Based Validation: A shift toward mandatory X.509 certificate validation for intermediate hops would require extending the known-hosts handling logic.