idnits 2.17.1 draft-ietf-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 (27 May 2021) is 1066 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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-02 Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 MASQUE D. Schinazi 3 Internet-Draft Google LLC 4 Intended status: Standards Track L. Pardue 5 Expires: 28 November 2021 Cloudflare 6 27 May 2021 8 Using QUIC Datagrams with HTTP/3 9 draft-ietf-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 describes how to use QUIC 18 DATAGRAM frames when the application protocol running over QUIC is 19 HTTP/3. It associates datagrams with client-initiated bidirectional 20 streams and defines an optional additional demultiplexing layer. 22 Discussion of this work is encouraged to happen on the MASQUE IETF 23 mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the 24 GitHub repository which contains the draft: https://github.com/ietf- 25 wg-masque/draft-ietf-masque-h3-datagram. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 28 November 2021. 44 Copyright Notice 46 Copyright (c) 2021 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Simplified BSD License text 55 as described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 62 2. Multiplexing . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2.1. Datagram Contexts . . . . . . . . . . . . . . . . . . . . 3 64 2.2. Context ID Allocation . . . . . . . . . . . . . . . . . . 4 65 3. HTTP/3 DATAGRAM Format . . . . . . . . . . . . . . . . . . . 4 66 4. CAPSULE HTTP/3 Frame Definition . . . . . . . . . . . . . . . 6 67 4.1. The REGISTER_DATAGRAM_CONTEXT Capsule . . . . . . . . . . 7 68 4.2. The REGISTER_DATAGRAM_NO_CONTEXT Capsule . . . . . . . . 8 69 4.3. The CLOSE_DATAGRAM_CONTEXT Capsule . . . . . . . . . . . 10 70 4.4. The DATAGRAM Capsule . . . . . . . . . . . . . . . . . . 11 71 5. Context Extensibility . . . . . . . . . . . . . . . . . . . . 12 72 5.1. The CLOSE_CODE Context Extension Type . . . . . . . . . . 12 73 5.2. The DETAILS Context Extension Type . . . . . . . . . . . 13 74 6. The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . . . . . 13 75 7. Prioritization . . . . . . . . . . . . . . . . . . . . . . . 14 76 8. HTTP/1.x and HTTP/2 Support . . . . . . . . . . . . . . . . . 14 77 9. Security Considerations . . . . . . . . . . . . . . . . . . . 14 78 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 79 10.1. HTTP/3 CAPSULE Frame . . . . . . . . . . . . . . . . . . 14 80 10.2. HTTP SETTINGS Parameter . . . . . . . . . . . . . . . . 14 81 10.3. Capsule Types . . . . . . . . . . . . . . . . . . . . . 15 82 10.4. Context Extension Types . . . . . . . . . . . . . . . . 16 83 10.5. Context Close Codes . . . . . . . . . . . . . . . . . . 16 84 11. Normative References . . . . . . . . . . . . . . . . . . . . 17 85 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 18 86 A.1. CONNECT-UDP . . . . . . . . . . . . . . . . . . . . . . . 18 87 A.2. CONNECT-UDP with Timestamp Extension . . . . . . . . . . 19 88 A.3. CONNECT-IP with IP compression . . . . . . . . . . . . . 19 89 A.4. WebTransport . . . . . . . . . . . . . . . . . . . . . . 20 90 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 21 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 93 1. Introduction 95 The QUIC DATAGRAM extension [DGRAM] provides application protocols 96 running over QUIC [QUIC] with a mechanism to send unreliable data 97 while leveraging the security and congestion-control properties of 98 QUIC. However, QUIC DATAGRAM frames do not provide a means to 99 demultiplex application contexts. This document describes how to use 100 QUIC DATAGRAM frames when the application protocol running over QUIC 101 is HTTP/3 [H3]. It associates datagrams with client-initiated 102 bidirectional streams and defines an optional additional 103 demultiplexing layer. 105 Discussion of this work is encouraged to happen on the MASQUE IETF 106 mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the 107 GitHub repository which contains the draft: https://github.com/ietf- 108 wg-masque/draft-ietf-masque-h3-datagram. 110 1.1. Conventions and Definitions 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in BCP 115 14 [RFC2119] [RFC8174] when, and only when, they appear in all 116 capitals, as shown here. 118 2. Multiplexing 120 In order to allow multiple exchanges of datagrams to coexist on a 121 given QUIC connection, HTTP datagrams contain two layers of 122 multiplexing. First, the QUIC DATAGRAM frame payload starts with an 123 encoded stream identifier that associates the datagram with a given 124 QUIC stream. Second, datagrams optionally carry a context identifier 125 (see Section 2.1) that allows multiplexing multiple datagram contexts 126 related to a given HTTP request. Conceptually, the first layer of 127 multiplexing is per-hop, while the second is end-to-end. 129 2.1. Datagram Contexts 131 Within the scope of a given HTTP request, contexts provide an 132 additional demultiplexing layer. Contexts determine the encoding of 133 datagrams, and can be used to implicitly convey metadata. For 134 example, contexts can be used for compression to elide some parts of 135 the datagram: the context identifier then maps to a compression 136 context that the receiver can use to reconstruct the elided data. 138 Contexts are optional, their use is negotiated on each request stream 139 using registration capsules, see Section 4.1 and Section 4.2. When 140 contexts are used, they are identified within the scope of a given 141 request by a numeric value, referred to as the context ID. A context 142 ID is a 62-bit integer (0 to 2^62-1). 144 While stream IDs are a per-hop concept, context IDs are an end-to-end 145 concept. In other words, if a datagram travels through one or more 146 intermediaries on its way from client to server, the stream ID will 147 most likely change from hop to hop, but the context ID will remain 148 the same. Context IDs are opaque to intermediaries. 150 2.2. Context ID Allocation 152 Implementations of HTTP/3 that support the DATAGRAM extension MUST 153 provide a context ID allocation service. That service will allow 154 applications co-located with HTTP/3 to request a unique context ID 155 that they can subsequently use for their own purposes. The HTTP/3 156 implementation will then parse the context ID of incoming DATAGRAM 157 frames and use it to deliver the frame to the appropriate application 158 context. 160 Even-numbered context IDs are client-initiated, while odd-numbered 161 context IDs are server-initiated. This means that an HTTP/3 client 162 implementation of the context ID allocation service MUST only provide 163 even-numbered IDs, while a server implementation MUST only provide 164 odd-numbered IDs. Note that, once allocated, any context ID can be 165 used by both client and server - only allocation carries separate 166 namespaces to avoid requiring synchronization. Additionally, note 167 that the context ID namespace is tied to a given HTTP request: it is 168 possible for the same numeral context ID to be used simultaneously in 169 distinct requests. 171 3. HTTP/3 DATAGRAM Format 173 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 174 frames uses the following format (using the notation from the 175 "Notational Conventions" section of [QUIC]): 177 HTTP/3 Datagram { 178 Quarter Stream ID (i), 179 [Context ID (i)], 180 HTTP/3 Datagram Payload (..), 181 } 183 Figure 1: HTTP/3 DATAGRAM Format 185 Quarter Stream ID: A variable-length integer that contains the value 186 of the client-initiated bidirectional stream that this datagram is 187 associated with, divided by four. (The division by four stems 188 from the fact that HTTP requests are sent on client-initiated 189 bidirectional streams, and those have stream IDs that are 190 divisible by four.) 192 Context ID: A variable-length integer indicating the context ID of 193 the datagram (see Section 2.1). Whether or not this field is 194 present depends on which registration capsules were exchanged on 195 the associated stream: if a REGISTER_DATAGRAM_CONTEXT capsule (see 196 Section 4.1) has been sent or received on this stream, then the 197 field is present; if a REGISTER_DATAGRAM_NO_CONTEXT capsule (see 198 Section 4.2) has been sent or received, then this field is absent; 199 if neither has been sent or received, then it is not yet possible 200 to parse this datagram and the receiver MUST either drop that 201 datagram silently or buffer it temporarily while awaiting the 202 registration capsule. 204 HTTP/3 Datagram Payload: The payload of the datagram, whose 205 semantics are defined by individual applications. Note that this 206 field can be empty. 208 Intermediaries parse the Quarter Stream ID field in order to 209 associate the QUIC DATAGRAM frame with a stream. If an intermediary 210 receives a QUIC DATAGRAM frame whose payload is too short to allow 211 parsing the Quarter Stream ID field, the intermediary MUST treat it 212 as an HTTP/3 connection error of type H3_GENERAL_PROTOCOL_ERROR. The 213 Context ID field is optional and its use is negotiated end-to-end, 214 see Section 4.2. Therefore intermediaries cannot know whether the 215 Context ID field is present or absent and they MUST ignore any HTTP/3 216 Datagram fields after the Quarter Stream ID. 218 Endpoints parse both the Quarter Stream ID field and the Context ID 219 field in order to associate the QUIC DATAGRAM frame with a stream and 220 context within that stream. If an endpoint receives a QUIC DATAGRAM 221 frame whose payload is too short to allow parsing the Quarter Stream 222 ID field, the endpoint MUST treat it as an HTTP/3 connection error of 223 type H3_GENERAL_PROTOCOL_ERROR. If an endpoint receives a QUIC 224 DATAGRAM frame whose payload is long enough to allow parsing the 225 Quarter Stream ID field but too short to allow parsing the Context ID 226 field, the endpoint MUST abruptly terminate the corresponding stream 227 with a stream error of type H3_GENERAL_PROTOCOL_ERROR. 229 Endpoints MUST NOT send HTTP/3 datagrams unless the corresponding 230 stream's send side is open. On a given endpoint, once the receive 231 side of a stream is closed, incoming datagrams for this stream are no 232 longer expected so the endpoint can release related state. Endpoints 233 MAY keep state for a short time to account for reordering. Once the 234 state is released, the endpoint MUST silently drop received 235 associated datagrams. 237 If an HTTP/3 datagram is received and its Quarter Stream ID maps to a 238 stream that has not yet been created, the receiver SHALL either drop 239 that datagram silently or buffer it temporarily while awaiting the 240 creation of the corresponding stream. 242 4. CAPSULE HTTP/3 Frame Definition 244 CAPSULE allows reliably sending request-related information end-to- 245 end, even in the presence of HTTP intermediaries. 247 CAPSULE is an HTTP/3 Frame (as opposed to a QUIC frame) which SHALL 248 only be sent in client-initiated bidirectional streams. 249 Intermediaries forward received CAPSULE frames on the same stream 250 where it would forward DATA frames. Each Capsule Type determines 251 whether it is opaque or transparent to intermediaries: opaque 252 capsules are forwarded unmodified while transparent ones can be 253 parsed, added, or removed by intermediaries. 255 This specification of CAPSULE currently uses HTTP/3 frame type 256 0xffcab5. If this document is approved, a lower number will be 257 requested from IANA. 259 CAPSULE HTTP/3 Frame { 260 Type (i) = 0xffcab5, 261 Length (i), 262 Capsule Type (i), 263 Capsule Data (..), 264 } 266 Figure 2: CAPSULE HTTP/3 Frame Format 268 The Type and Length fields follows the definition of HTTP/3 frames 269 from [H3]. The payload consists of: 271 Capsule Type: The type of this capsule. 273 Capsule Data: Data whose semantics depends on the Capsule Type. 275 Unless otherwise specified, all Capsule Types are defined as opaque 276 to intermediaries. Intermediaries MUST forward all received opaque 277 CAPSULE frames in their unmodified entirety. Intermediaries MUST NOT 278 send any opaque CAPSULE frames other than the ones it is forwarding. 279 All Capsule Types defined in this document are opaque, with the 280 exception of the DATAGRAM Capsule, see Section 4.4. Definitions of 281 new Capsule Types MAY specify that the newly introduced type is 282 transparent. Intermediaries MUST treat unknown Capsule Types as 283 opaque. 285 Intermediaries respect the order of opaque CAPSULE frames: if an 286 intermediary receives two opaque CAPSULE frames in a given order, it 287 MUST forward them in the same order. 289 Endpoints which receive a Capsule with an unknown Capsule Type MUST 290 silently drop that Capsule. 292 Receipt of a CAPSULE HTTP/3 Frame on a stream that is not a client- 293 initiated bidirectional stream MUST be treated as a connection error 294 of type H3_FRAME_UNEXPECTED. 296 4.1. The REGISTER_DATAGRAM_CONTEXT Capsule 298 The REGISTER_DATAGRAM_CONTEXT capsule (type=0x00) allows an endpoint 299 to inform its peer of the encoding and semantics of datagrams 300 associated with a given context ID. Its Capsule Data field consists 301 of: 303 REGISTER_DATAGRAM_CONTEXT Capsule { 304 Context ID (i), 305 Context Extensions (..), 306 } 308 Figure 3: REGISTER_DATAGRAM_CONTEXT Capsule Format 310 Context ID: The context ID to register. 312 Context Extensions: See Section 5. 314 Note that these registrations are unilateral and bidirectional: the 315 sender of the frame unilaterally defines the semantics it will apply 316 to the datagrams it sends and receives using this context ID. Once a 317 context ID is registered, it can be used in both directions. 319 Endpoints MUST NOT send DATAGRAM frames using a Context ID until they 320 have either sent or received a REGISTER_DATAGRAM_CONTEXT Capsule with 321 the same Context ID. However, due to reordering, an endpoint that 322 receives a DATAGRAM frame with an unknown Context ID MUST NOT treat 323 it as an error, it SHALL instead drop the DATAGRAM frame silently, or 324 buffer it temporarily while awaiting the corresponding 325 REGISTER_DATAGRAM_CONTEXT Capsule. 327 Endpoints MUST NOT register the same Context ID twice on the same 328 stream. This also applies to Context IDs that have been closed using 329 a CLOSE_DATAGRAM_CONTEXT capsule. Clients MUST NOT register server- 330 initiated Context IDs and servers MUST NOT register client-initiated 331 Context IDs. If an endpoint receives a REGISTER_DATAGRAM_CONTEXT 332 capsule that violates one or more of these requirements, the endpoint 333 MUST abruptly terminate the corresponding stream with a stream error 334 of type H3_GENERAL_PROTOCOL_ERROR. 336 Endpoints MUST NOT send a REGISTER_DATAGRAM_CONTEXT capsule on a 337 stream before they have sent at least one HEADERS frame on that 338 stream. This removes the need to buffer REGISTER_DATAGRAM_CONTEXT 339 capsules when the endpoint needs information from headers to 340 determine how to react to the capsule. If an endpoint receives a 341 REGISTER_DATAGRAM_CONTEXT capsule on a stream that hasn't yet 342 received a HEADERS frame, the endpoint MUST abruptly terminate the 343 corresponding stream with a stream error of type 344 H3_GENERAL_PROTOCOL_ERROR. 346 Servers MUST NOT send a REGISTER_DATAGRAM_CONTEXT capsule on a stream 347 before they have received at least one REGISTER_DATAGRAM_CONTEXT 348 capsule or one REGISTER_DATAGRAM_NO_CONTEXT capsule from the client 349 on that stream. This ensures that clients control whether datagrams 350 are allowed for a given request. If a client receives a 351 REGISTER_DATAGRAM_CONTEXT capsule on a stream where the client has 352 not yet sent a REGISTER_DATAGRAM_CONTEXT capsule, the client MUST 353 abruptly terminate the corresponding stream with a stream error of 354 type H3_GENERAL_PROTOCOL_ERROR. 356 Servers MUST NOT send a REGISTER_DATAGRAM_CONTEXT capsule on a stream 357 where it has received a REGISTER_DATAGRAM_NO_CONTEXT capsule. If a 358 client receives a REGISTER_DATAGRAM_CONTEXT capsule on a stream where 359 the client has sent a REGISTER_DATAGRAM_NO_CONTEXT capsule, the 360 client MUST abruptly terminate the corresponding stream with a stream 361 error of type H3_GENERAL_PROTOCOL_ERROR. 363 4.2. The REGISTER_DATAGRAM_NO_CONTEXT Capsule 365 The REGISTER_DATAGRAM_NO_CONTEXT capsule (type=0x03) allows a client 366 to inform the server that datagram contexts will not be used with 367 this stream. It also informs the server of the encoding and 368 semantics of datagrams associated with this stream. Its Capsule Data 369 field consists of: 371 REGISTER_DATAGRAM_NO_CONTEXT Capsule { 372 Context Extensions (..), 373 } 375 Figure 4: REGISTER_DATAGRAM_NO_CONTEXT Capsule Format 377 Context Extensions: See Section 5. 379 Note that this registration is unilateral and bidirectional: the 380 client unilaterally defines the semantics it will apply to the 381 datagrams it sends and receives with this stream. 383 Endpoints MUST NOT send DATAGRAM frames without a Context ID until 384 they have either sent or received a REGISTER_DATAGRAM_NO_CONTEXT 385 Capsule. However, due to reordering, an endpoint that receives a 386 DATAGRAM frame before receiving either a REGISTER_DATAGRAM_CONTEXT 387 capsule or a REGISTER_DATAGRAM_NO_CONTEXT capsule MUST NOT treat it 388 as an error, it SHALL instead drop the DATAGRAM frame silently, or 389 buffer it temporarily while awaiting a REGISTER_DATAGRAM_NO_CONTEXT 390 capsule or the corresponding REGISTER_DATAGRAM_CONTEXT capsule. 392 Servers MUST NOT send the REGISTER_DATAGRAM_NO_CONTEXT capsule. If a 393 client receives a REGISTER_DATAGRAM_NO_CONTEXT capsule, the client 394 MUST abruptly terminate the corresponding stream with a stream error 395 of type H3_GENERAL_PROTOCOL_ERROR. 397 Clients MUST NOT send more than one REGISTER_DATAGRAM_NO_CONTEXT 398 capsule on a stream. If a server receives a second 399 REGISTER_DATAGRAM_NO_CONTEXT capsule on the same stream, the server 400 MUST abruptly terminate the corresponding stream with a stream error 401 of type H3_GENERAL_PROTOCOL_ERROR. 403 Clients MUST NOT send a REGISTER_DATAGRAM_NO_CONTEXT capsule on a 404 stream before they have sent at least one HEADERS frame on that 405 stream. This removes the need to buffer REGISTER_DATAGRAM_CONTEXT 406 capsules when the server needs information from headers to determine 407 how to react to the capsule. If a server receives a 408 REGISTER_DATAGRAM_NO_CONTEXT capsule on a stream that hasn't yet 409 received a HEADERS frame, the server MUST abruptly terminate the 410 corresponding stream with a stream error of type 411 H3_GENERAL_PROTOCOL_ERROR. 413 Clients MUST NOT send both REGISTER_DATAGRAM_CONTEXT capsules and 414 REGISTER_DATAGRAM_NO_CONTEXT capsules on the same stream. If a 415 server receives both a REGISTER_DATAGRAM_CONTEXT capsule and a 416 REGISTER_DATAGRAM_NO_CONTEXT capsule on the same stream, the server 417 MUST abruptly terminate the corresponding stream with a stream error 418 of type H3_GENERAL_PROTOCOL_ERROR. 420 Extensions MAY define a different mechanism to negotiate the presence 421 of contexts, and they MAY do so in a way which is opaque to 422 intermediaries. 424 4.3. The CLOSE_DATAGRAM_CONTEXT Capsule 426 The CLOSE_DATAGRAM_CONTEXT capsule (type=0x01) allows an endpoint to 427 inform its peer that it will no longer send or parse received 428 datagrams associated with a given context ID. Its Capsule Data field 429 consists of: 431 CLOSE_DATAGRAM_CONTEXT Capsule { 432 Context ID (i), 433 Context Extensions (..), 434 } 436 Figure 5: CLOSE_DATAGRAM_CONTEXT Capsule Format 438 Context ID: The context ID to close. 440 Context Extensions: See Section 5. 442 Note that this close is unilateral and bidirectional: the sender of 443 the frame unilaterally informs its peer of the closure. Endpoints 444 can use CLOSE_DATAGRAM_CONTEXT capsules to close a context that was 445 initially registered by either themselves, or by their peer. 446 Endpoints MAY use the CLOSE_DATAGRAM_CONTEXT capsule to immediately 447 reject a context that was just registered using a 448 REGISTER_DATAGRAM_CONTEXT capsule if they find its Context Extensions 449 field to be unacceptable. 451 After an endpoint has either sent or received a 452 CLOSE_DATAGRAM_CONTEXT frame, it MUST NOT send any DATAGRAM frames 453 with that Context ID. However, due to reordering, an endpoint that 454 receives a DATAGRAM frame with a closed Context ID MUST NOT treat it 455 as an error, it SHALL instead drop the DATAGRAM frame silently. 457 Endpoints MUST NOT close a Context ID that was not previously 458 registered. Endpoints MUST NOT close a Context ID that has already 459 been closed. If an endpoint receives a CLOSE_DATAGRAM_CONTEXT 460 capsule that violates one or more of these requirements, the endpoint 461 MUST abruptly terminate the corresponding stream with a stream error 462 of type H3_GENERAL_PROTOCOL_ERROR. 464 All CLOSE_DATAGRAM_CONTEXT capsules MUST contain a CLOSE_CODE context 465 extension, see Section 5.1. If an endpoint receives a 466 CLOSE_DATAGRAM_CONTEXT capsule without a CLOSE_CODE context 467 extension, the endpoint MUST abruptly terminate the corresponding 468 stream with a stream error of type H3_GENERAL_PROTOCOL_ERROR. 470 4.4. The DATAGRAM Capsule 472 The DATAGRAM capsule (type=0x02) allows an endpoint to send a 473 datagram frame over an HTTP stream. This is particularly useful when 474 using a version of HTTP that does not support QUIC DATAGRAM frames. 475 Its Capsule Data field consists of: 477 DATAGRAM Capsule { 478 [Context ID (i)], 479 HTTP/3 Datagram Payload (..), 480 } 482 Figure 6: DATAGRAM Capsule Format 484 Context ID: A variable-length integer indicating the context ID of 485 the datagram (see Section 2.1). Whether or not this field is 486 present depends on which registration capsules were exchanged on 487 the associated stream: if a REGISTER_DATAGRAM_CONTEXT capsule (see 488 Section 4.1) has been sent or received on this stream, then the 489 field is present; if a REGISTER_DATAGRAM_NO_CONTEXT capsule (see 490 Section 4.2) has been sent or received, then this field is absent; 491 if neither has been sent or received, then it is not yet possible 492 to parse this datagram and the receiver MUST either drop that 493 datagram silently or buffer it temporarily while awaiting the 494 registration capsule. 496 HTTP/3 Datagram Payload: The payload of the datagram, whose 497 semantics are defined by individual applications. Note that this 498 field can be empty. 500 Datagrams sent using the DATAGRAM Capsule have the exact same 501 semantics as datagrams sent in QUIC DATAGRAM frames. In particular, 502 the restrictions on when it is allowed to send an HTTP/3 datagram and 503 how to process them from Section 3 also apply to HTTP/3 datagrams 504 sent and received using the DATAGRAM capsule. 506 The DATAGRAM Capsule is transparent to intermediaries, meaning that 507 intermediaries MAY parse it and send DATAGRAM Capsules that they did 508 not receive. This allows an intermediary to reencode HTTP/3 509 Datagrams as it forwards them: in other words, an intermediary MAY 510 send a DATAGRAM Capsule to forward an HTTP/3 Datagram which was 511 received in a QUIC DATAGRAM frame, and vice versa. 513 Note that while DATAGRAM capsules are sent on a stream, 514 intermediaries can reencode HTTP/3 datagrams into QUIC DATAGRAM 515 frames over the next hop, and those could be dropped. Because of 516 this, applications have to always consider HTTP/3 datagrams to be 517 unreliable, even if they were initially sent in a capsule. 519 5. Context Extensibility 521 In order to facilitate extensibility of contexts, the 522 REGISTER_DATAGRAM_CONTEXT, REGISTER_DATAGRAM_NO_CONTEXT, and the 523 CLOSE_DATAGRAM_CONTEXT capsules carry a Context Extensions field. 524 That field contains a sequence of context extensions: 526 Context Extensions { 527 Context Extension (..) ..., 528 } 530 Each context extension is encoded as a (type, length, value) tuple: 532 Context Extension { 533 Context Extension Type (i), 534 Context Extension Length (i), 535 Context Extension Value (..), 536 } 538 Context Extension Types are registered with IANA, see Section 10.4. 539 The Context Extension Length field contains the length of the Context 540 Extension Value field in bytes. The semantics of the Context 541 Extension Value field are defined by the corresponding Context 542 Extension Type. 544 5.1. The CLOSE_CODE Context Extension Type 546 The CLOSE_CODE context extension type (type=0x00) allows an endpoint 547 to provide additional information as to why a datagram context was 548 closed. This type SHALL only be sent in CLOSE_DATAGRAM_CONTEXT 549 capsules. Its Context Extension Value field consists of a single 550 variable-length integer which contains the close code. The following 551 codes are defined: 553 NO_ERROR (code=0x00): This indicates that the registration was 554 closed without any additional information. 556 DENIED (code=0x01): This indicates that the sender has rejected the 557 context registration based on its local policy. The endpoint that 558 had originally registered this context MUST NOT try to register 559 another context with the same context extensions on this stream. 561 RESOURCE_LIMIT (code=0x02): This indicates that the context was 562 closed to save resources. The recipient SHOULD limit its future 563 registration of resource-incentive contexts. 565 Receipt of an unknown close code MUST be treated as if the NO_ERROR 566 code was present. Close codes are registered with IANA, see 567 Section 10.5. 569 5.2. The DETAILS Context Extension Type 571 The DETAILS context extension type (type=0x01) allows an endpoint to 572 provide additional details to context capsules. It is meant for 573 debugging purposes. Its Context Extension Value field consists of a 574 human-readable string encoded in UTF-8. 576 6. The H3_DATAGRAM HTTP/3 SETTINGS Parameter 578 Implementations of HTTP/3 that support this mechanism can indicate 579 that to their peer by sending the H3_DATAGRAM SETTINGS parameter with 580 a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST 581 be either 0 or 1. A value of 0 indicates that this mechanism is not 582 supported. An endpoint that receives the H3_DATAGRAM SETTINGS 583 parameter with a value that is neither 0 or 1 MUST terminate the 584 connection with error H3_SETTINGS_ERROR. 586 An endpoint that sends the H3_DATAGRAM SETTINGS parameter with a 587 value of 1 MUST send the max_datagram_frame_size QUIC Transport 588 Parameter [DGRAM]. An endpoint that receives the H3_DATAGRAM 589 SETTINGS parameter with a value of 1 on a QUIC connection that did 590 not also receive the max_datagram_frame_size QUIC Transport Parameter 591 MUST terminate the connection with error H3_SETTINGS_ERROR. 593 When clients use 0-RTT, they MAY store the value of the server's 594 H3_DATAGRAM SETTINGS parameter. Doing so allows the client to use 595 HTTP/3 datagrams in 0-RTT packets. When servers decide to accept 596 0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater 597 than or equal to the value they sent to the client in the connection 598 where they sent them the NewSessionTicket message. If a client 599 stores the value of the H3_DATAGRAM SETTINGS parameter with their 600 0-RTT state, they MUST validate that the new value of the H3_DATAGRAM 601 SETTINGS parameter sent by the server in the handshake is greater 602 than or equal to the stored value; if not, the client MUST terminate 603 the connection with error H3_SETTINGS_ERROR. In all cases, the 604 maximum permitted value of the H3_DATAGRAM SETTINGS parameter is 1. 606 7. Prioritization 608 Prioritization of HTTP/3 datagrams is not defined in this document. 609 Future extensions MAY define how to prioritize datagrams, and MAY 610 define signaling to allow endpoints to communicate their 611 prioritization preferences. 613 8. HTTP/1.x and HTTP/2 Support 615 We can provide DATAGRAM support in HTTP/2 by defining the CAPSULE 616 frame in HTTP/2. 618 We can provide DATAGRAM support in HTTP/1.x by defining its data 619 stream format to a sequence of length-value capsules. 621 TODO: Refactor this document into "HTTP Datagrams" with definitions 622 for HTTP/1.x, HTTP/2, and HTTP/3. 624 9. Security Considerations 626 Since this feature requires sending an HTTP/3 Settings parameter, it 627 "sticks out". In other words, probing clients can learn whether a 628 server supports this feature. Implementations that support this 629 feature SHOULD always send this Settings parameter to avoid leaking 630 the fact that there are applications using HTTP/3 datagrams enabled 631 on this endpoint. 633 10. IANA Considerations 635 10.1. HTTP/3 CAPSULE Frame 637 This document will request IANA to register the following entry in 638 the "HTTP/3 Frames" registry: 640 +------------+----------+---------------+ 641 | Frame Type | Value | Specification | 642 +============+==========+===============+ 643 | CAPSULE | 0xffcab5 | This Document | 644 +------------+----------+---------------+ 646 10.2. HTTP SETTINGS Parameter 648 This document will request IANA to register the following entry in 649 the "HTTP/3 Settings" registry: 651 +--------------+----------+---------------+---------+ 652 | Setting Name | Value | Specification | Default | 653 +==============+==========+===============+=========+ 654 | H3_DATAGRAM | 0xffd276 | This Document | 0 | 655 +--------------+----------+---------------+---------+ 657 10.3. Capsule Types 659 This document establishes a registry for HTTP/3 capsule type codes. 660 The "HTTP Capsule Types" registry governs a 62-bit space. 661 Registrations in this registry MUST include the following fields: 663 Type: 665 A name or label for the capsule type. 667 Value: The value of the Capsule Type field (see Section 4) is a 668 62bit integer. 670 Reference: An optional reference to a specification for the type. 671 This field MAY be empty. 673 Registrations follow the "First Come First Served" policy (see 674 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 675 the same Type. 677 This registry initially contains the following entries: 679 +------------------------------+-------+---------------+ 680 | Capsule Type | Value | Specification | 681 +------------------------------+-------+---------------+ 682 | REGISTER_DATAGRAM_CONTEXT | 0x00 | This Document | 683 +------------------------------+-------+---------------+ 684 | CLOSE_DATAGRAM_CONTEXT | 0x01 | This Document | 685 +------------------------------+-------+---------------+ 686 | DATAGRAM | 0x02 | This Document | 687 +------------------------------+-------+---------------+ 688 | REGISTER_DATAGRAM_NO_CONTEXT | 0x03 | This Document | 689 +------------------------------+-------+---------------+ 691 Capsule types with a value of the form 41 * N + 23 for integer values 692 of N are reserved to exercise the requirement that unknown capsule 693 types be ignored. These capsules have no semantics and can carry 694 arbitrary values. These values MUST NOT be assigned by IANA and MUST 695 NOT appear in the listing of assigned values. 697 10.4. Context Extension Types 699 This document establishes a registry for HTTP/3 datagram context 700 extension type codes. The "HTTP Context Extension Types" registry 701 governs a 62-bit space. Registrations in this registry MUST include 702 the following fields: 704 Type: 706 A name or label for the context extension type. 708 Value: The value of the Context Extension Type field (see Section 5) 709 is a 62bit integer. 711 Reference: An optional reference to a specification for the 712 parameter. This field MAY be empty. 714 Registrations follow the "First Come First Served" policy (see 715 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 716 the same Type nor Value. 718 This registry initially contains the following entries: 720 +------------------------------+-------+---------------+ 721 | Context Extension Type | Value | Specification | 722 +------------------------------+-------+---------------+ 723 | CLOSE_CODE | 0x00 | This Document | 724 +------------------------------+-------+---------------+ 725 | DETAILS | 0x01 | This Document | 726 +------------------------------+-------+---------------+ 728 Context extension types with a value of the form 41 * N + 17 for 729 integer values of N are reserved to exercise the requirement that 730 unknown context extension types be ignored. These extensions have no 731 semantics and can carry arbitrary values. These values MUST NOT be 732 assigned by IANA and MUST NOT appear in the listing of assigned 733 values. 735 10.5. Context Close Codes 737 This document establishes a registry for HTTP/3 context extension 738 type codes. The "HTTP Context Close Codes" registry governs a 62-bit 739 space. Registrations in this registry MUST include the following 740 fields: 742 Type: 744 A name or label for the close code. 746 Value: The value of the CLOSE_CODE Context Extension Value field 747 (see Section 5.1) is a 62bit integer. 749 Reference: An optional reference to a specification for the 750 parameter. This field MAY be empty. 752 Registrations follow the "First Come First Served" policy (see 753 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 754 the same Type nor Value. 756 This registry initially contains the following entries: 758 +------------------------------+-------+---------------+ 759 | Context Close Code | Value | Specification | 760 +------------------------------+-------+---------------+ 761 | NO_ERROR | 0x00 | This Document | 762 +------------------------------+-------+---------------+ 763 | DENIED | 0x01 | This Document | 764 +------------------------------+-------+---------------+ 765 | RESOURCE_LIMIT | 0x02 | This Document | 766 +------------------------------+-------+---------------+ 768 Context close codes with a value of the form 41 * N + 19 for integer 769 values of N are reserved to exercise the requirement that unknown 770 context close codes be treated as NO_ERROR. These values MUST NOT be 771 assigned by IANA and MUST NOT appear in the listing of assigned 772 values. 774 11. Normative References 776 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 777 Datagram Extension to QUIC", Work in Progress, Internet- 778 Draft, draft-ietf-quic-datagram-02, 16 February 2021, 779 . 781 [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 782 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 783 quic-http-34, 2 February 2021, 784 . 786 [IANA-POLICY] 787 Cotton, M., Leiba, B., and T. Narten, "Guidelines for 788 Writing an IANA Considerations Section in RFCs", BCP 26, 789 RFC 8126, DOI 10.17487/RFC8126, June 2017, 790 . 792 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 793 and Secure Transport", Work in Progress, Internet-Draft, 794 draft-ietf-quic-transport-34, 14 January 2021, 795 . 798 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 799 Requirement Levels", BCP 14, RFC 2119, 800 DOI 10.17487/RFC2119, March 1997, 801 . 803 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 804 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 805 May 2017, . 807 Appendix A. Examples 809 A.1. CONNECT-UDP 811 Client Server 813 STREAM(44): HEADERS --------> 814 :method = CONNECT-UDP 815 :scheme = https 816 :path = / 817 :authority = target.example.org:443 819 STREAM(44): CAPSULE --------> 820 Capsule Type = REGISTER_DATAGRAM_CONTEXT 821 Context ID = 0 822 Context Extension = {} 824 DATAGRAM --------> 825 Quarter Stream ID = 11 826 Context ID = 0 827 Payload = Encapsulated UDP Payload 829 <-------- STREAM(44): HEADERS 830 :status = 200 832 /* Wait for target server to respond to UDP packet. */ 834 <-------- DATAGRAM 835 Quarter Stream ID = 11 836 Context ID = 0 837 Payload = Encapsulated UDP Payload 839 A.2. CONNECT-UDP with Timestamp Extension 841 Client Server 843 STREAM(44): HEADERS --------> 844 :method = CONNECT-UDP 845 :scheme = https 846 :path = / 847 :authority = target.example.org:443 849 STREAM(44): CAPSULE --------> 850 Capsule Type = REGISTER_DATAGRAM_CONTEXT 851 Context ID = 0 852 Context Extension = {} 854 DATAGRAM --------> 855 Quarter Stream ID = 11 856 Context ID = 0 857 Payload = Encapsulated UDP Payload 859 <-------- STREAM(44): HEADERS 860 :status = 200 862 /* Wait for target server to respond to UDP packet. */ 864 <-------- DATAGRAM 865 Quarter Stream ID = 11 866 Context ID = 0 867 Payload = Encapsulated UDP Payload 869 STREAM(44): CAPSULE --------> 870 Capsule Type = REGISTER_DATAGRAM_CONTEXT 871 Context ID = 2 872 Context Extension = {TIMESTAMP=""} 874 DATAGRAM --------> 875 Quarter Stream ID = 11 876 Context ID = 2 877 Payload = Encapsulated UDP Payload With Timestamp 879 A.3. CONNECT-IP with IP compression 880 Client Server 882 STREAM(44): HEADERS --------> 883 :method = CONNECT-IP 884 :scheme = https 885 :path = / 886 :authority = proxy.example.org:443 888 <-------- STREAM(44): HEADERS 889 :status = 200 891 /* Exchange CONNECT-IP configuration information. */ 893 STREAM(44): CAPSULE --------> 894 Capsule Type = REGISTER_DATAGRAM_CONTEXT 895 Context ID = 0 896 Context Extension = {} 898 DATAGRAM --------> 899 Quarter Stream ID = 11 900 Context ID = 0 901 Payload = Encapsulated IP Packet 903 /* Endpoint happily exchange encapsulated IP packets */ 904 /* using Quarter Stream ID 11 and Context ID 0. */ 906 DATAGRAM --------> 907 Quarter Stream ID = 11 908 Context ID = 0 909 Payload = Encapsulated IP Packet 911 /* After performing some analysis on traffic patterns, */ 912 /* the client decides it wants to compress a 5-tuple. */ 914 STREAM(44): CAPSULE --------> 915 Capsule Type = REGISTER_DATAGRAM_CONTEXT 916 Context ID = 2 917 Context Extension = {IP_COMPRESSION=tcp,192.0.2.6:9876,192.0.2.7:443} 919 DATAGRAM --------> 920 Quarter Stream ID = 11 921 Context ID = 2 922 Payload = Compressed IP Packet 924 A.4. WebTransport 925 Client Server 927 STREAM(44): HEADERS --------> 928 :method = CONNECT 929 :scheme = https 930 :method = webtransport 931 :path = /hello 932 :authority = webtransport.example.org:443 933 Origin = https://www.example.org:443 935 STREAM(44): CAPSULE --------> 936 Capsule Type = REGISTER_DATAGRAM_NO_CONTEXT 937 Context Extension = {} 939 <-------- STREAM(44): HEADERS 940 :status = 200 942 /* Both endpoints can now send WebTransport datagrams. */ 944 Acknowledgments 946 The DATAGRAM context identifier was previously part of the DATAGRAM 947 frame definition itself, the authors would like to acknowledge the 948 authors of that document and the members of the IETF MASQUE working 949 group for their suggestions. Additionally, the authors would like to 950 thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS 951 parameter. Furthermore, the authors would like to thank Ben Schwartz 952 for writing the first proposal that used two layers of indirection. 954 Authors' Addresses 956 David Schinazi 957 Google LLC 958 1600 Amphitheatre Parkway 959 Mountain View, California 94043, 960 United States of America 962 Email: dschinazi.ietf@gmail.com 964 Lucas Pardue 965 Cloudflare 967 Email: lucaspardue.24.7@gmail.com