ssh3

> [!NOTE] > SSH3 is probably going to change its name. It is still the SSH Connection Protocol (RFC4254) running on top of HTTP/3 Extended connect, but the required changes are heavy and > too distant from the philosophy of popular SSH implementations to be considered for integration. The [specification draft](https://datatracker.ietf.org/doc/draft-michel-remote-terminal-http3/) has already been renamed ("Remote Terminals over HTTP/3"), > but we need some time to come up with a nice permanent name. # SSH3: faster and rich secure shell using HTTP/3 SSH3 is a complete revisit of the SSH protocol, mapping its semantics on top of the HTTP mechanisms. It comes from our research work and we (researchers) recently proposed it as an [Internet-Draft](https://www.ietf.org/how/ids/) ([draft-michel-remote-terminal-http3-00](https://datatracker.ietf.org/doc/draft-michel-remote-terminal-http3/)). In a nutshell, SSH3 uses [QUIC](https://datatracker.ietf.org/doc/html/rfc9000)+[TLS1.3](https://datatracker.ietf.org/doc/html/rfc8446) for secure channel establishment and the [HTTP Authorization](https://www.rfc-editor.org/rfc/rfc9110.html#name-authorization) mechanisms for user authentication. Among others, SSH3 allows the following improvements: - Significantly faster session establishment - New HTTP authentication methods such as [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749) and [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) in addition to classical SSH authentication - Robustness to port scanning attacks: your SSH3 server can be made **invisible** to other Internet users - UDP port forwarding in addition to classical TCP port forwarding - All the features allowed by the modern QUIC protocol: including connection migration (soon) and multipath connections > [!TIP] > Quickly want to get started ? Checkout how to [install SSH3](#installing-ssh3). You will learn to [setup an SSH3 server](#deploying-an-ssh3-server) and [use the SSH3 client](#using-the-ssh3-client). ## ⚡ SSH3 is faster Faster for session establishment, not throughput ! SSH3 offers a significantly faster session establishment than SSHv2. Establishing a new session with SSHv2 can take 5 to 7 network round-trip times, which can easily be noticed by the user. SSH3 only needs 3 round-trip times. The keystroke latency in a running session is unchanged.

SSH3 (top) VS SSHv2 (bottom) session establishement with a 100ms ping towards the server.

## SSH3 security While SSHv2 defines its own protocols for user authentication and secure channel establishment, SSH3 relies on the robust and time-tested mechanisms of TLS 1.3, QUIC and HTTP. These protocols are already extensively used to secure security-critical applications on the Internet such as e-commerce and Internet banking. SSH3 already implements the common password-based and public-key (RSA and EdDSA/ed25519) authentication methods. It also supports new authentication methods such as OAuth 2.0 and allows logging in to your servers using your Google/Microsoft/Github accounts. ### SSH3 is still experimental While SSH3 shows promise for faster session establishment, it is still at an early proof-of-concept stage. As with any new complex protocol, **expert cryptographic review over an extended timeframe is required before reasonable security conclusions can be made**. We are developing SSH3 as an open source project to facilitate community feedback and analysis. However, we **cannot yet endorse its appropriateness for production systems** without further peer review. Please collaborate with us if you have relevant expertise! ### Do not deploy the SSH3 server on your production servers for now Given the current prototype state, we advise *testing SSH3 in sandboxed environments or private networks*. Be aware that making experimental servers directly Internet-accessible could introduce risk before thorough security vetting. While [hiding](#-your-ssh3-public-server-can-be-hidden) servers behind secret paths has potential benefits, it does not negate the need for rigorous vulnerability analysis before entering production. We are excited by SSH3's future possibilities but encourage additional scrutiny first. ## Your SSH3 public server can be hidden Using SSH3, you can avoid the usual stress of scanning and dictionary attacks against your SSH server. Similarly to your secret Google Drive documents, your SSH3 server can be hidden behind a secret link and only answer to authentication attempts that made an HTTP request to this specific link, like the following: ssh3-server -bind 192.0.2.0:443 -url-path By replacing `` by, let's say, the random value `M3MzkxYWMxMjYxMjc5YzJkODZiMTAyMjU`, your SSH3 server will only answer to SSH3 connection attempts made to the URL `https://192.0.2.0:443/M3MzkxYWMxMjYxMjc5YzJkODZiMTAyMjU` and it will respond a `404 Not Found` to other requests. Attackers and crawlers on the Internet can therefore not detect the presence of your SSH3 server. They will only see a simple web server answering 404 status codes to every request. **NOTE WELL**: placing your SSH3 server behind a secret URL may reduce the impact of scanning attacks but will and must *never* replace classical authentication mechanisms. The secret link should only be used to avoid your host to be discovered. Knowing the secret URL should not grant someone access to your server. Use the classical authentication mechanisms described above to protect your server. ## SSH3 is already feature-rich SSH3 provides new feature that could not be provided by the SSHv2 protocol. ### Brand new features - **UDP port forwarding**: you can now access your QUIC, DNS, RTP or any UDP-based server that are only reachable from your SSH3 host. UDP packets are forwarded using QUIC datagrams. - **X.509 certificates**: you can now use your classical HTTPS certificates to authenticate your SSH3 server. This mechanism is more secure than the classical SSHv2 host key mechanism. Certificates can be obtained easily using LetsEncrypt for instance. - **Hiding** your server behind a secret link. - **Keyless** secure user authentication using **OpenID Connect**. You can connect to your SSH3 server using the SSO of your company or your Google/Github account, and you don't need to copy the public keys of your users anymore. ### Famous OpenSSH features implemented This SSH3 implementation already provides many of the popular features of OpenSSH, so if you are used to OpenSSH, the process of adopting SSH3 will be smooth. Here is a list of some OpenSSH features that SSH3 also implements: - Parses `~/.ssh/authorized_keys` on the server - Certificate-based server authentication - `known_hosts` mechanism when X.509 certificates are not used. - Automatically using the `ssh-agent` for public key authentication - SSH agent forwarding to use your local keys on your remote server - Direct TCP port forwarding (reverse port forwarding will be implemented in the future) - Proxy jump (see the `-proxy-jump` parameter). If A is an SSH3 client and B and C are both SSH3 servers, you can connect from A to C using B as a gateway/proxy. The proxy uses UDP forwarding to forward the QUIC packets from A to C, so B cannot decrypt the traffic A<->C SSH3 traffic. - Parses `~/.ssh/config` on the client and handles the `Hostname`, `User`, `Port` and `IdentityFile` config options (the other options are currently ignored). Also parses a new `UDPProxyJump` that behaves similarly to OpenSSH's `ProxyJump`. ## Community support Help us progress SSH3 responsibly! We welcome capable security researchers to review our codebase and provide feedback. Please also connect us with relevant standards bodies to potentially advance SSH3 through the formal IETF/IRTF processes over time. With collaborative assistance, we hope to iteratively improve SSH3 towards safe production readiness. But we cannot credibly make definitive security claims without evidence of extensive expert cryptographic review and adoption by respected security authorities. Let's work together to realize SSH3's possibilities! ## Installing SSH3 You can either download the last [release binaries](https://github.com/francoismichel/ssh3/releases), [install it using `go install`](#installing-ssh3-and-ssh3-server-using-go-install) or generate these binaries yourself by compiling the code from source. > [!TIP] > SSH3 is still experimental and is the fruit of a research work. If you are afraid of deploying publicly a new SSH3 server, you can use the > [secret path](#-your-ssh3-public-server-can-be-hidden) feature of SSH3 to hide it behing a secret URL. ### Installing ssh3 and ssh3-server using Go install ```bash go install github.com/francoismichel/ssh3/cmd/...@latest ``` ### Compiling SSH3 from source You need a recent [Golang](https://go.dev/dl/) version to do this. Downloading the source code and compiling the binaries can be done with the following steps: ```bash git clone https://github.com/francoismichel/ssh3 # clone the repo cd ssh3 go build -o ssh3 cmd/ssh3/main.go # build the client CGO_ENABLED=1 go build -o ssh3-server cmd/ssh3-server/main.go # build the server, requires having gcc installed ``` If you have root/sudo privileges and you want to make ssh3 accessible to all you users, you can then directly copy the binaries to `/usr/bin`: ```bash cp ssh3 /usr/bin/ && cp ssh3-server /usr/bin ``` Otherwise, you can simply add the executables to your `PATH` environment variable by adding the following line at the end of your `.bashrc` or equivalent: ```bash export PATH=$PATH:/path/to/the/ssh3/directory ``` ### Deploying an SSH3 server Before connecting to your host, you need to deploy an SSH3 server on it. There is currently no SSH3 daemon, so right now, you will have to run the `ssh3-server` executable in background using `screen` or a similar utility. > [!NOTE] > As SSH3 runs on top of HTTP/3, a server needs an X.509 certificate and its corresponding private key. Public certificates can be generated automatically for your public domain name through Let's Encrypt using the `-generate-public-cert` command-line argument on the server. If you do not want to generate a certificate signed by a real certificate authority or if you don't have any public domain name, you can generate a self-signed one using the `-generate-selfsigned-cert` command-line argument. Self-signed certificates provide you with similar security guarantees to SSHv2's host keys mechanism, with the same security issue: you may be vulnerable to machine-in-the-middle attacks during your first connection to your server. Using real certificates signed by public certificate authorities such as Let's Encrypt avoids this issue. Here is the usage of the `ssh3-server` executable: ``` … ``` The following command starts a public SSH3 server on port 443 with a valid Let's Encrypt public certificate for domain `my-domain.example.org` and answers to new sessions requests querying the `/ssh3` URL path: ssh3-server -generate-public-cert my-domain.example.org -url-path /ssh3 If you don't have a public domain name (i.e. only an IP address), you can either use an existing certificate for your IP address using the `-cert` and `-key` arguments or generate a self-signed certificate using the `-generate-selfsigned-cert` argument. If you have existing certificates and keys, you can run the server as follows to use them= ssh3-server -cert /path/to/cert/or/fullchain -key /path/to/cert/private/key -url-path /ssh3 > [!NOTE] > Similarly to OpenSSH, the server must be run with root priviledges to log in as other users. #### Authorized keys and authorized identities By default, the SSH3 server will look for identities in the `~/.ssh/authorized_keys` and `~/.ssh3/authorized_identities` files for each user. `~/.ssh3/authorized_identities` allows new identities such as OpenID Connect (`oidc`) dis