--- 1/draft-ietf-masque-h3-datagram-02.txt 2021-07-12 16:13:45.658501609 -0700 +++ 2/draft-ietf-masque-h3-datagram-03.txt 2021-07-12 16:13:45.702502722 -0700 @@ -1,137 +1,147 @@ MASQUE D. Schinazi Internet-Draft Google LLC Intended status: Standards Track L. Pardue -Expires: 28 November 2021 Cloudflare - 27 May 2021 +Expires: 13 January 2022 Cloudflare + 12 July 2021 - Using QUIC Datagrams with HTTP/3 - draft-ietf-masque-h3-datagram-02 + Using Datagrams with HTTP + draft-ietf-masque-h3-datagram-03 Abstract The 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 describes how to use QUIC DATAGRAM frames when the application protocol running over QUIC is HTTP/3. It associates datagrams with client-initiated bidirectional streams and defines an optional additional demultiplexing layer. + Additionally, this document defines how to convey datagrams over + prior versions of HTTP. - Discussion of this work is encouraged to happen on the MASQUE IETF - mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the - GitHub repository which contains the draft: https://github.com/ietf- - wg-masque/draft-ietf-masque-h3-datagram. +Discussion Venues + + This note is to be removed before publishing as an RFC. + + Discussion of this document takes place on the MASQUE WG mailing list + (masque@ietf.org), which is archived at + https://mailarchive.ietf.org/arch/browse/masque/. + + Source for this draft and an issue tracker can be found at + https://github.com/ietf-wg-masque/draft-ietf-masque-h3-datagram. Status of This Memo 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 28 November 2021. + This Internet-Draft will expire on 13 January 2022. Copyright Notice 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 2. Multiplexing . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2.1. Datagram Contexts . . . . . . . . . . . . . . . . . . . . 3 + 2.1. Datagram Contexts . . . . . . . . . . . . . . . . . . . . 4 2.2. Context ID Allocation . . . . . . . . . . . . . . . . . . 4 3. HTTP/3 DATAGRAM Format . . . . . . . . . . . . . . . . . . . 4 4. CAPSULE HTTP/3 Frame Definition . . . . . . . . . . . . . . . 6 4.1. The REGISTER_DATAGRAM_CONTEXT Capsule . . . . . . . . . . 7 - 4.2. The REGISTER_DATAGRAM_NO_CONTEXT Capsule . . . . . . . . 8 + 4.2. The REGISTER_DATAGRAM_NO_CONTEXT Capsule . . . . . . . . 9 4.3. The CLOSE_DATAGRAM_CONTEXT Capsule . . . . . . . . . . . 10 4.4. The DATAGRAM Capsule . . . . . . . . . . . . . . . . . . 11 5. Context Extensibility . . . . . . . . . . . . . . . . . . . . 12 - 5.1. The CLOSE_CODE Context Extension Type . . . . . . . . . . 12 + 5.1. The CLOSE_CODE Context Extension Type . . . . . . . . . . 13 5.2. The DETAILS Context Extension Type . . . . . . . . . . . 13 6. The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . . . . . 13 7. Prioritization . . . . . . . . . . . . . . . . . . . . . . . 14 8. HTTP/1.x and HTTP/2 Support . . . . . . . . . . . . . . . . . 14 9. Security Considerations . . . . . . . . . . . . . . . . . . . 14 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 10.1. HTTP/3 CAPSULE Frame . . . . . . . . . . . . . . . . . . 14 - 10.2. HTTP SETTINGS Parameter . . . . . . . . . . . . . . . . 14 + 10.2. HTTP/3 SETTINGS Parameter . . . . . . . . . . . . . . . 15 10.3. Capsule Types . . . . . . . . . . . . . . . . . . . . . 15 10.4. Context Extension Types . . . . . . . . . . . . . . . . 16 - 10.5. Context Close Codes . . . . . . . . . . . . . . . . . . 16 + 10.5. Context Close Codes . . . . . . . . . . . . . . . . . . 17 11. Normative References . . . . . . . . . . . . . . . . . . . . 17 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 18 A.1. CONNECT-UDP . . . . . . . . . . . . . . . . . . . . . . . 18 A.2. CONNECT-UDP with Timestamp Extension . . . . . . . . . . 19 - A.3. CONNECT-IP with IP compression . . . . . . . . . . . . . 19 - A.4. WebTransport . . . . . . . . . . . . . . . . . . . . . . 20 - Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 + A.3. CONNECT-IP with IP compression . . . . . . . . . . . . . 20 + A.4. WebTransport . . . . . . . . . . . . . . . . . . . . . . 21 + + Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 22 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 1. Introduction The QUIC DATAGRAM extension [DGRAM] provides application protocols running over QUIC [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 describes how to use QUIC DATAGRAM frames when the application protocol running over QUIC is HTTP/3 [H3]. It associates datagrams with client-initiated bidirectional streams and defines an optional additional - demultiplexing layer. - - Discussion of this work is encouraged to happen on the MASQUE IETF - mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the - GitHub repository which contains the draft: https://github.com/ietf- - wg-masque/draft-ietf-masque-h3-datagram. + demultiplexing layer. Additionally, this document defines how to + convey datagrams over prior versions of HTTP. 1.1. Conventions and Definitions The 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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2. Multiplexing - In order to allow multiple exchanges of datagrams to coexist on a - given QUIC connection, HTTP datagrams contain two layers of - multiplexing. First, the QUIC DATAGRAM frame payload starts with an - encoded stream identifier that associates the datagram with a given - QUIC stream. Second, datagrams optionally carry a context identifier - (see Section 2.1) that allows multiplexing multiple datagram contexts - related to a given HTTP request. Conceptually, the first layer of - multiplexing is per-hop, while the second is end-to-end. + When running over HTTP/3, multiple exchanges of datagrams need the + ability to coexist on a given QUIC connection. To allow this, HTTP + datagrams contain two layers of multiplexing. First, the QUIC + DATAGRAM frame payload starts with an encoded stream identifier that + associates the datagram with a given QUIC stream. Second, datagrams + optionally carry a context identifier (see Section 2.1) that allows + multiplexing multiple datagram contexts related to a given HTTP + request. Conceptually, the first layer of multiplexing is per-hop, + while the second is end-to-end. + + When running over HTTP/2, the first level of demultiplexing is + provided by the HTTP/2 framing layer. When running over HTTP/1, + requests are strictly serialized in the connection, therefore the + first layer of demultiplexing is not needed. 2.1. Datagram Contexts Within the scope of a given HTTP request, contexts provide an additional demultiplexing layer. Contexts determine the encoding of datagrams, and can be used to implicitly convey metadata. For example, contexts can be used for compression to elide some parts of the datagram: the context identifier then maps to a compression context that the receiver can use to reconstruct the elided data. @@ -142,49 +152,48 @@ ID is a 62-bit integer (0 to 2^62-1). While stream IDs are a per-hop concept, context IDs are an end-to-end concept. In other words, if a datagram travels through one or more intermediaries on its way from client to server, the stream ID will most likely change from hop to hop, but the context ID will remain the same. Context IDs are opaque to intermediaries. 2.2. Context ID Allocation - Implementations of HTTP/3 that support the DATAGRAM extension MUST - provide a context ID allocation service. That service will allow - applications co-located with HTTP/3 to request a unique context ID - that they can subsequently use for their own purposes. The HTTP/3 - implementation will then parse the context ID of incoming DATAGRAM - frames and use it to deliver the frame to the appropriate application - context. + Implementations of HTTP Datagrams MUST provide a context ID + allocation service. That service will allow applications co-located + with HTTP to request a unique context ID that they can subsequently + use for their own purposes. The HTTP implementation will then parse + the context ID of incoming HTTP Datagrams and use it to deliver the + frame to the appropriate application context. Even-numbered context IDs are client-initiated, while odd-numbered - context IDs are server-initiated. This means that an HTTP/3 client + context IDs are server-initiated. This means that an HTTP client implementation of the context ID allocation service MUST only provide even-numbered IDs, while a server implementation MUST only provide odd-numbered IDs. Note that, once allocated, any context ID can be used by both client and server - only allocation carries separate namespaces to avoid requiring synchronization. Additionally, note that the context ID namespace is tied to a given HTTP request: it is possible for the same numeral context ID to be used simultaneously in distinct requests. 3. HTTP/3 DATAGRAM Format When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM frames uses the following format (using the notation from the "Notational Conventions" section of [QUIC]): HTTP/3 Datagram { Quarter Stream ID (i), [Context ID (i)], - HTTP/3 Datagram Payload (..), + HTTP Datagram Payload (..), } Figure 1: HTTP/3 DATAGRAM Format Quarter Stream ID: A variable-length integer that contains the value of the client-initiated bidirectional stream that this datagram is associated with, divided by four. (The division by four stems from the fact that HTTP requests are sent on client-initiated bidirectional streams, and those have stream IDs that are divisible by four.) @@ -194,23 +203,23 @@ present depends on which registration capsules were exchanged on the associated stream: if a REGISTER_DATAGRAM_CONTEXT capsule (see Section 4.1) has been sent or received on this stream, then the field is present; if a REGISTER_DATAGRAM_NO_CONTEXT capsule (see Section 4.2) has been sent or received, then this field is absent; if neither has been sent or received, then it is not yet possible to parse this datagram and the receiver MUST either drop that datagram silently or buffer it temporarily while awaiting the registration capsule. - HTTP/3 Datagram Payload: The payload of the datagram, whose - semantics are defined by individual applications. Note that this - field can be empty. + HTTP Datagram Payload: The payload of the datagram, whose semantics + are defined by individual applications. Note that this field can + be empty. Intermediaries parse the Quarter Stream ID field in order to associate the QUIC DATAGRAM frame with a stream. If an intermediary receives a QUIC DATAGRAM frame whose payload is too short to allow parsing the Quarter Stream ID field, the intermediary MUST treat it as an HTTP/3 connection error of type H3_GENERAL_PROTOCOL_ERROR. The Context ID field is optional and its use is negotiated end-to-end, see Section 4.2. Therefore intermediaries cannot know whether the Context ID field is present or absent and they MUST ignore any HTTP/3 Datagram fields after the Quarter Stream ID. @@ -469,59 +478,59 @@ 4.4. The DATAGRAM Capsule The DATAGRAM capsule (type=0x02) allows an endpoint to send a datagram frame over an HTTP stream. This is particularly useful when using a version of HTTP that does not support QUIC DATAGRAM frames. Its Capsule Data field consists of: DATAGRAM Capsule { [Context ID (i)], - HTTP/3 Datagram Payload (..), + HTTP Datagram Payload (..), } Figure 6: DATAGRAM Capsule Format Context ID: A variable-length integer indicating the context ID of the datagram (see Section 2.1). Whether or not this field is present depends on which registration capsules were exchanged on the associated stream: if a REGISTER_DATAGRAM_CONTEXT capsule (see Section 4.1) has been sent or received on this stream, then the field is present; if a REGISTER_DATAGRAM_NO_CONTEXT capsule (see Section 4.2) has been sent or received, then this field is absent; if neither has been sent or received, then it is not yet possible to parse this datagram and the receiver MUST either drop that datagram silently or buffer it temporarily while awaiting the registration capsule. - HTTP/3 Datagram Payload: The payload of the datagram, whose - semantics are defined by individual applications. Note that this - field can be empty. + HTTP Datagram Payload: The payload of the datagram, whose semantics + are defined by individual applications. Note that this field can + be empty. Datagrams sent using the DATAGRAM Capsule have the exact same semantics as datagrams sent in QUIC DATAGRAM frames. In particular, - the restrictions on when it is allowed to send an HTTP/3 datagram and - how to process them from Section 3 also apply to HTTP/3 datagrams - sent and received using the DATAGRAM capsule. + the restrictions on when it is allowed to send an HTTP Datagram and + how to process them from Section 3 also apply to HTTP Datagrams sent + and received using the DATAGRAM capsule. The DATAGRAM Capsule is transparent to intermediaries, meaning that intermediaries MAY parse it and send DATAGRAM Capsules that they did - not receive. This allows an intermediary to reencode HTTP/3 - Datagrams as it forwards them: in other words, an intermediary MAY - send a DATAGRAM Capsule to forward an HTTP/3 Datagram which was - received in a QUIC DATAGRAM frame, and vice versa. + not receive. This allows an intermediary to reencode HTTP Datagrams + as it forwards them: in other words, an intermediary MAY send a + DATAGRAM Capsule to forward an HTTP Datagram which was received in a + QUIC DATAGRAM frame, and vice versa. Note that while DATAGRAM capsules are sent on a stream, - intermediaries can reencode HTTP/3 datagrams into QUIC DATAGRAM - frames over the next hop, and those could be dropped. Because of - this, applications have to always consider HTTP/3 datagrams to be - unreliable, even if they were initially sent in a capsule. + intermediaries can reencode HTTP Datagrams into QUIC DATAGRAM frames + over the next hop, and those could be dropped. Because of this, + applications have to always consider HTTP Datagrams to be unreliable, + even if they were initially sent in a capsule. 5. Context Extensibility In order to facilitate extensibility of contexts, the REGISTER_DATAGRAM_CONTEXT, REGISTER_DATAGRAM_NO_CONTEXT, and the CLOSE_DATAGRAM_CONTEXT capsules carry a Context Extensions field. That field contains a sequence of context extensions: Context Extensions { Context Extension (..) ..., @@ -611,22 +620,22 @@ prioritization preferences. 8. HTTP/1.x and HTTP/2 Support We can provide DATAGRAM support in HTTP/2 by defining the CAPSULE frame in HTTP/2. We can provide DATAGRAM support in HTTP/1.x by defining its data stream format to a sequence of length-value capsules. - TODO: Refactor this document into "HTTP Datagrams" with definitions - for HTTP/1.x, HTTP/2, and HTTP/3. + TODO: Refactor this document and add definitions for HTTP/1.x and + HTTP/2. 9. Security Considerations Since this feature requires sending an HTTP/3 Settings parameter, it "sticks out". In other words, probing clients can learn whether a server supports this feature. Implementations that support this feature SHOULD always send this Settings parameter to avoid leaking the fact that there are applications using HTTP/3 datagrams enabled on this endpoint. @@ -636,34 +645,34 @@ This document will request IANA to register the following entry in the "HTTP/3 Frames" registry: +------------+----------+---------------+ | Frame Type | Value | Specification | +============+==========+===============+ | CAPSULE | 0xffcab5 | This Document | +------------+----------+---------------+ -10.2. HTTP SETTINGS Parameter +10.2. HTTP/3 SETTINGS Parameter This document will request IANA to register the following entry in the "HTTP/3 Settings" registry: +--------------+----------+---------------+---------+ | Setting Name | Value | Specification | Default | +==============+==========+===============+=========+ | H3_DATAGRAM | 0xffd276 | This Document | 0 | +--------------+----------+---------------+---------+ 10.3. Capsule Types - This document establishes a registry for HTTP/3 capsule type codes. + This document establishes a registry for HTTP capsule type codes. The "HTTP Capsule Types" registry governs a 62-bit space. Registrations in this registry MUST include the following fields: Type: A name or label for the capsule type. Value: The value of the Capsule Type field (see Section 4) is a 62bit integer. @@ -689,21 +698,21 @@ +------------------------------+-------+---------------+ Capsule types with a value of the form 41 * N + 23 for integer values of N are reserved to exercise the requirement that unknown capsule types be ignored. These capsules have no semantics and can carry arbitrary values. These values MUST NOT be assigned by IANA and MUST NOT appear in the listing of assigned values. 10.4. Context Extension Types - This document establishes a registry for HTTP/3 datagram context + This document establishes a registry for HTTP datagram context extension type codes. The "HTTP Context Extension Types" registry governs a 62-bit space. Registrations in this registry MUST include the following fields: Type: A name or label for the context extension type. Value: The value of the Context Extension Type field (see Section 5) is a 62bit integer. @@ -717,32 +726,31 @@ This registry initially contains the following entries: +------------------------------+-------+---------------+ | Context Extension Type | Value | Specification | +------------------------------+-------+---------------+ | CLOSE_CODE | 0x00 | This Document | +------------------------------+-------+---------------+ | DETAILS | 0x01 | This Document | +------------------------------+-------+---------------+ - Context extension types with a value of the form 41 * N + 17 for integer values of N are reserved to exercise the requirement that unknown context extension types be ignored. These extensions have no semantics and can carry arbitrary values. These values MUST NOT be assigned by IANA and MUST NOT appear in the listing of assigned values. 10.5. Context Close Codes - This document establishes a registry for HTTP/3 context extension - type codes. The "HTTP Context Close Codes" registry governs a 62-bit + This document establishes a registry for HTTP context extension type + codes. The "HTTP Context Close Codes" registry governs a 62-bit space. Registrations in this registry MUST include the following fields: Type: A name or label for the close code. Value: The value of the CLOSE_CODE Context Extension Value field (see Section 5.1) is a 62bit integer. @@ -768,39 +776,41 @@ Context close codes with a value of the form 41 * N + 19 for integer values of N are reserved to exercise the requirement that unknown context close codes be treated as NO_ERROR. These values MUST NOT be assigned by IANA and MUST NOT appear in the listing of assigned values. 11. Normative References [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable Datagram Extension to QUIC", Work in Progress, Internet- - Draft, draft-ietf-quic-datagram-02, 16 February 2021, - . + Draft, draft-ietf-quic-datagram-03, 12 July 2021, + . [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- quic-http-34, 2 February 2021, - . + . [IANA-POLICY] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed and Secure Transport", Work in Progress, Internet-Draft, draft-ietf-quic-transport-34, 14 January 2021, - . + . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, .