Reverse HTTP CONNECT for TCP and UDP

4.1. Listener Control Channel URI Template

The Listener Control Channel template is similar to the one defined in Section 3 of [CONNECT-IP] and it MAY contain two variables: "target" and "ipproto". These variables are used to define the scope of network services that the client accepts connectivity for.¶

Examples are shown below:¶

https://example.org/.well-known/masque/listen/{target}/{ipproto}/
https://proxy.example.org:4443/masque/listen?t={target}&i={ipproto}
https://proxy.example.org:4443/masque/listen{?target,ipproto}
https://masque.example.org/?user=bob

All template requirements listed in Section 3 of [CONNECT-IP] apply here.¶

If set, the variable "target" MUST contain one of the following values:¶

• A hostname according to Section 4.6 of [CONNECT-IP]¶

• IPv4 or IPv6 prefix according to Section 4.6 of [CONNECT-IP]¶

• "*" that does not limit scope¶

• A wildcard: a domain name prefixed by "*.". This implies that client MAY accept inbound sessions for any host in a given domain¶

• "." which means that the client will accept sessions to local services only and will not forward to other hosts¶

If set, the variable "ipproto" MUST contain one of the following values:¶

• "6" which means that the client will only accept TCP sessions.¶

• "17" which means that the client will only accept UDP sessions.¶

• "*" which means that the client will accept both TCP and UDP sessions.¶

As with [CONNECT-IP], some client configurations for Reverse Connect proxies will only allow the user to configure the proxy host and proxy port. Clients with such limitations MAY attempt to access proxying capabilities using the default template, which is defined as: "https://$PROXY_HOST:$PROXY_PORT/.well-known/masque/listen/{target}/{ipproto}/", where $PROXY_HOST and $PROXY_PORT are the configured host and port of the proxy, respectively. Reverse Connect proxy deployments SHOULD offer service at this location if they need to interoperate with such clients.¶

4.2. Establishing Listener Control Channel over HTTP/1.1

When establishing the Listener Control Channel using HTTP/1.1 [HTTP/1.1], the client follows the requirements from Section 4.2 of [CONNECT-IP] but uses "connect-listen" as the value for the Upgrade header.¶

For example, the client configured with the default URI Template "https://example.org/.well-known/masque/listen/{target}/{ipproto}/" can establish the Listener Control Channel for local TCP and UDP services by sending the following request:¶

GET https://example.org/.well-known/masque/listen/./*/ HTTP/1.1
Host: example.org
Connection: Upgrade
Upgrade: connect-listen
Capsule-Protocol: ?1

The server confirms successful registration of the client as described in Section 4.3 of [CONNECT-IP], but with "connect-listen" for the value for Upgrade header.¶

An example of the server confirming successful registration of the client is provided below:¶

HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: connect-listen
Capsule-Protocol: ?1

4.3. Establishing Listener Control Channel over HTTP/2 and HTTP/3

When establishing Listener Control Channel using HTTP/2 [HTTP/2] or HTTP/3 [HTTP/3], the client follows requirements from Section 4.4 of [CONNECT-IP], but uses "connect-listen" as the value for :protocol pseudo-header.¶

For example, the client configured with the default URI Template "https://example.org/.well-known/masque/listen/{target}/{ipproto}/" can establish the Listener Control Channel for local TCP and UDP services by sending the following request:¶

HEADERS
:method = CONNECT
:protocol = connect-listen
:scheme = https
:path = /.well-known/masque/listen/./*/
:authority = example.org
capsule-protocol = ?1

The server indicates a successful registration of the client as described in Section 4.5 of [CONNECT-IP].¶

Example of server confirming successful registration of the client is provided below:¶

HEADERS
:status = 200
capsule-protocol = ?1

4.4. Service Discovery

The Reverse Connect client MAY advertise offered TCP and UDP services to the proxy server through the AVAILABLE_SERVICES Capsule over the established Listener Control Channel. This information serves as a hint for the proxy server and does not constrain the server from attempting to establish sessions with services that were not advertised. The presence of a service in the AVAILABLE_SERVICES list does not guarantee actual service availability, as the client may not be able to track the health of the service.¶

Capsule format for AVAILABLE_SERVICES is the following:¶

AVAILABLE_SERVICES Capsule {
  Type (i) = 0xTBD,
  Length (i),
  Service (..) ...,
}

The AVAILABLE_SERVICES capsule contains a sequence of zero or more Services.¶

Service {
  Destination Type (8),
  Destination (..),
  Protocol (8),
  Port (16),
}

Each service record represents potential connection destination and contains the following fields:¶

Destination Type:

A single byte value defining type and format of Destination field. Valid destination types are:¶

• 0: Destination is local for the client.¶

• 1: Destination is specified by a hostname.¶

• 4: Destination is specified by an IPv4 address.¶

• 6: Destination is specified by an IPv6 address.¶

Destination:

Content of the Destination field is determined by the Destination Type. For local destination type destination is omitted. IPv4 destination carries 32 bits of IPv4 address. IPv6 destination carries 128 bits of IPv6 address. Hostname destination (destination type 1) is provided in the following format:¶

Hostname_Destination {
  Length (i),
  Hostname (..),
}

Length is encoded as a variable-length integer and Hostname contains the hostname string.¶

Protocol:

A single byte value of 6 for TCP and 17 for UDP.¶

Port:

Two bytes value of target TCP or UDP port.¶

AVAILABLE_SERVICES messages are not incremental. A new message completely overwrites the previous hint.¶

If any of the capsule fields are malformed upon reception, the server MUST follow the error-handling procedure defined in Section 3.3 of [HTTP-DGRAM].¶

5.1. Requesting Connection

To request a new outbound connection from the client for an inbound TCP or UDP session, the server sends a CONNECTION_REQUEST Capsule. The CONNECTION_REQUEST Capsule is defined as follows:¶

CONNECTION_REQUEST Capsule {
  Type (i) = 0xTBD,
  Length (i),
  Request ID (i),
  Service (..),
}

Request ID:

A unique request identifier, encoded as a variable-length integer. The Request ID MUST be unique for a given Listener Control Channel.¶

Service:

Session destination as described in Section 4.4.¶

If any of the capsule fields are malformed upon reception, or if the Request ID has been previously used on the same Listener Control Channel, the client MUST follow the error-handling procedure defined in Section 3.3 of [HTTP-DGRAM].¶

If the client declines the connection request it responds with a CONNECTION_REQUEST_DECLINED Capsule in the following format:¶

CONNECTION_REQUEST_DECLINED Capsule {
  Type (i) = 0xTBD,
  Length (i),
  Request ID (i),
}

If any of the capsule fields are malformed upon reception, or if the  Request ID does not correspond to an outstanding CONNECTION_REQUEST on the same Listener Control Channel, the server MUST follow the error-handling procedure defined in Section 3.3 of [HTTP-DGRAM].¶

5.2. Accepting Connection

To accept the inbound session, the client sends a new outbound request to the server. This request uses an Accepting Connection URI Template [TEMPLATE]. The URI Template MUST contain "request_id" variable.¶

Examples are shown below:¶

https://example.org/.well-known/masque/accept/{request_id}/
https://proxy.example.org:4443/masque/accept?id={request_id}
https://proxy.example.org:4443/masque/accept{?request_id}
https://masque.example.org/?user=bob&request_id={request_id}

The following requirements apply to the Accepting Connection URI Template:¶

• The URI Template MUST be a level 3 template or lower.¶

• The URI Template MUST be in absolute form and MUST include non-empty scheme, authority, and path components.¶

• The path component of the URI Template MUST start with a slash "/".¶

• All template variables MUST be within the path or query components of the URI.¶

• The URI Template MUST contain variable "request_id" and MAY contain other variables.¶

• The URI Template MUST NOT contain any non-ASCII Unicode characters and MUST only contain ASCII characters in the range 0x21-0x7E inclusive (note that percent-encoding is allowed; see Section 2.1 of [URI].¶

• The URI Template MUST NOT use Reserved Expansion ("+" operator), Fragment Expansion ("#" operator), Label Expansion with Dot-Prefix, Path Segment Expansion with Slash-Prefix, nor Path-Style Parameter Expansion with Semicolon-Prefix.¶

Clients SHOULD validate the requirements above; however, clients MAY use a general-purpose URI Template implementation that lacks this specific validation. If a client detects that any of the requirements above are not met by a URI Template, the client MUST reject its configuration and abort the request without sending it to the IP proxy.¶

As with [CONNECT-IP], some client configurations for Reverse Connect proxies will only allow the user to configure the proxy host and proxy port. Clients with such limitations MAY attempt to access proxying capabilities using the default template, which is defined as: "https://$PROXY_HOST:$PROXY_PORT/.well-known/masque/accept/{request_id}/", where $PROXY_HOST and $PROXY_PORT are the configured host and port of the proxy, respectively. Reverse Connect proxy deployments SHOULD offer service at this location if they need to interoperate with such clients.¶

GET https://example.org/.well-known/masque/accept/1/ HTTP/1.1
Host: example.org
Connection: Upgrade
Upgrade: connect-accept
Capsule-Protocol: ?1

HTTP/1.1 101 Switching Protocols
Connection: Upgrade
Upgrade: connect-accept
Capsule-Protocol: ?1

HEADERS
:method = CONNECT
:protocol = connect-accept
:scheme = https
:path = /.well-known/masque/accept/1/
:authority = example.org
capsule-Protocol = ?1

HEADERS
:status = 200
capsule-Protocol = ?1

5.3. Establishing Connection

Once the client receives a successful response from the proxy for the request accepting the connection it establishes the requested TCP or UDP socket to a local or internal destination. If the socket failed to establish, the client MUST immediately close the request stream.¶

For TCP flows, communicating parties carry TCP payload data in the payload of DATA Capsules over the established stream according to Section 8.3 of [Template-TCPCONNECT]. Either party MAY close the stream if TCP connection is terminated.¶

UDP data is carried in DATAGRAM capsules or encoded in QUIC DATAGRAM frames as explained in Section 5 of [CONNECT-UDP]. The lifetime of the UDP socket is tied to the request stream as described in Section 3.1 of [CONNECT-UDP].¶

7.1. HTTP Upgrade Tokens

IF APPROVED, IANA is requested to add the following entries to the HTTP Upgrade Token Registry:¶

7.2. New MASQUE Default Templates

IF APPROVED, IANA is requested to add the following entries to the MASQUE URI Suffixes Registry:¶

7.3. New HTTP Capsule Types

IF APPROVED, IANA is requested to add the following entries to the HTTP Capsule Types Registry:¶

All of these new entries use the following values for these fields:¶

Status: permanent Reference: (this document) Change Controller: IETF Contact: MASQUE Notes: None¶