idnits 2.17.1 draft-ietf-masque-h3-datagram-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (13 May 2021) is 1078 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-10) exists of draft-ietf-quic-datagram-02 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 MASQUE D. Schinazi 3 Internet-Draft Google LLC 4 Intended status: Standards Track L. Pardue 5 Expires: 14 November 2021 Cloudflare 6 13 May 2021 8 Using QUIC Datagrams with HTTP/3 9 draft-ietf-masque-h3-datagram-01 11 Abstract 13 The QUIC DATAGRAM extension provides application protocols running 14 over QUIC with a mechanism to send unreliable data while leveraging 15 the security and congestion-control properties of QUIC. However, 16 QUIC DATAGRAM frames do not provide a means to demultiplex 17 application contexts. This document describes how to use QUIC 18 DATAGRAM frames when the application protocol running over QUIC is 19 HTTP/3. It associates datagrams with client-initiated bidirectional 20 streams and defines an optional additional demultiplexing layer. 22 Discussion of this work is encouraged to happen on the MASQUE IETF 23 mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the 24 GitHub repository which contains the draft: https://github.com/ietf- 25 wg-masque/draft-ietf-masque-h3-datagram. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on 14 November 2021. 44 Copyright Notice 46 Copyright (c) 2021 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 51 license-info) in effect on the date of publication of this document. 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. Code Components 54 extracted from this document must include Simplified BSD License text 55 as described in Section 4.e of the Trust Legal Provisions and are 56 provided without warranty as described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 3 62 2. Multiplexing . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2.1. Datagram Contexts . . . . . . . . . . . . . . . . . . . . 3 64 2.2. Context ID Allocation . . . . . . . . . . . . . . . . . . 4 65 3. HTTP/3 DATAGRAM Frame Format . . . . . . . . . . . . . . . . 4 66 4. CAPSULE HTTP/3 Frame Definition . . . . . . . . . . . . . . . 5 67 4.1. The REGISTER_DATAGRAM_CONTEXT Capsule . . . . . . . . . . 6 68 4.2. The CLOSE_DATAGRAM_CONTEXT Capsule . . . . . . . . . . . 7 69 4.3. The DATAGRAM Capsule . . . . . . . . . . . . . . . . . . 8 70 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter . . . . . . . . . . 9 71 6. HTTP/1.x and HTTP/2 Support . . . . . . . . . . . . . . . . . 9 72 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10 73 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 74 8.1. HTTP/3 CAPSULE Frame . . . . . . . . . . . . . . . . . . 10 75 8.2. HTTP SETTINGS Parameter . . . . . . . . . . . . . . . . . 10 76 8.3. Capsule Types . . . . . . . . . . . . . . . . . . . . . . 10 77 8.4. Context Extension Keys . . . . . . . . . . . . . . . . . 11 78 9. Normative References . . . . . . . . . . . . . . . . . . . . 11 79 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 12 80 A.1. CONNECT-UDP . . . . . . . . . . . . . . . . . . . . . . . 12 81 A.2. CONNECT-UDP with Timestamp Extension . . . . . . . . . . 13 82 A.3. CONNECT-IP with IP compression . . . . . . . . . . . . . 14 83 A.4. WebTransport . . . . . . . . . . . . . . . . . . . . . . 15 84 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 16 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 87 1. Introduction 89 The QUIC DATAGRAM extension [DGRAM] provides application protocols 90 running over QUIC [QUIC] with a mechanism to send unreliable data 91 while leveraging the security and congestion-control properties of 92 QUIC. However, QUIC DATAGRAM frames do not provide a means to 93 demultiplex application contexts. This document describes how to use 94 QUIC DATAGRAM frames when the application protocol running over QUIC 95 is HTTP/3 [H3]. It associates datagrams with client-initiated 96 bidirectional streams and defines an optional additional 97 demultiplexing layer. 99 Discussion of this work is encouraged to happen on the MASQUE IETF 100 mailing list (masque@ietf.org (mailto:masque@ietf.org)) or on the 101 GitHub repository which contains the draft: https://github.com/ietf- 102 wg-masque/draft-ietf-masque-h3-datagram. 104 1.1. Conventions and Definitions 106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 108 "OPTIONAL" in this document are to be interpreted as described in BCP 109 14 [RFC2119] [RFC8174] when, and only when, they appear in all 110 capitals, as shown here. 112 2. Multiplexing 114 In order to allow multiple exchanges of datagrams to coexist on a 115 given QUIC connection, HTTP datagrams contain two layers of 116 multiplexing. First, the QUIC DATAGRAM frame payload starts with an 117 encoded stream identifier that associates the datagram with a given 118 QUIC stream. Second, datagrams carry a context identifier (see 119 Section 2.1) that allows multiplexing multiple datagram contexts 120 related to a given HTTP request. Conceptually, the first layer of 121 multiplexing is per-hop, while the second is end-to-end. 123 2.1. Datagram Contexts 125 Within the scope of a given HTTP request, contexts provide an 126 additional demultiplexing layer. Contexts determine the encoding of 127 datagrams, and can be used to implicitly convey metadata. For 128 example, contexts can be used for compression to elide some parts of 129 the datagram: the context identifier then maps to a compression 130 context that the receiver can use to reconstruct the elided data. 132 Contexts are identified within the scope of a given request by a 133 numeric value, referred to as the context ID. A context ID is a 134 62-bit integer (0 to 2^62-1). 136 While stream IDs are a per-hop concept, context IDs are an end-to-end 137 concept. In other words, if a datagram travels through one or more 138 intermediaries on its way from client to server, the stream ID will 139 most likely change from hop to hop, but the context ID will remain 140 the same. Context IDs are opaque to intermediaries. 142 2.2. Context ID Allocation 144 Implementations of HTTP/3 that support the DATAGRAM extension MUST 145 provide a context ID allocation service. That service will allow 146 applications co-located with HTTP/3 to request a unique context ID 147 that they can subsequently use for their own purposes. The HTTP/3 148 implementation will then parse the context ID of incoming DATAGRAM 149 frames and use it to deliver the frame to the appropriate application 150 context. 152 Even-numbered context IDs are client-initiated, while odd-numbered 153 context IDs are server-initiated. This means that an HTTP/3 client 154 implementation of the context ID allocation service MUST only provide 155 even-numbered IDs, while a server implementation MUST only provide 156 odd-numbered IDs. Note that, once allocated, any context ID can be 157 used by both client and server - only allocation carries separate 158 namespaces to avoid requiring synchronization. Additionally, note 159 that the context ID namespace is tied to a given HTTP request: it is 160 possible for the same numeral context ID to be used simultaneously in 161 distinct requests. 163 3. HTTP/3 DATAGRAM Frame Format 165 When used with HTTP/3, the Datagram Data field of QUIC DATAGRAM 166 frames uses the following format (using the notation from the 167 "Notational Conventions" section of [QUIC]): 169 HTTP/3 Datagram { 170 Quarter Stream ID (i), 171 Context ID (i), 172 HTTP/3 Datagram Payload (..), 173 } 175 Figure 1: HTTP/3 DATAGRAM Frame Format 177 Quarter Stream ID: A variable-length integer that contains the value 178 of the client-initiated bidirectional stream that this datagram is 179 associated with, divided by four. (The division by four stems 180 from the fact that HTTP requests are sent on client-initiated 181 bidirectional streams, and those have stream IDs that are 182 divisible by four.) 184 Context ID: A variable-length integer indicating the context ID of 185 the datagram (see Section 2.1). 187 HTTP/3 Datagram Payload: The payload of the datagram, whose 188 semantics are defined by individual applications. Note that this 189 field can be empty. 191 Intermediaries parse the Quarter Stream ID field in order to 192 associate the QUIC DATAGRAM frame with a stream. If an intermediary 193 receives a QUIC DATAGRAM frame whose payload is too short to allow 194 parsing the Quarter Stream ID field, the intermediary MUST treat it 195 as an HTTP/3 connection error of type H3_GENERAL_PROTOCOL_ERROR. 196 Intermediaries MUST ignore any HTTP/3 Datagram fields after the 197 Quarter Stream ID. 199 Endpoints parse both the Quarter Stream ID field and the Context ID 200 field in order to associate the QUIC DATAGRAM frame with a stream and 201 context within that stream. If an endpoint receives a QUIC DATAGRAM 202 frame whose payload is too short to allow parsing the Quarter Stream 203 ID field, the endpoint MUST treat it as an HTTP/3 connection error of 204 type H3_GENERAL_PROTOCOL_ERROR. If an endpoint receives a QUIC 205 DATAGRAM frame whose payload is long enough to allow parsing the 206 Quarter Stream ID field but too short to allow parsing the Context ID 207 field, the endpoint MUST abruptly terminate the corresponding stream 208 with a stream error of type H3_GENERAL_PROTOCOL_ERROR. 210 If a DATAGRAM frame is received and its Quarter Stream ID maps to a 211 stream that has already been closed, the receiver MUST silently drop 212 that frame. If a DATAGRAM frame is received and its Quarter Stream 213 ID maps to a stream that has not yet been created, the receiver SHALL 214 either drop that frame silently or buffer it temporarily while 215 awaiting the creation of the corresponding stream. 217 4. CAPSULE HTTP/3 Frame Definition 219 CAPSULE allows reliably sending request-related information end-to- 220 end, even in the presence of HTTP intermediaries. 222 CAPSULE is an HTTP/3 Frame (as opposed to a QUIC frame) which SHALL 223 only be sent in client-initiated bidirectional streams. 224 Intermediaries MUST forward all received CAPSULE frames in their 225 unmodified entirety on the same stream where it would forward DATA 226 frames. Intermediaries MUST NOT send any CAPSULE frames other than 227 the ones it is forwarding. 229 This specification of CAPSULE currently uses HTTP/3 frame type 230 0xffcab5. If this document is approved, a lower number will be 231 requested from IANA. 233 CAPSULE HTTP/3 Frame { 234 Type (i) = 0xffcab5, 235 Length (i), 236 Capsule Type (i), 237 Capsule Data (..), 238 } 240 Figure 2: CAPSULE HTTP/3 Frame Format 242 The Type and Length fields follows the definition of HTTP/3 frames 243 from [H3]. The payload consists of: 245 Capsule Type: The type of this capsule. 247 Capsule Data: Data whose semantics depends on the Capsule Type. 249 Endpoints which receive a Capsule with an unknown Capsule Type MUST 250 silently drop that Capsule. Intermediaries MUST forward Capsules, 251 even if they do not know the Capsule Type or cannot parse the Capsule 252 Data. 254 4.1. The REGISTER_DATAGRAM_CONTEXT Capsule 256 The REGISTER_DATAGRAM_CONTEXT capsule (type=0x00) allows an endpoint 257 to inform its peer of the encoding and semantics of datagrams 258 associated with a given context ID. Its Capsule Data field consists 259 of: 261 REGISTER_DATAGRAM_CONTEXT Capsule { 262 Context ID (i), 263 Extension String (..), 264 } 266 Figure 3: REGISTER_DATAGRAM_CONTEXT Capsule Format 268 Context ID: The context ID to register. 270 Extension String: A string of comma-separated key-value pairs to 271 enable extensibility. Keys are registered with IANA, see 272 Section 8.4. 274 The ABNF for the Extension String field is as follows (using syntax 275 from Section 3.2.6 of [RFC7230]): 277 extension-string = [ ext-member *( "," ext-member ) ] 278 ext-member = ext-member-key "=" ext-member-value 279 ext-member-key = token 280 ext-member-value = token 282 Note that these registrations are unilateral and bidirectional: the 283 sender of the frame unilaterally defines the semantics it will apply 284 to the datagrams it sends and receives using this context ID. Once a 285 context ID is registered, it can be used in both directions. 287 Endpoints MUST NOT send DATAGRAM frames using a Context ID until they 288 have either sent or received a REGISTER_DATAGRAM_CONTEXT Capsule with 289 the same Context ID. However, due to reordering, an endpoint that 290 receives a DATAGRAM frame with an unknown Context ID MUST NOT treat 291 it as an error, it SHALL instead drop the DATAGRAM frame silently, or 292 buffer it temporarily while awaiting the corresponding 293 REGISTER_DATAGRAM_CONTEXT Capsule. 295 Endpoints MUST NOT register the same Context ID twice on the same 296 stream. This also applies to Context IDs that have been closed using 297 a CLOSE_DATAGRAM_CONTEXT capsule. Clients MUST NOT register server- 298 initiated Context IDs and servers MUST NOT register client-initiated 299 Context IDs. If an endpoint receives a REGISTER_DATAGRAM_CONTEXT 300 capsule that violates one or more of these requirements, the endpoint 301 MUST abruptly terminate the corresponding stream with a stream error 302 of type H3_GENERAL_PROTOCOL_ERROR. 304 4.2. The CLOSE_DATAGRAM_CONTEXT Capsule 306 The CLOSE_DATAGRAM_CONTEXT capsule (type=0x01) allows an endpoint to 307 inform its peer that it will no longer send or parse received 308 datagrams associated with a given context ID. Its Capsule Data field 309 consists of: 311 CLOSE_DATAGRAM_CONTEXT Capsule { 312 Context ID (i), 313 Extension String (..), 314 } 316 Figure 4: CLOSE_DATAGRAM_CONTEXT Capsule Format 318 Context ID: The context ID to close. 320 Extension String: A string of comma-separated key-value pairs to 321 enable extensibility, see the definition of the same field in 322 Section 4.1 for details. 324 Note that this close is unilateral and bidirectional: the sender of 325 the frame unilaterally informs its peer of the closure. Endpoints 326 can use CLOSE_DATAGRAM_CONTEXT capsules to close a context that was 327 initially registered by either themselves, or by their peer. 328 Endpoints MAY use the CLOSE_DATAGRAM_CONTEXT capsule to immediately 329 reject a context that was just registered using a 330 REGISTER_DATAGRAM_CONTEXT capsule if they find its Extension String 331 to be unacceptable. 333 After an endpoint has either sent or received a 334 CLOSE_DATAGRAM_CONTEXT frame, it MUST NOT send any DATAGRAM frames 335 with that Context ID. However, due to reordering, an endpoint that 336 receives a DATAGRAM frame with a closed Context ID MUST NOT treat it 337 as an error, it SHALL instead drop the DATAGRAM frame silently. 339 Endpoints MUST NOT close a Context ID that was not previously 340 registered. Endpoints MUST NOT close a Context ID that has already 341 been closed. If an endpoint receives a CLOSE_DATAGRAM_CONTEXT 342 capsule that violates one or more of these requirements, the endpoint 343 MUST abruptly terminate the corresponding stream with a stream error 344 of type H3_GENERAL_PROTOCOL_ERROR. 346 4.3. The DATAGRAM Capsule 348 The DATAGRAM capsule (type=0x02) allows an endpoint to send a 349 datagram frame over an HTTP stream. This is particularly useful when 350 using a version of HTTP that does not support QUIC DATAGRAM frames. 351 Its Capsule Data field consists of: 353 DATAGRAM Capsule { 354 Context ID (i), 355 HTTP/3 Datagram Payload (..), 356 } 358 Figure 5: DATAGRAM Capsule Format 360 Context ID: A variable-length integer indicating the context ID of 361 the datagram (see Section 2.1). 363 HTTP/3 Datagram Payload: The payload of the datagram, whose 364 semantics are defined by individual applications. Note that this 365 field can be empty. 367 Datagrams sent using the DATAGRAM Capsule have the exact same 368 semantics as datagrams sent in QUIC DATAGRAM frames. 370 5. The H3_DATAGRAM HTTP/3 SETTINGS Parameter 372 Implementations of HTTP/3 that support this mechanism can indicate 373 that to their peer by sending the H3_DATAGRAM SETTINGS parameter with 374 a value of 1. The value of the H3_DATAGRAM SETTINGS parameter MUST 375 be either 0 or 1. A value of 0 indicates that this mechanism is not 376 supported. An endpoint that receives the H3_DATAGRAM SETTINGS 377 parameter with a value that is neither 0 or 1 MUST terminate the 378 connection with error H3_SETTINGS_ERROR. 380 An endpoint that sends the H3_DATAGRAM SETTINGS parameter with a 381 value of 1 MUST send the max_datagram_frame_size QUIC Transport 382 Parameter [DGRAM]. An endpoint that receives the H3_DATAGRAM 383 SETTINGS parameter with a value of 1 on a QUIC connection that did 384 not also receive the max_datagram_frame_size QUIC Transport Parameter 385 MUST terminate the connection with error H3_SETTINGS_ERROR. 387 When clients use 0-RTT, they MAY store the value of the server's 388 H3_DATAGRAM SETTINGS parameter. Doing so allows the client to use 389 HTTP/3 datagrams in 0-RTT packets. When servers decide to accept 390 0-RTT data, they MUST send a H3_DATAGRAM SETTINGS parameter greater 391 than or equal to the value they sent to the client in the connection 392 where they sent them the NewSessionTicket message. If a client 393 stores the value of the H3_DATAGRAM SETTINGS parameter with their 394 0-RTT state, they MUST validate that the new value of the H3_DATAGRAM 395 SETTINGS parameter sent by the server in the handshake is greater 396 than or equal to the stored value; if not, the client MUST terminate 397 the connection with error H3_SETTINGS_ERROR. In all cases, the 398 maximum permitted value of the H3_DATAGRAM SETTINGS parameter is 1. 400 6. HTTP/1.x and HTTP/2 Support 402 We can provide DATAGRAM support in HTTP/2 by defining the CAPSULE 403 frame in HTTP/2. 405 We can provide DATAGRAM support in HTTP/1.x by defining its data 406 stream format to a sequence of length-value capsules. 408 TODO: Refactor this document into "HTTP Datagrams" with definitions 409 for HTTP/1.x, HTTP/2, and HTTP/3. 411 7. Security Considerations 413 Since this feature requires sending an HTTP/3 Settings parameter, it 414 "sticks out". In other words, probing clients can learn whether a 415 server supports this feature. Implementations that support this 416 feature SHOULD always send this Settings parameter to avoid leaking 417 the fact that there are applications using HTTP/3 datagrams enabled 418 on this endpoint. 420 8. IANA Considerations 422 8.1. HTTP/3 CAPSULE Frame 424 This document will request IANA to register the following entry in 425 the "HTTP/3 Frames" registry: 427 +------------+----------+---------------+ 428 | Frame Type | Value | Specification | 429 +============+==========+===============+ 430 | CAPSULE | 0xffcab5 | This Document | 431 +------------+----------+---------------+ 433 8.2. HTTP SETTINGS Parameter 435 This document will request IANA to register the following entry in 436 the "HTTP/3 Settings" registry: 438 +--------------+----------+---------------+---------+ 439 | Setting Name | Value | Specification | Default | 440 +==============+==========+===============+=========+ 441 | H3_DATAGRAM | 0xffd276 | This Document | 0 | 442 +--------------+----------+---------------+---------+ 444 8.3. Capsule Types 446 This document establishes a registry for HTTP/3 frame type codes. 447 The "HTTP Capsule Types" registry governs a 62-bit space. 448 Registrations in this registry MUST include the following fields: 450 Type: 452 A name or label for the capsule type. 454 Value: The value of the Capsule Type field (see Section 4) is a 455 62bit integer. 457 Reference: An optional reference to a specification for the type. 458 This field MAY be empty. 460 Registrations follow the "First Come First Served" policy (see 461 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 462 the same Type. 464 This registry initially contains the following entries: 466 +---------------------------+-------+---------------+ 467 | Capsule Type | Value | Specification | 468 +---------------------------+-------+---------------+ 469 | REGISTER_DATAGRAM_CONTEXT | 0x00 | This Document | 470 +---------------------------+-------+---------------+ 471 | CLOSE_DATAGRAM_CONTEXT | 0x01 | This Document | 472 +---------------------------+-------+---------------+ 473 | DATAGRAM | 0x02 | This Document | 474 +---------------------------+-------+---------------+ 476 8.4. Context Extension Keys 478 REGISTER_DATAGRAM_CONTEXT capsules carry key-value pairs, see 479 Section 4.1. This document will request IANA to create an "HTTP 480 Datagram Context Extension Keys" registry. Registrations in this 481 registry MUST include the following fields: 483 Key: The key (see Section 4.1). Keys MUST be valid tokens as 484 defined in Section 3.2.6 of [RFC7230]. 486 Description: A brief description of the key semantics, which MAY be 487 a summary if a specification reference is provided. 489 Reference: An optional reference to a specification for the 490 parameter. This field MAY be empty. 492 Registrations follow the "First Come First Served" policy (see 493 Section 4.4 of [IANA-POLICY]) where two registrations MUST NOT have 494 the same Key. This registry is initially empty. 496 9. Normative References 498 [DGRAM] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable 499 Datagram Extension to QUIC", Work in Progress, Internet- 500 Draft, draft-ietf-quic-datagram-02, 16 February 2021, 501 . 503 [H3] Bishop, M., "Hypertext Transfer Protocol Version 3 504 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 505 quic-http-34, 2 February 2021, 506 . 508 [IANA-POLICY] 509 Cotton, M., Leiba, B., and T. Narten, "Guidelines for 510 Writing an IANA Considerations Section in RFCs", BCP 26, 511 RFC 8126, DOI 10.17487/RFC8126, June 2017, 512 . 514 [QUIC] Iyengar, J. and M. Thomson, "QUIC: A UDP-Based Multiplexed 515 and Secure Transport", Work in Progress, Internet-Draft, 516 draft-ietf-quic-transport-34, 14 January 2021, 517 . 520 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 521 Requirement Levels", BCP 14, RFC 2119, 522 DOI 10.17487/RFC2119, March 1997, 523 . 525 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 526 Protocol (HTTP/1.1): Message Syntax and Routing", 527 RFC 7230, DOI 10.17487/RFC7230, June 2014, 528 . 530 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 531 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 532 May 2017, . 534 Appendix A. Examples 536 A.1. CONNECT-UDP 537 Client Server 539 STREAM(44): HEADERS --------> 540 :method = CONNECT-UDP 541 :scheme = https 542 :path = / 543 :authority = target.example.org:443 545 STREAM(44): CAPSULE --------> 546 Capsule Type = REGISTER_DATAGRAM_CONTEXT 547 Context ID = 0 548 Extension String = "" 550 DATAGRAM --------> 551 Quarter Stream ID = 11 552 Context ID = 0 553 Payload = Encapsulated UDP Payload 555 <-------- STREAM(44): HEADERS 556 :status = 200 558 /* Wait for target server to respond to UDP packet. */ 560 <-------- DATAGRAM 561 Quarter Stream ID = 11 562 Context ID = 0 563 Payload = Encapsulated UDP Payload 565 A.2. CONNECT-UDP with Timestamp Extension 566 Client Server 568 STREAM(44): HEADERS --------> 569 :method = CONNECT-UDP 570 :scheme = https 571 :path = / 572 :authority = target.example.org:443 574 STREAM(44): CAPSULE --------> 575 Capsule Type = REGISTER_DATAGRAM_CONTEXT 576 Context ID = 0 577 Extension String = "" 579 DATAGRAM --------> 580 Quarter Stream ID = 11 581 Context ID = 0 582 Payload = Encapsulated UDP Payload 584 <-------- STREAM(44): HEADERS 585 :status = 200 587 /* Wait for target server to respond to UDP packet. */ 589 <-------- DATAGRAM 590 Quarter Stream ID = 11 591 Context ID = 0 592 Payload = Encapsulated UDP Payload 594 STREAM(44): CAPSULE --------> 595 Capsule Type = REGISTER_DATAGRAM_CONTEXT 596 Context ID = 2 597 Extension String = "timestamp" 599 DATAGRAM --------> 600 Quarter Stream ID = 11 601 Context ID = 2 602 Payload = Encapsulated UDP Payload With Timestamp 604 A.3. CONNECT-IP with IP compression 605 Client Server 607 STREAM(44): HEADERS --------> 608 :method = CONNECT-IP 609 :scheme = https 610 :path = / 611 :authority = proxy.example.org:443 613 <-------- STREAM(44): HEADERS 614 :status = 200 616 /* Exchange CONNECT-IP configuration information. */ 618 STREAM(44): CAPSULE --------> 619 Capsule Type = REGISTER_DATAGRAM_CONTEXT 620 Context ID = 0 621 Extension String = "" 623 DATAGRAM --------> 624 Quarter Stream ID = 11 625 Context ID = 0 626 Payload = Encapsulated IP Packet 628 /* Endpoint happily exchange encapsulated IP packets */ 629 /* using Quarter Stream ID 11 and Context ID 0. */ 631 DATAGRAM --------> 632 Quarter Stream ID = 11 633 Context ID = 0 634 Payload = Encapsulated IP Packet 636 /* After performing some analysis on traffic patterns, */ 637 /* the client decides it wants to compress a 5-tuple. */ 639 STREAM(44): CAPSULE --------> 640 Capsule Type = REGISTER_DATAGRAM_CONTEXT 641 Context ID = 2 642 Extension String = "ip=192.0.2.42,port=443" 644 DATAGRAM --------> 645 Quarter Stream ID = 11 646 Context ID = 2 647 Payload = Compressed IP Packet 649 A.4. WebTransport 650 Client Server 652 STREAM(44): HEADERS --------> 653 :method = CONNECT 654 :scheme = https 655 :method = webtransport 656 :path = /hello 657 :authority = webtransport.example.org:443 658 Origin = https://www.example.org:443 660 STREAM(44): CAPSULE --------> 661 Capsule Type = REGISTER_DATAGRAM_CONTEXT 662 Context ID = 0 663 Extension String = "" 665 <-------- STREAM(44): HEADERS 666 :status = 200 668 /* Both endpoints can now send WebTransport datagrams. */ 670 Acknowledgments 672 The DATAGRAM context identifier was previously part of the DATAGRAM 673 frame definition itself, the authors would like to acknowledge the 674 authors of that document and the members of the IETF MASQUE working 675 group for their suggestions. Additionally, the authors would like to 676 thank Martin Thomson for suggesting the use of an HTTP/3 SETTINGS 677 parameter. Furthermore, the authors would like to thank Ben Schwartz 678 for writing the first proposal that used two layers of indirection. 680 Authors' Addresses 682 David Schinazi 683 Google LLC 684 1600 Amphitheatre Parkway 685 Mountain View, California 94043, 686 United States of America 688 Email: dschinazi.ietf@gmail.com 690 Lucas Pardue 691 Cloudflare 693 Email: lucaspardue.24.7@gmail.com