Secure shell over HTTP/3 connections

1.1.1. QUIC: datagrams support, streams multiplexing and connection migration

Using QUIC, SSH3 can send data through both reliable streams and unreliable datagrams. This makes SSH3 able to support port forwarding for both UDP [UDP] and TCP-based protocols. Being based exclusively on TCP, SSHv2 does not offer UDP port forwarding and therefore provides no support to UDP-based protocols such as RTP or QUIC. This lack of UDP support in SSHv2 may become problematic as the use of QUIC-based applications (HTTP/3, MOQT [MOQT], DOQ [DOQ]) grows. Support for UDP port forwarding with SSH3 also allows accessing real-time media content such as low-latency live video available on the server. The stream multiplexing capabilities of QUIC allow reducing the head-of-line blocking that SSHv2 encounters when multiplexing several SSH channels over the same TCP connection.¶

QUIC also supports connection migration (Section 9 of [QUIC]). Using connection migration, a mobile host roaming between networks can maintain established connections alive across different networks by migrating them on their newly acquired IP address. This avoids disrupting the SSH conversation upon network changes. Finally, QUIC also offers a significantly reduced connection establishment time compared to the SSHv2 session establishment.¶

1.1.2. Protecting transport-layer control fields

Since QUIC integrates authentication and encryption as part of its transport features, it makes SSH3 robust to transport-layer attacks that were possible with TCP, such as packet injections or reset attacks [RFC5961]. For instance, the recent Terrapin attack [TERRAPIN] manipulates the TCP sequence number to alter the SSH extension negotiation mechanism [RFC8308] and downgrade the client authentication algorithms. QUIC control information such as packet numbers and frame formats are all authenticated and encrypted starting from the Handshake encryption level. Furthermore, QUIC prevents middlebox interference.¶

1.1.3. Leveraging the X.509 ecosystem

By using TLS for their secure channel establishment, HTTPS and QUIC leverage the X.509 certificates ecosystem with low implementation effort. TLS and QUIC libraries already implement support for generating, parsing and verifying X.509 certificates. Similarly to classical OpenSSH certificates, this avoids encouraging SSH users to rely on the Trust On First Use pattern when connecting to their remote hosts. Relying on the X.509 certificates ecosystem additionally enables SSH3 servers to use ACME [ACME] to automatically (with no additional user action) generate X.509 certificates for their domain names using well-known certificate authorities such as Let's Encrypt. These certificates are publicly valid and can be verified like classical HTTPS certificates. Client certificates can also be issued and used as an authentication method for the client.¶

1.1.4. HTTP authentication: compatibility with existing authentication systems

Using HTTP authentication schemes for user authentication allows implementing diverse authentication mechanisms such as the classical password-based and public key authentication, but also popular web authentication mechanisms such as OpenID Connect [OpenID.Core], SAML2 [OASIS.saml-core-2.0-os] or the recent Passkeys/WebAuthn standard [WebAuthn]. All these authentication schemes are already deployed for managing access to critical resources in different organizations. Sharing computing resources using SSHv2 through these mechanisms generally requires the deployment of a middleware managing the mapping between identities and SSH keys or certificates. Adding HTTP authentication to SSH allows welcoming these authentication methods directly and interfaces SSH3 more naturally with existing architectures. As a proof-of-concept, OpenID Connect support has been added to our SSH3 prototype [SSH3-PROTOTYPE]. Other web authentication standards such as Passkeys/WebAuthn [WebAuthn] allow administrators to restrict remote access to specific client devices in addition to users.¶

1.1.5. URL multiplexing and undiscoverability

Relying on HTTP allows easily placing SSH endpoints as resources accessible through specific URLs. First, this makes it easier to integrate SSH endpoints on web servers that already perform user authentication and authorization. Second, it allows placing several SSH server instances on the same physical machine on the same port. These instances can run in different virtual machines, containers or simply different users with user's priviledges and be multiplexed on a URL-basis. Finally, SSH3 endpoints can be placed behind secret URLs, reducing the exposure of SSH3 hosts to scanning and brute force attacks. This goes in line with the will of having undiscoverable resources also tackled by other IETF working groups [HTTP-SIGNATURE]. This property is not provided by SSHv2 since the SSHv2 server announces its SSH version string to any connected TCP client. If wanted, SSH3 hosts can be made indistinguishable from any HTTP server. This is however only complementary to and MUST NOT replace user authentication.¶

3.1.1. Password authentication using HTTP Basic Authentication

Password-based authentication is performed using the HTTP Basic authentication scheme [HTTP-BASIC]. The user-id part of the <credentials> in the Authorization header defined in [HTTP-BASIC] MUST be equal to the username variable in the request URI defined in Section 3.¶

  Client
     |                QUIC HANDSHAKE                 |
     |<--------------------------------------------->|
     |                                               |
     | HTTP/3, Stream x CONNECT /<path>?user=<user>  |
     |         :protocol="ssh3"                      |
     |         Authorization="Basic <credentials>"   |
     |---------------------------------------------->|
     |                                               |
     |               HTTP/3, Stream x 200 OK         |
     |<----------------------------------------------|
     |                                               |
     |           Conversation established            |
     +-----------------------------------------------+
     |                                               |

3.1.2. Public key authentication using OAUTH2 and JWTs

Classical public key authentication can be performed using the OAUTH2 framework [OAUTH2]: the HTTP Bearer authentication scheme is used to carry an OAUTH access token encoded in the JWT [JWT] format [OAUTH2-JWT].¶

  Client
     |                QUIC HANDSHAKE                 |
     |<--------------------------------------------->|
     |                                               |
     | HTTP/3, Stream x CONNECT /<path>?user=<user>  |
     |         :protocol="ssh3"                      |
     |         Authorization="Bearer <JWT token>"    |
     |---------------------------------------------->|
     |                                               |
     |               HTTP/3, Stream x 200 OK         |
     |<----------------------------------------------|
     |                                               |
     |           Conversation established            |
     +-----------------------------------------------+
     |                                               |

For classical client-server public key authentication with no third-party involved, only the following claims are required (see [JWT] for their definition):¶

• sub: set to ssh3-<user>¶

• iat: set to the date of issuance of the JWT¶

• exp: set to a short expiration value to limit the token replay window¶

The jti claim may also be used to prevent the token from being replayed.¶

3.1.3. Public key authentication using HTTP Signature authentication

Public key authentication can also be performed using the HTTP Signature Authentication scheme [HTTP-SIGNATURE]. The <k> parameter designates the key ID of the public key used by the authentication process. Classical SSH implementations usually do not assign IDs to public keys. The value <k> can therefore be set to the cryptographic hash of the public key instead.¶

  Client
     |                QUIC HANDSHAKE                 |
     |<--------------------------------------------->|
     |                                               |
     | HTTP/3, Stream x CONNECT /<path>?user=<user>  |
     |    :protocol="ssh3"                           |
     |    Signature k=<k>, a=<a>,s=<s>,v=<v>,p=<p>   |
     |---------------------------------------------->|
     |                                               |
     |               HTTP/3, Stream x 200 OK         |
     |<----------------------------------------------|
     |                                               |
     |           Conversation established            |
     +-----------------------------------------------+
     |                                               |

4.1.1. Opening a channel

SSH channels can be opened on HTTP/3 client-initiated bidirectional streams. By default, HTTP/3 considers every client-initiated bidirectional stream as a request stream. Similarly to WebTransport, SSH3 extends HTTP/3 using a specific signal value. An SSH3 client can open a stream with this signal value to indicate that it is not a request stream and that the remaining stream bytes will be used arbitrarily by the SSH3 protocol to carry the content of a channel. For experimental purpose, the signal value is chosen at random and will change over time. The current signal value is 0xaf3627e6. The content of an HTTP/3 stream carrying an SSH3 channel is illustrated below.¶

Channel {
    Signal Value (i) = 0xaf3627e6,
    Conversation ID (i),
    Channel Type Length (i)
    Channel Type (..)
    Maximum Message Size (i)
    SSH messages (..)
}

The first value sent on the HTTP/3 stream is the Signal Value. The Channel Type is a UTF-8-encoded string whose length is defined by the Channel Type Length field.¶

[[Note: SSHv2 uses text-based channel types. Should we keep that or use something else instead ? If we change, we loose a 1-1 mapping with SSHv2.]]¶

The Maximum Message Size field defines the maximum size in bytes of SSH messages.¶

The remaining bytes of the stream are interpreted as a sequence of SSH messages. Their format and length can vary depending on the message type (see Section 4.1.4).¶

4.1.2. Channel types

This document defines the following channel types, the four first being also defined in [SSH-CONNECT]:¶

• session¶

• x11¶

• direct-tcp¶

• reverse-tcp¶

• direct-udp¶

• reverse-udp¶

The direct-tcp and direct-udp channels offer TCP and UDP port forwarding from a local port on the client towards a remote address accessible from the remote host. The reverse-tcp and reverse-udp channels offer the forwarding of UDP packets and TCP connections arriving on a specific port on the remote host to the client.¶

4.1.3. Port forwarding

The HTTP bidirectional stream attached to the direct-tcp or reverse-tcp channel directly carries the TCP payload to forward.¶

For UDP forwarding, UDP packets are carried through HTTP Datagrams (Section 2 of [HTTP-DATAGRAM]) whose Quarter Stream IDs refer directly to the HTTP Stream ID of the corresponding direct-udp or reverse-udp channel.¶

Forwarding of other layers (e.g. IP) is left for future versions of the document.¶

4.1.4. Messages

Messages are exchanged over channels similarly to SSHv2. The same message format as the one defined in [SSH-CONNECT] applies, with channel numbers removed from the messages headers as channel run over dedicated HTTP streams. Hereunder is an example showing the wire format of the exit-status SSH message for SSH3. Its SSHv2 variant is described in Section 6.10 of [SSH-CONNECT].¶

ExitStatusMessage {
    Message Type (string) = "exit-status",
    Want Reply (bool) = false,
    Exit Status (i)
}