idnits 2.17.1 draft-ietf-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 (12 July 2021) is 1019 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-03 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: 13 January 2022 Cloudflare 6 12 July 2021 8 Using Datagrams with HTTP 9 draft-ietf-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 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. 21 Additionally, this document defines how to convey datagrams over 22 prior versions of HTTP. 24 Discussion Venues 26 This note is to be removed before publishing as an RFC. 28 Discussion of this document takes place on the MASQUE WG mailing list 29 (masque@ietf.org), which is archived at 30 https://mailarchive.ietf.org/arch/browse/masque/. 32 Source for this draft and an issue tracker can be found at 33 https://github.com/ietf-wg-masque/draft-ietf-masque-h3-datagram. 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on 13 January 2022. 51 Copyright Notice 53 Copyright (c) 2021 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 58 license-info) in effect on the date of publication of this document. 59 Please review these documents carefully, as they describe your rights 60 and restrictions with respect to this document. Code Components 61 extracted from this document must include Simplified BSD License text 62 as described in Section 4.e of the Trust Legal Provisions and are 63 provided without warranty as described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 69 2. Multiplexing . . . . . . . . . . . . . . . . . . . . . . . . 3 70 2.1. Datagram Contexts . . . . . . . . . . . . . . . . . . . . 4 71 2.2. Context ID Allocation . . . . . . . . . . . . . . . . . . 4 72 3. HTTP/3 DATAGRAM Format . . . . . . . . . . . . . . . . . . . 4 73 4. CAPSULE HTTP/3 Frame Definition . . . . . . . . . . . . . . . 6 74 4.1. The REGISTER_DATAGRAM_CONTEXT Capsule . . . . . . . . . . 7 75 4.2. The REGISTER_DATAGRAM_NO_CONTEXT Capsule . . . . . . . . 9 76 4.3. The CLOSE_DATAGRAM_CONTEXT Capsule . . . . . . . . . . . 10 77 4.4. The DATAGRAM Capsule . . . . . . . . . . . . . . . . . . 11 78 5. Context Extensibility . . . . . . . . . . . . . . . . . . . . 12 79 5.1. The CLOSE_CODE Context Extension Type . . . . . . . . . . 13 80 5.2. The DETAILS Context Extension Type . . . . . . . . . . . 13 81 6. The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . . . . . 13 82 7. Prioritization . . . . . . . . . . . . . . . . . . . . . . . 14 83 8. HTTP/1.x and HTTP/2 Support . . . . . . . . . . . . . . . . . 14 84 9. Security Considerations . . . . . . . . . . . . . . . . . . . 14 85 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 86 10.1. HTTP/3 CAPSULE Frame . . . . . . . . . . . . . . . . . . 14 87 10.2. HTTP/3 SETTINGS Parameter . . . . . . . . . . . . . . . 15 88 10.3. Capsule Types . . . . . . . . . . . . . . . . . . . . . 15 89 10.4. Context Extension Types . . . . . . . . . . . . . . . . 16 90 10.5. Context Close Codes . . . . . . . . . . . . . . . . . . 17 91 11. Normative References . . . . . . . . . . . . . . . . . . . . 17 92 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 18 93 A.1. CONNECT-UDP . . . . . . . . . . . . . . . . . . . . . . . 18 94 A.2. CONNECT-UDP with Timestamp Extension . . . . . . . . . . 19 95 A.3. CONNECT-IP with IP compression . . . . . . . . . . . . . 20 96 A.4. WebTransport . . . . . . . . . . . . . . . . . . . . . . 21 98 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 22 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 101 1. Introduction 103 The QUIC DATAGRAM extension [DGRAM] provides application protocols 104 running over QUIC [QUIC] with a mechanism to send unreliable data 105 while leveraging the security and congestion-control properties of 106 QUIC. However, QUIC DATAGRAM frames do not provide a means to 107 demultiplex application contexts. This document describes how to use 108 QUIC DATAGRAM frames when the application protocol running over QUIC 109 is HTTP/3 [H3]. It associates datagrams with client-initiated 110 bidirectional streams and defines an optional additional 111 demultiplexing layer. Additionally, this document defines how to 112 convey datagrams over prior versions of HTTP. 114 1.1. Conventions and Definitions 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 118 "OPTIONAL" in this document are to be interpreted as described in BCP 119 14 [RFC2119] [RFC8174] when, and only when, they appear in all 120 capitals, as shown here. 122 2. Multiplexing 124 When running over HTTP/3, multiple exchanges of datagrams need the 125 ability to coexist on a given QUIC connection. To allow this, HTTP 126 datagrams contain two layers of multiplexing. First, the QUIC 127 DATAGRAM frame payload starts with an encoded stream identifier that 128 associates the datagram with a given QUIC stream. Second, datagrams 129 optionally carry a context identifier (see Section 2.1) that allows 130 multiplexing multiple datagram contexts related to a given HTTP 131 request. Conceptually, the first layer of multiplexing is per-hop, 132 while the second is end-to-end. 134 When running over HTTP/2, the first level of demultiplexing is 135 provided by the HTTP/2 framing layer. When running over HTTP/1, 136 requests are strictly serialized in the connection, therefore the 137 first layer of demultiplexing is not needed. 139 2.1. Datagram Contexts 141 Within the scope of a given HTTP request, contexts provide an 142 additional demultiplexing layer. Contexts determine the encoding of 143 datagrams, and can be used to implicitly convey metadata. For 144 example, contexts can be used for compression to elide some parts of 145 the datagram: the context identifier then maps to a compression 146 context that the receiver can use to reconstruct the elided data. 148 Contexts are optional, their use is negotiated on each request stream 149 using registration capsules, see Section 4.1 and Section 4.2. When 150 contexts are used, they are identified within the scope of a given 151 request by a numeric value, referred to as the context ID. A context 152 ID is a 62-bit integer (0 to 2^62-1). 154 While stream IDs are a per-hop concept, context IDs are an end-to-end 155 concept. In other words, if a datagram travels through one or more 156 intermediaries on its way from client to server, the stream ID will 157 most likely change from hop to hop, but the context ID will remain 158 the same. Context IDs are opaque to intermediaries. 160 2.2. Context ID Allocation 162 Implementations of HTTP Datagrams MUST provide a context ID 163 allocation service. That service will allow applications co-located 164 with HTTP to request a unique context ID that they can subsequently 165 use for their own purposes. The HTTP implementation will then parse 166 the context ID of incoming HTTP Datagrams and use it to deliver the 167 frame to the appropriate application context. 169 Even-numbered context IDs are client-initiated, while odd-numbered 170 context IDs are server-initiated. This means that an HTTP client 171 implementation of the context ID allocation service MUST only provide 172 even-numbered IDs, while a server implementation MUST only provide 173 odd-numbered IDs. Note that, once allocated, any context ID can be 174 used by both client and server - only allocation carries separate 175 namespaces to avoid requiring synchronization. Additionally, note 176 that the context ID namespace is tied to a given HTTP request: it is 177 possible for the same numeral context ID to be used simultaneously in 178 distinct requests. 180 3. HTTP/3 DATAGRAM Format 182 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 183 frames uses the following format (using the notation from the 184 "Notational Conventions" section of [QUIC]): 186 HTTP/3 Datagram { 187 Quarter Stream ID (i), 188 [Context ID (i)], 189 HTTP Datagram Payload (..), 190 } 192 Figure 1: HTTP/3 DATAGRAM Format 194 Quarter Stream ID: A variable-length integer that contains the value 195 of the client-initiated bidirectional stream that this datagram is 196 associated with, divided by four. (The division by four stems 197 from the fact that HTTP requests are sent on client-initiated 198 bidirectional streams, and those have stream IDs that are 199 divisible by four.) 201 Context ID: A variable-length integer indicating the context ID of 202 the datagram (see Section 2.1). Whether or not this field is 203 present depends on which registration capsules were exchanged on 204 the associated stream: if a REGISTER_DATAGRAM_CONTEXT capsule (see 205 Section 4.1) has been sent or received on this stream, then the 206 field is present; if a REGISTER_DATAGRAM_NO_CONTEXT capsule (see 207 Section 4.2) has been sent or received, then this field is absent; 208 if neither has been sent or received, then it is not yet possible 209 to parse this datagram and the receiver MUST either drop that 210 datagram silently or buffer it temporarily while awaiting the 211 registration capsule. 213 HTTP Datagram Payload: The payload of the datagram, whose semantics 214 are defined by individual applications. Note that this field can 215 be empty. 217 Intermediaries parse the Quarter Stream ID field in order to 218 associate the QUIC DATAGRAM frame with a stream. If an intermediary 219 receives a QUIC DATAGRAM frame whose payload is too short to allow 220 parsing the Quarter Stream ID field, the intermediary MUST treat it 221 as an HTTP/3 connection error of type H3_GENERAL_PROTOCOL_ERROR. The 222 Context ID field is optional and its use is negotiated end-to-end, 223 see Section 4.2. Therefore intermediaries cannot know whether the 224 Context ID field is present or absent and they MUST ignore any HTTP/3 225 Datagram fields after the Quarter Stream ID. 227 Endpoints parse both the Quarter Stream ID field and the Context ID 228 field in order to associate the QUIC DATAGRAM frame with a stream and 229 context within that stream. If an endpoint receives a QUIC DATAGRAM 230 frame whose payload is too short to allow parsing the Quarter Stream 231 ID field, the endpoint MUST treat it as an HTTP/3 connection error of 232 type H3_GENERAL_PROTOCOL_ERROR. If an endpoint receives a QUIC 233 DATAGRAM frame whose payload is long enough to allow parsing the 234 Quarter Stream ID field but too short to allow parsing the Context ID 235 field, the endpoint MUST abruptly terminate the corresponding stream 236 with a stream error of type H3_GENERAL_PROTOCOL_ERROR. 238 Endpoints MUST NOT send HTTP/3 datagrams unless the corresponding 239 stream's send side is open. On a given endpoint, once the receive 240 side of a stream is closed, incoming datagrams for this stream are no 241 longer expected so the endpoint can release related state. Endpoints 242 MAY keep state for a short time to account for reordering. Once the 243 state is released, the endpoint MUST silently drop received 244 associated datagrams. 246 If an HTTP/3 datagram is received and its Quarter Stream ID maps to a 247 stream that has not yet been created, the receiver SHALL either drop 248 that datagram silently or buffer it temporarily while awaiting the 249 creation of the corresponding stream. 251 4. CAPSULE HTTP/3 Frame Definition 253 CAPSULE allows reliably sending request-related information end-to- 254 end, even in the presence of HTTP intermediaries. 256 CAPSULE is an HTTP/3 Frame (as opposed to a QUIC frame) which SHALL 257 only be sent in client-initiated bidirectional streams. 258 Intermediaries forward received CAPSULE frames on the same stream 259 where it would forward DATA frames. Each Capsule Type determines 260 whether it is opaque or transparent to intermediaries: opaque 261 capsules are forwarded unmodified while transparent ones can be 262 parsed, added, or removed by intermediaries. 264 This specification of CAPSULE currently uses HTTP/3 frame type 265 0xffcab5. If this document is approved, a lower number will be 266 requested from IANA. 268 CAPSULE HTTP/3 Frame { 269 Type (i) = 0xffcab5, 270 Length (i), 271 Capsule Type (i), 272 Capsule Data (..), 273 } 275 Figure 2: CAPSULE HTTP/3 Frame Format 277 The Type and Length fields follows the definition of HTTP/3 frames 278 from [H3]. The payload consists of: 280 Capsule Type: The type of this capsule. 282 Capsule Data: Data whose semantics depends on the Capsule Type. 284 Unless otherwise specified, all Capsule Types are defined as opaque 285 to intermediaries. Intermediaries MUST forward all received opaque 286 CAPSULE frames in their unmodified entirety. Intermediaries MUST NOT 287 send any opaque CAPSULE frames other than the ones it is forwarding. 288 All Capsule Types defined in this document are opaque, with the 289 exception of the DATAGRAM Capsule, see Section 4.4. Definitions of 290 new Capsule Types MAY specify that the newly introduced type is 291 transparent. Intermediaries MUST treat unknown Capsule Types as 292 opaque. 294 Intermediaries respect the order of opaque CAPSULE frames: if an 295 intermediary receives two opaque CAPSULE frames in a given order, it 296 MUST forward them in the same order. 298 Endpoints which receive a Capsule with an unknown Capsule Type MUST 299 silently drop that Capsule. 301 Receipt of a CAPSULE HTTP/3 Frame on a stream that is not a client- 302 initiated bidirectional stream MUST be treated as a connection error 303 of type H3_FRAME_UNEXPECTED. 305 4.1. The REGISTER_DATAGRAM_CONTEXT Capsule 307 The REGISTER_DATAGRAM_CONTEXT capsule (type=0x00) allows an endpoint 308 to inform its peer of the encoding and semantics of datagrams 309 associated with a given context ID. Its Capsule Data field consists 310 of: 312 REGISTER_DATAGRAM_CONTEXT Capsule { 313 Context ID (i), 314 Context Extensions (..), 315 } 317 Figure 3: REGISTER_DATAGRAM_CONTEXT Capsule Format 319 Context ID: The context ID to register. 321 Context Extensions: See Section 5. 323 Note that these registrations are unilateral and bidirectional: the 324 sender of the frame unilaterally defines the semantics it will apply 325 to the datagrams it sends and receives using this context ID. Once a 326 context ID is registered, it can be used in both directions. 328 Endpoints MUST NOT send DATAGRAM frames using a Context ID until they 329 have either sent or received a REGISTER_DATAGRAM_CONTEXT Capsule with 330 the same Context ID. However, due to reordering, an endpoint that 331 receives a DATAGRAM frame with an unknown Context ID MUST NOT treat 332 it as an error, it SHALL instead drop the DATAGRAM frame silently, or 333 buffer it temporarily while awaiting the corresponding 334 REGISTER_DATAGRAM_CONTEXT Capsule. 336 Endpoints MUST NOT register the same Context ID twice on the same 337 stream. This also applies to Context IDs that have been closed using 338 a CLOSE_DATAGRAM_CONTEXT capsule. Clients MUST NOT register server- 339 initiated Context IDs and servers MUST NOT register client-initiated 340 Context IDs. If an endpoint receives a REGISTER_DATAGRAM_CONTEXT 341 capsule that violates one or more of these requirements, the endpoint 342 MUST abruptly terminate the corresponding stream with a stream error 343 of type H3_GENERAL_PROTOCOL_ERROR. 345 Endpoints MUST NOT send a REGISTER_DATAGRAM_CONTEXT capsule on a 346 stream before they have sent at least one HEADERS frame on that 347 stream. This removes the need to buffer REGISTER_DATAGRAM_CONTEXT 348 capsules when the endpoint needs information from headers to 349 determine how to react to the capsule. If an endpoint receives a 350 REGISTER_DATAGRAM_CONTEXT capsule on a stream that hasn't yet 351 received a HEADERS frame, the endpoint MUST abruptly terminate the 352 corresponding stream with a stream error of type 353 H3_GENERAL_PROTOCOL_ERROR. 355 Servers MUST NOT send a REGISTER_DATAGRAM_CONTEXT capsule on a stream 356 before they have received at least one REGISTER_DATAGRAM_CONTEXT 357 capsule or one REGISTER_DATAGRAM_NO_CONTEXT capsule from the client 358 on that stream. This ensures that clients control whether datagrams 359 are allowed for a given request. If a client receives a 360 REGISTER_DATAGRAM_CONTEXT capsule on a stream where the client has 361 not yet sent a REGISTER_DATAGRAM_CONTEXT capsule, the client MUST 362 abruptly terminate the corresponding stream with a stream error of 363 type H3_GENERAL_PROTOCOL_ERROR. 365 Servers MUST NOT send a REGISTER_DATAGRAM_CONTEXT capsule on a stream 366 where it has received a REGISTER_DATAGRAM_NO_CONTEXT capsule. If a 367 client receives a REGISTER_DATAGRAM_CONTEXT capsule on a stream where 368 the client has sent a REGISTER_DATAGRAM_NO_CONTEXT capsule, the 369 client MUST abruptly terminate the corresponding stream with a stream 370 error of type H3_GENERAL_PROTOCOL_ERROR. 372 4.2. The REGISTER_DATAGRAM_NO_CONTEXT Capsule 374 The REGISTER_DATAGRAM_NO_CONTEXT capsule (type=0x03) allows a client 375 to inform the server that datagram contexts will not be used with 376 this stream. It also informs the server of the encoding and 377 semantics of datagrams associated with this stream. Its Capsule Data 378 field consists of: 380 REGISTER_DATAGRAM_NO_CONTEXT Capsule { 381 Context Extensions (..), 382 } 384 Figure 4: REGISTER_DATAGRAM_NO_CONTEXT Capsule Format 386 Context Extensions: See Section 5. 388 Note that this registration is unilateral and bidirectional: the 389 client unilaterally defines the semantics it will apply to the 390 datagrams it sends and receives with this stream. 392 Endpoints MUST NOT send DATAGRAM frames without a Context ID until 393 they have either sent or received a REGISTER_DATAGRAM_NO_CONTEXT 394 Capsule. However, due to reordering, an endpoint that receives a 395 DATAGRAM frame before receiving either a REGISTER_DATAGRAM_CONTEXT 396 capsule or a REGISTER_DATAGRAM_NO_CONTEXT capsule MUST NOT treat it 397 as an error, it SHALL instead drop the DATAGRAM frame silently, or 398 buffer it temporarily while awaiting a REGISTER_DATAGRAM_NO_CONTEXT 399 capsule or the corresponding REGISTER_DATAGRAM_CONTEXT capsule. 401 Servers MUST NOT send the REGISTER_DATAGRAM_NO_CONTEXT capsule. If a 402 client receives a REGISTER_DATAGRAM_NO_CONTEXT capsule, the client 403 MUST abruptly terminate the corresponding stream with a stream error 404 of type H3_GENERAL_PROTOCOL_ERROR. 406 Clients MUST NOT send more than one REGISTER_DATAGRAM_NO_CONTEXT 407 capsule on a stream. If a server receives a second 408 REGISTER_DATAGRAM_NO_CONTEXT capsule on the same stream, the server 409 MUST abruptly terminate the corresponding stream with a stream error 410 of type H3_GENERAL_PROTOCOL_ERROR. 412 Clients MUST NOT send a REGISTER_DATAGRAM_NO_CONTEXT capsule on a 413 stream before they have sent at least one HEADERS frame on that 414 stream. This removes the need to buffer REGISTER_DATAGRAM_CONTEXT 415 capsules when the server needs information from headers to determine 416 how to react to the capsule. If a server receives a 417 REGISTER_DATAGRAM_NO_CONTEXT capsule on a stream that hasn't yet 418 received a HEADERS frame, the server MUST abruptly terminate the 419 corresponding stream with a stream error of type 420 H3_GENERAL_PROTOCOL_ERROR. 422 Clients MUST NOT send both REGISTER_DATAGRAM_CONTEXT capsules and 423 REGISTER_DATAGRAM_NO_CONTEXT capsules on the same stream. If a 424 server receives both a REGISTER_DATAGRAM_CONTEXT capsule and a 425 REGISTER_DATAGRAM_NO_CONTEXT capsule on the same stream, the server 426 MUST abruptly terminate the corresponding stream with a stream error 427 of type H3_GENERAL_PROTOCOL_ERROR. 429 Extensions MAY define a different mechanism to negotiate the presence 430 of contexts, and they MAY do so in a way which is opaque to 431 intermediaries. 433 4.3. The CLOSE_DATAGRAM_CONTEXT Capsule 435 The CLOSE_DATAGRAM_CONTEXT capsule (type=0x01) allows an endpoint to 436 inform its peer that it will no longer send or parse received 437 datagrams associated with a given context ID. Its Capsule Data field 438 consists of: 440 CLOSE_DATAGRAM_CONTEXT Capsule { 441 Context ID (i), 442 Context Extensions (..), 443 } 445 Figure 5: CLOSE_DATAGRAM_CONTEXT Capsule Format 447 Context ID: The context ID to close. 449 Context Extensions: See Section 5. 451 Note that this close is unilateral and bidirectional: the sender of 452 the frame unilaterally informs its peer of the closure. Endpoints 453 can use CLOSE_DATAGRAM_CONTEXT capsules to close a context that was 454 initially registered by either themselves, or by their peer. 455 Endpoints MAY use the CLOSE_DATAGRAM_CONTEXT capsule to immediately 456 reject a context that was just registered using a 457 REGISTER_DATAGRAM_CONTEXT capsule if they find its Context Extensions 458 field to be unacceptable. 460 After an endpoint has either sent or received a 461 CLOSE_DATAGRAM_CONTEXT frame, it MUST NOT send any DATAGRAM frames 462 with that Context ID. However, due to reordering, an endpoint that 463 receives a DATAGRAM frame with a closed Context ID MUST NOT treat it 464 as an error, it SHALL instead drop the DATAGRAM frame silently. 466 Endpoints MUST NOT close a Context ID that was not previously 467 registered. Endpoints MUST NOT close a Context ID that has already 468 been closed. If an endpoint receives a CLOSE_DATAGRAM_CONTEXT 469 capsule that violates one or more of these requirements, the endpoint 470 MUST abruptly terminate the corresponding stream with a stream error 471 of type H3_GENERAL_PROTOCOL_ERROR. 473 All CLOSE_DATAGRAM_CONTEXT capsules MUST contain a CLOSE_CODE context 474 extension, see Section 5.1. If an endpoint receives a 475 CLOSE_DATAGRAM_CONTEXT capsule without a CLOSE_CODE context 476 extension, the endpoint MUST abruptly terminate the corresponding 477 stream with a stream error of type H3_GENERAL_PROTOCOL_ERROR. 479 4.4. The DATAGRAM Capsule 481 The DATAGRAM capsule (type=0x02) allows an endpoint to send a 482 datagram frame over an HTTP stream. This is particularly useful when 483 using a version of HTTP that does not support QUIC DATAGRAM frames. 484 Its Capsule Data field consists of: 486 DATAGRAM Capsule { 487 [Context ID (i)], 488 HTTP Datagram Payload (..), 489 } 491 Figure 6: DATAGRAM Capsule Format 493 Context ID: A variable-length integer indicating the context ID of 494 the datagram (see Section 2.1). Whether or not this field is 495 present depends on which registration capsules were exchanged on 496 the associated stream: if a REGISTER_DATAGRAM_CONTEXT capsule (see 497 Section 4.1) has been sent or received on this stream, then the 498 field is present; if a REGISTER_DATAGRAM_NO_CONTEXT capsule (see 499 Section 4.2) has been sent or received, then this field is absent; 500 if neither has been sent or received, then it is not yet possible 501 to parse this datagram and the receiver MUST either drop that 502 datagram silently or buffer it temporarily while awaiting the 503 registration capsule. 505 HTTP Datagram Payload: The payload of the datagram, whose semantics 506 are defined by individual applications. Note that this field can 507 be empty. 509 Datagrams sent using the DATAGRAM Capsule have the exact same 510 semantics as datagrams sent in QUIC DATAGRAM frames. In particular, 511 the restrictions on when it is allowed to send an HTTP Datagram and 512 how to process them from Section 3 also apply to HTTP Datagrams sent 513 and received using the DATAGRAM capsule. 515 The DATAGRAM Capsule is transparent to intermediaries, meaning that 516 intermediaries MAY parse it and send DATAGRAM Capsules that they did 517 not receive. This allows an intermediary to reencode HTTP Datagrams 518 as it forwards them: in other words, an intermediary MAY send a 519 DATAGRAM Capsule to forward an HTTP Datagram which was received in a 520 QUIC DATAGRAM frame, and vice versa. 522 Note that while DATAGRAM capsules are sent on a stream, 523 intermediaries can reencode HTTP Datagrams into QUIC DATAGRAM frames 524 over the next hop, and those could be dropped. Because of this, 525 applications have to always consider HTTP Datagrams to be unreliable, 526 even if they were initially sent in a capsule. 528 5. Context Extensibility 530 In order to facilitate extensibility of contexts, the 531 REGISTER_DATAGRAM_CONTEXT, REGISTER_DATAGRAM_NO_CONTEXT, and the 532 CLOSE_DATAGRAM_CONTEXT capsules carry a Context Extensions field. 533 That field contains a sequence of context extensions: 535 Context Extensions { 536 Context Extension (..) ..., 537 } 539 Each context extension is encoded as a (type, length, value) tuple: 541 Context Extension { 542 Context Extension Type (i), 543 Context Extension Length (i), 544 Context Extension Value (..), 545 } 547 Context Extension Types are registered with IANA, see Section 10.4. 548 The Context Extension Length field contains the length of the Context 549 Extension Value field in bytes. The semantics of the Context 550 Extension Value field are defined by the corresponding Context 551 Extension Type. 553 5.1. The CLOSE_CODE Context Extension Type 555 The CLOSE_CODE context extension type (type=0x00) allows an endpoint 556 to provide additional information as to why a datagram context was 557 closed. This type SHALL only be sent in CLOSE_DATAGRAM_CONTEXT 558 capsules. Its Context Extension Value field consists of a single 559 variable-length integer which contains the close code. The following 560 codes are defined: 562 NO_ERROR (code=0x00): This indicates that the registration was 563 closed without any additional information. 565 DENIED (code=0x01): This indicates that the sender has rejected the 566 context registration based on its local policy. The endpoint that 567 had originally registered this context MUST NOT try to register 568 another context with the same context extensions on this stream. 570 RESOURCE_LIMIT (code=0x02): This indicates that the context was 571 closed to save resources. The recipient SHOULD limit its future 572 registration of resource-incentive contexts. 574 Receipt of an unknown close code MUST be treated as if the NO_ERROR 575 code was present. Close codes are registered with IANA, see 576 Section 10.5. 578 5.2. The DETAILS Context Extension Type 580 The DETAILS context extension type (type=0x01) allows an endpoint to 581 provide additional details to context capsules. It is meant for 582 debugging purposes. Its Context Extension Value field consists of a 583 human-readable string encoded in UTF-8. 585 6. The H3_DATAGRAM HTTP/3 SETTINGS Parameter 587 Implementations of HTTP/3 that support this mechanism can indicate 588 that to their peer by sending the H3_DATAGRAM SETTINGS parameter with 589 a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST 590 be either 0 or 1. A value of 0 indicates that this mechanism is not 591 supported. An endpoint that receives the H3_DATAGRAM SETTINGS 592 parameter with a value that is neither 0 or 1 MUST terminate the 593 connection with error H3_SETTINGS_ERROR. 595 An endpoint that sends the H3_DATAGRAM SETTINGS parameter with a 596 value of 1 MUST send the max_datagram_frame_size QUIC Transport 597 Parameter [DGRAM]. An endpoint that receives the H3_DATAGRAM 598 SETTINGS parameter with a value of 1 on a QUIC connection that did 599 not also receive the max_datagram_frame_size QUIC Transport Parameter 600 MUST terminate the connection with error H3_SETTINGS_ERROR. 602 When clients use 0-RTT, they MAY store the value of the server's 603 H3_DATAGRAM SETTINGS parameter. Doing so allows the client to use 604 HTTP/3 datagrams in 0-RTT packets. When servers decide to accept 605 0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater 606 than or equal to the value they sent to the client in the connection 607 where they sent them the NewSessionTicket message. If a client 608 stores the value of the H3_DATAGRAM SETTINGS parameter with their 609 0-RTT state, they MUST validate that the new value of the H3_DATAGRAM 610 SETTINGS parameter sent by the server in the handshake is greater 611 than or equal to the stored value; if not, the client MUST terminate 612 the connection with error H3_SETTINGS_ERROR. In all cases, the 613 maximum permitted value of the H3_DATAGRAM SETTINGS parameter is 1. 615 7. Prioritization 617 Prioritization of HTTP/3 datagrams is not defined in this document. 618 Future extensions MAY define how to prioritize datagrams, and MAY 619 define signaling to allow endpoints to communicate their 620 prioritization preferences. 622 8. HTTP/1.x and HTTP/2 Support 624 We can provide DATAGRAM support in HTTP/2 by defining the CAPSULE 625 frame in HTTP/2. 627 We can provide DATAGRAM support in HTTP/1.x by defining its data 628 stream format to a sequence of length-value capsules. 630 TODO: Refactor this document and add definitions for HTTP/1.x and 631 HTTP/2. 633 9. Security Considerations 635 Since this feature requires sending an HTTP/3 Settings parameter, it 636 "sticks out". In other words, probing clients can learn whether a 637 server supports this feature. Implementations that support this 638 feature SHOULD always send this Settings parameter to avoid leaking 639 the fact that there are applications using HTTP/3 datagrams enabled 640 on this endpoint. 642 10. IANA Considerations 644 10.1. HTTP/3 CAPSULE Frame 646 This document will request IANA to register the following entry in 647 the "HTTP/3 Frames" registry: 649 +------------+----------+---------------+ 650 | Frame Type | Value | Specification | 651 +============+==========+===============+ 652 | CAPSULE | 0xffcab5 | This Document | 653 +------------+----------+---------------+ 655 10.2. HTTP/3 SETTINGS Parameter 657 This document will request IANA to register the following entry in 658 the "HTTP/3 Settings" registry: 660 +--------------+----------+---------------+---------+ 661 | Setting Name | Value | Specification | Default | 662 +==============+==========+===============+=========+ 663 | H3_DATAGRAM | 0xffd276 | This Document | 0 | 664 +--------------+----------+---------------+---------+ 666 10.3. Capsule Types 668 This document establishes a registry for HTTP capsule type codes. 669 The "HTTP Capsule Types" registry governs a 62-bit space. 670 Registrations in this registry MUST include the following fields: 672 Type: 674 A name or label for the capsule type. 676 Value: The value of the Capsule Type field (see Section 4) is a 677 62bit integer. 679 Reference: An optional reference to a specification for the type. 680 This field MAY be empty. 682 Registrations follow the "First Come First Served" policy (see 683 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 684 the same Type. 686 This registry initially contains the following entries: 688 +------------------------------+-------+---------------+ 689 | Capsule Type | Value | Specification | 690 +------------------------------+-------+---------------+ 691 | REGISTER_DATAGRAM_CONTEXT | 0x00 | This Document | 692 +------------------------------+-------+---------------+ 693 | CLOSE_DATAGRAM_CONTEXT | 0x01 | This Document | 694 +------------------------------+-------+---------------+ 695 | DATAGRAM | 0x02 | This Document | 696 +------------------------------+-------+---------------+ 697 | REGISTER_DATAGRAM_NO_CONTEXT | 0x03 | This Document | 698 +------------------------------+-------+---------------+ 700 Capsule types with a value of the form 41 * N + 23 for integer values 701 of N are reserved to exercise the requirement that unknown capsule 702 types be ignored. These capsules have no semantics and can carry 703 arbitrary values. These values MUST NOT be assigned by IANA and MUST 704 NOT appear in the listing of assigned values. 706 10.4. Context Extension Types 708 This document establishes a registry for HTTP datagram context 709 extension type codes. The "HTTP Context Extension Types" registry 710 governs a 62-bit space. Registrations in this registry MUST include 711 the following fields: 713 Type: 715 A name or label for the context extension type. 717 Value: The value of the Context Extension Type field (see Section 5) 718 is a 62bit integer. 720 Reference: An optional reference to a specification for the 721 parameter. This field MAY be empty. 723 Registrations follow the "First Come First Served" policy (see 724 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 725 the same Type nor Value. 727 This registry initially contains the following entries: 729 +------------------------------+-------+---------------+ 730 | Context Extension Type | Value | Specification | 731 +------------------------------+-------+---------------+ 732 | CLOSE_CODE | 0x00 | This Document | 733 +------------------------------+-------+---------------+ 734 | DETAILS | 0x01 | This Document | 735 +------------------------------+-------+---------------+ 736 Context extension types with a value of the form 41 * N + 17 for 737 integer values of N are reserved to exercise the requirement that 738 unknown context extension types be ignored. These extensions have no 739 semantics and can carry arbitrary values. These values MUST NOT be 740 assigned by IANA and MUST NOT appear in the listing of assigned 741 values. 743 10.5. Context Close Codes 745 This document establishes a registry for HTTP context extension type 746 codes. The "HTTP Context Close Codes" registry governs a 62-bit 747 space. Registrations in this registry MUST include the following 748 fields: 750 Type: 752 A name or label for the close code. 754 Value: The value of the CLOSE_CODE Context Extension Value field 755 (see Section 5.1) is a 62bit integer. 757 Reference: An optional reference to a specification for the 758 parameter. This field MAY be empty. 760 Registrations follow the "First Come First Served" policy (see 761 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 762 the same Type nor Value. 764 This registry initially contains the following entries: 766 +------------------------------+-------+---------------+ 767 | Context Close Code | Value | Specification | 768 +------------------------------+-------+---------------+ 769 | NO_ERROR | 0x00 | This Document | 770 +------------------------------+-------+---------------+ 771 | DENIED | 0x01 | This Document | 772 +------------------------------+-------+---------------+ 773 | RESOURCE_LIMIT | 0x02 | This Document | 774 +------------------------------+-------+---------------+ 776 Context close codes with a value of the form 41 * N + 19 for integer 777 values of N are reserved to exercise the requirement that unknown 778 context close codes be treated as NO_ERROR. These values MUST NOT be 779 assigned by IANA and MUST NOT appear in the listing of assigned 780 values. 782 11. Normative References 784 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 785 Datagram Extension to QUIC", Work in Progress, Internet- 786 Draft, draft-ietf-quic-datagram-03, 12 July 2021, 787 . 790 [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 791 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 792 quic-http-34, 2 February 2021, 793 . 796 [IANA-POLICY] 797 Cotton, M., Leiba, B., and T. Narten, "Guidelines for 798 Writing an IANA Considerations Section in RFCs", BCP 26, 799 RFC 8126, DOI 10.17487/RFC8126, June 2017, 800 . 802 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 803 and Secure Transport", Work in Progress, Internet-Draft, 804 draft-ietf-quic-transport-34, 14 January 2021, 805 . 808 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 809 Requirement Levels", BCP 14, RFC 2119, 810 DOI 10.17487/RFC2119, March 1997, 811 . 813 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 814 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 815 May 2017, . 817 Appendix A. Examples 819 A.1. CONNECT-UDP 820 Client Server 822 STREAM(44): HEADERS --------> 823 :method = CONNECT-UDP 824 :scheme = https 825 :path = / 826 :authority = target.example.org:443 828 STREAM(44): CAPSULE --------> 829 Capsule Type = REGISTER_DATAGRAM_CONTEXT 830 Context ID = 0 831 Context Extension = {} 833 DATAGRAM --------> 834 Quarter Stream ID = 11 835 Context ID = 0 836 Payload = Encapsulated UDP Payload 838 <-------- STREAM(44): HEADERS 839 :status = 200 841 /* Wait for target server to respond to UDP packet. */ 843 <-------- DATAGRAM 844 Quarter Stream ID = 11 845 Context ID = 0 846 Payload = Encapsulated UDP Payload 848 A.2. CONNECT-UDP with Timestamp Extension 849 Client Server 851 STREAM(44): HEADERS --------> 852 :method = CONNECT-UDP 853 :scheme = https 854 :path = / 855 :authority = target.example.org:443 857 STREAM(44): CAPSULE --------> 858 Capsule Type = REGISTER_DATAGRAM_CONTEXT 859 Context ID = 0 860 Context Extension = {} 862 DATAGRAM --------> 863 Quarter Stream ID = 11 864 Context ID = 0 865 Payload = Encapsulated UDP Payload 867 <-------- STREAM(44): HEADERS 868 :status = 200 870 /* Wait for target server to respond to UDP packet. */ 872 <-------- DATAGRAM 873 Quarter Stream ID = 11 874 Context ID = 0 875 Payload = Encapsulated UDP Payload 877 STREAM(44): CAPSULE --------> 878 Capsule Type = REGISTER_DATAGRAM_CONTEXT 879 Context ID = 2 880 Context Extension = {TIMESTAMP=""} 882 DATAGRAM --------> 883 Quarter Stream ID = 11 884 Context ID = 2 885 Payload = Encapsulated UDP Payload With Timestamp 887 A.3. CONNECT-IP with IP compression 888 Client Server 890 STREAM(44): HEADERS --------> 891 :method = CONNECT-IP 892 :scheme = https 893 :path = / 894 :authority = proxy.example.org:443 896 <-------- STREAM(44): HEADERS 897 :status = 200 899 /* Exchange CONNECT-IP configuration information. */ 901 STREAM(44): CAPSULE --------> 902 Capsule Type = REGISTER_DATAGRAM_CONTEXT 903 Context ID = 0 904 Context Extension = {} 906 DATAGRAM --------> 907 Quarter Stream ID = 11 908 Context ID = 0 909 Payload = Encapsulated IP Packet 911 /* Endpoint happily exchange encapsulated IP packets */ 912 /* using Quarter Stream ID 11 and Context ID 0. */ 914 DATAGRAM --------> 915 Quarter Stream ID = 11 916 Context ID = 0 917 Payload = Encapsulated IP Packet 919 /* After performing some analysis on traffic patterns, */ 920 /* the client decides it wants to compress a 5-tuple. */ 922 STREAM(44): CAPSULE --------> 923 Capsule Type = REGISTER_DATAGRAM_CONTEXT 924 Context ID = 2 925 Context Extension = {IP_COMPRESSION=tcp,192.0.2.6:9876,192.0.2.7:443} 927 DATAGRAM --------> 928 Quarter Stream ID = 11 929 Context ID = 2 930 Payload = Compressed IP Packet 932 A.4. WebTransport 933 Client Server 935 STREAM(44): HEADERS --------> 936 :method = CONNECT 937 :scheme = https 938 :method = webtransport 939 :path = /hello 940 :authority = webtransport.example.org:443 941 Origin = https://www.example.org:443 943 STREAM(44): CAPSULE --------> 944 Capsule Type = REGISTER_DATAGRAM_NO_CONTEXT 945 Context Extension = {} 947 <-------- STREAM(44): HEADERS 948 :status = 200 950 /* Both endpoints can now send WebTransport datagrams. */ 952 Acknowledgments 954 The DATAGRAM context identifier was previously part of the DATAGRAM 955 frame definition itself, the authors would like to acknowledge the 956 authors of that document and the members of the IETF MASQUE working 957 group for their suggestions. Additionally, the authors would like to 958 thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS 959 parameter. Furthermore, the authors would like to thank Ben Schwartz 960 for writing the first proposal that used two layers of indirection. 962 Authors' Addresses 964 David Schinazi 965 Google LLC 966 1600 Amphitheatre Parkway 967 Mountain View, California 94043, 968 United States of America 970 Email: dschinazi.ietf@gmail.com 972 Lucas Pardue 973 Cloudflare 975 Email: lucaspardue.24.7@gmail.com