The MASQUE ProtocolGoogle LLC1600 Amphitheatre ParkwayMountain View, California 94043United States of Americadschinazi.ietf@gmail.comInternet-DraftThis document describes MASQUE (Multiplexed Application Substrate over QUIC
Encryption). MASQUE is a framework that allows concurrently running multiple
networking applications inside an HTTP/3 connection. For example, MASQUE can
allow a QUIC client to negotiate proxying capability with an HTTP/3 server,
and subsequently make use of this functionality while concurrently processing
HTTP/3 requests and responses.Discussion of this work is encouraged to happen on the MASQUE IETF mailing
list masque@ietf.org or on the GitHub repository which contains the draft:
https://github.com/DavidSchinazi/masque-drafts.IntroductionThis document describes MASQUE (Multiplexed Application Substrate over QUIC
Encryption). MASQUE is a framework that allows concurrently running multiple
networking applications inside an HTTP/3 connection (see
). For example, MASQUE can allow a QUIC client to
negotiate proxying capability with an HTTP/3 server, and subsequently make use
of this functionality while concurrently processing HTTP/3 requests and
responses.MASQUE Negotiation is performed using HTTP mechanisms, but MASQUE applications
can subsequently leverage QUIC features
without using HTTP.Discussion of this work is encouraged to happen on the MASQUE IETF mailing
list masque@ietf.org or on the GitHub repository which contains the draft:
https://github.com/DavidSchinazi/masque-drafts.Conventions and DefinitionsThe key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14
when, and only when, they appear in all capitals, as shown here.MASQUE NegotiationIn order to negotiate the use of the MASQUE protocol, the client starts by
sending a MASQUE request in the HTTP data of an HTTP POST request to
"/.well-known/masque/initial". The client can use this to request specific
MASQUE applications and advertise support for MASQUE extensions. The MASQUE
server indicates support for MASQUE by sending an HTTP status code 200 response,
and can use the data to inform the client of which MASQUE applications are now
in use, and various configuration parameters.Both the MASQUE negotiation initial request and its response carry a sequence
of MASQUE applications, as shown in :Each MASQUE Application is encoded as an (identifier, length, value) tuple,
as shown in :The MASQUE Application Length field contains the length of the MASQUE
Application Value field. The contents of the MASQUE Application Value
field are defined by its corresponding MASQUE application. When parsing,
endpoints MUST ignore unknown MASQUE applications. A given MASQUE application
ID MUST NOT appear twice in a given sequence of MASQUE applications.MASQUE ApplicationsWhen the MASQUE server accepts the client's MASQUE initial request, it
advertises support for MASQUE Applications, which will be multiplexed over this
HTTP/3 connection.HTTP ProxyThe client can make proxied HTTP requests through the server to other
servers. In practice this will mean using the HTTP CONNECT method to establish
a stream over which to run TLS to a different remote destination. The proxy
applies back-pressure to streams in both directions.HTTP Proxy NegotiationUse of the HTTP Proxying MASQUE application is negotiated by sending the
http_proxying (type 0x00) type-length-value during MASQUE negotiation.
The length MUST be zero.DNS over HTTPSThe client can send DNS queries using DNS over HTTPS to the
MASQUE server.DNS over HTTPS NegotiationUse of the DNS over HTTPS MASQUE application is negotiated by sending the
dns_over_https (type 0x01) type-length-value during MASQUE negotiation.
When sent by the client, the length MUST be zero. When sent by the server,
the value contains the DoH URI Template encoded as a non-null-terminated
UTF-8 string.QUIC ProxyingBy leveraging QUIC client connection IDs, a MASQUE server can act as a QUIC
proxy while only using one UDP port. To allow this, the MASQUE server informs
the client of a required client connection ID length during negotiation. The
client is then able to send proxied packets to the MASQUE server who will
forward them on to the desired IP address and UDP port. Return packets are
similarly forwarded in the opposite direction.Compared to UDP proxying, this mode has the advantage of only requiring one UDP
port to be open on the MASQUE server, and can lower the overhead on the link
between client and MASQUE server by compressing connection IDs.QUIC Proxy CompressionTo reduce the overhead of proxying, QUIC Proxying leverages compression to
elide the connection IDs on the link between the client and MASQUE server.
This uses the concept of a compression context. Compression contexts are
indexed using a datagram flow identifiers
, and contain the tuple
(client connection ID, server connection ID, server IP address, server port).Any time and endpoint wants to send a proxied packet to its peer, it searches
its list of compression contexts looking for one that matches the address, port
and connection IDs from the proxied packet. If there was no match, the endpoint
creates a new compression context and adds it to the list.Compression contexts also carry a boolean value representing whether the
context has been validated, which means that this endpoint is confident
that its peer is aware if the given compression context. Compression contexts
that were created by the peer start off validated, whereas locally-created
ones are not validated until the endpoint receives a packet using that
compression context, or an acknowledgement for a sent packet that uses the
context.The DATAGRAM frame format below allows both
endpoints to immediately start sending proxied QUIC packets using unvalidated
compression contexts. Once contexts are vaidated, the server IP address,
server port and the connection IDs can be ommited.TODO: garbage collect obsolete compression contexts.QUIC Proxy NegotiationUse of the QUIC Proxying MASQUE application is negotiated by sending the
quic_proxying (type 0x02) type-length-value during MASQUE negotiation.When sent by the client, the value contains a single variable-length
integer, called new_quic_proxy_compression_context_flow_id, that represents
the DATAGRAM flow ID used to negotiate compression contexts.When sent by the server, the value contains two variable-length integers,
the DATAGRAM flow ID used to negotiate compression contexts (called
new_quic_proxy_compression_context_flow_id), followed by the required
connection ID length.QUIC Proxy EncodingOnce negotiated, the QUIC Proxying MASQUE Application only uses DATAGRAM
frames, whose content is shown in and
.Unvalidated QUIC Proxy DATAGRAM frames contain the following fields:
Flow Identifier:
The flow identifier represents the compression context used
by this frame. Unvalidated compression contexts use the
new_quic_proxy_compression_context_flow_id value received during
negotiation.
New Compression Context ID:
The new Compression Context ID that this frame uses. The
connection IDs and server IP address family, address, and port
are associated with this context.
CCIDL:
Length of the Client Connection ID field.
Client Connection ID:
The client connection ID associated with this compression context.
SCIDL:
Length of the Server Connection ID field.
Server Connection ID:
The server connection ID associated with this compression context.
Server Port Number:
The UDP port number used by the server.
Family:
The IP address family of the Server IP Address field. Can be either
4 or 6.
Server IP Address:
The IP address of the server. This field is 32 bits long if Family is 4
and 128 bits long if Family is 6.
Byte 1:
The first byte of the QUIC packet being transferred.
Version:
The QUIC version in the long header of the QUIC packet being transferred.
This field is present if and only if the first bit of the Byte 1 field is set.
QUIC Payload:
The contents of the QUIC packet being transmitted, starting after the last
byte of last connection ID field.
Validated QUIC Proxy DATAGRAM frames contain the following fields:
Flow Identifier:
The flow identifier represents the compression context used
by this frame. Calidated compression contexts MUST NOT use the
new_quic_proxy_compression_context_flow_id value received during
negotiation.
Byte 1:
The first byte of the QUIC packet being transferred.
Version:
The QUIC version in the long header of the QUIC packet being transferred.
This field is present if and only if the first bit of the Byte 1 field is set.
QUIC Payload:
The contents of the QUIC packet being transmitted, starting after the last
byte of last connection ID field.
QUIC Proxy RoutingA MASQUE server keeps a mapping from client connection IDs to MASQUE clients,
so that it can correctly route return packets. When a MASQUE server receives a
QUIC Proxy DATAGRAM frame, it forwards it to the IP address and UDP port from
the corresponding compression context. Additionally, the MASQUE server will
ensure that the client connection ID from that compression context maps to
that MASQUE client.TODO: garbage collect this mapping from client connection ID to MASQUE client.UDP ProxyingIn order to support WebRTC to further servers, clients need a way to
relay UDP onwards to a remote server. In practice for most widely deployed
protocols other than DNS, this involves many datagrams over the same ports.
Therefore this mechanism can compress the server's IP address and UDP port
to reduce overhead.UDP Proxy CompressionUDP Proxy leverages compression similarly to QUIC proxying, except that it
only compresses the IP address and port, not QUIC connection IDs.UDP Proxy NegotiationUse of the UDP Proxying MASQUE application is negotiated by sending the
udp_proxying (type 0x03) type-length-value during MASQUE negotiation.The value contains a single variable-length integer, called
new_udp_proxy_compression_context_flow_id, that represents
the DATAGRAM flow ID used to negotiate compression contexts.UDP Proxy EncodingOnce negotiated, the UDP Proxying MASQUE Application only uses DATAGRAM
frames, whose content is shown in and
.Unvalidated UDP Proxy DATAGRAM frames contain the following fields:
Flow Identifier:
The flow identifier represents the compression context used
by this frame. Unvalidated compression contexts use the
new_udp_proxy_compression_context_flow_id value received during
negotiation.
New Compression Context ID:
The new Compression Context ID that this frame uses. The
server IP address family, address, and port are associated with this context.
Server Port Number:
The UDP port number used by the server.
Family:
The IP address family of the Server IP Address field. Can be either
4 or 6.
Server IP Address:
The IP address of the server. This field is 32 bits long if Family is 4
and 128 bits long if Family is 6.
UDP Payload:
The contents of the UDP packet being transmitted, starting after the last
byte of the UDP checksum field.
Validated UDP Proxy DATAGRAM frames contain the following fields:
Flow Identifier:
The flow identifier represents the compression context used
by this frame. Calidated compression contexts MUST NOT use the
new_udp_proxy_compression_context_flow_id value received during
negotiation.
UDP Payload:
The contents of the UDP packet being transmitted, starting after the last
byte of the UDP checksum field.
IP ProxyingFor the rare cases where the previous mechanisms are not sufficient, proxying
can be performed at the IP layer. This would use a different DATAGRAM_ID and
IP datagrams would be encoded inside it without framing.IP Proxy NegotiationUse of the IP Proxying MASQUE application is negotiated by sending the
ip_proxying (type 0x04) type-length-value during MASQUE negotiation.The value contains a single variable-length integer, called
ip_proxy_flow_id, that represents the DATAGRAM flow ID used by IP Proxying
DATAGRAM frames.IP Proxy EncodingOnce negotiated, the IP Proxying MASQUE Application only uses DATAGRAM
frames, whose content is shown in .IP Proxy DATAGRAM frames contain the following fields:
Flow Identifier:
The flow identifier MUST be set to the ip_proxy_flow_id value received
during negotiation.
IP Packet:
The full IP packet, starting from the IP Version field.
Service RegistrationMASQUE can be used to make a home server accessible on the wide area. The home
server authenticates to the MASQUE server and registers a domain name it wishes
to serve. The MASQUE server can then forward any traffic it receives for that
domain name (by inspecting the TLS Server Name Indication (SNI) extension) to
the home server. This received traffic is not authenticated and it allows
non-modified clients to communicate with the home server without knowing it is
not colocated with the MASQUE server.To help obfuscate the home server, deployments can use Encrypted Server Name
Indication . That will require the MASQUE server
sending the cleartext SNI to the home server.TODO: define the wire format for Service Registration.Security ConsiderationsHere be dragons. TODO: slay the dragons.IANA ConsiderationsMASQUE Well-Known URIThis document will request IANA to register the "/.well-known/masque/" URI
(expert review)
https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml.MASQUE Applications RegistryThis document will request IANA to create a new MASQUE Applications registry
which governs a 62-bit space of MASQUE application types. This registry
follows the same registration policy as the QUIC Transport Parameter Registry;
see the IANA Considerations section of .The initial contents of this registry are shown in :
Initial MASQUE Applications Entries
Value
Parameter Name
Specification
0x00
http_proxying
0x01
dns_over_https
0x02
quic_proxying
0x03
udp_proxying
0x04
ip_proxying
ReferencesNormative ReferencesHypertext Transfer Protocol Version 3 (HTTP/3)The QUIC transport protocol has several features that are desirable in a transport for HTTP, such as stream multiplexing, per-stream flow control, and low-latency connection establishment. This document describes a mapping of HTTP semantics over QUIC. This document also identifies HTTP/2 features that are subsumed by QUIC, and describes how HTTP/2 extensions can be ported to HTTP/3.QUIC: A UDP-Based Multiplexed and Secure TransportThis document defines the core of the QUIC transport protocol. Accompanying documents describe QUIC's loss detection and congestion control and the use of TLS for key negotiation. Note to Readers Discussion of this draft takes place on the QUIC working group mailing list (quic@ietf.org), which is archived at <https://mailarchive.ietf.org/arch/search/?email_list=quic>. Working Group information can be found at <https://github.com/ quicwg>; source code and issues list for this draft can be found at <https://github.com/quicwg/base-drafts/labels/-transport>.Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.DNS Queries over HTTPS (DoH)This document defines a protocol for sending DNS queries and getting DNS responses over HTTPS. Each DNS query-response pair is mapped into an HTTP exchange.Using QUIC Datagrams with HTTP/3The QUIC DATAGRAM extension provides application protocols running over QUIC with a mechanism to send unreliable data while leveraging the security and congestion-control properties of QUIC. However, QUIC DATAGRAM frames do not provide a means to demultiplex application contexts. This document defines how to use QUIC DATAGRAM frames when the application protocol running over QUIC is HTTP/3 by adding an identifier at the start of the frame payload. Discussion of this work is encouraged to happen on the QUIC IETF mailing list quic@ietf.org [1] or on the GitHub repository which contains the draft: https://github.com/DavidSchinazi/draft- h3-datagram [2].An Unreliable Datagram Extension to QUICThis document defines an extension to the QUIC transport protocol to add support for sending and receiving unreliable datagrams over a QUIC connection. Discussion of this work is encouraged to happen on the QUIC IETF mailing list quic@ietf.org (mailto:quic@ietf.org) or on the GitHub repository which contains the draft: https://github.com/quicwg/ datagram (https://github.com/quicwg/datagram).Informative ReferencesEncrypted Server Name Indication for TLS 1.3This document defines a simple mechanism for encrypting the Server Name Indication for TLS 1.3.AcknowledgmentsThis proposal was inspired directly or indirectly by prior work from many
people. The author would like to thank
Nick Harper,
Christian Huitema,
Marcus Ihlar,
Eric Kinnear,
Mirja Kuehlewind,
Brendan Moran,
Lucas Pardue,
Tommy Pauly,
Zaheduzzaman Sarker,
Ben Schwartz,
and
Christopher A. Wood
for their input.