| Internet-Draft | WebTransport-H2 | July 2021 |
| Frindell, et al. | Expires 31 January 2022 | [Page] |
WebTransport [OVERVIEW] is a protocol framework that enables clients constrained by the Web security model to communicate with a remote server using a secure multiplexed transport. This document describes a WebTransport protocol that is based on HTTP/2 [RFC7540] and provides support for unidirectional streams, bidirectional streams and datagrams, all multiplexed within the same HTTP/2 connection.¶
Discussion of this draft takes place on the WebTransport mailing list (webtransport@ietf.org), which is archived at https://mailarchive.ietf.org/arch/search/?email_list=webtransport.¶
The repository tracking the issues for this draft can be found at https://github.com/ietf-wg-webtrans/draft-webtransport-http2. The web API draft corresponding to this document can be found at https://w3c.github.io/webtransport/.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 31 January 2022.¶
Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.¶
Currently, the only mechanism in HTTP/2 for server to client communication is server push. That is, servers can initiate unidirectional push promised streams to clients, but clients cannot respond to them; they can only accept them or discard them. Additionally, intermediaries along the path may have different server push policies and may not forward push promised streams to the downstream client. This best effort mechanism is not sufficient to reliably deliver messages from servers to clients, limiting server to client use-cases such as chat messages or notifications.¶
Several techniques have been developed to workaround these limitations: long polling [RFC6202], WebSocket [RFC8441], and tunneling using the CONNECT method. All of these approaches have limitations.¶
This document defines a mechanism for multiplexing non-HTTP data with HTTP/2 in a manner that conforms with the WebTransport protocol requirements and semantics [OVERVIEW]. Using the mechanism described here, multiple WebTransport instances can be multiplexed simultaneously with regular HTTP traffic on the same HTTP/2 connection.¶
The keywords "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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This document follows terminology defined in Section 1.2 of [OVERVIEW]. Note that this document distinguishes between a WebTransport server and an HTTP/2 server. An HTTP/2 server is the server that terminates HTTP/2 connections; a WebTransport server is an application that accepts WebTransport sessions, which can be accessed via an HTTP/2 server.¶
WebTransport servers are identified by an HTTPS URI as defined in Section 4.2.2 of [HTTP].¶
When an HTTP/2 connection is established, both the client and server have to send a SETTINGS_ENABLE_WEBTRANSPORT setting in order to indicate that they both support WebTransport over HTTP/2.¶
WebTransport sessions are initiated inside a given HTTP/2 connection by the client, who sends an extended CONNECT request [RFC8441]. If the server accepts the request, an WebTransport session is established. The resulting stream will be further referred to as a CONNECT stream, and its stream ID is used to uniquely identify a given WebTransport session within the connection. The ID of the CONNECT stream that established a given WebTransport session will be further referred to as a Session ID.¶
After the session is established, the peers can exchange data using the following mechanisms:¶
A WebTransport session is terminated when the CONNECT stream that created it is closed.¶
In order to indicate support for WebTransport, both the client and the server MUST send a SETTINGS_ENABLE_WEBTRANSPORT value set to "1" in their SETTINGS frame. Endpoints MUST NOT use any WebTransport-related functionality unless the parameter has been negotiated.¶
[RFC8441] defines an extended CONNECT method in Section 4, enabled by the SETTINGS_ENABLE_CONNECT_PROTOCOL parameter. An endpoint does not need to send both SETTINGS_ENABLE_CONNECT_PROTOCOL and SETTINGS_ENABLE_WEBTRANSPORT; the SETTINGS_ENABLE_WEBTRANSPORT setting implies that an endpoint supports extended CONNECT.¶
As WebTransport sessions are established over HTTP/2, they are identified
using the https URI scheme [RFC7230].¶
In order to create a new WebTransport session, a client can send an HTTP CONNECT
request. The :protocol pseudo-header field ([RFC8441]) MUST be set to
webtransport (Section 7.1 of [WEBTRANSPORT-H3]). The :scheme field MUST be
https. Both the :authority and the :path value MUST be set; those fields
indicate the desired WebTransport server. An Origin header [RFC6454] MUST
be provided within the request.¶
Upon receiving an extended CONNECT request with a :protocol field set to
webtransport, the HTTP/2 server can check if it
has a WebTransport server associated with the specified :authority and :path
values. If it does not, it SHOULD reply with status code 404 (Section 6.5.4,
[RFC7231]). If it does, it MAY accept the session by replying with status
code 200. The WebTransport server MUST verify the Origin header to ensure
that the specified origin is allowed to access the server in question.¶
From the client's perspective, a WebTransport session is established when the client receives a 200 response. From the server's perspective, a session is established once it sends a 200 response. Both endpoints MUST NOT open any streams or send any datagrams on a given session before that session is established.¶
From the flow control perspective, WebTransport sessions count against the stream flow control just like regular HTTP requests, since they are established via an HTTP CONNECT request. This document does not make any effort to introduce a separate flow control mechanism for sessions, nor to separate HTTP requests from WebTransport data streams. If the server needs to limit the rate of incoming requests, it has alternative mechanisms at its disposal:¶
HTTP_STREAM_REFUSED error code defined in [RFC7540] indicates to the
receiving HTTP/2 stack that the request was not processed in any way.¶
WebTransport over HTTP/2 provides the following features described in [OVERVIEW]: unidirectional streams, bidirectional streams and datagrams, initiated by either endpoint.¶
Session IDs are used to demultiplex streams and datagrams belonging to different WebTransport sessions. On the wire, session IDs are encoded using a 31-bit integer field.¶
A new HTTP/2 frame called WT_STREAM is introduced for either endpoint to establish WebTransport streams. WT_STREAM frames can be sent on a stream in the "idle", "reserved (local)", "open", or "half-closed (remote)" state.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+ |Pad Length? (8)| +-+-------------+-----------------------------------------------+ |R| Session ID (31) | +-+-------------------------------------------------------------+ | Padding (*) ... +---------------------------------------------------------------+
The WT_STREAM frame define the following fields:¶
Pad Length: An 8-bit field containing the length of the frame padding in units of octets. This field is conditional (as signified by a "?" in the diagram) and is only present if the PADDED flag is set.¶
Session ID: An unsigned 31-bit integer that identifies the
stream Connect Stream for this Web Transport stream. The
Session ID MUST be MUST be an open stream negotiated via the
extended CONNECT protocol with a :protocol value of
"webtransport".¶
The WT_STREAM frame defines the following flags:¶
UNIDIRECTIONAL (0x1): When set, the stream begins in the "half-closed (remote)" state at the sender, and in the "half-closed (local)" state at the receiver.¶
As with all HTTP/2 streams, WebTransport streams initiated by a client have odd stream IDs and those initiated by a server have even stream IDs.¶
The recipient MUST respond with a stream error of type WT_STREAM_ERROR if the specified WebTransport Connect Stream does not exist, is not a stream established via extended CONNECT to use the "webtransport" protocol, or if it is in the "closed" or "half-closed (remote)" stream state.¶
The RST_STREAM frame defined in HTTP/2 moves a stream to the "closed" state, but WebTransport streams can be reset unidirectionally, as in QUIC and HTTP/3. A new HTTP/2 frame called WT_RST_STREAM is introduced for an endpoint to unidirectionally reset a stream for writing. WT_RST_STREAM frames can be sent on a stream in the "open", or "half-closed (remote)" state.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------------------------------------------------------+ | Error Code (32) | +---------------------------------------------------------------+
The WT_RST_STREAM frame contains a single unsigned, 32-bit integer identifying the error code. The error code indicates why the stream is being abruptly terminated for writing.¶
The WT_RST_STREAM frame does not define any flags.¶
The WT_RST_STREAM frame half-closes the referenced stream and effects the same state machine transitions as sending or receiving the END_STREAM flag. If the sender is in the "open" state, it transitions to "half-closed (local)". If the sender is in the "half-closed (remote)" state, it transitions to "closed". If the receiver is in the "open" state, it transitions to "half-closed (remote)". If the receiver is in the "half-closed (local)" state, it transitions to "closed".¶
After sending a WT_RST_STREAM on a stream, the sender MUST NOT send additional DATA frames for that stream. If another frame is received on a stream after receiving a WT_RST_STREAM, the recipient MUST treat this as a connection error of type PROTOCOL_ERROR.¶
WT_RST_STREAM frames MUST be associated with a WebTransport stream. If a WT_RST_STREAM frame is received with a stream identifier of 0x0, or a request or push stream, the recipient MUST treat this as a connection error of type PROTOCOL_ERROR.¶
WT_RST_STREAM frames MUST NOT be sent for a stream in any state other than "open" or "half-closed (remote)". If a WT_RST_STREAM frame identifying a stream in the "idle", "reserved (local)", "reserved (remote)" state is received, the recipient MUST treat this as a connection error (Section 5.4.1) of type PROTOCOL_ERROR. Because of race conditions with WT_STOP_SENDING, it is possible to receive a WT_RST_STREAM in the "half-closed (remote)" or "closed" state. The recipient should ignore the frame in this case.¶
A WT_RST_STREAM frame with a length other than 4 octets MUST be treated as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR.¶
The RST_STREAM frame defined in HTTP/2 moves a stream to the "closed" state, but WebTransport streams can be reset unidirectionally, as in QUIC and HTTP/3. A new HTTP/2 frame called WT_STOP_SENDING is introduced for an endpoint to unidirectionally reset a stream for reading. WT_STOP_SENDING frames can be sent on a stream in the "open", or "half-closed (local)" state.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------------------------------------------------------+ | Error Code (32) | +---------------------------------------------------------------+
The WT_STOP_SENDING frame contains a single unsigned, 32-bit integer identifying the error code. The error code indicates why the reading the stream is being abandoned.¶
The WT_STOP_SENDING frame does not define any flags.¶
The WT_STOP_SENDING frame half-closes the referenced stream and effects the same state machine transitions as sending or receiving the END_STREAM flag. If the sender is in the open state, it transitions to "half-closed (remote)". If the sender is in the "half-closed (local)" state, it transitions to "closed". If the receiver is in the "open" state, it transitions to "half-closed (local)". If the receiver is in the "half-closed (remote)" state, it transitions to "closed".¶
After receiving a WT_STOP_SENDING on a stream, the sender MUST NOT send additional frames for that stream. After sending the WT_STOP_SENDING, the sending endpoint MUST be prepared to receive and handle additional frames sent on the stream that might have been sent by the peer prior to the arrival of the WT_STOP_SENDING.¶
WT_STOP_SENDING frames MUST be associated with a WebTransport stream. If a WT_STOP_SENDING frame is received with a stream identifier of 0x0, or a request or push stream, the recipient MUST treat this as a connection error of type PROTOCOL_ERROR.¶
WT_STOP_SENDING frames MUST NOT be sent for a stream in any state other than "open" or "half-closed (local)". It is possible to receive a WT_STOP_SENDING in another state however, because the sender might have closed or reset the stream while the WT_STOP_SENDING was in flight. If a WT_STOP_SENDING frame identifying a stream that is already "closed" or "half-closed (local)", the recipient SHOULD ignore the frame.¶
It is also possible to receive DATA frames on a WebTransport stream in the "half-closed (remote)" or "closed" states if the stream transitioned there via WT_STOP_SENDING. If a DATA frame is received on a WebTransport stream in one of these states, the recipient MUST account for its contribution against the connection flow-control window and MUST NOT treat it as an error.¶
A WT_STOP_SENDING frame with a length other than 4 octets MUST be treated as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR.¶
A new HTTP/2 frame called WT_DATAGRAM is introduced for either endpoint to transmit a datagram. WT_DATAGRAM frames are sent with Stream Identifier 0.¶
0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +---------------+ |Pad Length? (8)| +-+-------------+-----------------------------------------------+ |R| Session ID (31) | +-+-------------------------------------------------------------+ | Data (*) ... +---------------------------------------------------------------+ | Padding (*) ... +---------------------------------------------------------------+
The WT_DATAGRAM frame define the following fields:¶
Pad Length: An 8-bit field containing the length of the frame padding in units of octets. This field is conditional (as signified by a "?" in the diagram) and is only present if the PADDED flag is set.¶
Session ID: An unsigned 31-bit integer that identifies the
stream Connect Stream for this Web Transport stream. The
Session ID MUST be MUST be an open stream negotiated via the
extended CONNECT protocol with a :protocol value of
"webtransport".¶
Data: Application data. The amount of data is the remainder of the frame payload after subtracting the length of the other fields that are present.¶
The WT_DATAGRAM frame does not define any flags.¶
The recipient MAY respond with a stream error of type WT_STREAM_ERROR if the specified WebTransport Connect Stream does not exist, is not a stream established via extended CONNECT to use the "webtransport" protocol, or if it is in the "closed" or "half-closed (remote)" stream state.¶
The data in WT_DATAGRAM frames is not subject to flow control. The receiver MAY discard this data if it does not have sufficient space to buffer it.¶
An intermediary could forward the data in a WT_DATAGRAM frame over another protocol, such as WebTransport over HTTP/3. In QUIC, a datagram frame can span at most one packet. Because of that, the applications have to know the maximum size of the datagram they can send. However, when proxying the datagrams, the hop-by-hop MTUs can vary.¶
An WebTransport session over HTTP/2 is terminated when either endpoint closes the stream associated with the CONNECT request that initiated the session. Upon learning about the session being terminated, the endpoint MUST stop sending new datagrams and reset all of the streams associated with the session.¶
The WebTransport framework [OVERVIEW] defines a set of optional transport properties that clients can use to determine the presence of features which might allow additional optimizations beyond the common set of properties available via all WebTransport protocols. Below are details about support in Http2Transport for those properties.¶
Http2Transport does not support stream independence, as HTTP/2 inherently has head of line blocking.¶
Http2Transport does not support partial reliability, as HTTP/2 retransmits any lost data. This means that any datagrams sent via Http2Transport will be retransmitted regardless of the preference of the application. The receiver is permitted to drop them, however, if it is unable to buffer them.¶
Http2Transport supports pooling, as multiple transports using Http2Transport may share the same underlying HTTP/2 connection and therefore share a congestion controller and other transport context.¶
Http2Transport does not support connection mobility, unless an underlying transport protocol that supports multipath or migration, such as MPTCP [RFC7540], is used underneath HTTP/2 and TLS. Without such support, Http2Transport connections cannot survive network transitions.¶
WebTransport over HTTP/2 satisfies all of the security requirements imposed by [OVERVIEW] on WebTransport protocols, thus providing a secure framework for client-server communication in cases when the client is potentially untrusted.¶
WebTransport over HTTP/2 requires explicit opt-in through the use of HTTP SETTINGS; this avoids potential protocol confusion attacks by ensuring the HTTP/2 server explicitly supports it. It also requires the use of the Origin header, providing the server with the ability to deny access to Web-based clients that do not originate from a trusted origin.¶
Just like HTTP traffic going over HTTP/2, WebTransport pools traffic to different origins within a single connection. Different origins imply different trust domains, meaning that the implementations have to treat each transport as potentially hostile towards others on the same connection. One potential attack is a resource exhaustion attack: since all of the transports share both congestion control and flow control context, a single client aggressively using up those resources can cause other transports to stall. The user agent thus SHOULD implement a fairness scheme that ensures that each transport within connection gets a reasonable share of controlled resources; this applies both to sending data and to opening new streams.¶
The following entry is added to the "HTTP/2 Settings" registry established by [RFC7540]:¶
The SETTINGS_ENABLE_WEBTRANSPORT parameter indicates that the specified
HTTP/2 connection is WebTransport-capable.¶
The following entries are added to the "HTTP/2 Frame Type" registry established by [RFC7540]:¶
The WT_STREAM frame allows HTTP/2 client- and server-initiated unidirectional
and bidirectional streams to be used by WebTransport:¶
The WT_RST_STREAM frame allows HTTP/2 WebTransport streams to be
unidirectionally reset for writing:¶
The WT_STOP_SENDING frame allows HTTP/2 WebTransport streams to be
unidirectionally reset for reading:¶
The WT_DATAGRAM frame allows HTTP/2 client and server to exchange datagrams
used by WebTransport:¶
The following entries are added to the "HTTP/2 Error Code" registry that was established by Section 11.2 of [RFC7540].¶
An example of negotiating a WebTransport Stream on an HTTP/2 connection follows. This example is intended to closely follow the example in Section 5.1 of [RFC8441] to help illustrate the differences defined in this document.¶
[[ From Client ]] [[ From Server ]]
SETTINGS
SETTINGS_ENABLE_WEBTRANSPORT = 1
SETTINGS
SETTINGS_ENABLE_WEBTRANSPORT = 1
HEADERS + END_HEADERS
Stream ID = 3
:method = CONNECT
:protocol = webtransport
:scheme = https
:path = /
:authority = server.example.com
origin: server.example.com
HEADERS + END_HEADERS
Stream ID = 3
:status = 200
WT_STREAM
Stream ID = 5
Session ID = 3
DATA
Stream ID = 5
WebTransport Data
DATA + END_STREAM
Stream ID = 5
WebTransport Data
DATA + END_STREAM
Stream ID = 5
WebTransport Data
¶
An example of the server initiating a WebTransport Stream follows. The only difference here is the endpoint that sends the first WT_STREAM frame.¶
[[ From Client ]] [[ From Server ]]
SETTINGS
SETTINGS_ENABLE_WEBTRANSPORT = 1
SETTINGS
SETTINGS_ENABLE_WEBTRANSPORT = 1
HEADERS + END_HEADERS
Stream ID = 3
:method = CONNECT
:protocol = webtransport
:scheme = https
:path = /
:authority = server.example.com
origin: server.example.com
HEADERS + END_HEADERS
Stream ID = 3
:status = 200
WT_STREAM
Stream ID = 2
Session ID = 3
DATA
Stream ID = 2
WebTransport Data
DATA + END_STREAM
Stream ID = 2
WebTransport Data
DATA + END_STREAM
Stream ID = 2
WebTransport Data
¶
Thanks to Anthony Chivetta, Joshua Otto, and Valentin Pistol for their contributions in the design and implementation of this work.¶