idnits 2.17.1 draft-schinazi-masque-h3-datagram-01.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 (13 December 2020) is 1229 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-32 ** 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 13 December 2020 5 Expires: 16 June 2021 7 Using QUIC Datagrams with HTTP/3 8 draft-schinazi-masque-h3-datagram-01 10 Abstract 12 The QUIC DATAGRAM extension provides application protocols running 13 over QUIC with a mechanism to send unreliable data while leveraging 14 the security and congestion-control properties of QUIC. However, 15 QUIC DATAGRAM frames do not provide a means to demultiplex 16 application contexts. This document defines how to use QUIC DATAGRAM 17 frames when the application protocol running over QUIC is HTTP/3 by 18 adding an identifier at the start of the frame payload. This allows 19 HTTP messages to convey related information using unreliable DATAGRAM 20 frames, ensuring those frames are properly associated with an HTTP 21 message. 23 Discussion of this work is encouraged to happen on the MASQUE IETF 24 mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the 25 GitHub repository which contains the draft: 26 https://github.com/DavidSchinazi/draft-h3-datagram. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on 16 June 2021. 45 Copyright Notice 47 Copyright (c) 2020 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 52 license-info) in effect on the date of publication of this document. 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. Code Components 55 extracted from this document must include Simplified BSD License text 56 as described in Section 4.e of the Trust Legal Provisions and are 57 provided without warranty as described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 63 2. Flow Identifiers . . . . . . . . . . . . . . . . . . . . . . 3 64 3. Flow Identifier Allocation . . . . . . . . . . . . . . . . . 3 65 4. HTTP/3 DATAGRAM Frame Format . . . . . . . . . . . . . . . . 3 66 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . . . . . 4 67 6. Datagram-Flow-Id Header Definition . . . . . . . . . . . . . 5 68 7. HTTP Intermediaries . . . . . . . . . . . . . . . . . . . . . 6 69 8. Security Considerations . . . . . . . . . . . . . . . . . . . 6 70 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 71 9.1. HTTP SETTINGS Parameter . . . . . . . . . . . . . . . . . 6 72 9.2. HTTP Header . . . . . . . . . . . . . . . . . . . . . . . 6 73 10. Normative References . . . . . . . . . . . . . . . . . . . . 7 74 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8 77 1. Introduction 79 The QUIC DATAGRAM extension [DGRAM] provides application protocols 80 running over QUIC [QUIC] with a mechanism to send unreliable data 81 while leveraging the security and congestion-control properties of 82 QUIC. However, QUIC DATAGRAM frames do not provide a means to 83 demultiplex application contexts. This document defines how to use 84 QUIC DATAGRAM frames when the application protocol running over QUIC 85 is HTTP/3 [H3] by adding an identifier at the start of the frame 86 payload. This allows HTTP messages to convey related information 87 using unreliable DATAGRAM frames, ensuring those frames are properly 88 associated with an HTTP message. 90 This design mimics the use of Stream Types in HTTP/3, which provide a 91 demultiplexing identifier at the start of each unidirectional stream. 93 Discussion of this work is encouraged to happen on the MASQUE IETF 94 mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the 95 GitHub repository which contains the draft: 96 https://github.com/DavidSchinazi/draft-h3-datagram. 98 1.1. Conventions and Definitions 100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 102 "OPTIONAL" in this document are to be interpreted as described in BCP 103 14 [RFC2119] [RFC8174] when, and only when, they appear in all 104 capitals, as shown here. 106 2. Flow Identifiers 108 Flow identifiers represent bidirectional flows of datagrams within a 109 single QUIC connection. These are conceptually similar to streams in 110 the sense that they allow multiplexing of application data. Flows 111 lack any of the ordering or reliability guarantees of streams. 113 Beyond this, a sender SHOULD ensure that DATAGRAM frames within a 114 single flow are transmitted in order relative to one another. If 115 multiple DATAGRAM frames can be packed into a single QUIC packet, the 116 sender SHOULD group them by flow identifier to promote fate-sharing 117 within a specific flow and improve the ability to process batches of 118 datagram messages efficiently on the receiver. 120 3. Flow Identifier Allocation 122 Implementations of HTTP/3 that support the DATAGRAM extension MUST 123 provide a flow identifier allocation service. That service will 124 allow applications co-located with HTTP/3 to request a unique flow 125 identifier that they can subsequently use for their own purposes. 126 The HTTP/3 implementation will then parse the flow identifier of 127 incoming DATAGRAM frames and use it to deliver the frame to the 128 appropriate application. 130 Even flow identifiers are client-initiated, while odd flow 131 identifiers are server-initiated. This means that an HTTP/3 client 132 implementation of the flow identifier allocation service MUST only 133 provide even identifiers, while a server implementation MUST only 134 provide odd identifiers. Note that, once allocated, any flow 135 identifier can be used by both client and server - only allocation 136 carries separate namespaces to avoid requiring synchronization. 138 4. HTTP/3 DATAGRAM Frame Format 140 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 141 frames uses the following format (using the notation from the 142 "Notational Conventions" section of [QUIC]): 144 HTTP/3 DATAGRAM Frame { 145 Flow Identifier (i), 146 HTTP/3 Datagram Payload (..), 147 } 149 Figure 1: HTTP/3 DATAGRAM Frame Format 151 Flow Identifier: A variable-length integer indicating the Flow 152 Identifier of the datagram (see Section 2). 154 HTTP/3 Datagram Payload: The payload of the datagram, whose 155 semantics are defined by individual applications. Note that this 156 field can be empty. 158 Endpoints MUST treat receipt of a DATAGRAM frame whose payload is too 159 short to parse the flow identifier as a connection error of type 160 PROTOCOL_VIOLATION. 162 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter 164 Implementations of HTTP/3 that support this mechanism can indicate 165 that to their peer by sending the H3_DATAGRAM SETTINGS parameter with 166 a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST 167 be either 0 or 1. A value of 0 indicates that this mechanism is not 168 supported. An endpoint that receives the H3_DATAGRAM SETTINGS 169 parameter with a value that is neither 0 or 1 MUST terminate the 170 connection with error H3_SETTINGS_ERROR. 172 And endpoint that sends the H3_DATAGRAM SETTINGS parameter with a 173 value of 1 MUST send the max_datagram_frame_size QUIC Transport 174 Parameter [DGRAM]. An endpoint that receives the H3_DATAGRAM 175 SETTINGS parameter with a value of 1 on a QUIC connection that did 176 not also receive the max_datagram_frame_size QUIC Transport Parameter 177 MUST terminate the connection with error H3_SETTINGS_ERROR. 179 When clients use 0-RTT, they MAY store the value of the server's 180 H3_DATAGRAM SETTINGS parameter. Doing so allows the client to use 181 HTTP/3 datagrams in 0-RTT packets. When servers decide to accept 182 0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater 183 or equal to the value they sent to the client in the connection where 184 they sent them the NewSessionTicket message. If a client stores the 185 value of the H3_DATAGRAM SETTINGS parameter with their 0-RTT state, 186 they MUST validate that the new value of the H3_DATAGRAM SETTINGS 187 parameter sent by the server in the handshake is greater or equal to 188 the stored value; if not, the client MUST terminate the connection 189 with error H3_SETTINGS_ERROR. 191 6. Datagram-Flow-Id Header Definition 193 "Datagram-Flow-Id" is a Item Structured Header [STRUCT-HDR]. Its 194 value MUST be an Integer. Its ABNF is: 196 Datagram-Flow-Id = sh-integer 198 The "Datagram-Flow-Id" header is used to associate a datagram flow 199 identifier with an HTTP message. For example, the definition of an 200 HTTP method could instruct the client to use its flow identifier 201 allocation service to allocate a new flow identifier, and then the 202 client will add the "Datagram-Flow-Id" header to its request to 203 communicate that value to the server. For example, the resulting 204 header could look like: 206 Datagram-Flow-Id = 2 208 Definitions of HTTP features that use the "Datagram-Flow-Id" header 209 MAY define their own parameters (parameters are defined in 210 Section 3.1.2 of [STRUCT-HDR]). For example, an HTTP method that 211 wishes to use two datagram flow identifiers for the lifetime of its 212 request stream could encode the second flow identifier as a 213 parameter, which could look like this: 215 Datagram-Flow-Id = 42; alternate=44 217 The "Datagram-Flow-Id" header MUST NOT be present more than once on a 218 given HTTP message; any HTTP message containing more than one 219 "Datagram-Flow-Id" header is malformed. 221 Since the QUIC STREAM frame that contains the "Datagram-Flow-Id" 222 header could be lost or reordered, it is possible that an endpoint 223 will receive an HTTP/3 datagram with a flow identifier that it does 224 not know as it has not yet received the corresponding "Datagram-Flow- 225 Id" header. Endpoints MUST NOT treat that as an error; they MUST 226 either silently discard the datagram or buffer it until they receive 227 the "Datagram-Flow-Id" header. 229 Note that integer structured fields can only encode values up to 230 10^15-1, therefore the maximum possible value of the "Datagram-Flow- 231 Id" header is lower then the theoretical maximum value of a flow 232 identifier which is 2^62-1 due to the QUIC variable length integer 233 encoding. If the flow identifier allocation service of an endpoint 234 runs out of values lower than 10^15-1, the endpoint MUST treat is as 235 a connection error of type H3_ID_ERROR. 237 7. HTTP Intermediaries 239 HTTP/3 DATAGRAM flow identifiers are specific to a given HTTP/3 240 connection. However, in some cases, an HTTP request may travel 241 across multiple HTTP connections if there are HTTP intermediaries 242 involved; see Section 2.3 of [RFC7230]. 244 If an intermediary has sent the H3_DATAGRAM SETTINGS parameter with a 245 value of 1 on its client-facing connection, it MUST inspect all HTTP 246 requests from that connection and check for the presence of the 247 "Datagram-Flow-Id" header. If the HTTP method of the request is not 248 supported by the intermediary, it MUST remove the "Datagram-Flow-Id" 249 header before forwarding the request. If the intermediary supports 250 the method, it MUST either remove the header or adhere to the 251 requirements leveraged by that method on intermediaries. 253 If an intermediary has sent the H3_DATAGRAM SETTINGS parameter with a 254 value of 1 on its server-facing connection, it MUST inspect all HTTP 255 responses from that connection and check for the presence of the 256 "Datagram-Flow-Id" header. If the HTTP method of the request is not 257 supported by the intermediary, it MUST remove the "Datagram-Flow-Id" 258 header before forwarding the response. If the intermediary supports 259 the method, it MUST either remove the header or adhere to the 260 requirements leveraged by that method on intermediaries. 262 8. Security Considerations 264 This document does not have additional security considerations beyond 265 those defined in [QUIC] and [DGRAM]. 267 9. IANA Considerations 269 9.1. HTTP SETTINGS Parameter 271 This document will request IANA to register the following entry in 272 the "HTTP/3 Settings" registry: 274 +--------------+-------+---------------+---------+ 275 | Setting Name | Value | Specification | Default | 276 +==============+=======+===============+=========+ 277 | H3_DATAGRAM | 0x276 | This Document | 0 | 278 +--------------+-------+---------------+---------+ 280 9.2. HTTP Header 282 This document will request IANA to register the "Datagram-Flow-Id" 283 header in the "Permanent Message Header Field Names" registry 284 maintained at . 286 +-------------------+----------+--------+---------------+ 287 | Header Field Name | Protocol | Status | Reference | 288 +-------------------+----------+--------+---------------+ 289 | Datagram-Flow-Id | http | std | This document | 290 +-------------------+----------+--------+---------------+ 292 10. Normative References 294 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 295 Datagram Extension to QUIC", Work in Progress, Internet- 296 Draft, draft-ietf-quic-datagram-01, 24 August 2020, 297 . 300 [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 301 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 302 quic-http-32, 20 October 2020, . 305 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 306 and Secure Transport", Work in Progress, Internet-Draft, 307 draft-ietf-quic-transport-32, 20 October 2020, 308 . 311 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 312 Requirement Levels", BCP 14, RFC 2119, 313 DOI 10.17487/RFC2119, March 1997, 314 . 316 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 317 Protocol (HTTP/1.1): Message Syntax and Routing", 318 RFC 7230, DOI 10.17487/RFC7230, June 2014, 319 . 321 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 322 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 323 May 2017, . 325 [STRUCT-HDR] 326 Nottingham, M. and P. Kamp, "Structured Field Values for 327 HTTP", Work in Progress, Internet-Draft, draft-ietf- 328 httpbis-header-structure-19, 3 June 2020, 329 . 332 Acknowledgments 334 The DATAGRAM flow identifier was previously part of the DATAGRAM 335 frame definition itself, the author would like to acknowledge the 336 authors of that document and the members of the IETF QUIC working 337 group for their suggestions. Additionally, the author would like to 338 thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS 339 parameter. Thanks to Lucas Pardue for their inputs on this document. 341 Author's Address 343 David Schinazi 344 Google LLC 345 1600 Amphitheatre Parkway 346 Mountain View, California 94043, 347 United States of America 349 Email: dschinazi.ietf@gmail.com