idnits 2.17.1 draft-ietf-masque-h3-datagram-08.txt: -(646): 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 (28 March 2022) is 760 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. 'H1' -- Possible downref: Normative reference to a draft: ref. 'HTTP' Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 3 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: 29 September 2022 Cloudflare 6 28 March 2022 8 HTTP Datagrams and the Capsule Protocol 9 draft-ietf-masque-h3-datagram-08 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 Both are intended for use by HTTP extensions, not applications. 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 29 September 2022. 51 Copyright Notice 53 Copyright (c) 2022 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 Revised BSD License text as 62 described in Section 4.e of the Trust Legal Provisions and are 63 provided without warranty as described in the Revised BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 69 2. HTTP Datagrams . . . . . . . . . . . . . . . . . . . . . . . 3 70 2.1. HTTP/3 Datagrams . . . . . . . . . . . . . . . . . . . . 4 71 2.1.1. The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . 5 72 2.2. HTTP Datagrams using Capsules . . . . . . . . . . . . . . 6 73 3. Capsules . . . . . . . . . . . . . . . . . . . . . . . . . . 6 74 3.1. HTTP Data Streams . . . . . . . . . . . . . . . . . . . . 7 75 3.2. The Capsule Protocol . . . . . . . . . . . . . . . . . . 7 76 3.3. Error Handling . . . . . . . . . . . . . . . . . . . . . 8 77 3.4. The Capsule-Protocol Header Field . . . . . . . . . . . . 9 78 3.5. The DATAGRAM Capsule . . . . . . . . . . . . . . . . . . 9 79 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 80 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 81 5.1. HTTP/3 SETTINGS Parameter . . . . . . . . . . . . . . . . 11 82 5.2. HTTP/3 Error Code . . . . . . . . . . . . . . . . . . . . 12 83 5.3. HTTP Header Field Name . . . . . . . . . . . . . . . . . 12 84 5.4. Capsule Types . . . . . . . . . . . . . . . . . . . . . . 12 85 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 86 6.1. Normative References . . . . . . . . . . . . . . . . . . 13 87 6.2. Informative References . . . . . . . . . . . . . . . . . 14 88 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 15 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 91 1. Introduction 93 HTTP extensions sometimes need to access underlying transport 94 protocol features such as unreliable delivery (as offered by [DGRAM]) 95 to enable desirable features like an unreliable version of the 96 CONNECT method, and unreliable delivery in WebSockets [RFC6455] (or 97 its successors). 99 In Section 2, this document describes HTTP Datagrams, a convention 100 that supports the bidirectional and possibly multiplexed exchange of 101 data inside an HTTP connection. While HTTP datagrams are associated 102 with HTTP requests, they are not part of message content; instead, 103 they are intended for use by HTTP extensions (such as the CONNECT 104 method), and are compatible with all versions of HTTP. When the 105 underlying transport protocol supports unreliable delivery (such as 106 when the QUIC DATAGRAM extension is available in HTTP/3), they can 107 use that capability. 109 This document also describes the HTTP Capsule Protocol in Section 3, 110 to allow conveyance of HTTP Datagrams when the QUIC DATAGRAM frame is 111 unavailable or undesirable, such as when earlier versions of HTTP are 112 in use. 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 119 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 120 capitals, as shown here. 122 2. HTTP Datagrams 124 HTTP Datagrams are a convention for conveying bidirectional and 125 potentially unreliable datagrams inside an HTTP connection, with 126 multiplexing when possible. All HTTP Datagrams are associated with 127 an HTTP request. 129 When HTTP Datagrams are conveyed on an HTTP/3 connection, the QUIC 130 DATAGRAM frame can be used to achieve these goals, including 131 unreliable delivery; see Section 2.1. Negotiation is achieved using 132 a setting; see Section 2.1.1. 134 When running over HTTP/2, demultiplexing is provided by the HTTP/2 135 framing layer, but unreliable delivery is unavailable. HTTP 136 Datagrams are negotiated and conveyed using the Capsule Protocol; see 137 Section 3.5. 139 When running over HTTP/1, requests are strictly serialized in the 140 connection, and therefore demultiplexing is not available. 141 Unreliable delivery is likewise not available. HTTP Datagrams are 142 negotiated and conveyed using the Capsule Protocol; see Section 3.5. 144 HTTP Datagrams MUST only be sent with an association to a stream 145 whose HTTP semantics explicitly supports HTTP Datagrams. For 146 example, existing HTTP methods GET and POST do not define semantics 147 for associated HTTP Datagrams; therefore, HTTP Datagrams cannot be 148 sent associated with GET or POST request streams. 150 If an HTTP Datagram associated with a method that has no known 151 semantics for HTTP Datagrams is received, the receiver MUST abort the 152 corresponding stream; if HTTP/3 is in use, the stream MUST be aborted 153 with H3_DATAGRAM_ERROR. HTTP extensions can override these 154 requirements by defining a negotiation mechanism and semantics for 155 HTTP Datagrams. 157 2.1. HTTP/3 Datagrams 159 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 160 frames uses the following format (using the notation from the 161 "Notational Conventions" section of [QUIC]): 163 HTTP/3 Datagram { 164 Quarter Stream ID (i), 165 HTTP Datagram Payload (..), 166 } 168 Figure 1: HTTP/3 Datagram Format 170 Quarter Stream ID: A variable-length integer that contains the value 171 of the client-initiated bidirectional stream that this datagram is 172 associated with, divided by four (the division by four stems from 173 the fact that HTTP requests are sent on client-initiated 174 bidirectional streams, and those have stream IDs that are 175 divisible by four). The largest legal QUIC stream ID value is 176 2^62-1, so the largest legal value of Quarter Stream ID is 2^60-1. 177 Receipt of an HTTP/3 Datagram that includes a larger value MUST be 178 treated as an HTTP/3 connection error of type H3_DATAGRAM_ERROR. 180 HTTP Datagram Payload: The payload of the datagram, whose semantics 181 are defined by the extension that is using HTTP Datagrams. Note 182 that this field can be empty. 184 Receipt of a QUIC DATAGRAM frame whose payload is too short to allow 185 parsing the Quarter Stream ID field MUST be treated as an HTTP/3 186 connection error of type H3_DATAGRAM_ERROR. 188 HTTP/3 Datagrams MUST NOT be sent unless the corresponding stream's 189 send side is open. Once the receive side of a stream is closed, 190 incoming datagrams for this stream are no longer expected so related 191 state can be released. State MAY be kept for a short time to account 192 for reordering. Once the state is released, the received associated 193 datagrams MUST be silently dropped. 195 If an HTTP/3 datagram is received and its Quarter Stream ID maps to a 196 stream that has not yet been created, the receiver SHALL either drop 197 that datagram silently or buffer it temporarily (on the order of a 198 round trip) while awaiting the creation of the corresponding stream. 200 If an HTTP/3 datagram is received and its Quarter Stream ID maps to a 201 stream that cannot be created due to client-initiated bidirectional 202 stream limits, it SHOULD be treated as an HTTP/3 connection error of 203 type H3_ID_ERROR. Generating an error is not mandatory in this case 204 because HTTP/3 implementations might have practical barriers to 205 determining the active stream concurrency limit that is applied by 206 the QUIC layer. 208 Prioritization of HTTP/3 datagrams is not defined in this document. 209 Future extensions MAY define how to prioritize datagrams, and MAY 210 define signaling to allow communicating prioritization preferences. 212 2.1.1. The H3_DATAGRAM HTTP/3 SETTINGS Parameter 214 Implementations of HTTP/3 that support HTTP Datagrams can indicate 215 that to their peer by sending the H3_DATAGRAM SETTINGS parameter with 216 a value of 1. 218 The value of the H3_DATAGRAM SETTINGS parameter MUST be either 0 or 219 1. A value of 0 indicates that HTTP Datagrams are not supported. If 220 the H3_DATAGRAM SETTINGS parameter is received with a value that is 221 neither 0 or 1, the receiver MUST terminate the connection with error 222 H3_SETTINGS_ERROR. 224 QUIC DATAGRAM frames MUST NOT be sent until the H3_DATAGRAM SETTINGS 225 parameter has been both sent and received with a value of 1. 227 When clients use 0-RTT, they MAY store the value of the server's 228 H3_DATAGRAM SETTINGS parameter. Doing so allows the client to send 229 QUIC DATAGRAM frames in 0-RTT packets. When servers decide to accept 230 0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater 231 than or equal to the value they sent to the client in the connection 232 where they sent them the NewSessionTicket message. If a client 233 stores the value of the H3_DATAGRAM SETTINGS parameter with their 234 0-RTT state, they MUST validate that the new value of the H3_DATAGRAM 235 SETTINGS parameter sent by the server in the handshake is greater 236 than or equal to the stored value; if not, the client MUST terminate 237 the connection with error H3_SETTINGS_ERROR. In all cases, the 238 maximum permitted value of the H3_DATAGRAM SETTINGS parameter is 1. 240 It is RECOMMENDED that implementations that support receiving HTTP 241 Datagrams using QUIC always send the H3_DATAGRAM SETTINGS parameter 242 with a value of 1, even if the application does not intend to use 243 HTTP Datagrams. This helps to avoid "sticking out"; see Section 4. 245 2.1.1.1. Note About Draft Versions 247 [[RFC editor: please remove this section before publication.]] 249 Some revisions of this draft specification use a different value (the 250 Identifier field of a Setting in the HTTP/3 SETTINGS frame) for the 251 H3_DATAGRAM Settings Parameter. This allows new draft revisions to 252 make incompatible changes. Multiple draft versions MAY be supported 253 by sending multiple values for H3_DATAGRAM. Once SETTINGS have been 254 sent and received, an implementation that supports multiple drafts 255 MUST compute the intersection of the values it has sent and received, 256 and then it MUST select and use the most recent draft version from 257 the intersection set. This ensures that both peers negotiate the 258 same draft version. 260 2.2. HTTP Datagrams using Capsules 262 When HTTP/3 Datagrams are unavailable or undesirable, HTTP Datagrams 263 can be sent using the Capsule Protocol, see Section 3.5. 265 3. Capsules 267 One mechanism to extend HTTP is to introduce new HTTP Upgrade Tokens 268 (see Section 16.7 of [HTTP]). In HTTP/1.x, these tokens are used via 269 the Upgrade mechanism (see Section 7.8 of [HTTP]). In HTTP/2 and 270 HTTP/3, these tokens are used via the Extended CONNECT mechanism (see 271 [EXT-CONNECT2] and [EXT-CONNECT3]). 273 This specification introduces the Capsule Protocol. The Capsule 274 Protocol is a sequence of type-length-value tuples that definitions 275 of new HTTP Upgrade Tokens can choose to use. It allows endpoints to 276 reliably communicate request-related information end-to-end on HTTP 277 request streams, even in the presence of HTTP intermediaries. The 278 Capsule Protocol can be used to exchange HTTP Datagrams, which is 279 necessary when HTTP is running over a transport that does not support 280 the QUIC DATAGRAM frame. 282 3.1. HTTP Data Streams 284 This specification defines the "data stream" of an HTTP request as 285 the bidirectional stream of bytes that follows the header section of 286 the request message and the final, successful (i.e., 2xx) response 287 message. 289 In HTTP/1.x, the data stream consists of all bytes on the connection 290 that follow the blank line that concludes either the request header 291 section, or the response header section. As a result, only a single 292 HTTP request starting the capsule protocol can be sent on HTTP/1.x 293 connections. 295 In HTTP/2 and HTTP/3, the data stream of a given HTTP request 296 consists of all bytes sent in DATA frames with the corresponding 297 stream ID. 299 The concept of a data stream is particularly relevant for methods 300 such as CONNECT where there is no HTTP message content after the 301 headers. 303 Data streams can be prioritized using any means suited to stream or 304 request prioritization. For example, see Section 11 of [PRIORITY]. 306 3.2. The Capsule Protocol 308 Definitions of new HTTP Upgrade Tokens can state that their 309 associated request's data stream uses the Capsule Protocol. If they 310 do so, that means that the contents of the associated request's data 311 stream uses the following format (using the notation from the 312 "Notational Conventions" section of [QUIC]): 314 Capsule Protocol { 315 Capsule (..) ..., 316 } 318 Figure 2: Capsule Protocol Stream Format 320 Capsule { 321 Capsule Type (i), 322 Capsule Length (i), 323 Capsule Value (..), 324 } 326 Figure 3: Capsule Format 328 Capsule Type: A variable-length integer indicating the Type of the 329 capsule. 331 Capsule Length: The length of the Capsule Value field following this 332 field, encoded as a variable-length integer. Note that this field 333 can have a value of zero. 335 Capsule Value: The payload of this capsule. Its semantics are 336 determined by the value of the Capsule Type field. 338 An intermediary can identify the use of the capsule protocol either 339 through the presence of the Capsule-Protocol header field 340 (Section 3.4) or by understanding the chosen HTTP Upgrade token. 342 Because new protocols or extensions might define new capsule types, 343 intermediaries that wish to allow for future extensibility SHOULD 344 forward capsules without modification, unless the definition of the 345 Capsule Type in use specifies additional intermediary processing. 346 One such Capsule Type is the DATAGRAM capsule; see Section 3.5. In 347 particular, intermediaries SHOULD forward Capsules with an unknown 348 Capsule Type without modification. 350 Endpoints which receive a Capsule with an unknown Capsule Type MUST 351 silently drop that Capsule and skip over it to parse the next 352 Capsule. 354 By virtue of the definition of the data stream, the Capsule Protocol 355 is not in use on responses unless the response includes a 2xx 356 (Successful) status code. 358 The Capsule Protocol MUST NOT be used with messages that contain 359 Content-Length, Content-Type, or Transfer-Encoding header fields. 360 Additionally, HTTP status codes 204 (No Content), 205 (Reset 361 Content), and 206 (Partial Content) MUST NOT be sent on responses 362 that use the Capsule Protocol. A receiver that observes a violation 363 of these requirements MUST treat the HTTP message as malformed. 365 3.3. Error Handling 367 When an error occurs in processing the Capsule Protocol, the receiver 368 MUST treat the message as malformed or incomplete, according to the 369 underlying transport protocol. For HTTP/3, the handling of malformed 370 messages is described in Section 4.1.3 of [H3]. For HTTP/2, the 371 handling of malformed messages is described in Section 8.1.1 of [H2]. 372 For HTTP/1.1, the handling of incomplete messages is described in 373 Section 8 of [H1]. 375 Each capsule's payload MUST contain exactly the fields identified in 376 its description. A capsule payload that contains additional bytes 377 after the identified fields or a capsule payload that terminates 378 before the end of the identified fields MUST be treated as a 379 malformed or incomplete message. In particular, redundant length 380 encodings MUST be verified to be self-consistent. 382 When a stream carrying capsules terminates cleanly, if the last 383 capsule on the stream was truncated, this MUST be treated as a 384 malformed or incomplete message. 386 3.4. The Capsule-Protocol Header Field 388 The "Capsule-Protocol" header field is an Item Structured Field, see 389 Section 3.3 of [STRUCT-FIELD]; its value MUST be a Boolean; any other 390 value type MUST be handled as if the field were not present by 391 recipients (for example, if this field is included multiple times, 392 its type will become a List and the field will therefore be ignored). 393 This document does not define any parameters for the Capsule-Protocol 394 header field value, but future documents might define parameters. 395 Receivers MUST ignore unknown parameters. 397 Endpoints indicate that the Capsule Protocol is in use on a data 398 stream by sending a Capsule-Protocol header field with a true value. 399 A Capsule-Protocol header field with a false value has the same 400 semantics as when the header is not present. 402 Intermediaries MAY use this header field to allow processing of HTTP 403 Datagrams for unknown HTTP Upgrade Tokens; note that this is only 404 possible for HTTP Upgrade or Extended CONNECT. 406 The Capsule-Protocol header field MUST NOT be used on HTTP responses 407 with a status code outside the 2xx range. 409 When using the Capsule Protocol, HTTP endpoints SHOULD send the 410 Capsule-Protocol header field to simplify intermediary processing. 411 Definitions of new HTTP Upgrade Tokens that use the Capsule Protocol 412 MAY alter this recommendation. 414 3.5. The DATAGRAM Capsule 416 This document defines the DATAGRAM capsule type (see Section 5.4 for 417 the value of the capsule type). This capsule allows HTTP Datagrams 418 to be sent on a stream using the Capsule Protocol. This is 419 particularly useful when HTTP is running over a transport that does 420 not support the QUIC DATAGRAM frame. 422 Datagram Capsule { 423 Type (i) = DATAGRAM, 424 Length (i), 425 HTTP Datagram Payload (..), 426 } 428 Figure 4: DATAGRAM Capsule Format 430 HTTP Datagram Payload: The payload of the datagram, whose semantics 431 are defined by the extension that is using HTTP Datagrams. Note 432 that this field can be empty. 434 HTTP Datagrams sent using the DATAGRAM capsule have the same 435 semantics as those sent in QUIC DATAGRAM frames. In particular, the 436 restrictions on when it is allowed to send an HTTP Datagram and how 437 to process them from Section 2.1 also apply to HTTP Datagrams sent 438 and received using the DATAGRAM capsule. 440 An intermediary can reencode HTTP Datagrams as it forwards them. In 441 other words, an intermediary MAY send a DATAGRAM capsule to forward 442 an HTTP Datagram which was received in a QUIC DATAGRAM frame, and 443 vice versa. 445 Note that while DATAGRAM capsules that are sent on a stream are 446 reliably delivered in order, intermediaries can reencode DATAGRAM 447 capsules into QUIC DATAGRAM frames when forwarding messages, which 448 could result in loss or reordering. 450 If an intermediary receives an HTTP Datagram in a QUIC DATAGRAM frame 451 and is forwarding it on a connection that supports QUIC DATAGRAM 452 frames, the intermediary SHOULD NOT convert that HTTP Datagram to a 453 DATAGRAM capsule. If the HTTP Datagram is too large to fit in a 454 DATAGRAM frame (for example because the path MTU of that QUIC 455 connection is too low or if the maximum UDP payload size advertised 456 on that connection is too low), the intermediary SHOULD drop the HTTP 457 Datagram instead of converting it to a DATAGRAM capsule. This 458 preserves the end-to-end unreliability characteristic that methods 459 such as Datagram Packetization Layer Path MTU Discovery (DPLPMTUD) 460 depend on [DPLPMTUD]. An intermediary that converts QUIC DATAGRAM 461 frames to DATAGRAM capsules allows HTTP Datagrams to be arbitrarily 462 large without suffering any loss; this can misrepresent the true path 463 properties, defeating methods such as DPLPMTUD. 465 While DATAGRAM capsules can theoretically carry a payload of length 466 2^62-1, most HTTP extensions that use HTTP Datagrams will have their 467 own limits on what datagram payload sizes are practical. 468 Implementations SHOULD take those limits into account when parsing 469 DATAGRAM capsules: if an incoming DATAGRAM capsule has a length that 470 is known to be so large as to not be usable, the implementation 471 SHOULD discard the capsule without buffering its contents into 472 memory. 474 Note that use of the Capsule Protocol is not required to use HTTP 475 Datagrams. If an HTTP extension that uses HTTP Datagrams is only 476 defined over transports that support QUIC DATAGRAM frames, it might 477 not need a stream encoding. Additionally, HTTP extensions can use 478 HTTP Datagrams with their own data stream protocol. However, new 479 HTTP extensions that wish to use HTTP Datagrams SHOULD use the 480 Capsule Protocol unless they have a good reason not to. 482 4. Security Considerations 484 Since transmitting HTTP Datagrams using QUIC DATAGRAM frames requires 485 sending an HTTP/3 Settings parameter, it "sticks out". In other 486 words, probing clients can learn whether a server supports HTTP 487 Datagrams over QUIC DATAGRAM frames. As some servers might wish to 488 obfuscate the fact that they offer application services that use HTTP 489 datagrams, it's best for all implementations that support this 490 feature to always send this Settings parameter, see Section 2.1.1. 492 Since use of the Capsule Protocol is restricted to new HTTP Upgrade 493 Tokens, it is not accessible from Web Platform APIs (such as those 494 commonly accessed via JavaScript in web browsers). 496 5. IANA Considerations 498 5.1. HTTP/3 SETTINGS Parameter 500 This document will request IANA to register the following entry in 501 the "HTTP/3 Settings" registry: 503 Value: 0xffd277 (note that this will switch to a lower value before 504 publication) 506 Setting Name: H3_DATAGRAM 508 Default: 0 510 Status: provisional (permanent if this document is approved) 512 Specification: This Document 514 Change Controller: IETF 516 Contact: HTTP_WG; HTTP working group; ietf-http-wg@w3.org 518 5.2. HTTP/3 Error Code 520 This document will request IANA to register the following entry in 521 the "HTTP/3 Error Codes" registry: 523 Value: 0x4A1268 (note that this will switch to a lower value before 524 publication) 526 Name: H3_DATAGRAM_ERROR 528 Description: Datagram or capsule protocol parse error 530 Status: provisional (permanent if this document is approved) 532 Specification: This Document 534 Change Controller: IETF 536 Contact: HTTP_WG; HTTP working group; ietf-http-wg@w3.org 538 5.3. HTTP Header Field Name 540 This document will request IANA to register the following entry in 541 the "HTTP Field Name" registry: 543 Field Name: Capsule-Protocol 545 Template: None 547 Status: provisional (permanent if this document is approved) 549 Reference: This document 551 Comments: None 553 5.4. Capsule Types 555 This document establishes a registry for HTTP capsule type codes. 556 The "HTTP Capsule Types" registry governs a 62-bit space. 557 Registrations in this registry MUST include the following fields: 559 Type: A name or label for the capsule type. 561 Value: The value of the Capsule Type field (see Section 3.2) is a 562 62-bit integer. 564 Reference: An optional reference to a specification for the type. 565 This field MAY be empty. 567 Registrations follow the "First Come First Served" policy (see 568 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 569 the same Type. 571 This registry initially contains the following entry: 573 Capsule Type: DATAGRAM 575 Value: 0xff37a5 (note that this will switch to a lower value before 576 publication) 578 Reference: This document 580 Capsule types with a value of the form 41 * N + 23 for integer values 581 of N are reserved to exercise the requirement that unknown capsule 582 types be ignored. These capsules have no semantics and can carry 583 arbitrary values. These values MUST NOT be assigned by IANA and MUST 584 NOT appear in the listing of assigned values. 586 6. References 588 6.1. Normative References 590 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 591 Datagram Extension to QUIC", Work in Progress, Internet- 592 Draft, draft-ietf-quic-datagram-10, 4 February 2022, 593 . 596 [H1] Fielding, R. T., Nottingham, M., and J. Reschke, 597 "HTTP/1.1", Work in Progress, Internet-Draft, draft-ietf- 598 httpbis-messaging-19, 12 September 2021, 599 . 602 [H2] Thomson, M. and C. Benfield, "HTTP/2", Work in Progress, 603 Internet-Draft, draft-ietf-httpbis-http2bis-07, 24 January 604 2022, . 607 [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 608 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 609 quic-http-34, 2 February 2021, 610 . 613 [HTTP] Fielding, R. T., Nottingham, M., and J. Reschke, "HTTP 614 Semantics", Work in Progress, Internet-Draft, draft-ietf- 615 httpbis-semantics-19, 12 September 2021, 616 . 619 [IANA-POLICY] 620 Cotton, M., Leiba, B., and T. Narten, "Guidelines for 621 Writing an IANA Considerations Section in RFCs", BCP 26, 622 RFC 8126, DOI 10.17487/RFC8126, June 2017, 623 . 625 [QUIC] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 626 Multiplexed and Secure Transport", RFC 9000, 627 DOI 10.17487/RFC9000, May 2021, 628 . 630 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 631 Requirement Levels", BCP 14, RFC 2119, 632 DOI 10.17487/RFC2119, March 1997, 633 . 635 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 636 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 637 May 2017, . 639 [STRUCT-FIELD] 640 Nottingham, M. and P-H. Kamp, "Structured Field Values for 641 HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021, 642 . 644 6.2. Informative References 646 [DPLPMTUD] Fairhurst, G., Jones, T., Tüxen, M., Rüngeler, I., and T. 647 Völker, "Packetization Layer Path MTU Discovery for 648 Datagram Transports", RFC 8899, DOI 10.17487/RFC8899, 649 September 2020, . 651 [EXT-CONNECT2] 652 McManus, P., "Bootstrapping WebSockets with HTTP/2", 653 RFC 8441, DOI 10.17487/RFC8441, September 2018, 654 . 656 [EXT-CONNECT3] 657 Hamilton, R., "Bootstrapping WebSockets with HTTP/3", Work 658 in Progress, Internet-Draft, draft-ietf-httpbis-h3- 659 websockets-04, 8 February 2022, 660 . 663 [PRIORITY] Oku, K. and L. Pardue, "Extensible Prioritization Scheme 664 for HTTP", Work in Progress, Internet-Draft, draft-ietf- 665 httpbis-priority-12, 17 January 2022, 666 . 669 [RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", 670 RFC 6455, DOI 10.17487/RFC6455, December 2011, 671 . 673 Acknowledgments 675 Portions of this document were previously part of the QUIC DATAGRAM 676 frame definition itself, the authors would like to acknowledge the 677 authors of that document and the members of the IETF MASQUE working 678 group for their suggestions. Additionally, the authors would like to 679 thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS 680 parameter. Furthermore, the authors would like to thank Ben Schwartz 681 for writing the first proposal that used two layers of indirection. 682 The final design in this document came out of the HTTP Datagrams 683 Design Team, whose members were Alan Frindell, Alex Chernyakhovsky, 684 Ben Schwartz, Eric Rescorla, Marcus Ihlar, Martin Thomson, Mike 685 Bishop, Tommy Pauly, Victor Vasiliev, and the authors of this 686 document. The authors thank Mark Nottingham and Philipp Tiesel for 687 their helpful comments. 689 Authors' Addresses 691 David Schinazi 692 Google LLC 693 1600 Amphitheatre Parkway 694 Mountain View, California 94043, 695 United States of America 696 Email: dschinazi.ietf@gmail.com 698 Lucas Pardue 699 Cloudflare 700 Email: lucaspardue.24.7@gmail.com