idnits 2.17.1 draft-shade-quic-http2-mapping-00.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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 8, 2016) is 2842 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFC 7540' is mentioned on line 86, but not defined ** Obsolete undefined reference: RFC 7540 (Obsoleted by RFC 9113) == Unused Reference: 'RFC2119' is defined on line 486, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) Summary: 4 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Shade 3 Internet-Draft M. Warres 4 Intended status: Informational Google 5 Expires: January 9, 2017 July 8, 2016 7 HTTP/2 Semantics Using The QUIC Transport Protocol 8 draft-shade-quic-http2-mapping-00 10 Abstract 12 The QUIC transport protocol has several features that are desirable 13 in a transport for HTTP/2, such as stream multiplexing, per-stream 14 flow control, and low-latency connection establishment. This 15 document describes a mapping of HTTP/2 semantics over QUIC. 16 Specifically, this document identifies HTTP/2 features that are 17 subsumed by QUIC, and describes how the other features can be 18 implemented atop QUIC. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on January 9, 2017. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. QUIC advertisement . . . . . . . . . . . . . . . . . . . . . 2 56 3. Connection establishment . . . . . . . . . . . . . . . . . . 3 57 4. Sending a request on an HTTP/2-over-QUIC connection . . . . . 4 58 4.1. Terminating a stream . . . . . . . . . . . . . . . . . . 5 59 5. Writing data to QUIC streams . . . . . . . . . . . . . . . . 5 60 6. Stream Mapping . . . . . . . . . . . . . . . . . . . . . . . 5 61 6.1. Reserved Streams . . . . . . . . . . . . . . . . . . . . 6 62 6.1.1. Stream 3: headers . . . . . . . . . . . . . . . . . . 6 63 6.1.2. Stream states . . . . . . . . . . . . . . . . . . . . 7 64 7. Stream Priorities . . . . . . . . . . . . . . . . . . . . . . 7 65 8. Flow Control . . . . . . . . . . . . . . . . . . . . . . . . 8 66 9. Server Push . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 10. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 11. Other HTTP/2 frames . . . . . . . . . . . . . . . . . . . . . 10 69 11.1. GOAWAY frame . . . . . . . . . . . . . . . . . . . . . . 10 70 11.2. PING frame . . . . . . . . . . . . . . . . . . . . . . . 10 71 11.3. PADDING frame . . . . . . . . . . . . . . . . . . . . . 11 72 12. Normative References . . . . . . . . . . . . . . . . . . . . 11 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 75 1. Introduction 77 The QUIC transport protocol has several features that are desirable 78 in a transport for HTTP/2, such as stream multiplexing, per-stream 79 flow control, and low-latency connection establishment. This 80 document describes a mapping of HTTP/2 semantics over QUIC. 81 Specifically, this document identifies HTTP/2 features that are 82 subsumed by QUIC, and describes how the other features can be 83 implemented atop QUIC. 85 QUIC is described in [draft-hamilton-quic-transport-protocol]. For a 86 full description of HTTP/2, see [RFC 7540]. 88 2. QUIC advertisement 90 A server advertises that it can speak HTTP/2-over-QUIC via the Alt- 91 Svc HTTP response header. It does so by including the header in any 92 response sent over a non-QUIC (e.g. HTTP/2 over TLS) connection: 94 Alt-Svc: quic=":443" 95 In addition, the list of QUIC versions supported by the server can be 96 specified by the v= parameter. For example, if a server supported 97 both version 33 and 34 it would specify the following header: 99 Alt-Svc: quic=":443"; v="34,33" 101 On receipt of this header, a client may attempt to establish a QUIC 102 connection on port 443 and, if successful, send HTTP/2 requests using 103 the mapping described in this document. 105 Connectivity problems (e.g. firewall blocking UDP) may result in QUIC 106 connection establishment failure, in which case the client should 107 gracefully fallback to HTTP/2-over-TLS/TCP. 109 3. Connection establishment 111 HTTP/2-over-QUIC connections are established as described in [draft- 112 hamilton-quic-transport-protocol]. The QUIC crypto handshake MUST 113 use TLS [draft-thomson-quic-tls]. 115 While connection-level options pertaining to the core QUIC protocol 116 are set in the initial crypto handshake [Combined Crypto and 117 Transport Handshake], HTTP/2-specific settings are conveyed in the 118 HTTP/2 SETTINGS frame. After the QUIC connection is established, an 119 HTTP/2 SETTINGS frame may be sent as the initial frame of the QUIC 120 headers stream (StreamID 3, See [Stream Mapping]). As in HTTP/2, 121 additional SETTINGS frames may be sent mid-connection by either 122 endpoint. 124 TODO: decide whether to acknowledge receipt of SETTINGS through empty 125 SETTINGS frames with ACK bit set, as in HTTP/2, or rely on transport- 126 level acknowledgment. 128 Some transport-level options that HTTP/2-over-TCP specifies via the 129 SETTINGS frame are superseded by QUIC transport parameters in HTTP/2- 130 over-QUIC. Below is a listing of how each HTTP/2 SETTINGS parameter 131 is mapped: 133 o SETTINGS_HEADER_TABLE_SIZE 135 * Sent in HTTP/2 SETTINGS frame. 137 o SETTINGS_ENABLE_PUSH 139 * Sent in HTTP/2 SETTINGS frame [TBD, currently set using QUIC 140 "SPSH" connection option] 142 o SETTINGS_MAX_CONCURRENT_STREAMS 143 * QUIC requires the maximum number of incoming streams per 144 connection to be specified in the initial crypto handshake, 145 using the "MSPC" tag. Specifying 146 SETTINGS_MAX_CONCURRENT_STREAMS in the HTTP/2 SETTINGS frame is 147 an error. 149 o SETTINGS_INITIAL_WINDOW_SIZE 151 * QUIC requires both stream and connection flow control window 152 sizes to be specified in the initial crypto handshake, using 153 the "SFCW" and "CFCW" tags, respectively. Specifying 154 SETTINGS_INITIAL_WINDOW_SIZE in the HTTP/2 SETTINGS frame is an 155 error. 157 o SETTINGS_MAX_FRAME_SIZE 159 * This setting has no equivalent in QUIC. Specifying it in the 160 HTTP/2 SETTINGS frame is an error. 162 o SETTINGS_MAX_HEADER_LIST_SIZE 164 * Sent in HTTP/2 SETTINGS frame. 166 As with HTTP/2-over-TCP, unknown SETTINGS parameters are tolerated 167 but ignored. SETTINGS parameters are acknowledged by the receiving 168 peer, by sending an empty SETTINGS frame in response with the ACK bit 169 set. 171 4. Sending a request on an HTTP/2-over-QUIC connection 173 A high level overview of sending an HTTP/2 request on an established 174 QUIC connection is as follows, with further details in later sections 175 of this document. A client should first encode any HTTP headers 176 using HPACK [RFC7541] and frame them as HTTP/2 HEADERS frames. These 177 are sent on StreamID 3 (see [Stream Mapping]). The exact layout of 178 the HEADERS frame is described in Section 6.2 of [RFC7540]. No 179 HTTP/2 padding is required: QUIC provides a PADDING frame for this 180 purpose. 182 While HEADERS are sent on stream 3, the mandatory stream identifier 183 in each HEADERS frame indicates the QUIC StreamID on which a 184 corresponding request body may be sent. If there is no non-header 185 data, the specified QUIC data stream will never be used. 187 4.1. Terminating a stream 189 A stream can be terminated in one of three ways: 191 o the request/response is headers only, in which case a HEADERS 192 frame with the END_STREAM bit set ends the stream specified in the 193 HEADERS frame 195 o the request/response has headers and body but no trailing headers, 196 in which case the final QUIC STREAM frame will have the FIN bit 197 set 199 o the request/response has headers, body, and trailing headers, in 200 which case the final QUIC STREAM frame will not have the FIN bit 201 set, and the trailing HEADERS frame will have the END_STREAM bit 202 set 204 (TODO: Describe mapping of HTTP/2 stream state machine to QUIC stream 205 state machine.) 207 5. Writing data to QUIC streams 209 A QUIC stream provides reliable in-order delivery of bytes, within 210 that stream. On the wire, data is framed into QUIC STREAM frames, 211 but this framing is invisible to the HTTP/2 layer. A QUIC receiver 212 buffers and orders received STREAM frames, exposing the data 213 contained within as a reliable byte stream to the application. 215 Bytes written to Stream 3 must be HTTP/2 HEADERS frames (or other 216 HTTP/2 non-data frames), whereas bytes written to data streams should 217 simply be request or response bodies. No further framing is required 218 by HTTP/2 (i.e. no HTTP/2 DATA frames are used). 220 If data arrives on a data stream before the corresponding HEADERS 221 have arrived on stream 3, then the data is buffered until the HEADERS 222 arrive. 224 6. Stream Mapping 226 When HTTP/2 headers and data are sent over QUIC, the QUIC layer 227 handles most of the stream management. HTTP/2 StreamIDs are replaced 228 by QUIC StreamIDs. HTTP/2 does not need to do any explicit stream 229 framing when using QUIC---data sent over a QUIC stream simply 230 consists of HTTP/2 headers or body. Requests and responses are 231 considered complete when the QUIC stream is closed in the 232 corresponding direction. 234 Like HTTP/2, QUIC uses odd-numbered StreamIDs for client initiated 235 streams, and even-numbered IDs for server initiated (i.e. server 236 push) streams. Unlike HTTP/2 there are a couple of reserved (or 237 dedicated) StreamIDs in QUIC. 239 6.1. Reserved Streams 241 StreamID 1 is reserved for crypto operations (the handshake, crypto 242 config updates), and MUST NOT be used for HTTP/2 headers or body, see 243 [core protocol doc]. StreamID 3 is reserved for sending and 244 receiving HTTP/2 HEADERS frames. Therefore the first client 245 initiated data stream has StreamID 5. 247 There are no reserved server initiated StreamIDs, so the first server 248 initiated (i.e. server push) stream has an ID of 2, followed by 4, 249 etc. 251 6.1.1. Stream 3: headers 253 HTTP/2-over-QUIC uses HPACK header compression as described in 254 [RFC7541]. HPACK was designed for HTTP/2 with the assumption of in- 255 order delivery such as that provided by TCP. A sequence of encoded 256 header blocks must arrive (and be decoded) at an endpoint in the same 257 order in which they were encoded. This ensures that the dynamic 258 state at the two endpoints remains in sync. 260 QUIC streams provide in-order delivery of data sent on those streams, 261 but there are no guarantees about order of delivery between streams. 262 To achieve in-order delivery of HEADERS frames in QUIC, they are all 263 sent on the reserved Stream 3. Data (request/response bodies) which 264 arrive on other data streams are buffered until the corresponding 265 HEADERS arrive and are read out of Stream 3. 267 This does introduce head-of-line blocking: if the packet containing 268 HEADERS for stream N is lost or reordered then stream N+2 cannot be 269 processed until they it has been retransmitted successfully, even 270 though the HEADERS for stream N+2 may have arrived. 272 Trailing headers (trailers) can also be sent on stream 3. These are 273 sent as HTTP/2 HEADERS frames, but MUST have the END_STREAM bit set, 274 and MUST include a ":final-offset" pseudo-header. Since QUIC 275 supports out of order delivery, receipt of a HEADERS frame with the 276 END_STREAM bit set does not guarantee that the entire request/ 277 response body has been fully received. Therefore, the extra ":final- 278 offset" pseudo-header is included in trailing HEADERS frames to 279 indicate the total number of body bytes sent on the corresponding 280 data stream. This is used by the QUIC layer to determine when the 281 full request has been received and therefore when it is safe to tear 282 down local stream state. The ":final-offset" pseudo header is 283 stripped from the HEADERS before passing to the HTTP/2 layer. 285 6.1.2. Stream states 287 The mapping of HTTP/2-over-QUIC with potential out of order delivery 288 of HEADERS frames results in some changes to the HTTP/2 stream state 289 transition diagram [https://tools.ietf.org/html/rfc7540#section-5.1]. 290 Specifically the transition from "open" to "half closed (remote)", 291 and the transition from "half closed (local)" to "closed" takes place 292 only when: 294 o the peer has explicitly ended the stream via either 296 * an HTTP/2 HEADERS frame with END_STREAM bit set and, in the 297 case of trailing headers, the :final-offset pseudo-header 299 * or a QUIC stream frame with the FIN bit set. 301 o and the full request or response body has been received. 303 7. Stream Priorities 305 HTTP/2-over-QUIC uses the HTTP/2 priority scheme described in 306 [RFC7540 Section 5.3]. In the HTTP/2 priority scheme, a given stream 307 can be designated as dependent upon another stream, which expresses 308 the preference that the latter stream (the "parent" stream) be 309 allocated resources before the former stream (the "dependent" 310 stream). Taken together, the dependencies across all streams in a 311 connection form a dependency tree. The structure of the dependency 312 tree changes as HTTP/2 HEADERS and PRIORITY frames add, remove, or 313 change the dependency links between streams. 315 Implicit in this scheme is the notion of in-order delivery of 316 priority changes (i.e., dependency tree mutations): since operations 317 on the dependency tree such as reparenting a subtree are not 318 commutative, both sender and receiver must apply them in the same 319 order to ensure that both sides have a consistent view of the stream 320 dependency tree. HTTP/2 specifies priority assignments in PRIORITY 321 frames and (optionally) in HEADERS frames. To achieve in-order 322 delivery of HTTP/2 priority changes in HTTP/2-over-QUIC, HTTP/2 323 PRIORITY frames, in addition to HEADERS frames, are also sent on 324 reserved stream 3. The semantics of the Stream Dependency, Weight, E 325 flag, and (for HEADERS frames) PRIORITY flag are the same as in 326 HTTP/2-over-TCP. 328 Since HEADERS and PRIORITY frames are sent on a different stream than 329 the STREAM frames for the streams they reference, they may be 330 delivered out-of-order with respect to the STREAM frames. There is 331 no special handling for this--the receiver should simply assign 332 resources according to the most recent stream priority information 333 that it has received. 335 ALTERNATIVE DESIGN: if the core QUIC protocol implements priorities, 336 then this document should map the HTTP/2 priorities scheme to that 337 provided by the core protocol. This would likely involve prohibiting 338 the sending of HTTP/2 PRIORITY frames and setting of the PRIORITY 339 flag in HTTP/2 HEADERS frames, to avoid conflicting directives. 341 8. Flow Control 343 QUIC provides stream and connection level flow control, similar in 344 principle to HTTP/2's flow control but with some implementation 345 differences. As flow control is handled by QUIC, the HTTP/2 mapping 346 need not concern itself with maintaining flow control state, or how/ 347 when to send flow control frames to the peer. The HTTP/2 mapping 348 must not send HTTP/2 WINDOW_UPDATE frames. 350 The initial flow control window sizes (stream and connection) are 351 communicated during the crypto handshake (see [Connection 352 establishment]). Setting these values to the maximum size (2^31 - 1) 353 effectively disables flow control. 355 Relatively small initial windows can be used, as QUIC will attempt to 356 auto-tune the flow control windows based on usage. See [draft- 357 hamilton-quic-transport-protocol] for more details. 359 9. Server Push 361 HTTP/2-over-QUIC supports HTTP/2 server push. During connection 362 establishment, the client indicates whether or it is willing to 363 receive server pushes via the SETTINGS_ENABLE_PUSH setting in the 364 HTTP/2 SETTINGS frame (see [Connection Establishment]), which 365 defaults to 1 (true). 367 As with server push for HTTP/2-over-TCP, the server initiates a 368 server push by sending an HTTP/2 PUSH_PROMISE frame containing the 369 StreamID of the stream to be pushed, as well as request header fields 370 attributed to the request. The PUSH_PROMISE frame is sent on stream 371 3, to ensure proper ordering with respect to other HEADERS and non- 372 data frames. Within the PUSH_PROMISE frame, the StreamID in the 373 common HTTP/2 frame header indicates the associated (client- 374 initiated) stream for the new push stream, while the Promised Stream 375 ID field specifies the StreamID of the new push stream. 377 The server push response is conveyed in the same way as a non-server- 378 push response, with response headers and (if present) trailers 379 carried by HTTP/2 HEADERS frames sent on reserved stream 3, and 380 response body (if any) sent via QUIC stream frames on the stream 381 specified in the corresponding PUSH_PROMISE frame. 383 10. Error Codes 385 The HTTP/2 error codes defined in [RFC7540 Section 7] map to QUIC 386 error codes as follows: 388 o NO_ERROR (0x0) 390 * Maps to QUIC_NO_ERROR 392 o PROTOCOL_ERROR (0x1) 394 * No single mapping? 396 o INTERNAL_ERROR (0x2) 398 * QUIC_INTERNAL_ERROR? (not currently defined in core protocol 399 spec) 401 o FLOW_CONTROL_ERROR (0x3) 403 * QUIC_FLOW_CONTROL_RECEIVED_TOO_MUCH_DATA? (not currently 404 defined in core protocol spec) 406 o SETTINGS_TIMEOUT (0x4) 408 * ? (depends on whether we support SETTINGS acks) 410 o STREAM_CLOSED (0x5) 412 * QUIC_STREAM_DATA_AFTER_TERMINATION 414 o FRAME_SIZE_ERROR (0x6) 416 * QUIC_INVALID_FRAME_DATA 418 o REFUSED_STREAM (0x7) 420 * ? 422 o CANCEL (0x8) 424 * ? 426 o COMPRESSION_ERROR (0x9) 428 * QUIC_DECOMPRESSION_FAILURE (not currently defined in core spec) 430 o CONNECT_ERROR (0xa) 432 * ? (depends whether we decide to support CONNECT) 434 o ENHANCE_YOUR_CALM (0xb) 436 * ? 438 o INADEQUATE_SECURITY (0xc) 440 * QUIC_HANDSHAKE_FAILED, QUIC_CRYPTO_NO_SUPPORT 442 o HTTP_1_1_REQUIRED (0xd) 444 TODO: fill in missing error code mappings. 446 11. Other HTTP/2 frames 448 QUIC includes some features (e.g. flow control) which are also 449 present in HTTP/2. In these cases the HTTP/2 mapping need not re- 450 implement them. As a result some HTTP/2 frame types are not required 451 when using QUIC, as they either are directly implemented in the QUIC 452 layer, or their functionality is provided via other means. This 453 section of the document describes these cases. 455 11.1. GOAWAY frame 457 QUIC has its own GOAWAY frame, and QUIC implementations may to expose 458 the sending of a GOAWAY to the application. The semantics of sending 459 a GOAWAY in QUIC are identical to HTTP/2: an endpoint sending a 460 GOAWAY will continue processing open streams, but will not accept 461 newly created streams. 463 QUIC's GOAWAY frame is described in detail in the [draft-hamilton- 464 quic-transport-protocol]. 466 11.2. PING frame 468 QUIC has its own PING frame, which is currently exposed to the 469 application. QUIC clients send periodic PINGs to servers if there 470 are no currently active data streams on the connection. 472 QUIC's PING frame is described in detail in the [draft-hamilton-quic- 473 transport-protocol]. 475 11.3. PADDING frame 477 There is no HTTP/2 padding in this mapping; padding is instead 478 provided at the QUIC layer by including QUIC PADDING frames in a 479 packet payload. An HTTP/2 over QUIC mapping should treat any HTTP/2 480 level padding as an error, to avoid any possibility of inconsistent 481 flow control states between endpoints (e.g. client sends HTTP/2 482 padding, counts it against flow control, server ignores). 484 12. Normative References 486 [RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate 487 Requirement Levels", March 1997. 489 [RFC7540] Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer 490 Protocol Version 2 (HTTP/2)", May 2015. 492 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 493 HTTP/2", May 2015. 495 [draft-hamilton-quic-transport-protocol] 496 Hamilton, R., Iyengar, J., Swett, I., and A. Wilk, "QUIC: 497 A UDP-Based Multiplexed and Secure Transport", July 2016. 499 [draft-thomson-quic-tls] 500 Thomson, M. and R. Hamilton, "Porting QUIC to TLS", March 501 2016. 503 [draft-iyengar-quic-loss-recovery] 504 Iyengar, J. and I. Swett, "QUIC Loss Recovery and 505 Congestion Control", July 2016. 507 Authors' Addresses 509 Robbie Shade 510 Google 512 Email: rjshade@google.com 514 Mike Warres 515 Google 517 Email: mpw@google.com