idnits 2.17.1 draft-schinazi-masque-h3-datagram-02.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 (14 December 2020) is 1228 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 == Outdated reference: A later version (-34) exists of draft-ietf-quic-http-32 == 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: 1 error (**), 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: 17 June 2021 Cloudflare 6 14 December 2020 8 Using QUIC Datagrams with HTTP/3 9 draft-schinazi-masque-h3-datagram-02 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 17 June 2021. 46 Copyright Notice 48 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . . . 6 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 6 71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 72 9.1. HTTP SETTINGS Parameter . . . . . . . . . . . . . . . . . 6 73 9.2. HTTP Header Field . . . . . . . . . . . . . . . . . . . . 7 74 10. Normative References . . . . . . . . . . . . . . . . . . . . 7 75 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8 76 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 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 4. HTTP/3 DATAGRAM Frame Format 142 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 143 frames uses the following format (using the notation from the 144 "Notational Conventions" section of [QUIC]): 146 HTTP/3 DATAGRAM Frame { 147 Flow Identifier (i), 148 HTTP/3 Datagram Payload (..), 149 } 151 Figure 1: HTTP/3 DATAGRAM Frame Format 153 Flow Identifier: A variable-length integer indicating the Flow 154 Identifier of the datagram (see Section 2). 156 HTTP/3 Datagram Payload: The payload of the datagram, whose 157 semantics are defined by individual applications. Note that this 158 field can be empty. 160 Endpoints MUST treat receipt of a DATAGRAM frame whose payload is too 161 short to parse the flow identifier as a connection error of type 162 PROTOCOL_VIOLATION. 164 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter 166 Implementations of HTTP/3 that support this mechanism can indicate 167 that to their peer by sending the H3_DATAGRAM SETTINGS parameter with 168 a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST 169 be either 0 or 1. A value of 0 indicates that this mechanism is not 170 supported. An endpoint that receives the H3_DATAGRAM SETTINGS 171 parameter with a value that is neither 0 or 1 MUST terminate the 172 connection with error H3_SETTINGS_ERROR. 174 An endpoint that sends the H3_DATAGRAM SETTINGS parameter with a 175 value of 1 MUST send the max_datagram_frame_size QUIC Transport 176 Parameter [DGRAM]. An endpoint that receives the H3_DATAGRAM 177 SETTINGS parameter with a value of 1 on a QUIC connection that did 178 not also receive the max_datagram_frame_size QUIC Transport Parameter 179 MUST terminate the connection with error H3_SETTINGS_ERROR. 181 When clients use 0-RTT, they MAY store the value of the server's 182 H3_DATAGRAM SETTINGS parameter. Doing so allows the client to use 183 HTTP/3 datagrams in 0-RTT packets. When servers decide to accept 184 0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater 185 or equal to the value they sent to the client in the connection where 186 they sent them the NewSessionTicket message. If a client stores the 187 value of the H3_DATAGRAM SETTINGS parameter with their 0-RTT state, 188 they MUST validate that the new value of the H3_DATAGRAM SETTINGS 189 parameter sent by the server in the handshake is greater or equal to 190 the stored value; if not, the client MUST terminate the connection 191 with error H3_SETTINGS_ERROR. 193 6. Datagram-Flow-Id Header Field Definition 195 "Datagram-Flow-Id" is a Item Structured Field [STRUCT-FIELD]. Its 196 value MUST be an Integer. Its ABNF is: 198 Datagram-Flow-Id = sf-integer 200 The "Datagram-Flow-Id" header field is used to associate a datagram 201 flow identifier with an HTTP message. For example, the definition of 202 an HTTP method could instruct the client to use its flow identifier 203 allocation service to allocate a new flow identifier, and then the 204 client will add the "Datagram-Flow-Id" header field to its request to 205 communicate that value to the server. For example, the resulting 206 header field could look like: 208 Datagram-Flow-Id = 2 210 Definitions of HTTP features that use the "Datagram-Flow-Id" header 211 field MAY define their own parameters (parameters are defined in 212 Section 3.1.2 of [STRUCT-FIELD]). For example, an HTTP method that 213 wishes to use two datagram flow identifiers for the lifetime of its 214 request stream could encode the second flow identifier as a 215 parameter, which could look like this: 217 Datagram-Flow-Id = 42; alternate=44 219 The "Datagram-Flow-Id" header field MUST NOT be present more than 220 once on a given HTTP message; any HTTP message containing more than 221 one "Datagram-Flow-Id" header field is malformed. 223 Since the QUIC STREAM frame that contains the "Datagram-Flow-Id" 224 header field could be lost or reordered, it is possible that an 225 endpoint will receive an HTTP/3 datagram with a flow identifier that 226 it does not know as it has not yet received the corresponding 227 "Datagram-Flow-Id" header field. Endpoints MUST NOT treat that as an 228 error; they MUST either silently discard the datagram or buffer it 229 until they receive the "Datagram-Flow-Id" header field. 231 Note that integer structured fields can only encode values up to 232 10^15-1, therefore the maximum possible value of the "Datagram-Flow- 233 Id" header field is lower then the theoretical maximum value of a 234 flow identifier which is 2^62-1 due to the QUIC variable length 235 integer encoding. If the flow identifier allocation service of an 236 endpoint runs out of values lower than 10^15-1, the endpoint MUST 237 treat is as a connection error of type H3_ID_ERROR. 239 7. HTTP Intermediaries 241 HTTP/3 DATAGRAM flow identifiers are specific to a given HTTP/3 242 connection. However, in some cases, an HTTP request may travel 243 across multiple HTTP connections if there are HTTP intermediaries 244 involved; see Section 2.3 of [RFC7230]. 246 If an intermediary has sent the H3_DATAGRAM SETTINGS parameter with a 247 value of 1 on its client-facing connection, it MUST inspect all HTTP 248 requests from that connection and check for the presence of the 249 "Datagram-Flow-Id" header field. If the HTTP method of the request 250 is not supported by the intermediary, it MUST remove the "Datagram- 251 Flow-Id" header field before forwarding the request. If the 252 intermediary supports the method, it MUST either remove the header 253 field or adhere to the requirements leveraged by that method on 254 intermediaries. 256 If an intermediary has sent the H3_DATAGRAM SETTINGS parameter with a 257 value of 1 on its server-facing connection, it MUST inspect all HTTP 258 responses from that connection and check for the presence of the 259 "Datagram-Flow-Id" header field. If the HTTP method of the request 260 is not supported by the intermediary, it MUST remove the "Datagram- 261 Flow-Id" header field before forwarding the response. If the 262 intermediary supports the method, it MUST either remove the header 263 field or adhere to the requirements leveraged by that method on 264 intermediaries. 266 8. Security Considerations 268 This document does not have additional security considerations beyond 269 those defined in [QUIC] and [DGRAM]. 271 9. IANA Considerations 273 9.1. HTTP SETTINGS Parameter 275 This document will request IANA to register the following entry in 276 the "HTTP/3 Settings" registry: 278 +--------------+-------+---------------+---------+ 279 | Setting Name | Value | Specification | Default | 280 +==============+=======+===============+=========+ 281 | H3_DATAGRAM | 0x276 | This Document | 0 | 282 +--------------+-------+---------------+---------+ 284 9.2. HTTP Header Field 286 This document will request IANA to register the "Datagram-Flow-Id" 287 header field in the "Permanent Message Header Field Names" registry 288 maintained at . 290 +-------------------+----------+--------+---------------+ 291 | Header Field Name | Protocol | Status | Reference | 292 +-------------------+----------+--------+---------------+ 293 | Datagram-Flow-Id | http | std | This document | 294 +-------------------+----------+--------+---------------+ 296 10. Normative References 298 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 299 Datagram Extension to QUIC", Work in Progress, Internet- 300 Draft, draft-ietf-quic-datagram-01, 24 August 2020, 301 . 304 [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 305 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 306 quic-http-32, 20 October 2020, . 309 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 310 and Secure Transport", Work in Progress, Internet-Draft, 311 draft-ietf-quic-transport-33, 13 December 2020, 312 . 315 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 316 Requirement Levels", BCP 14, RFC 2119, 317 DOI 10.17487/RFC2119, March 1997, 318 . 320 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 321 Protocol (HTTP/1.1): Message Syntax and Routing", 322 RFC 7230, DOI 10.17487/RFC7230, June 2014, 323 . 325 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 326 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 327 May 2017, . 329 [STRUCT-FIELD] 330 Nottingham, M. and P. Kamp, "Structured Field Values for 331 HTTP", Work in Progress, Internet-Draft, draft-ietf- 332 httpbis-header-structure-19, 3 June 2020, 333 . 336 Acknowledgments 338 The DATAGRAM flow identifier was previously part of the DATAGRAM 339 frame definition itself, the author would like to acknowledge the 340 authors of that document and the members of the IETF QUIC working 341 group for their suggestions. Additionally, the author would like to 342 thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS 343 parameter. 345 Authors' Addresses 347 David Schinazi 348 Google LLC 349 1600 Amphitheatre Parkway 350 Mountain View, California 94043, 351 United States of America 353 Email: dschinazi.ietf@gmail.com 355 Lucas Pardue 356 Cloudflare 358 Email: lucaspardue.24.7@gmail.com