idnits 2.17.1 draft-ietf-masque-h3-datagram-04.txt: -(926): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 2 instances of lines with non-ascii characters in the document. 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 (7 October 2021) is 932 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-06 == Outdated reference: A later version (-12) exists of draft-ietf-httpbis-priority-06 Summary: 0 errors (**), 0 flaws (~~), 4 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: 10 April 2022 Cloudflare 6 7 October 2021 8 Using Datagrams with HTTP 9 draft-ietf-masque-h3-datagram-04 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 10 April 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 . . . . . . . . . . . . . . . 4 69 2. Multiplexing . . . . . . . . . . . . . . . . . . . . . . . . 4 70 2.1. Datagram Contexts . . . . . . . . . . . . . . . . . . . . 4 71 2.2. Datagram Formats . . . . . . . . . . . . . . . . . . . . 5 72 2.3. Context ID Allocation . . . . . . . . . . . . . . . . . . 5 73 3. HTTP/3 DATAGRAM Format . . . . . . . . . . . . . . . . . . . 6 74 4. Capsules . . . . . . . . . . . . . . . . . . . . . . . . . . 7 75 4.1. Capsule Protocol . . . . . . . . . . . . . . . . . . . . 8 76 4.2. Requirements . . . . . . . . . . . . . . . . . . . . . . 9 77 4.3. Intermediary Processing . . . . . . . . . . . . . . . . . 9 78 4.4. Capsule Types . . . . . . . . . . . . . . . . . . . . . . 10 79 4.4.1. The REGISTER_DATAGRAM_CONTEXT Capsule . . . . . . . . 10 80 4.4.2. The REGISTER_DATAGRAM_NO_CONTEXT Capsule . . . . . . 11 81 4.4.3. The CLOSE_DATAGRAM_CONTEXT Capsule . . . . . . . . . 12 82 4.4.4. The DATAGRAM Capsule . . . . . . . . . . . . . . . . 14 83 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . . . . . 16 84 5.1. Note About Draft Versions . . . . . . . . . . . . . . . . 16 85 6. Prioritization . . . . . . . . . . . . . . . . . . . . . . . 16 86 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 87 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 88 8.1. HTTP/3 SETTINGS Parameter . . . . . . . . . . . . . . . . 17 89 8.2. Capsule Types . . . . . . . . . . . . . . . . . . . . . . 17 90 8.3. Datagram Format Types . . . . . . . . . . . . . . . . . . 18 91 8.4. Context Close Codes . . . . . . . . . . . . . . . . . . . 19 92 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 93 9.1. Normative References . . . . . . . . . . . . . . . . . . 19 94 9.2. Informative References . . . . . . . . . . . . . . . . . 20 95 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 21 96 A.1. CONNECT-UDP . . . . . . . . . . . . . . . . . . . . . . . 21 97 A.2. CONNECT-UDP with Timestamp Extension . . . . . . . . . . 21 98 A.3. CONNECT-IP with IP compression . . . . . . . . . . . . . 22 99 A.4. WebTransport . . . . . . . . . . . . . . . . . . . . . . 24 100 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 24 101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 103 1. Introduction 105 The QUIC DATAGRAM extension [DGRAM] provides application protocols 106 running over QUIC [QUIC] with a mechanism to send unreliable data 107 while leveraging the security and congestion-control properties of 108 QUIC. However, QUIC DATAGRAM frames do not provide a means to 109 demultiplex application contexts. This document describes how to use 110 QUIC DATAGRAM frames when the application protocol running over QUIC 111 is HTTP/3 [H3]. It associates datagrams with client-initiated 112 bidirectional streams and defines an optional additional 113 demultiplexing layer. Additionally, this document defines how to 114 convey datagrams over prior versions of HTTP. 116 This document is structured as follows: 118 * Section 2 presents core concepts for multiplexing across HTTP 119 versions. 121 - Section 2.1 defines datagram contexts, an optional end-to-end 122 multiplexing concept scoped to each HTTP request. 124 - Section 2.2 defines datagram formats, which are scoped to 125 contexts. Formats communicate the format and encoding of 126 datagrams sent using the associated context. 128 - Contexts are identified using a variable-length integer. 129 Requirements for allocating identifier values are detailed in 130 Section 2.3. 132 * Section 3 defines how QUIC DATAGRAM frames are used with HTTP/3. 133 Section 5 defines an HTTP/3 setting that endpoints can use to 134 advertise support of the frame. 136 * Section 4 introduces the Capsule Protocol and the "data stream" 137 concept. Data streams are initiated using special-purpose HTTP 138 requests, after which Capsules, an end-to-end message, can be 139 sent. 141 - The following Capsule types are defined, together with guidance 142 for defining new types: 144 o REGISTER_DATAGRAM_CONTEXT Section 4.4.1 145 o REGISTER_DATAGRAM_NO_CONTEXT Section 4.4.2 147 o CLOSE_DATAGRAM_CONTEXT Section 4.4.3 149 o DATAGRAM Section 4.4.4 151 1.1. Conventions and Definitions 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 155 "OPTIONAL" in this document are to be interpreted as described in BCP 156 14 [RFC2119] [RFC8174] when, and only when, they appear in all 157 capitals, as shown here. 159 2. Multiplexing 161 When running over HTTP/3, multiple exchanges of datagrams need the 162 ability to coexist on a given QUIC connection. To allow this, HTTP 163 datagrams contain two layers of multiplexing. First, the QUIC 164 DATAGRAM frame payload starts with an encoded stream identifier that 165 associates the datagram with a given QUIC stream. Second, datagrams 166 optionally carry a context identifier (see Section 2.1) that allows 167 multiplexing multiple datagram contexts related to a given HTTP 168 request. Conceptually, the first layer of multiplexing is per-hop, 169 while the second is end-to-end. 171 When running over HTTP/2, the first level of demultiplexing is 172 provided by the HTTP/2 framing layer. When running over HTTP/1, 173 requests are strictly serialized in the connection, therefore the 174 first layer of demultiplexing is not needed. 176 2.1. Datagram Contexts 178 Within the scope of a given HTTP request, contexts provide an 179 additional demultiplexing layer. Contexts determine the encoding of 180 datagrams, and can be used to implicitly convey metadata. For 181 example, contexts can be used for compression to elide some parts of 182 the datagram: the context identifier then maps to a compression 183 context that the receiver can use to reconstruct the elided data. 185 Contexts are optional, whether to use them or not is decided by the 186 client on each request stream using registration capsules, see 187 Section 4.4.1 and Section 4.4.2. When contexts are used, they are 188 identified within the scope of a given request by a numeric value, 189 referred to as the context ID. A context ID is a 62-bit integer (0 190 to 2^62-1). 192 While stream IDs are a per-hop concept, context IDs are an end-to-end 193 concept. In other words, if a datagram travels through one or more 194 intermediaries on its way from client to server, the stream ID will 195 most likely change from hop to hop, but the context ID will remain 196 the same. Context IDs are opaque to intermediaries. 198 2.2. Datagram Formats 200 When an endpoint registers a datagram context (or the lack of 201 contexts), it communicates the format (i.e., the semantics and 202 encoding) of datagrams sent using this context. This is 203 acccomplished by sending a Datagram Format Type as part of the 204 registration capsule, see Section 4.4.1 and Section 4.4.2. This type 205 identifier is registered with IANA (see Section 8.3) and allows 206 applications that use HTTP Datagrams to indicate what the content of 207 datagrams are. Registration capsules carry a Datagram Format 208 Additional Data field which allows sending some additional 209 information that would impact the format of datagrams. 211 For example, a protocol which proxies IP packets can define a 212 Datagram Format Type which represents an IP packet. The 213 corresponding Datagram Format Additional Data field would be empty. 214 An extension to such a protocol that wishes to compress IP addresses 215 could define a distinct Datagram Format Type and exchange two IP 216 addresses via the Datagram Format Additional Data field. Then any 217 datagrams with that type would contain the IP packet with addresses 218 elided. 220 2.3. Context ID Allocation 222 Implementations of HTTP Datagrams MUST provide a context ID 223 allocation service. That service will allow applications co-located 224 with HTTP to request a unique context ID that they can subsequently 225 use for their own purposes. The HTTP implementation will then parse 226 the context ID of incoming HTTP Datagrams and use it to deliver the 227 frame to the appropriate application context. 229 Even-numbered context IDs are client-initiated, while odd-numbered 230 context IDs are server-initiated. This means that an HTTP client 231 implementation of the context ID allocation service MUST only provide 232 even-numbered IDs, while a server implementation MUST only provide 233 odd-numbered IDs. Note that, once allocated, any context ID can be 234 used by both client and server - only allocation carries separate 235 namespaces to avoid requiring synchronization. Additionally, note 236 that the context ID namespace is tied to a given HTTP request: it is 237 possible for the same numeral context ID to be used simultaneously in 238 distinct requests. 240 3. HTTP/3 DATAGRAM Format 242 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 243 frames uses the following format (using the notation from the 244 "Notational Conventions" section of [QUIC]): 246 HTTP/3 Datagram { 247 Quarter Stream ID (i), 248 [Context ID (i)], 249 HTTP Datagram Payload (..), 250 } 252 Figure 1: HTTP/3 DATAGRAM Format 254 Quarter Stream ID: A variable-length integer that contains the value 255 of the client-initiated bidirectional stream that this datagram is 256 associated with, divided by four (the division by four stems from 257 the fact that HTTP requests are sent on client-initiated 258 bidirectional streams, and those have stream IDs that are 259 divisible by four). The largest legal QUIC stream ID value is 260 2^62-1, so the largest legal value of Quarter Stream ID is 2^62-1 261 / 4. Receipt of a frame that includes a larger value MUST be 262 treated as a connection error of type FRAME_ENCODING_ERROR. 264 Context ID: A variable-length integer indicating the context ID of 265 the datagram (see Section 2.1). Whether or not this field is 266 present depends on which registration capsules were exchanged on 267 the associated stream: if a REGISTER_DATAGRAM_CONTEXT capsule (see 268 Section 4.4.1) has been sent or received on this stream, then the 269 field is present; if a REGISTER_DATAGRAM_NO_CONTEXT capsule (see 270 Section 4.4.2) has been sent or received, then this field is 271 absent; if neither has been sent or received, then it is not yet 272 possible to parse this datagram and the receiver MUST either drop 273 that datagram silently or buffer it temporarily while awaiting the 274 registration capsule. 276 HTTP Datagram Payload: The payload of the datagram, whose semantics 277 are defined by individual applications. Note that this field can 278 be empty. 280 Intermediaries parse the Quarter Stream ID field in order to 281 associate the QUIC DATAGRAM frame with a stream. If an intermediary 282 receives a QUIC DATAGRAM frame whose payload is too short to allow 283 parsing the Quarter Stream ID field, the intermediary MUST treat it 284 as an HTTP/3 connection error of type H3_GENERAL_PROTOCOL_ERROR. The 285 Context ID field is optional and whether it is present or not is 286 decided end-to-end by the client, see Section 4.4.2. Therefore 287 intermediaries cannot know whether the Context ID field is present or 288 absent and they MUST ignore any HTTP/3 Datagram fields after the 289 Quarter Stream ID. 291 Endpoints parse both the Quarter Stream ID field and the Context ID 292 field in order to associate the QUIC DATAGRAM frame with a stream and 293 context within that stream. If an endpoint receives a QUIC DATAGRAM 294 frame whose payload is too short to allow parsing the Quarter Stream 295 ID field, the endpoint MUST treat it as an HTTP/3 connection error of 296 type H3_GENERAL_PROTOCOL_ERROR. If an endpoint receives a QUIC 297 DATAGRAM frame whose payload is long enough to allow parsing the 298 Quarter Stream ID field but too short to allow parsing the Context ID 299 field, the endpoint MUST abruptly terminate the corresponding stream 300 with a stream error of type H3_GENERAL_PROTOCOL_ERROR. 302 Endpoints MUST NOT send HTTP/3 datagrams unless the corresponding 303 stream's send side is open. On a given endpoint, once the receive 304 side of a stream is closed, incoming datagrams for this stream are no 305 longer expected so the endpoint can release related state. Endpoints 306 MAY keep state for a short time to account for reordering. Once the 307 state is released, the endpoint MUST silently drop received 308 associated datagrams. 310 If an HTTP/3 datagram is received and its Quarter Stream ID maps to a 311 stream that has not yet been created, the receiver SHALL either drop 312 that datagram silently or buffer it temporarily while awaiting the 313 creation of the corresponding stream. 315 4. Capsules 317 This specification introduces the Capsule Protocol. The Capsule 318 Protocol is a sequence of type-length-value tuples that allows 319 endpoints to reliably communicate request-related information end-to- 320 end, even in the presence of HTTP intermediaries. 322 4.1. Capsule Protocol 324 This specification defines the "data stream" of an HTTP request as 325 the bidirectional stream of bytes that follow the headers in both 326 directions. In HTTP/1.x, the data stream consists of all bytes on 327 the connection that follow the blank line that concludes either the 328 request header section, or the 2xx (Successful) response header 329 section. In HTTP/2 and HTTP/3, the data stream of a given HTTP 330 request consists of all bytes sent in DATA frames with the 331 corresponding stream ID. The concept of a data stream is 332 particularly relevant for methods such as CONNECT where there is no 333 HTTP message content after the headers. 335 Definitions of new HTTP Methods or of new HTTP Upgrade Tokens can 336 state that their data stream uses the Capsule Protocol. If they do 337 so, that means that the contents of their data stream uses the 338 following format (using the notation from the "Notational 339 Conventions" section of [QUIC]): 341 Capsule Protocol { 342 Capsule (..) ..., 343 } 345 Figure 2: Capsule Protocol Stream Format 347 Capsule { 348 Capsule Type (i), 349 Capsule Length (i), 350 Capsule Value (..), 351 } 353 Figure 3: Capsule Format 355 Capsule Type: A variable-length integer indicating the Type of the 356 capsule. Endpoints that receive a capsule with an unknown Capsule 357 Type MUST silently skip over that capsule. 359 Capsule Length: The length of the Capsule Value field following this 360 field, encoded as a variable-length integer. Note that this field 361 can have a value of zero. 363 Capsule Value: The payload of this capsule. Its semantics are 364 determined by the value of the Capsule Type field. 366 4.2. Requirements 368 If the definition of an HTTP Method or HTTP Upgrade Token states that 369 it uses the capsule protocol, its implementations MUST follow the 370 following requirements: 372 * A server MUST NOT send any Transfer-Encoding or Content-Length 373 header fields in a 2xx (Successful) response. If a client 374 receives a Content-Length or Transfer-Encoding header fields in a 375 successful response, it MUST treat that response as malformed. 377 * A request message does not have content. 379 * A successful response message does not have content. 381 * Responses are not cacheable. 383 4.3. Intermediary Processing 385 Intermediaries MUST operate in one of the two following modes: 387 Pass-through mode: In this mode, the intermediary forwards the data 388 stream between two associated streams without any modification of 389 the data stream. 391 Participant mode: In this mode, the intermediary terminates the data 392 stream and parses all Capsule Type and Capsule Length fields it 393 receives. 395 Each Capsule Type determines whether it is opaque or transparent to 396 intermediaries in participant mode: opaque capsules are forwarded 397 unmodified while transparent ones can be parsed, added, or removed by 398 intermediaries. Intermediaries MAY modify the contents of the 399 Capsule Data field of transparent capsule types. 401 Unless otherwise specified, all Capsule Types are defined as opaque 402 to intermediaries. Intermediaries MUST forward all received opaque 403 CAPSULE frames in their unmodified entirety. Intermediaries MUST NOT 404 send any opaque CAPSULE frames other than the ones it is forwarding. 405 All Capsule Types defined in this document are opaque, with the 406 exception of the DATAGRAM Capsule, see Section 4.4.4. Definitions of 407 new Capsule Types MAY specify that the newly introduced type is 408 transparent. Intermediaries MUST treat unknown Capsule Types as 409 opaque. 411 Intermediaries respect the order of opaque CAPSULE frames: if an 412 intermediary receives two opaque CAPSULE frames in a given order, it 413 MUST forward them in the same order. 415 Endpoints which receive a Capsule with an unknown Capsule Type MUST 416 silently drop that Capsule. 418 4.4. Capsule Types 420 4.4.1. The REGISTER_DATAGRAM_CONTEXT Capsule 422 The REGISTER_DATAGRAM_CONTEXT capsule (see Section 8.2 for the value 423 of the capsule type) allows an endpoint to inform its peer of the 424 encoding and semantics of datagrams associated with a given context 425 ID. 427 REGISTER_DATAGRAM_CONTEXT Capsule { 428 Type (i) = REGISTER_DATAGRAM_CONTEXT, 429 Length (i), 430 Context ID (i), 431 Datagram Format Type (i), 432 Datagram Format Additional Data (..), 433 } 435 Figure 4: REGISTER_DATAGRAM_CONTEXT Capsule Format 437 Context ID: The context ID to register. 439 Datagram Format Type: A variable-length integer that defines the 440 semantics and encoding of the HTTP Datagram Payload field of 441 datagrams with this context ID, see Section 2.2. 443 Datagram Format Additional Data: This field carries additional 444 information that impact the format of datagrams with this context 445 ID, see Section 2.2. 447 Note that these registrations are unilateral and bidirectional: the 448 sender of the frame unilaterally defines the semantics it will apply 449 to the datagrams it sends and receives using this context ID. Once a 450 context ID is registered, it can be used in both directions. 452 Endpoints MUST NOT send DATAGRAM frames using a Context ID until they 453 have either sent or received a REGISTER_DATAGRAM_CONTEXT Capsule with 454 the same Context ID. However, reordering can cause DATAGRAM frames 455 to be received with an unknown Context ID. Receipt of such frames 456 MUST NOT be treated as an error. Endpoints SHALL drop the DATAGRAM 457 frame silently, or buffer it temporarily while awaiting the 458 corresponding REGISTER_DATAGRAM_CONTEXT Capsule. Intermediaries 459 SHALL drop the DATAGRAM frame silently, MAY buffer it, or forward it 460 on immediately. 462 Endpoints MUST NOT register the same Context ID twice on the same 463 stream. This also applies to Context IDs that have been closed using 464 a CLOSE_DATAGRAM_CONTEXT capsule. Clients MUST NOT register server- 465 initiated Context IDs and servers MUST NOT register client-initiated 466 Context IDs. If an endpoint receives a REGISTER_DATAGRAM_CONTEXT 467 capsule that violates one or more of these requirements, the endpoint 468 MUST abruptly terminate the corresponding stream with a stream error 469 of type H3_GENERAL_PROTOCOL_ERROR. 471 Servers MUST NOT send a REGISTER_DATAGRAM_CONTEXT capsule on a stream 472 before they have received at least one REGISTER_DATAGRAM_CONTEXT 473 capsule or one REGISTER_DATAGRAM_NO_CONTEXT capsule from the client 474 on that stream. This ensures that clients control whether datagrams 475 are allowed for a given request. If a client receives a 476 REGISTER_DATAGRAM_CONTEXT capsule on a stream where the client has 477 not yet sent a REGISTER_DATAGRAM_CONTEXT capsule, the client MUST 478 abruptly terminate the corresponding stream with a stream error of 479 type H3_GENERAL_PROTOCOL_ERROR. 481 Servers MUST NOT send a REGISTER_DATAGRAM_CONTEXT capsule on a stream 482 where it has received a REGISTER_DATAGRAM_NO_CONTEXT capsule. If a 483 client receives a REGISTER_DATAGRAM_CONTEXT capsule on a stream where 484 the client has sent a REGISTER_DATAGRAM_NO_CONTEXT capsule, the 485 client MUST abruptly terminate the corresponding stream with a stream 486 error of type H3_GENERAL_PROTOCOL_ERROR. 488 4.4.2. The REGISTER_DATAGRAM_NO_CONTEXT Capsule 490 The REGISTER_DATAGRAM_NO_CONTEXT capsule (see Section 8.2 for the 491 value of the capsule type) allows a client to inform the server that 492 datagram contexts will not be used with this stream. It also informs 493 the server of the encoding and semantics of datagrams associated with 494 this stream. 496 REGISTER_DATAGRAM_NO_CONTEXT Capsule { 497 Type (i) = REGISTER_DATAGRAM_NO_CONTEXT, 498 Length (i), 499 Datagram Format Type (i), 500 Datagram Format Additional Data (..), 501 } 503 Figure 5: REGISTER_DATAGRAM_NO_CONTEXT Capsule Format 505 Datagram Format Type: A variable-length integer that defines the 506 semantics and encoding of the HTTP Datagram Payload field of 507 datagrams, see Section 2.2. 509 Datagram Format Additional Data: This field carries additional 510 information that impact the format of datagrams, see Section 2.2. 512 Note that this registration is unilateral and bidirectional: the 513 client unilaterally defines the semantics it will apply to the 514 datagrams it sends and receives with this stream. 516 Endpoints MUST NOT send DATAGRAM frames without a Context ID until 517 they have either sent or received a REGISTER_DATAGRAM_NO_CONTEXT 518 Capsule. However, due to reordering, an endpoint that receives a 519 DATAGRAM frame before receiving either a REGISTER_DATAGRAM_CONTEXT 520 capsule or a REGISTER_DATAGRAM_NO_CONTEXT capsule MUST NOT treat it 521 as an error, it SHALL instead drop the DATAGRAM frame silently, or 522 buffer it temporarily while awaiting a REGISTER_DATAGRAM_NO_CONTEXT 523 capsule or the corresponding REGISTER_DATAGRAM_CONTEXT capsule. 525 Servers MUST NOT send the REGISTER_DATAGRAM_NO_CONTEXT capsule. If a 526 client receives a REGISTER_DATAGRAM_NO_CONTEXT capsule, the client 527 MUST abruptly terminate the corresponding stream with a stream error 528 of type H3_GENERAL_PROTOCOL_ERROR. 530 Clients MUST NOT send more than one REGISTER_DATAGRAM_NO_CONTEXT 531 capsule on a stream. If a server receives a second 532 REGISTER_DATAGRAM_NO_CONTEXT capsule on the same stream, the server 533 MUST abruptly terminate the corresponding stream with a stream error 534 of type H3_GENERAL_PROTOCOL_ERROR. 536 Clients MUST NOT send both REGISTER_DATAGRAM_CONTEXT capsules and 537 REGISTER_DATAGRAM_NO_CONTEXT capsules on the same stream. If a 538 server receives both a REGISTER_DATAGRAM_CONTEXT capsule and a 539 REGISTER_DATAGRAM_NO_CONTEXT capsule on the same stream, the server 540 MUST abruptly terminate the corresponding stream with a stream error 541 of type H3_GENERAL_PROTOCOL_ERROR. 543 Extensions MAY define a different mechanism to communicate whether 544 contexts are in use, and they MAY do so in a way which is opaque to 545 intermediaries. 547 4.4.3. The CLOSE_DATAGRAM_CONTEXT Capsule 549 The CLOSE_DATAGRAM_CONTEXT capsule (see Section 8.2 for the value of 550 the capsule type) allows an endpoint to inform its peer that it will 551 no longer send or parse received datagrams associated with a given 552 context ID. 554 CLOSE_DATAGRAM_CONTEXT Capsule { 555 Type (i) = CLOSE_DATAGRAM_CONTEXT, 556 Length (i), 557 Context ID (i), 558 Close Code (i), 559 Close Details (..), 560 } 562 Figure 6: CLOSE_DATAGRAM_CONTEXT Capsule Format 564 Context ID: The context ID to close. 566 Close Code: The close code allows an endpoint to provide additional 567 information as to why a datagram context was closed. 568 Section 4.4.3.1 defines a set of codes, the circumstances under 569 which an implementation sends them, and how receivers react. 571 Close Details: This is meant for debugging purposes. It consists of 572 a human-readable string encoded in UTF-8. 574 Note that this close is unilateral and bidirectional: the sender of 575 the frame unilaterally informs its peer of the closure. Endpoints 576 can use CLOSE_DATAGRAM_CONTEXT capsules to close a context that was 577 initially registered by either themselves, or by their peer. 578 Endpoints MAY use the CLOSE_DATAGRAM_CONTEXT capsule to immediately 579 reject a context that was just registered using a 580 REGISTER_DATAGRAM_CONTEXT capsule if they find its Datagram Format 581 Type field to be unacceptable. 583 After an endpoint has either sent or received a 584 CLOSE_DATAGRAM_CONTEXT frame, it MUST NOT send any DATAGRAM frames 585 with that Context ID. However, due to reordering, an endpoint that 586 receives a DATAGRAM frame with a closed Context ID MUST NOT treat it 587 as an error, it SHALL instead drop the DATAGRAM frame silently. 589 Endpoints MUST NOT close a Context ID that was not previously 590 registered. Endpoints MUST NOT close a Context ID that has already 591 been closed. If an endpoint receives a CLOSE_DATAGRAM_CONTEXT 592 capsule that violates one or more of these requirements, the endpoint 593 MUST abruptly terminate the corresponding stream with a stream error 594 of type H3_GENERAL_PROTOCOL_ERROR. 596 4.4.3.1. Close Codes 598 Close codes are intended to allow implementations to react 599 differently when they receive them - for example, some close codes 600 require the receiver to not open another context under certain 601 conditions. 603 This specification defines the close codes below. Their numeric 604 values are in Section 8.4. Extensions to this mechanism MAY define 605 new close codes and they SHOULD state how receivers react to them. 607 NO_ERROR: This indicates that a context was closed without any 608 action specified for the receiver. 610 UNKNOWN_FORMAT: This indicates that the sender does not know how to 611 interpret the datagram format type associated with this context. 612 The endpoint that had originally registered this context MUST NOT 613 try to register another context with the same datagram format type 614 on this stream. 616 DENIED: This indicates that the sender has rejected the context 617 registration based on its local policy. The endpoint that had 618 originally registered this context MUST NOT try to register 619 another context with the same datagram format type and datagram 620 format data on this stream. 622 RESOURCE_LIMIT: This indicates that the context was closed to save 623 resources. The recipient SHOULD limit its future registration of 624 resource-intensive contexts. 626 Receipt of an unknown close code MUST be treated as if the NO_ERROR 627 code was present. Close codes are registered with IANA, see 628 Section 8.4. 630 4.4.4. The DATAGRAM Capsule 632 The DATAGRAM capsule (see Section 8.2 for the value of the capsule 633 type) allows an endpoint to send a datagram frame over an HTTP 634 stream. This is particularly useful when using a version of HTTP 635 that does not support QUIC DATAGRAM frames. 637 DATAGRAM Capsule { 638 Type (i) = DATAGRAM, 639 Length (i), 640 [Context ID (i)], 641 HTTP Datagram Payload (..), 642 } 644 Figure 7: DATAGRAM Capsule Format 646 Context ID: A variable-length integer indicating the context ID of 647 the datagram (see Section 2.1). Whether or not this field is 648 present depends on which registration capsules were exchanged on 649 the associated stream: if a REGISTER_DATAGRAM_CONTEXT capsule (see 650 Section 4.4.1) has been sent or received on this stream, then the 651 field is present; if a REGISTER_DATAGRAM_NO_CONTEXT capsule (see 652 Section 4.4.2) has been sent or received, then this field is 653 absent; if neither has been sent or received, then it is not yet 654 possible to parse this datagram and the receiver MUST either drop 655 that datagram silently or buffer it temporarily while awaiting the 656 registration capsule. 658 HTTP Datagram Payload: The payload of the datagram, whose semantics 659 are defined by individual applications. Note that this field can 660 be empty. 662 Datagrams sent using the DATAGRAM Capsule have the exact same 663 semantics as datagrams sent in QUIC DATAGRAM frames. In particular, 664 the restrictions on when it is allowed to send an HTTP Datagram and 665 how to process them from Section 3 also apply to HTTP Datagrams sent 666 and received using the DATAGRAM capsule. 668 The DATAGRAM Capsule is transparent to intermediaries, meaning that 669 intermediaries MAY parse it and send DATAGRAM Capsules that they did 670 not receive. This allows an intermediary to reencode HTTP Datagrams 671 as it forwards them: in other words, an intermediary MAY send a 672 DATAGRAM Capsule to forward an HTTP Datagram which was received in a 673 QUIC DATAGRAM frame, and vice versa. 675 Note that while DATAGRAM capsules are sent on a stream, 676 intermediaries can reencode HTTP Datagrams into QUIC DATAGRAM frames 677 over the next hop, and those could be dropped. Because of this, 678 applications have to always consider HTTP Datagrams to be unreliable, 679 even if they were initially sent in a capsule. 681 If an intermediary receives an HTTP Datagram in a QUIC DATAGRAM frame 682 and is forwarding it on a connection that supports QUIC DATAGRAM 683 frames, the intermediary SHOULD NOT convert that HTTP Datagram to a 684 DATAGRAM capsule. If the HTTP Datagram is too large to fit in a 685 DATAGRAM frame (for example because the path MTU of that QUIC 686 connection is too low or if the maximum UDP payload size advertised 687 on that connection is too low), the intermediary SHOULD drop the HTTP 688 Datagram instead of converting it to a DATAGRAM capsule. This 689 preserves the end-to-end unreliability characteristic that methods 690 such as Datagram Packetization Layer Path MTU Discovery (DPLPMTUD) 691 depend on [RFC8899]. An intermediary that converts QUIC DATAGRAM 692 frames to DATAGRAM capsules allows HTTP Datagrams to be arbitrarily 693 large without suffering any loss; this can misrepresent the true path 694 properties, defeating methods such a DPLPMTUD. 696 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter 698 Implementations of HTTP/3 that support HTTP Datagrams can indicate 699 that to their peer by sending the H3_DATAGRAM SETTINGS parameter with 700 a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST 701 be either 0 or 1. A value of 0 indicates that HTTP Datagrams are not 702 supported. An endpoint that receives the H3_DATAGRAM SETTINGS 703 parameter with a value that is neither 0 or 1 MUST terminate the 704 connection with error H3_SETTINGS_ERROR. 706 Endpoints MUST NOT send QUIC DATAGRAM frames until they have both 707 sent and received the H3_DATAGRAM SETTINGS parameter with a value of 708 1. 710 When clients use 0-RTT, they MAY store the value of the server's 711 H3_DATAGRAM SETTINGS parameter. Doing so allows the client to send 712 QUIC DATAGRAM frames in 0-RTT packets. When servers decide to accept 713 0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater 714 than or equal to the value they sent to the client in the connection 715 where they sent them the NewSessionTicket message. If a client 716 stores the value of the H3_DATAGRAM SETTINGS parameter with their 717 0-RTT state, they MUST validate that the new value of the H3_DATAGRAM 718 SETTINGS parameter sent by the server in the handshake is greater 719 than or equal to the stored value; if not, the client MUST terminate 720 the connection with error H3_SETTINGS_ERROR. In all cases, the 721 maximum permitted value of the H3_DATAGRAM SETTINGS parameter is 1. 723 5.1. Note About Draft Versions 725 [[RFC editor: please remove this section before publication.]] 727 Some revisions of this draft specification use a different value (the 728 Identifier field of a Setting in the HTTP/3 SETTINGS frame) for the 729 H3_DATAGRAM Settings Parameter. This allows new draft revisions to 730 make incompatible changes. Multiple draft versions MAY be supported 731 by either endpoint in a connection. Such endpoints MUST send 732 multiple values for H3_DATAGRAM. Once an endpoint has sent and 733 received SETTINGS, it MUST compute the intersection of the values it 734 has sent and received, and then it MUST select and use the most 735 recent draft version from the intersection set. This ensures that 736 both endpoints negotiate the same draft version. 738 6. Prioritization 740 Data streams (see Section 4.1) can be prioritized using any means 741 suited to stream or request prioritization. For example, see 742 Section 11 of [PRIORITY]. 744 Prioritization of HTTP/3 datagrams is not defined in this document. 745 Future extensions MAY define how to prioritize datagrams, and MAY 746 define signaling to allow endpoints to communicate their 747 prioritization preferences. 749 7. Security Considerations 751 Since this feature requires sending an HTTP/3 Settings parameter, it 752 "sticks out". In other words, probing clients can learn whether a 753 server supports this feature. Implementations that support this 754 feature SHOULD always send this Settings parameter to avoid leaking 755 the fact that there are applications using HTTP/3 datagrams enabled 756 on this endpoint. 758 8. IANA Considerations 760 8.1. HTTP/3 SETTINGS Parameter 762 This document will request IANA to register the following entry in 763 the "HTTP/3 Settings" registry: 765 +==============+==========+===============+=========+ 766 | Setting Name | Value | Specification | Default | 767 +==============+==========+===============+=========+ 768 | H3_DATAGRAM | 0xffd277 | This Document | 0 | 769 +--------------+----------+---------------+---------+ 771 Table 1: New HTTP/3 Settings 773 8.2. Capsule Types 775 This document establishes a registry for HTTP capsule type codes. 776 The "HTTP Capsule Types" registry governs a 62-bit space. 777 Registrations in this registry MUST include the following fields: 779 Type: A name or label for the capsule type. 781 Value: The value of the Capsule Type field (see Section 4.1) is a 782 62-bit integer. 784 Reference: An optional reference to a specification for the type. 785 This field MAY be empty. 787 Registrations follow the "First Come First Served" policy (see 788 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 789 the same Type. 791 This registry initially contains the following entries: 793 +==============================+==========+===============+ 794 | Capsule Type | Value | Specification | 795 +==============================+==========+===============+ 796 | DATAGRAM | 0xff37a0 | This Document | 797 +------------------------------+----------+---------------+ 798 | REGISTER_DATAGRAM_CONTEXT | 0xff37a1 | This Document | 799 +------------------------------+----------+---------------+ 800 | REGISTER_DATAGRAM_NO_CONTEXT | 0xff37a2 | This Document | 801 +------------------------------+----------+---------------+ 802 | CLOSE_DATAGRAM_CONTEXT | 0xff37a3 | This Document | 803 +------------------------------+----------+---------------+ 805 Table 2: Initial Capsule Types Registry Entries 807 Capsule types with a value of the form 41 * N + 23 for integer values 808 of N are reserved to exercise the requirement that unknown capsule 809 types be ignored. These capsules have no semantics and can carry 810 arbitrary values. These values MUST NOT be assigned by IANA and MUST 811 NOT appear in the listing of assigned values. 813 8.3. Datagram Format Types 815 This document establishes a registry for HTTP datagram format type 816 codes. The "HTTP Datagram Format Types" registry governs a 62-bit 817 space. Registrations in this registry MUST include the following 818 fields: 820 Type: A name or label for the datagram format type. 822 Value: The value of the Datagram Format Type field (see Section 2.2) 823 is a 62-bit integer. 825 Reference: An optional reference to a specification for the 826 parameter. This field MAY be empty. 828 Registrations follow the "First Come First Served" policy (see 829 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 830 the same Type nor Value. 832 This registry is initially empty. 834 Datagram format types with a value of the form 41 * N + 17 for 835 integer values of N are reserved to exercise the requirement that 836 unknown datagram format types be ignored. These format types have no 837 semantics and can carry arbitrary values. These values MUST NOT be 838 assigned by IANA and MUST NOT appear in the listing of assigned 839 values. 841 8.4. Context Close Codes 843 This document establishes a registry for HTTP context close codes. 844 The "HTTP Context Close Codes" registry governs a 62-bit space. 845 Registrations in this registry MUST include the following fields: 847 Type: A name or label for the close code. 849 Value: The value of the Close Code field (see Section 4.4.3) is a 850 62-bit integer. 852 Reference: An optional reference to a specification for the 853 parameter. This field MAY be empty. 855 Registrations follow the "First Come First Served" policy (see 856 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 857 the same Type nor Value. 859 This registry initially contains the following entries: 861 +====================+==========+===============+ 862 | Context Close Code | Value | Specification | 863 +====================+==========+===============+ 864 | NO_ERROR | 0xff78a0 | This Document | 865 +--------------------+----------+---------------+ 866 | UNKNOWN_FORMAT | 0xff78a1 | This Document | 867 +--------------------+----------+---------------+ 868 | DENIED | 0xff78a2 | This Document | 869 +--------------------+----------+---------------+ 870 | RESOURCE_LIMIT | 0xff78a3 | This Document | 871 +--------------------+----------+---------------+ 873 Table 3: Initial Context Close Code Registry 874 Entries 876 Context close codes with a value of the form 41 * N + 19 for integer 877 values of N are reserved to exercise the requirement that unknown 878 context close codes be treated as NO_ERROR. These values MUST NOT be 879 assigned by IANA and MUST NOT appear in the listing of assigned 880 values. 882 9. References 884 9.1. Normative References 886 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 887 Datagram Extension to QUIC", Work in Progress, Internet- 888 Draft, draft-ietf-quic-datagram-06, 5 October 2021, 889 . 892 [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 893 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 894 quic-http-34, 2 February 2021, 895 . 898 [IANA-POLICY] 899 Cotton, M., Leiba, B., and T. Narten, "Guidelines for 900 Writing an IANA Considerations Section in RFCs", BCP 26, 901 RFC 8126, DOI 10.17487/RFC8126, June 2017, 902 . 904 [QUIC] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 905 Multiplexed and Secure Transport", RFC 9000, 906 DOI 10.17487/RFC9000, May 2021, 907 . 909 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 910 Requirement Levels", BCP 14, RFC 2119, 911 DOI 10.17487/RFC2119, March 1997, 912 . 914 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 915 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 916 May 2017, . 918 9.2. Informative References 920 [PRIORITY] Oku, K. and L. Pardue, "Extensible Prioritization Scheme 921 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 922 httpbis-priority-06, 30 September 2021, 923 . 926 [RFC8899] Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and T. 927 Völker, "Packetization Layer Path MTU Discovery for 928 Datagram Transports", RFC 8899, DOI 10.17487/RFC8899, 929 September 2020, . 931 Appendix A. Examples 933 A.1. CONNECT-UDP 935 Client Server 937 STREAM(44): HEADERS --------> 938 :method = CONNECT-UDP 939 :scheme = https 940 :path = / 941 :authority = target.example.org:443 943 STREAM(44): DATA --------> 944 Capsule Type = REGISTER_DATAGRAM_CONTEXT 945 Context ID = 0 946 Datagram Format Type = UDP_PAYLOAD 947 Datagram Format Additional Data = "" 949 DATAGRAM --------> 950 Quarter Stream ID = 11 951 Context ID = 0 952 Payload = Encapsulated UDP Payload 954 <-------- STREAM(44): HEADERS 955 :status = 200 957 /* Wait for target server to respond to UDP packet. */ 959 <-------- DATAGRAM 960 Quarter Stream ID = 11 961 Context ID = 0 962 Payload = Encapsulated UDP Payload 964 A.2. CONNECT-UDP with Timestamp Extension 965 Client Server 967 STREAM(44): HEADERS --------> 968 :method = CONNECT-UDP 969 :scheme = https 970 :path = / 971 :authority = target.example.org:443 973 STREAM(44): DATA --------> 974 Capsule Type = REGISTER_DATAGRAM_CONTEXT 975 Context ID = 0 976 Datagram Format Type = UDP_PAYLOAD 977 Datagram Format Additional Data = "" 979 DATAGRAM --------> 980 Quarter Stream ID = 11 981 Context ID = 0 982 Payload = Encapsulated UDP Payload 984 <-------- STREAM(44): HEADERS 985 :status = 200 987 /* Wait for target server to respond to UDP packet. */ 989 <-------- DATAGRAM 990 Quarter Stream ID = 11 991 Context ID = 0 992 Payload = Encapsulated UDP Payload 994 STREAM(44): DATA --------> 995 Capsule Type = REGISTER_DATAGRAM_CONTEXT 996 Context ID = 2 997 Datagram Format Type = UDP_PAYLOAD_WITH_TIMESTAMP 998 Datagram Format Additional Data = "" 1000 DATAGRAM --------> 1001 Quarter Stream ID = 11 1002 Context ID = 2 1003 Payload = Encapsulated UDP Payload With Timestamp 1005 A.3. CONNECT-IP with IP compression 1006 Client Server 1008 STREAM(44): HEADERS --------> 1009 :method = CONNECT-IP 1010 :scheme = https 1011 :path = / 1012 :authority = proxy.example.org:443 1014 <-------- STREAM(44): HEADERS 1015 :status = 200 1017 /* Exchange CONNECT-IP configuration information. */ 1019 STREAM(44): DATA --------> 1020 Capsule Type = REGISTER_DATAGRAM_CONTEXT 1021 Context ID = 0 1022 Datagram Format Type = IP_PACKET 1023 Datagram Format Additional Data = "" 1025 DATAGRAM --------> 1026 Quarter Stream ID = 11 1027 Context ID = 0 1028 Payload = Encapsulated IP Packet 1030 /* Endpoint happily exchange encapsulated IP packets */ 1031 /* using Quarter Stream ID 11 and Context ID 0. */ 1033 DATAGRAM --------> 1034 Quarter Stream ID = 11 1035 Context ID = 0 1036 Payload = Encapsulated IP Packet 1038 /* After performing some analysis on traffic patterns, */ 1039 /* the client decides it wants to compress a 2-tuple. */ 1041 STREAM(44): DATA --------> 1042 Capsule Type = REGISTER_DATAGRAM_CONTEXT 1043 Context ID = 2 1044 Datagram Format Type = COMPRESSED_IP_PACKET 1045 Datagram Format Additional Data = "192.0.2.6,192.0.2.7" 1047 DATAGRAM --------> 1048 Quarter Stream ID = 11 1049 Context ID = 2 1050 Payload = Compressed IP Packet 1052 A.4. WebTransport 1054 Client Server 1056 STREAM(44): HEADERS --------> 1057 :method = CONNECT 1058 :scheme = https 1059 :method = webtransport 1060 :path = /hello 1061 :authority = webtransport.example.org:443 1062 Origin = https://www.example.org:443 1064 STREAM(44): DATA --------> 1065 Capsule Type = REGISTER_DATAGRAM_NO_CONTEXT 1066 Datagram Format Type = WEBTRANSPORT_DATAGRAM 1067 Datagram Format Additional Data = "" 1069 <-------- STREAM(44): HEADERS 1070 :status = 200 1072 /* Both endpoints can now send WebTransport datagrams. */ 1074 Acknowledgments 1076 The DATAGRAM context identifier was previously part of the DATAGRAM 1077 frame definition itself, the authors would like to acknowledge the 1078 authors of that document and the members of the IETF MASQUE working 1079 group for their suggestions. Additionally, the authors would like to 1080 thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS 1081 parameter. Furthermore, the authors would like to thank Ben Schwartz 1082 for writing the first proposal that used two layers of indirection. 1084 Authors' Addresses 1086 David Schinazi 1087 Google LLC 1088 1600 Amphitheatre Parkway 1089 Mountain View, California 94043, 1090 United States of America 1092 Email: dschinazi.ietf@gmail.com 1094 Lucas Pardue 1095 Cloudflare 1097 Email: lucaspardue.24.7@gmail.com