idnits 2.17.1 draft-ietf-masque-h3-datagram-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (29 January 2021) is 1183 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-10) exists of draft-ietf-quic-datagram-01 ** Obsolete normative reference: RFC 7540 (ref. 'H2') (Obsoleted by RFC 9113) == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-33 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Schinazi 3 Internet-Draft Google LLC 4 Intended status: Standards Track L. Pardue 5 Expires: 2 August 2021 Cloudflare 6 29 January 2021 8 Using QUIC Datagrams with HTTP/3 9 draft-ietf-masque-h3-datagram-00 11 Abstract 13 The QUIC DATAGRAM extension provides application protocols running 14 over QUIC with a mechanism to send unreliable data while leveraging 15 the security and congestion-control properties of QUIC. However, 16 QUIC DATAGRAM frames do not provide a means to demultiplex 17 application contexts. This document defines how to use QUIC DATAGRAM 18 frames when the application protocol running over QUIC is HTTP/3 by 19 adding an identifier at the start of the frame payload. This allows 20 HTTP messages to convey related information using unreliable DATAGRAM 21 frames, ensuring those frames are properly associated with an HTTP 22 message. 24 Discussion of this work is encouraged to happen on the MASQUE IETF 25 mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the 26 GitHub repository which contains the draft: https://github.com/ietf- 27 wg-masque/draft-ietf-masque-h3-datagram. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 2 August 2021. 46 Copyright Notice 48 Copyright (c) 2021 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 64 2. Flow Identifiers . . . . . . . . . . . . . . . . . . . . . . 3 65 3. Flow Identifier Allocation . . . . . . . . . . . . . . . . . 3 66 4. HTTP/3 DATAGRAM Frame Format . . . . . . . . . . . . . . . . 4 67 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . . . . . 4 68 6. Datagram-Flow-Id Header Field Definition . . . . . . . . . . 5 69 7. HTTP Intermediaries . . . . . . . . . . . . . . . . . . . . . 7 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 7 71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 72 9.1. HTTP SETTINGS Parameter . . . . . . . . . . . . . . . . . 7 73 9.2. HTTP Header Field . . . . . . . . . . . . . . . . . . . . 8 74 9.3. Flow Identifier Parameters . . . . . . . . . . . . . . . 8 75 10. Normative References . . . . . . . . . . . . . . . . . . . . 8 76 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 10 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 79 1. Introduction 81 The QUIC DATAGRAM extension [DGRAM] provides application protocols 82 running over QUIC [QUIC] with a mechanism to send unreliable data 83 while leveraging the security and congestion-control properties of 84 QUIC. However, QUIC DATAGRAM frames do not provide a means to 85 demultiplex application contexts. This document defines how to use 86 QUIC DATAGRAM frames when the application protocol running over QUIC 87 is HTTP/3 [H3] by adding an identifier at the start of the frame 88 payload. This allows HTTP messages to convey related information 89 using unreliable DATAGRAM frames, ensuring those frames are properly 90 associated with an HTTP message. 92 This design mimics the use of Stream Types in HTTP/3, which provide a 93 demultiplexing identifier at the start of each unidirectional stream. 95 Discussion of this work is encouraged to happen on the MASQUE IETF 96 mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the 97 GitHub repository which contains the draft: https://github.com/ietf- 98 wg-masque/draft-ietf-masque-h3-datagram. 100 1.1. Conventions and Definitions 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in BCP 105 14 [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 2. Flow Identifiers 110 Flow identifiers represent bidirectional flows of datagrams within a 111 single QUIC connection. These are conceptually similar to streams in 112 the sense that they allow multiplexing of application data. Flows 113 lack any of the ordering or reliability guarantees of streams. 115 Beyond this, a sender SHOULD ensure that DATAGRAM frames within a 116 single flow are transmitted in order relative to one another. If 117 multiple DATAGRAM frames can be packed into a single QUIC packet, the 118 sender SHOULD group them by flow identifier to promote fate-sharing 119 within a specific flow and improve the ability to process batches of 120 datagram messages efficiently on the receiver. 122 3. Flow Identifier Allocation 124 Implementations of HTTP/3 that support the DATAGRAM extension MUST 125 provide a flow identifier allocation service. That service will 126 allow applications co-located with HTTP/3 to request a unique flow 127 identifier that they can subsequently use for their own purposes. 128 The HTTP/3 implementation will then parse the flow identifier of 129 incoming DATAGRAM frames and use it to deliver the frame to the 130 appropriate application. 132 Even-numbered flow identifiers are client-initiated, while odd- 133 numbered flow identifiers are server-initiated. This means that an 134 HTTP/3 client implementation of the flow identifier allocation 135 service MUST only provide even-numbered identifiers, while a server 136 implementation MUST only provide odd-numbered identifiers. Note 137 that, once allocated, any flow identifier can be used by both client 138 and server - only allocation carries separate namespaces to avoid 139 requiring synchronization. 141 The flow allocation service SHOULD also provide a mechanism for 142 applications to indicate they have completed their usage of a flow 143 identifier and will no longer be using that flow identifier, this 144 process is called "retiring" a flow identifier. Applications MUST 145 NOT retire a flow identifier until after they have received 146 confirmation that the peer has also stopped using that flow 147 identifier. The flow identifier allocation service MAY reuse 148 previously retired flow identifiers once they have ascertained that 149 there are no packets with DATAGRAM frames using that flow identifier 150 still in flight. Reusing flow identifiers can improve performance by 151 transmitting the flow identifier using a shorter variable-length 152 integer encoding. 154 4. HTTP/3 DATAGRAM Frame Format 156 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 157 frames uses the following format (using the notation from the 158 "Notational Conventions" section of [QUIC]): 160 HTTP/3 DATAGRAM Frame { 161 Flow Identifier (i), 162 HTTP/3 Datagram Payload (..), 163 } 165 Figure 1: HTTP/3 DATAGRAM Frame Format 167 Flow Identifier: A variable-length integer indicating the Flow 168 Identifier of the datagram (see Section 2). 170 HTTP/3 Datagram Payload: The payload of the datagram, whose 171 semantics are defined by individual applications. Note that this 172 field can be empty. 174 Endpoints MUST treat receipt of a DATAGRAM frame whose payload is too 175 short to parse the flow identifier as an HTTP/3 connection error of 176 type H3_GENERAL_PROTOCOL_ERROR. 178 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter 180 Implementations of HTTP/3 that support this mechanism can indicate 181 that to their peer by sending the H3_DATAGRAM SETTINGS parameter with 182 a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST 183 be either 0 or 1. A value of 0 indicates that this mechanism is not 184 supported. An endpoint that receives the H3_DATAGRAM SETTINGS 185 parameter with a value that is neither 0 or 1 MUST terminate the 186 connection with error H3_SETTINGS_ERROR. 188 An endpoint that sends the H3_DATAGRAM SETTINGS parameter with a 189 value of 1 MUST send the max_datagram_frame_size QUIC Transport 190 Parameter [DGRAM]. An endpoint that receives the H3_DATAGRAM 191 SETTINGS parameter with a value of 1 on a QUIC connection that did 192 not also receive the max_datagram_frame_size QUIC Transport Parameter 193 MUST terminate the connection with error H3_SETTINGS_ERROR. 195 When clients use 0-RTT, they MAY store the value of the server's 196 H3_DATAGRAM SETTINGS parameter. Doing so allows the client to use 197 HTTP/3 datagrams in 0-RTT packets. When servers decide to accept 198 0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater 199 than or equal to the value they sent to the client in the connection 200 where they sent them the NewSessionTicket message. If a client 201 stores the value of the H3_DATAGRAM SETTINGS parameter with their 202 0-RTT state, they MUST validate that the new value of the H3_DATAGRAM 203 SETTINGS parameter sent by the server in the handshake is greater 204 than or equal to the stored value; if not, the client MUST terminate 205 the connection with error H3_SETTINGS_ERROR. In all cases, the 206 maximum permitted value of the H3_DATAGRAM SETTINGS parameter is 1. 208 6. Datagram-Flow-Id Header Field Definition 210 "Datagram-Flow-Id" is a List Structured Field [STRUCT-FIELD], whose 211 members MUST all be Items of type Integer. Its ABNF is: 213 Datagram-Flow-Id = sf-list 215 The "Datagram-Flow-Id" header field is used to associate one or more 216 datagram flow identifiers with an HTTP message. As a simple example 217 using a single identifier, the definition of an HTTP method could 218 instruct the client to use its flow identifier allocation service to 219 allocate a new flow identifier, and then the client will add the 220 "Datagram-Flow-Id" header field to its request to communicate that 221 value to the server. In this example, the resulting header field 222 could look like: 224 Datagram-Flow-Id = 2 226 List members are flow identifier elements, which can be named or 227 unnamed. One element in the list is allowed to be unnamed, but all 228 but one elements MUST carry a name. The name of an element is 229 encoded in the key of the first parameter of that element (parameters 230 are defined in Section 3.1.2 of [STRUCT-FIELD]). Each name MUST NOT 231 appear more than once in the list. The value of the first parameter 232 of each named element (whose corresponding key conveys the element 233 name) MUST be of type Boolean and equal to true. The value of the 234 first parameter of the unnamed element MUST NOT be of type Boolean. 235 The ordering of the list does not carry any semantics. For example, 236 an HTTP method that wishes to use four datagram flow identifiers for 237 the lifetime of its request stream could look like this: 239 Datagram-Flow-Id = 42, 44; ecn-ect0, 46; ecn-ect1, 48; ecn-ce 241 In this example, 42 is the unnamed flow identifier, 44 represents the 242 name "ecn-ect0", 46 represents "ecn-ect1", and 48 represents "ecn- 243 ce". Note that, since the list ordering does not carry semantics, 244 this example can be equivalently encoded as: 246 Datagram-Flow-Id = 44; ecn-ect0, 42, 48; ecn-ce, 46; ecn-ect1 248 Even if a sender attempts to communicate the meaning of a flow 249 identifier before it uses it in an HTTP/3 datagram, it is possible 250 that its peer will receive an HTTP/3 datagram with a flow identifier 251 that it does not know as it has not yet received the corresponding 252 "Datagram-Flow-Id" header field. (For example, this could happen if 253 the QUIC STREAM frame that contains the "Datagram-Flow-Id" header 254 field is reordered and arrives afer the DATAGRAM frame.) Endpoints 255 MUST NOT treat that scenario as an error; they MUST either silently 256 discard the datagram or buffer it until they receive the "Datagram- 257 Flow-Id" header field. 259 Distinct HTTP requests MAY refer to the same flow identifier in their 260 respective "Datagram-Flow-Id" header fields. 262 Note that integer structured fields can only encode values up to 263 10^15-1, therefore the maximum possible value of an element of the 264 "Datagram-Flow-Id" header field is lower then the theoretical maximum 265 value of a flow identifier which is 2^62-1 due to the QUIC variable 266 length integer encoding. If the flow identifier allocation service 267 of an endpoint runs out of values lower than 10^15-1, the endpoint 268 MUST fail the flow identifier allocation. An HTTP message that 269 carries a "Datagram-Flow-Id" header field with a flow identifier 270 value above 10^15-1 is malformed (see Section 8.1.2.6 of [H2]). 272 7. HTTP Intermediaries 274 HTTP/3 DATAGRAM flow identifiers are specific to a given HTTP/3 275 connection. However, in some cases, an HTTP request may travel 276 across multiple HTTP connections if there are HTTP intermediaries 277 involved; see Section 2.3 of [RFC7230]. 279 If an intermediary has sent the H3_DATAGRAM SETTINGS parameter with a 280 value of 1 on its client-facing connection, it MUST inspect all HTTP 281 requests from that connection and check for the presence of the 282 "Datagram-Flow-Id" header field. If the HTTP method of the request 283 is not supported by the intermediary, it MUST remove the "Datagram- 284 Flow-Id" header field before forwarding the request. If the 285 intermediary supports the method, it MUST either remove the header 286 field or adhere to the requirements leveraged by that method on 287 intermediaries. 289 If an intermediary has sent the H3_DATAGRAM SETTINGS parameter with a 290 value of 1 on its server-facing connection, it MUST inspect all HTTP 291 responses from that connection and check for the presence of the 292 "Datagram-Flow-Id" header field. If the HTTP method of the request 293 is not supported by the intermediary, it MUST remove the "Datagram- 294 Flow-Id" header field before forwarding the response. If the 295 intermediary supports the method, it MUST either remove the header 296 field or adhere to the requirements leveraged by that method on 297 intermediaries. 299 If an intermediary processes distinct HTTP requests that refer to the 300 same flow identifier in their respective "Datagram-Flow-Id" header 301 fields, it MUST ensure that those requests are routed to the same 302 backend. 304 8. Security Considerations 306 This document does not have additional security considerations beyond 307 those defined in [QUIC] and [DGRAM]. 309 9. IANA Considerations 311 9.1. HTTP SETTINGS Parameter 313 This document will request IANA to register the following entry in 314 the "HTTP/3 Settings" registry: 316 +--------------+-------+---------------+---------+ 317 | Setting Name | Value | Specification | Default | 318 +==============+=======+===============+=========+ 319 | H3_DATAGRAM | 0x276 | This Document | 0 | 320 +--------------+-------+---------------+---------+ 322 9.2. HTTP Header Field 324 This document will request IANA to register the "Datagram-Flow-Id" 325 header field in the "Permanent Message Header Field Names" registry 326 maintained at . 328 +-------------------+----------+--------+---------------+ 329 | Header Field Name | Protocol | Status | Reference | 330 +-------------------+----------+--------+---------------+ 331 | Datagram-Flow-Id | http | std | This document | 332 +-------------------+----------+--------+---------------+ 334 9.3. Flow Identifier Parameters 336 This document will request IANA to create an "HTTP Datagram Flow 337 Identifier Parameters" registry. Registrations in this registry MUST 338 include the following fields: 340 Key: The key of a parameter that is associated with a datagram flow 341 identifier list member (see Section 6). Keys MUST be valid 342 structured field parameter keys (see Section 3.1.2 of 343 [STRUCT-FIELD]). 345 Description: A brief description of the parameter semantics, which 346 MAY be a summary if a specification reference is provided. 348 Is Name: This field MUST be either Yes or No. Yes indicates that 349 this parameter is the name of a named element (see Section 6). No 350 indicates that it is a parameter that is not a name. 352 Reference: An optional reference to a specification for the 353 parameter. This field MAY be empty. 355 Registrations follow the "First Come First Served" policy (see 356 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 357 the same Key. This registry is initially empty. 359 10. Normative References 361 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 362 Datagram Extension to QUIC", Work in Progress, Internet- 363 Draft, draft-ietf-quic-datagram-01, 24 August 2020, 364 . 367 [H2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 368 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 369 DOI 10.17487/RFC7540, May 2015, 370 . 372 [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 373 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 374 quic-http-33, 15 December 2020, . 377 [IANA-POLICY] 378 Cotton, M., Leiba, B., and T. Narten, "Guidelines for 379 Writing an IANA Considerations Section in RFCs", BCP 26, 380 RFC 8126, DOI 10.17487/RFC8126, June 2017, 381 . 383 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 384 and Secure Transport", Work in Progress, Internet-Draft, 385 draft-ietf-quic-transport-34, 14 January 2021, 386 . 389 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 390 Requirement Levels", BCP 14, RFC 2119, 391 DOI 10.17487/RFC2119, March 1997, 392 . 394 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 395 Protocol (HTTP/1.1): Message Syntax and Routing", 396 RFC 7230, DOI 10.17487/RFC7230, June 2014, 397 . 399 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 400 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 401 May 2017, . 403 [STRUCT-FIELD] 404 Nottingham, M. and P. Kamp, "Structured Field Values for 405 HTTP", Work in Progress, Internet-Draft, draft-ietf- 406 httpbis-header-structure-19, 3 June 2020, 407 . 410 Acknowledgments 412 The DATAGRAM flow identifier was previously part of the DATAGRAM 413 frame definition itself, the author would like to acknowledge the 414 authors of that document and the members of the IETF MASQUE working 415 group for their suggestions. Additionally, the author would like to 416 thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS 417 parameter. 419 Authors' Addresses 421 David Schinazi 422 Google LLC 423 1600 Amphitheatre Parkway 424 Mountain View, California 94043, 425 United States of America 427 Email: dschinazi.ietf@gmail.com 429 Lucas Pardue 430 Cloudflare 432 Email: lucaspardue.24.7@gmail.com