idnits 2.17.00 (12 Aug 2021) /tmp/idnits36279/draft-ietf-masque-h3-datagram-09.txt: -(652): 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 document date (11 April 2022) is 33 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Normative reference to a draft: ref. 'HTTP' Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 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 October 2022 Cloudflare 6 11 April 2022 8 HTTP Datagrams and the Capsule Protocol 9 draft-ietf-masque-h3-datagram-09 11 Abstract 13 This document describes HTTP Datagrams, a convention for conveying 14 multiplexed, potentially unreliable datagrams inside an HTTP 15 connection. 17 In HTTP/3, HTTP Datagrams can be conveyed natively using the QUIC 18 DATAGRAM extension. When the QUIC DATAGRAM frame is unavailable or 19 undesirable, they can be sent using the Capsule Protocol, a more 20 general convention for conveying data in HTTP connections. 22 HTTP Datagrams and the Capsule Protocol are intended for use by HTTP 23 extensions, not applications. 25 About This Document 27 This note is to be removed before publishing as an RFC. 29 The latest revision of this draft can be found at https://ietf-wg- 30 masque.github.io/draft-ietf-masque-h3-datagram/draft-ietf-masque- 31 h3-datagram.html. Status information for this document may be found 32 at https://datatracker.ietf.org/doc/draft-ietf-masque-h3-datagram/. 34 Discussion of this document takes place on the MASQUE Working Group 35 mailing list (mailto:masque@ietf.org), which is archived at 36 https://mailarchive.ietf.org/arch/browse/masque/. 38 Source for this draft and an issue tracker can be found at 39 https://github.com/ietf-wg-masque/draft-ietf-masque-h3-datagram. 41 Status of This Memo 43 This Internet-Draft is submitted in full conformance with the 44 provisions of BCP 78 and BCP 79. 46 Internet-Drafts are working documents of the Internet Engineering 47 Task Force (IETF). Note that other groups may also distribute 48 working documents as Internet-Drafts. The list of current Internet- 49 Drafts is at https://datatracker.ietf.org/drafts/current/. 51 Internet-Drafts are draft documents valid for a maximum of six months 52 and may be updated, replaced, or obsoleted by other documents at any 53 time. It is inappropriate to use Internet-Drafts as reference 54 material or to cite them other than as "work in progress." 56 This Internet-Draft will expire on 13 October 2022. 58 Copyright Notice 60 Copyright (c) 2022 IETF Trust and the persons identified as the 61 document authors. All rights reserved. 63 This document is subject to BCP 78 and the IETF Trust's Legal 64 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 65 license-info) in effect on the date of publication of this document. 66 Please review these documents carefully, as they describe your rights 67 and restrictions with respect to this document. Code Components 68 extracted from this document must include Revised BSD License text as 69 described in Section 4.e of the Trust Legal Provisions and are 70 provided without warranty as described in the Revised BSD License. 72 Table of Contents 74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 75 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 76 2. HTTP Datagrams . . . . . . . . . . . . . . . . . . . . . . . 3 77 2.1. HTTP/3 Datagrams . . . . . . . . . . . . . . . . . . . . 4 78 2.1.1. The SETTINGS_H3_DATAGRAM HTTP/3 Setting . . . . . . . 5 79 2.2. HTTP Datagrams using Capsules . . . . . . . . . . . . . . 6 80 3. Capsules . . . . . . . . . . . . . . . . . . . . . . . . . . 7 81 3.1. HTTP Data Streams . . . . . . . . . . . . . . . . . . . . 7 82 3.2. The Capsule Protocol . . . . . . . . . . . . . . . . . . 8 83 3.3. Error Handling . . . . . . . . . . . . . . . . . . . . . 9 84 3.4. The Capsule-Protocol Header Field . . . . . . . . . . . . 9 85 3.5. The DATAGRAM Capsule . . . . . . . . . . . . . . . . . . 10 86 4. Security Considerations . . . . . . . . . . . . . . . . . . . 12 87 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 88 5.1. HTTP/3 Setting . . . . . . . . . . . . . . . . . . . . . 12 89 5.2. HTTP/3 Error Code . . . . . . . . . . . . . . . . . . . . 12 90 5.3. HTTP Header Field Name . . . . . . . . . . . . . . . . . 12 91 5.4. Capsule Types . . . . . . . . . . . . . . . . . . . . . . 13 92 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 93 6.1. Normative References . . . . . . . . . . . . . . . . . . 13 94 6.2. Informative References . . . . . . . . . . . . . . . . . 15 95 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 15 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 98 1. Introduction 100 HTTP extensions sometimes need to access underlying transport 101 protocol features such as unreliable delivery (as offered by [DGRAM]) 102 to enable desirable features. For example, this could allow 103 introducing an unreliable version of the CONNECT method, or adding 104 unreliable delivery to WebSockets [RFC6455]. 106 In Section 2, this document describes HTTP Datagrams, a convention 107 that supports the bidirectional and optionally multiplexed exchange 108 of data inside an HTTP connection. While HTTP datagrams are 109 associated with HTTP requests, they are not part of message content; 110 instead, they are intended for use by HTTP extensions (such as the 111 CONNECT method), and are compatible with all versions of HTTP. 113 When HTTP is running over a transport protocol that supports 114 unreliable delivery (such as when the QUIC DATAGRAM extension is 115 available to HTTP/3), HTTP Datagrams can use that capability. 117 This document also describes the HTTP Capsule Protocol in Section 3, 118 to allow conveyance of HTTP Datagrams using reliable delivery. This 119 addresses HTTP/3 cases where use of the QUIC DATAGRAM frame is 120 unavailable or undesirable, or where the transport protocol only 121 provides reliable delivery, such as with HTTP/1 or HTTP/2 over TCP. 123 1.1. Conventions and Definitions 125 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 126 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 127 "OPTIONAL" in this document are to be interpreted as described in 128 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 129 capitals, as shown here. 131 2. HTTP Datagrams 133 HTTP Datagrams are a convention for conveying bidirectional and 134 potentially unreliable datagrams inside an HTTP connection, with 135 multiplexing when possible. All HTTP Datagrams are associated with 136 an HTTP request. 138 When HTTP Datagrams are conveyed on an HTTP/3 connection, the QUIC 139 DATAGRAM frame can be used to achieve these goals, including 140 unreliable delivery; see Section 2.1. Negotiating the use of QUIC 141 DATAGRAM frames for HTTP Datagrams is achieved via the exchange of 142 HTTP/3 settings; see Section 2.1.1. 144 When running over HTTP/2, demultiplexing is provided by the HTTP/2 145 framing layer, but unreliable delivery is unavailable. HTTP 146 Datagrams are negotiated and conveyed using the Capsule Protocol; see 147 Section 3.5. 149 When running over HTTP/1, requests are strictly serialized in the 150 connection, and therefore demultiplexing is not available. 151 Unreliable delivery is likewise not available. HTTP Datagrams are 152 negotiated and conveyed using the Capsule Protocol; see Section 3.5. 154 HTTP Datagrams MUST only be sent with an association to an HTTP 155 request that explicitly supports them. For example, existing HTTP 156 methods GET and POST do not define semantics for associated HTTP 157 Datagrams; therefore, HTTP Datagrams cannot be sent associated with 158 GET or POST request streams. 160 If an HTTP Datagram is received and it is associated with a request 161 that has no known semantics for HTTP Datagrams, the receiver MUST 162 terminate the request; if HTTP/3 is in use, the request stream MUST 163 be aborted with H3_DATAGRAM_ERROR (0x33). HTTP extensions can 164 override these requirements by defining a negotiation mechanism and 165 semantics for HTTP Datagrams. 167 2.1. HTTP/3 Datagrams 169 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 170 frames uses the following format (using the notation from the 171 "Notational Conventions" section of [QUIC]): 173 HTTP/3 Datagram { 174 Quarter Stream ID (i), 175 HTTP Datagram Payload (..), 176 } 178 Figure 1: HTTP/3 Datagram Format 180 Quarter Stream ID: A variable-length integer that contains the value 181 of the client-initiated bidirectional stream that this datagram is 182 associated with, divided by four (the division by four stems from 183 the fact that HTTP requests are sent on client-initiated 184 bidirectional streams, and those have stream IDs that are 185 divisible by four). The largest legal QUIC stream ID value is 186 2^62-1, so the largest legal value of Quarter Stream ID is 2^60-1. 187 Receipt of an HTTP/3 Datagram that includes a larger value MUST be 188 treated as an HTTP/3 connection error of type H3_DATAGRAM_ERROR 189 (0x33). 191 HTTP Datagram Payload: The payload of the datagram, whose semantics 192 are defined by the extension that is using HTTP Datagrams. Note 193 that this field can be empty. 195 Receipt of a QUIC DATAGRAM frame whose payload is too short to allow 196 parsing the Quarter Stream ID field MUST be treated as an HTTP/3 197 connection error of type H3_DATAGRAM_ERROR (0x33). 199 HTTP/3 Datagrams MUST NOT be sent unless the corresponding stream's 200 send side is open. If a datagram is received after the corresponding 201 stream's receive side is closed, the received datagrams MUST be 202 silently dropped. 204 If an HTTP/3 datagram is received and its Quarter Stream ID maps to a 205 stream that has not yet been created, the receiver SHALL either drop 206 that datagram silently or buffer it temporarily (on the order of a 207 round trip) while awaiting the creation of the corresponding stream. 209 If an HTTP/3 datagram is received and its Quarter Stream ID maps to a 210 stream that cannot be created due to client-initiated bidirectional 211 stream limits, it SHOULD be treated as an HTTP/3 connection error of 212 type H3_ID_ERROR. Generating an error is not mandatory in this case 213 because HTTP/3 implementations might have practical barriers to 214 determining the active stream concurrency limit that is applied by 215 the QUIC layer. 217 Prioritization of HTTP/3 datagrams is not defined in this document. 218 Future extensions MAY define how to prioritize datagrams, and MAY 219 define signaling to allow communicating prioritization preferences. 221 2.1.1. The SETTINGS_H3_DATAGRAM HTTP/3 Setting 223 Endpoints can indicate to their peer that they are willing to receive 224 HTTP/3 Datagrams by sending the SETTINGS_H3_DATAGRAM (0x33) setting 225 with a value of 1. 227 The value of the SETTINGS_H3_DATAGRAM setting MUST be either 0 or 1. 228 A value of 0 indicates that the implementation is not willing to 229 receive HTTP Datagrams. If the SETTINGS_H3_DATAGRAM setting is 230 received with a value that is neither 0 or 1, the receiver MUST 231 terminate the connection with error H3_SETTINGS_ERROR. 233 QUIC DATAGRAM frames MUST NOT be sent until the SETTINGS_H3_DATAGRAM 234 setting has been both sent and received with a value of 1. 236 When clients use 0-RTT, they MAY store the value of the server's 237 SETTINGS_H3_DATAGRAM setting. Doing so allows the client to send 238 QUIC DATAGRAM frames in 0-RTT packets. When servers decide to accept 239 0-RTT data, they MUST send a SETTINGS_H3_DATAGRAM setting greater 240 than or equal to the value they sent to the client in the connection 241 where they sent them the NewSessionTicket message. If a client 242 stores the value of the SETTINGS_H3_DATAGRAM setting with their 0-RTT 243 state, they MUST validate that the new value of the 244 SETTINGS_H3_DATAGRAM setting sent by the server in the handshake is 245 greater than or equal to the stored value; if not, the client MUST 246 terminate the connection with error H3_SETTINGS_ERROR. In all cases, 247 the maximum permitted value of the SETTINGS_H3_DATAGRAM setting 248 parameter is 1. 250 It is RECOMMENDED that implementations that support receiving HTTP/3 251 Datagrams always send the SETTINGS_H3_DATAGRAM setting with a value 252 of 1, even if the application does not intend to use HTTP/3 253 Datagrams. This helps to avoid "sticking out"; see Section 4. 255 2.1.1.1. Note About Draft Versions 257 [[RFC editor: please remove this section before publication.]] 259 Some revisions of this draft specification use a different value (the 260 Identifier field of a Setting in the HTTP/3 SETTINGS frame) for the 261 SETTINGS_H3_DATAGRAM setting. This allows new draft revisions to 262 make incompatible changes. Multiple draft versions MAY be supported 263 by sending multiple values for SETTINGS_H3_DATAGRAM. Once SETTINGS 264 have been sent and received, an implementation that supports multiple 265 drafts MUST compute the intersection of the values it has sent and 266 received, and then it MUST select and use the most recent draft 267 version from the intersection set. This ensures that both peers 268 negotiate the same draft version. 270 2.2. HTTP Datagrams using Capsules 272 When HTTP/3 Datagrams are unavailable or undesirable, HTTP Datagrams 273 can be sent using the Capsule Protocol, see Section 3.5. 275 3. Capsules 277 One mechanism to extend HTTP is to introduce new HTTP Upgrade Tokens 278 (see Section 16.7 of [HTTP]). In HTTP/1.x, these tokens are used via 279 the Upgrade mechanism (see Section 7.8 of [HTTP]). In HTTP/2 and 280 HTTP/3, these tokens are used via the Extended CONNECT mechanism (see 281 [EXT-CONNECT2] and [EXT-CONNECT3]). 283 This specification introduces the Capsule Protocol. The Capsule 284 Protocol is a sequence of type-length-value tuples that definitions 285 of new HTTP Upgrade Tokens can choose to use. It allows endpoints to 286 reliably communicate request-related information end-to-end on HTTP 287 request streams, even in the presence of HTTP intermediaries. The 288 Capsule Protocol can be used to exchange HTTP Datagrams, which is 289 necessary when HTTP is running over a transport that does not support 290 the QUIC DATAGRAM frame. The Capsule Protocol can also be used to 291 communicate reliable and bidirectional control messages associated 292 with a datagram-based protocol even when HTTP/3 Datagrams are in use. 294 3.1. HTTP Data Streams 296 This specification defines the "data stream" of an HTTP request as 297 the bidirectional stream of bytes that follows the header section of 298 the request message and the final, successful (i.e., 2xx) response 299 message. 301 In HTTP/1.x, the data stream consists of all bytes on the connection 302 that follow the blank line that concludes either the request header 303 section, or the response header section. As a result, only a single 304 HTTP request starting the capsule protocol can be sent on HTTP/1.x 305 connections. 307 In HTTP/2 and HTTP/3, the data stream of a given HTTP request 308 consists of all bytes sent in DATA frames with the corresponding 309 stream ID. 311 The concept of a data stream is particularly relevant for methods 312 such as CONNECT where there is no HTTP message content after the 313 headers. 315 Data streams can be prioritized using any means suited to stream or 316 request prioritization. For example, see Section 11 of [PRIORITY]. 318 3.2. The Capsule Protocol 320 Definitions of new HTTP Upgrade Tokens can state that their 321 associated request's data stream uses the Capsule Protocol. If they 322 do so, that means that the contents of the associated request's data 323 stream uses the following format (using the notation from the 324 "Notational Conventions" section of [QUIC]): 326 Capsule Protocol { 327 Capsule (..) ..., 328 } 330 Figure 2: Capsule Protocol Stream Format 332 Capsule { 333 Capsule Type (i), 334 Capsule Length (i), 335 Capsule Value (..), 336 } 338 Figure 3: Capsule Format 340 Capsule Type: A variable-length integer indicating the Type of the 341 capsule. 343 Capsule Length: The length of the Capsule Value field following this 344 field, encoded as a variable-length integer. Note that this field 345 can have a value of zero. 347 Capsule Value: The payload of this capsule. Its semantics are 348 determined by the value of the Capsule Type field. 350 An intermediary can identify the use of the capsule protocol either 351 through the presence of the Capsule-Protocol header field 352 (Section 3.4) or by understanding the chosen HTTP Upgrade token. 354 Because new protocols or extensions might define new capsule types, 355 intermediaries that wish to allow for future extensibility SHOULD 356 forward capsules without modification, unless the definition of the 357 Capsule Type in use specifies additional intermediary processing. 358 One such Capsule Type is the DATAGRAM capsule; see Section 3.5. In 359 particular, intermediaries SHOULD forward Capsules with an unknown 360 Capsule Type without modification. 362 Endpoints which receive a Capsule with an unknown Capsule Type MUST 363 silently drop that Capsule and skip over it to parse the next 364 Capsule. 366 By virtue of the definition of the data stream: 368 * The Capsule Protocol is not in use unless the response includes a 369 2xx (Successful) status code. 371 * When the Capsule Protocol is in use, the associated HTTP request 372 and response do not carry HTTP content. A future extension MAY 373 define a new capsule type to carry HTTP content. 375 The Capsule Protocol MUST NOT be used with messages that contain 376 Content-Length, Content-Type, or Transfer-Encoding header fields. 377 Additionally, HTTP status codes 204 (No Content), 205 (Reset 378 Content), and 206 (Partial Content) MUST NOT be sent on responses 379 that use the Capsule Protocol. A receiver that observes a violation 380 of these requirements MUST treat the HTTP message as malformed. 382 3.3. Error Handling 384 When an error occurs in processing the Capsule Protocol, the receiver 385 MUST treat the message as malformed or incomplete, according to the 386 underlying transport protocol. For HTTP/3, the handling of malformed 387 messages is described in Section 4.1.3 of [HTTP/3]. For HTTP/2, the 388 handling of malformed messages is described in Section 8.1.1 of 389 [HTTP/2]. For HTTP/1.1, the handling of incomplete messages is 390 described in Section 8 of [HTTP/1.1]. 392 Each capsule's payload MUST contain exactly the fields identified in 393 its description. A capsule payload that contains additional bytes 394 after the identified fields or a capsule payload that terminates 395 before the end of the identified fields MUST be treated as a 396 malformed or incomplete message. In particular, redundant length 397 encodings MUST be verified to be self-consistent. 399 If the receive side of a stream carrying capsules is terminated 400 cleanly (for example, in HTTP/3 this is defined as receiving a QUIC 401 STREAM frame with the FIN bit set) and the last capsule on the stream 402 was truncated, this MUST be treated as a malformed or incomplete 403 message. 405 3.4. The Capsule-Protocol Header Field 407 The "Capsule-Protocol" header field is an Item Structured Field, see 408 Section 3.3 of [STRUCT-FIELD]; its value MUST be a Boolean; any other 409 value type MUST be handled as if the field were not present by 410 recipients (for example, if this field is included multiple times, 411 its type will become a List and the field will therefore be ignored). 412 This document does not define any parameters for the Capsule-Protocol 413 header field value, but future documents might define parameters. 415 Receivers MUST ignore unknown parameters. 417 Endpoints indicate that the Capsule Protocol is in use on a data 418 stream by sending a Capsule-Protocol header field with a true value. 419 A Capsule-Protocol header field with a false value has the same 420 semantics as when the header is not present. 422 Intermediaries MAY use this header field to allow processing of HTTP 423 Datagrams for unknown HTTP Upgrade Tokens; note that this is only 424 possible for HTTP Upgrade or Extended CONNECT. 426 The Capsule-Protocol header field MUST NOT be used on HTTP responses 427 with a status code outside the 2xx range. 429 When using the Capsule Protocol, HTTP endpoints SHOULD send the 430 Capsule-Protocol header field to simplify intermediary processing. 431 Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol 432 MAY alter this recommendation. 434 3.5. The DATAGRAM Capsule 436 This document defines the DATAGRAM (0x00) capsule type. This capsule 437 allows HTTP Datagrams to be sent on a stream using the Capsule 438 Protocol. This is particularly useful when HTTP is running over a 439 transport that does not support the QUIC DATAGRAM frame. 441 Datagram Capsule { 442 Type (i) = 0x00, 443 Length (i), 444 HTTP Datagram Payload (..), 445 } 447 Figure 4: DATAGRAM Capsule Format 449 HTTP Datagram Payload: The payload of the datagram, whose semantics 450 are defined by the extension that is using HTTP Datagrams. Note 451 that this field can be empty. 453 HTTP Datagrams sent using the DATAGRAM capsule have the same 454 semantics as those sent in QUIC DATAGRAM frames. In particular, the 455 restrictions on when it is allowed to send an HTTP Datagram and how 456 to process them from Section 2.1 also apply to HTTP Datagrams sent 457 and received using the DATAGRAM capsule. 459 An intermediary can reencode HTTP Datagrams as it forwards them. In 460 other words, an intermediary MAY send a DATAGRAM capsule to forward 461 an HTTP Datagram that was received in a QUIC DATAGRAM frame, and vice 462 versa. Intermediaries MUST NOT perform this reencoding unless they 463 have identified the use of the Capsule Protocol on the corresponding 464 request stream; see Section 3.2. 466 Note that while DATAGRAM capsules that are sent on a stream are 467 reliably delivered in order, intermediaries can reencode DATAGRAM 468 capsules into QUIC DATAGRAM frames when forwarding messages, which 469 could result in loss or reordering. 471 If an intermediary receives an HTTP Datagram in a QUIC DATAGRAM frame 472 and is forwarding it on a connection that supports QUIC DATAGRAM 473 frames, the intermediary SHOULD NOT convert that HTTP Datagram to a 474 DATAGRAM capsule. If the HTTP Datagram is too large to fit in a 475 DATAGRAM frame (for example because the path MTU of that QUIC 476 connection is too low or if the maximum UDP payload size advertised 477 on that connection is too low), the intermediary SHOULD drop the HTTP 478 Datagram instead of converting it to a DATAGRAM capsule. This 479 preserves the end-to-end unreliability characteristic that methods 480 such as Datagram Packetization Layer Path MTU Discovery (DPLPMTUD) 481 depend on [DPLPMTUD]. An intermediary that converts QUIC DATAGRAM 482 frames to DATAGRAM capsules allows HTTP Datagrams to be arbitrarily 483 large without suffering any loss; this can misrepresent the true path 484 properties, defeating methods such as DPLPMTUD. 486 While DATAGRAM capsules can theoretically carry a payload of length 487 2^62-1, most HTTP extensions that use HTTP Datagrams will have their 488 own limits on what datagram payload sizes are practical. 489 Implementations SHOULD take those limits into account when parsing 490 DATAGRAM capsules: if an incoming DATAGRAM capsule has a length that 491 is known to be so large as to not be usable, the implementation 492 SHOULD discard the capsule without buffering its contents into 493 memory. 495 Note that it is possible for an HTTP extension to use HTTP Datagrams 496 without using the Capsule Protocol. For example, if an HTTP 497 extension that uses HTTP Datagrams is only defined over transports 498 that support QUIC DATAGRAM frames, it might not need a stream 499 encoding. Additionally, HTTP extensions can use HTTP Datagrams with 500 their own data stream protocol. However, new HTTP extensions that 501 wish to use HTTP Datagrams SHOULD use the Capsule Protocol as failing 502 to do so will make it harder for the HTTP extension to support 503 versions of HTTP other than HTTP/3 and will prevent interoperability 504 with intermediaries that only support the Capsule Protocol. 506 4. Security Considerations 508 Since transmitting HTTP Datagrams using QUIC DATAGRAM frames requires 509 sending the HTTP/3 SETTINGS_H3_DATAGRAM setting, it "sticks out". In 510 other words, probing clients can learn whether a server supports HTTP 511 Datagrams over QUIC DATAGRAM frames. As some servers might wish to 512 obfuscate the fact that they offer application services that use HTTP 513 datagrams, it's best for all implementations that support this 514 feature to always send this setting, see Section 2.1.1. 516 Since use of the Capsule Protocol is restricted to new HTTP Upgrade 517 Tokens, it is not accessible from Web Platform APIs (such as those 518 commonly accessed via JavaScript in web browsers). 520 5. IANA Considerations 522 5.1. HTTP/3 Setting 524 This document will request IANA to register the following entry in 525 the "HTTP/3 Settings" registry: 527 Value: 0x33 528 Setting Name: SETTINGS_H3_DATAGRAM 529 Default: 0 530 Status: provisional (permanent if this document is approved) 531 Specification: This Document 532 Change Controller: IETF 533 Contact: HTTP_WG; HTTP working group; ietf-http-wg@w3.org 535 5.2. HTTP/3 Error Code 537 This document will request IANA to register the following entry in 538 the "HTTP/3 Error Codes" registry: 540 Value: 0x33 541 Name: H3_DATAGRAM_ERROR 542 Description: Datagram or capsule protocol parse error 543 Status: provisional (permanent if this document is approved) 544 Specification: This Document 545 Change Controller: IETF 546 Contact: HTTP_WG; HTTP working group; ietf-http-wg@w3.org 548 5.3. HTTP Header Field Name 550 This document will request IANA to register the following entry in 551 the "HTTP Field Name" registry: 553 Field Name: Capsule-Protocol 554 Template: None 555 Status: provisional (permanent if this document is approved) 556 Reference: This document 557 Comments: None 559 5.4. Capsule Types 561 This document establishes a registry for HTTP capsule type codes. 562 The "HTTP Capsule Types" registry governs a 62-bit space, and 563 operates under the QUIC registration policy documented in 564 Section 22.1 of [QUIC]. This new registry includes the common set of 565 fields listed in Section 22.1.1 of [QUIC]. In addition to those 566 common fields, all registrations in this registry MUST include a 567 "Capsule Type" field which contains a short name or label for the 568 capsule type. 570 Permanent registrations in this registry are assigned using the 571 Specification Required policy (Section 4.6 of [IANA-POLICY]), except 572 for values between 0x00 and 0x3f (in hexadecimal; inclusive), which 573 are assigned using Standards Action or IESG Approval as defined in 574 Sections 4.9 and 4.10 of [IANA-POLICY]. 576 Capsule types with a value of the form 0x29 * N + 0x17 for integer 577 values of N are reserved to exercise the requirement that unknown 578 capsule types be ignored. These capsules have no semantics and can 579 carry arbitrary values. These values MUST NOT be assigned by IANA 580 and MUST NOT appear in the listing of assigned values. 582 This registry initially contains the following entry: 584 Value: 0x00 585 Capsule Type: DATAGRAM 586 Status: permanent 587 Specification: This document 588 Change Controller: IETF 589 Contact: MASQUE Working Group masque@ietf.org 590 (mailto:masque@ietf.org) 591 Notes: None 593 6. References 595 6.1. Normative References 597 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 598 Datagram Extension to QUIC", RFC 9221, 599 DOI 10.17487/RFC9221, March 2022, 600 . 602 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 603 Semantics", Work in Progress, Internet-Draft, draft-ietf- 604 httpbis-semantics-19, 12 September 2021, 605 . 608 [HTTP/1.1] Fielding, R. T., Nottingham, M., and J. Reschke, 609 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 610 httpbis-messaging-19, 12 September 2021, 611 . 614 [HTTP/2] Thomson, M. and C. Benfield, "HTTP/2", Work in Progress, 615 Internet-Draft, draft-ietf-httpbis-http2bis-07, 24 January 616 2022, . 619 [HTTP/3] Bishop, M., "Hypertext Transfer Protocol Version 3 620 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 621 quic-http-34, 2 February 2021, 622 . 625 [IANA-POLICY] 626 Cotton, M., Leiba, B., and T. Narten, "Guidelines for 627 Writing an IANA Considerations Section in RFCs", BCP 26, 628 RFC 8126, DOI 10.17487/RFC8126, June 2017, 629 . 631 [QUIC] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 632 Multiplexed and Secure Transport", RFC 9000, 633 DOI 10.17487/RFC9000, May 2021, 634 . 636 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 637 Requirement Levels", BCP 14, RFC 2119, 638 DOI 10.17487/RFC2119, March 1997, 639 . 641 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 642 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 643 May 2017, . 645 [STRUCT-FIELD] 646 Nottingham, M. and P-H. Kamp, "Structured Field Values for 647 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 648 . 650 6.2. Informative References 652 [DPLPMTUD] Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and T. 653 Völker, "Packetization Layer Path MTU Discovery for 654 Datagram Transports", RFC 8899, DOI 10.17487/RFC8899, 655 September 2020, . 657 [EXT-CONNECT2] 658 McManus, P., "Bootstrapping WebSockets with HTTP/2", 659 RFC 8441, DOI 10.17487/RFC8441, September 2018, 660 . 662 [EXT-CONNECT3] 663 Hamilton, R., "Bootstrapping WebSockets with HTTP/3", Work 664 in Progress, Internet-Draft, draft-ietf-httpbis-h3- 665 websockets-04, 8 February 2022, 666 . 669 [PRIORITY] Oku, K. and L. Pardue, "Extensible Prioritization Scheme 670 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 671 httpbis-priority-12, 17 January 2022, 672 . 675 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 676 RFC 6455, DOI 10.17487/RFC6455, December 2011, 677 . 679 Acknowledgments 681 Portions of this document were previously part of the QUIC DATAGRAM 682 frame definition itself, the authors would like to acknowledge the 683 authors of that document and the members of the IETF MASQUE working 684 group for their suggestions. Additionally, the authors would like to 685 thank Martin Thomson for suggesting the use of an HTTP/3 setting. 686 Furthermore, the authors would like to thank Ben Schwartz for writing 687 the first proposal that used two layers of indirection. The final 688 design in this document came out of the HTTP Datagrams Design Team, 689 whose members were Alan Frindell, Alex Chernyakhovsky, Ben Schwartz, 690 Eric Rescorla, Marcus Ihlar, Martin Thomson, Mike Bishop, Tommy 691 Pauly, Victor Vasiliev, and the authors of this document. The 692 authors thank Mark Nottingham and Philipp Tiesel for their helpful 693 comments. 695 Authors' Addresses 696 David Schinazi 697 Google LLC 698 1600 Amphitheatre Parkway 699 Mountain View, CA 94043 700 United States of America 701 Email: dschinazi.ietf@gmail.com 703 Lucas Pardue 704 Cloudflare 705 Email: lucaspardue.24.7@gmail.com