idnits 2.17.1 draft-schinazi-masque-h3-datagram-03.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 (5 January 2021) is 1178 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 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-33 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 4 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: 9 July 2021 Cloudflare 6 5 January 2021 8 Using QUIC Datagrams with HTTP/3 9 draft-schinazi-masque-h3-datagram-03 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: 27 https://github.com/DavidSchinazi/draft-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 9 July 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 10. Normative References . . . . . . . . . . . . . . . . . . . . 8 75 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 78 1. Introduction 80 The QUIC DATAGRAM extension [DGRAM] provides application protocols 81 running over QUIC [QUIC] with a mechanism to send unreliable data 82 while leveraging the security and congestion-control properties of 83 QUIC. However, QUIC DATAGRAM frames do not provide a means to 84 demultiplex application contexts. This document defines how to use 85 QUIC DATAGRAM frames when the application protocol running over QUIC 86 is HTTP/3 [H3] by adding an identifier at the start of the frame 87 payload. This allows HTTP messages to convey related information 88 using unreliable DATAGRAM frames, ensuring those frames are properly 89 associated with an HTTP message. 91 This design mimics the use of Stream Types in HTTP/3, which provide a 92 demultiplexing identifier at the start of each unidirectional stream. 94 Discussion of this work is encouraged to happen on the MASQUE IETF 95 mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the 96 GitHub repository which contains the draft: 97 https://github.com/DavidSchinazi/draft-h3-datagram. 99 1.1. Conventions and Definitions 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 103 "OPTIONAL" in this document are to be interpreted as described in BCP 104 14 [RFC2119] [RFC8174] when, and only when, they appear in all 105 capitals, as shown here. 107 2. Flow Identifiers 109 Flow identifiers represent bidirectional flows of datagrams within a 110 single QUIC connection. These are conceptually similar to streams in 111 the sense that they allow multiplexing of application data. Flows 112 lack any of the ordering or reliability guarantees of streams. 114 Beyond this, a sender SHOULD ensure that DATAGRAM frames within a 115 single flow are transmitted in order relative to one another. If 116 multiple DATAGRAM frames can be packed into a single QUIC packet, the 117 sender SHOULD group them by flow identifier to promote fate-sharing 118 within a specific flow and improve the ability to process batches of 119 datagram messages efficiently on the receiver. 121 3. Flow Identifier Allocation 123 Implementations of HTTP/3 that support the DATAGRAM extension MUST 124 provide a flow identifier allocation service. That service will 125 allow applications co-located with HTTP/3 to request a unique flow 126 identifier that they can subsequently use for their own purposes. 127 The HTTP/3 implementation will then parse the flow identifier of 128 incoming DATAGRAM frames and use it to deliver the frame to the 129 appropriate application. 131 Even-numbered flow identifiers are client-initiated, while odd- 132 numbered flow identifiers are server-initiated. This means that an 133 HTTP/3 client implementation of the flow identifier allocation 134 service MUST only provide even-numbered identifiers, while a server 135 implementation MUST only provide odd-numbered identifiers. Note 136 that, once allocated, any flow identifier can be used by both client 137 and server - only allocation carries separate namespaces to avoid 138 requiring synchronization. 140 The flow allocation service SHOULD also provide a mechanism for 141 applications to indicate they have completed their usage of a flow 142 identifier and will no longer be using that flow identifier, this 143 process is called "retiring" a flow identifier. Applications MUST 144 NOT retire a flow identifier until after they have received 145 confirmation that the peer has also stopped using that flow 146 identifier. The flow identifier allocation service MAY reuse 147 previously retired flow identifiers once they have ascertained that 148 there are no packets with DATAGRAM frames using that flow identifier 149 still in flight. Reusing flow identifiers can improve performance by 150 transmitting the flow identifier using a shorter variable-length 151 integer encoding. 153 4. HTTP/3 DATAGRAM Frame Format 155 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 156 frames uses the following format (using the notation from the 157 "Notational Conventions" section of [QUIC]): 159 HTTP/3 DATAGRAM Frame { 160 Flow Identifier (i), 161 HTTP/3 Datagram Payload (..), 162 } 164 Figure 1: HTTP/3 DATAGRAM Frame Format 166 Flow Identifier: A variable-length integer indicating the Flow 167 Identifier of the datagram (see Section 2). 169 HTTP/3 Datagram Payload: The payload of the datagram, whose 170 semantics are defined by individual applications. Note that this 171 field can be empty. 173 Endpoints MUST treat receipt of a DATAGRAM frame whose payload is too 174 short to parse the flow identifier as an HTTP/3 connection error of 175 type H3_GENERAL_PROTOCOL_ERROR. 177 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter 179 Implementations of HTTP/3 that support this mechanism can indicate 180 that to their peer by sending the H3_DATAGRAM SETTINGS parameter with 181 a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST 182 be either 0 or 1. A value of 0 indicates that this mechanism is not 183 supported. An endpoint that receives the H3_DATAGRAM SETTINGS 184 parameter with a value that is neither 0 or 1 MUST terminate the 185 connection with error H3_SETTINGS_ERROR. 187 An endpoint that sends the H3_DATAGRAM SETTINGS parameter with a 188 value of 1 MUST send the max_datagram_frame_size QUIC Transport 189 Parameter [DGRAM]. An endpoint that receives the H3_DATAGRAM 190 SETTINGS parameter with a value of 1 on a QUIC connection that did 191 not also receive the max_datagram_frame_size QUIC Transport Parameter 192 MUST terminate the connection with error H3_SETTINGS_ERROR. 194 When clients use 0-RTT, they MAY store the value of the server's 195 H3_DATAGRAM SETTINGS parameter. Doing so allows the client to use 196 HTTP/3 datagrams in 0-RTT packets. When servers decide to accept 197 0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater 198 than or equal to the value they sent to the client in the connection 199 where they sent them the NewSessionTicket message. If a client 200 stores the value of the H3_DATAGRAM SETTINGS parameter with their 201 0-RTT state, they MUST validate that the new value of the H3_DATAGRAM 202 SETTINGS parameter sent by the server in the handshake is greater 203 than or equal to the stored value; if not, the client MUST terminate 204 the connection with error H3_SETTINGS_ERROR. In all cases, the 205 maximum permitted value of the H3_DATAGRAM SETTINGS parameter is 1. 207 6. Datagram-Flow-Id Header Field Definition 209 "Datagram-Flow-Id" is a List Structured Field [STRUCT-FIELD], whose 210 members MUST all be Items of type Integer. Its ABNF is: 212 Datagram-Flow-Id = sf-list 214 The "Datagram-Flow-Id" header field is used to associate one or more 215 datagram flow identifiers with an HTTP message. As a simple example 216 using a single identifier, the definition of an HTTP method could 217 instruct the client to use its flow identifier allocation service to 218 allocate a new flow identifier, and then the client will add the 219 "Datagram-Flow-Id" header field to its request to communicate that 220 value to the server. In this example, the resulting header field 221 could look like: 223 Datagram-Flow-Id = 2 225 List members are flow identifier elements, which can be named or 226 unnamed. One element in the list is allowed to be unnamed, but all 227 but one elements MUST carry a name. The name of an element is 228 encoded in the key of the first parameter of that element (parameters 229 are defined in Section 3.1.2 of [STRUCT-FIELD]). Each name MUST NOT 230 appear more than once in the list. The value of the first parameter 231 of each named element (whose corresponding key conveys the element 232 name) MUST be of type Boolean and equal to true. The value of the 233 first parameter of the unnamed element MUST NOT be of type Boolean. 234 The ordering of the list does not carry any semantics. For example, 235 an HTTP method that wishes to use four datagram flow identifiers for 236 the lifetime of its request stream could look like this: 238 Datagram-Flow-Id = 42, 44; ecn-ect0, 46; ecn-ect1, 48; ecn-ce 240 In this example, 42 is the unnamed flow identifier, 44 represents the 241 name "ecn-ect0", 46 represents "ecn-ect1", and 48 represents "ecn- 242 ce". Note that, since the list ordering does not carry semantics, 243 this example can be equivalently encoded as: 245 Datagram-Flow-Id = 44; ecn-ect0, 42, 48; ecn-ce, 46; ecn-ect1 247 Even if a sender attempts to communicate the meaning of a flow 248 identifier before it uses it in an HTTP/3 datagram, it is possible 249 that its peer will receive an HTTP/3 datagram with a flow identifier 250 that it does not know as it has not yet received the corresponding 251 "Datagram-Flow-Id" header field. (For example, this could happen if 252 the QUIC STREAM frame that contains the "Datagram-Flow-Id" header 253 field is reordered and arrives afer the DATAGRAM frame.) Endpoints 254 MUST NOT treat that scenario as an error; they MUST either silently 255 discard the datagram or buffer it until they receive the "Datagram- 256 Flow-Id" header field. 258 Distinct HTTP requests MAY refer to the same flow identifier in their 259 respective "Datagram-Flow-Id" header fields. 261 Note that integer structured fields can only encode values up to 262 10^15-1, therefore the maximum possible value of an element of the 263 "Datagram-Flow-Id" header field is lower then the theoretical maximum 264 value of a flow identifier which is 2^62-1 due to the QUIC variable 265 length integer encoding. If the flow identifier allocation service 266 of an endpoint runs out of values lower than 10^15-1, the endpoint 267 MUST fail the flow identifier allocation. An HTTP message that 268 carries a "Datagram-Flow-Id" header field with a flow identifier 269 value above 10^15-1 is malformed (see Section 8.1.2.6 of [H2]). 271 7. HTTP Intermediaries 273 HTTP/3 DATAGRAM flow identifiers are specific to a given HTTP/3 274 connection. However, in some cases, an HTTP request may travel 275 across multiple HTTP connections if there are HTTP intermediaries 276 involved; see Section 2.3 of [RFC7230]. 278 If an intermediary has sent the H3_DATAGRAM SETTINGS parameter with a 279 value of 1 on its client-facing connection, it MUST inspect all HTTP 280 requests from that connection and check for the presence of the 281 "Datagram-Flow-Id" header field. If the HTTP method of the request 282 is not supported by the intermediary, it MUST remove the "Datagram- 283 Flow-Id" header field before forwarding the request. If the 284 intermediary supports the method, it MUST either remove the header 285 field or adhere to the requirements leveraged by that method on 286 intermediaries. 288 If an intermediary has sent the H3_DATAGRAM SETTINGS parameter with a 289 value of 1 on its server-facing connection, it MUST inspect all HTTP 290 responses from that connection and check for the presence of the 291 "Datagram-Flow-Id" header field. If the HTTP method of the request 292 is not supported by the intermediary, it MUST remove the "Datagram- 293 Flow-Id" header field before forwarding the response. If the 294 intermediary supports the method, it MUST either remove the header 295 field or adhere to the requirements leveraged by that method on 296 intermediaries. 298 If an intermediary processes distinct HTTP requests that refer to the 299 same flow identifier in their respective "Datagram-Flow-Id" header 300 fields, it MUST ensure that those requests are routed to the same 301 backend. 303 8. Security Considerations 305 This document does not have additional security considerations beyond 306 those defined in [QUIC] and [DGRAM]. 308 9. IANA Considerations 310 9.1. HTTP SETTINGS Parameter 312 This document will request IANA to register the following entry in 313 the "HTTP/3 Settings" registry: 315 +--------------+-------+---------------+---------+ 316 | Setting Name | Value | Specification | Default | 317 +==============+=======+===============+=========+ 318 | H3_DATAGRAM | 0x276 | This Document | 0 | 319 +--------------+-------+---------------+---------+ 321 9.2. HTTP Header Field 323 This document will request IANA to register the "Datagram-Flow-Id" 324 header field in the "Permanent Message Header Field Names" registry 325 maintained at . 327 +-------------------+----------+--------+---------------+ 328 | Header Field Name | Protocol | Status | Reference | 329 +-------------------+----------+--------+---------------+ 330 | Datagram-Flow-Id | http | std | This document | 331 +-------------------+----------+--------+---------------+ 333 10. Normative References 335 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 336 Datagram Extension to QUIC", Work in Progress, Internet- 337 Draft, draft-ietf-quic-datagram-01, 24 August 2020, 338 . 341 [H2] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 342 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 343 DOI 10.17487/RFC7540, May 2015, 344 . 346 [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 347 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 348 quic-http-33, 15 December 2020, . 351 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 352 and Secure Transport", Work in Progress, Internet-Draft, 353 draft-ietf-quic-transport-33, 13 December 2020, 354 . 357 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 358 Requirement Levels", BCP 14, RFC 2119, 359 DOI 10.17487/RFC2119, March 1997, 360 . 362 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 363 Protocol (HTTP/1.1): Message Syntax and Routing", 364 RFC 7230, DOI 10.17487/RFC7230, June 2014, 365 . 367 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 368 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 369 May 2017, . 371 [STRUCT-FIELD] 372 Nottingham, M. and P. Kamp, "Structured Field Values for 373 HTTP", Work in Progress, Internet-Draft, draft-ietf- 374 httpbis-header-structure-19, 3 June 2020, 375 . 378 Acknowledgments 380 The DATAGRAM flow identifier was previously part of the DATAGRAM 381 frame definition itself, the author would like to acknowledge the 382 authors of that document and the members of the IETF MASQUE working 383 group for their suggestions. Additionally, the author would like to 384 thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS 385 parameter. 387 Authors' Addresses 389 David Schinazi 390 Google LLC 391 1600 Amphitheatre Parkway 392 Mountain View, California 94043, 393 United States of America 395 Email: dschinazi.ietf@gmail.com 397 Lucas Pardue 398 Cloudflare 400 Email: lucaspardue.24.7@gmail.com