idnits 2.17.00 (12 Aug 2021) /tmp/idnits23257/draft-ietf-httpbis-http2-10.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 (February 13, 2014) is 3018 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) == Missing Reference: 'Priority' is mentioned on line 1198, but not defined == Outdated reference: draft-ietf-httpbis-header-compression has been published as RFC 7541 == Outdated reference: draft-ietf-httpbis-p1-messaging has been published as RFC 7230 == Outdated reference: draft-ietf-httpbis-p2-semantics has been published as RFC 7231 == Outdated reference: draft-ietf-httpbis-p4-conditional has been published as RFC 7232 == Outdated reference: draft-ietf-httpbis-p5-range has been published as RFC 7233 == Outdated reference: draft-ietf-httpbis-p6-cache has been published as RFC 7234 == Outdated reference: draft-ietf-httpbis-p7-auth has been published as RFC 7235 ** Downref: Normative reference to an Informational RFC: RFC 2818 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (ref. 'TLS12') (Obsoleted by RFC 8446) == Outdated reference: draft-ietf-tls-applayerprotoneg has been published as RFC 7301 == Outdated reference: A later version (-05) exists of draft-nottingham-httpbis-alt-svc-01 -- Obsolete informational reference (is this intentional?): RFC 1323 (Obsoleted by RFC 7323) == Outdated reference: A later version (-02) exists of draft-sheffer-tls-bcp-01 Summary: 3 errors (**), 0 flaws (~~), 12 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group M. Belshe 3 Internet-Draft Twist 4 Intended status: Standards Track R. Peon 5 Expires: August 17, 2014 Google, Inc 6 M. Thomson, Ed. 7 Mozilla 8 February 13, 2014 10 Hypertext Transfer Protocol version 2 11 draft-ietf-httpbis-http2-10 13 Abstract 15 This specification describes an optimized expression of the syntax of 16 the Hypertext Transfer Protocol (HTTP). HTTP/2 enables a more 17 efficient use of network resources and a reduced perception of 18 latency by introducing header field compression and allowing multiple 19 concurrent messages on the same connection. It also introduces 20 unsolicited push of representations from servers to clients. 22 This document is an alternative to, but does not obsolete, the 23 HTTP/1.1 message syntax. HTTP's existing semantics remain unchanged. 25 Editorial Note (To be removed by RFC Editor) 27 Discussion of this draft takes place on the HTTPBIS working group 28 mailing list (ietf-http-wg@w3.org), which is archived at 29 . 31 Working Group information and related documents can be found at 32 (Wiki) and 33 (source code and issues 34 tracker). 36 The changes in this draft are summarized in Appendix A. 38 Status of This Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at http://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on August 17, 2014. 55 Copyright Notice 57 Copyright (c) 2014 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents 62 (http://trustee.ietf.org/license-info) in effect on the date of 63 publication of this document. Please review these documents 64 carefully, as they describe your rights and restrictions with respect 65 to this document. Code Components extracted from this document must 66 include Simplified BSD License text as described in Section 4.e of 67 the Trust Legal Provisions and are provided without warranty as 68 described in the Simplified BSD License. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 1.1. Document Organization . . . . . . . . . . . . . . . . . . 5 74 1.2. Conventions and Terminology . . . . . . . . . . . . . . . 6 75 2. HTTP/2 Protocol Overview . . . . . . . . . . . . . . . . . . . 7 76 2.1. HTTP Frames . . . . . . . . . . . . . . . . . . . . . . . 7 77 2.2. HTTP Multiplexing . . . . . . . . . . . . . . . . . . . . 7 78 2.3. HTTP Semantics . . . . . . . . . . . . . . . . . . . . . . 7 79 3. Starting HTTP/2 . . . . . . . . . . . . . . . . . . . . . . . 7 80 3.1. HTTP/2 Version Identification . . . . . . . . . . . . . . 8 81 3.2. Starting HTTP/2 for "http" URIs . . . . . . . . . . . . . 9 82 3.2.1. HTTP2-Settings Header Field . . . . . . . . . . . . . 10 83 3.3. Starting HTTP/2 for "https" URIs . . . . . . . . . . . . . 11 84 3.4. Starting HTTP/2 with Prior Knowledge . . . . . . . . . . . 11 85 3.5. HTTP/2 Connection Header . . . . . . . . . . . . . . . . . 11 86 4. HTTP Frames . . . . . . . . . . . . . . . . . . . . . . . . . 12 87 4.1. Frame Format . . . . . . . . . . . . . . . . . . . . . . . 12 88 4.2. Frame Size . . . . . . . . . . . . . . . . . . . . . . . . 13 89 4.3. Header Compression and Decompression . . . . . . . . . . . 14 90 5. Streams and Multiplexing . . . . . . . . . . . . . . . . . . . 15 91 5.1. Stream States . . . . . . . . . . . . . . . . . . . . . . 15 92 5.1.1. Stream Identifiers . . . . . . . . . . . . . . . . . . 20 93 5.1.2. Stream Concurrency . . . . . . . . . . . . . . . . . . 20 94 5.2. Flow Control . . . . . . . . . . . . . . . . . . . . . . . 21 95 5.2.1. Flow Control Principles . . . . . . . . . . . . . . . 21 96 5.2.2. Appropriate Use of Flow Control . . . . . . . . . . . 22 98 5.3. Stream priority . . . . . . . . . . . . . . . . . . . . . 22 99 5.4. Error Handling . . . . . . . . . . . . . . . . . . . . . . 23 100 5.4.1. Connection Error Handling . . . . . . . . . . . . . . 23 101 5.4.2. Stream Error Handling . . . . . . . . . . . . . . . . 24 102 5.4.3. Connection Termination . . . . . . . . . . . . . . . . 24 103 6. Frame Definitions . . . . . . . . . . . . . . . . . . . . . . 24 104 6.1. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 105 6.2. HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . 27 106 6.3. PRIORITY . . . . . . . . . . . . . . . . . . . . . . . . . 29 107 6.4. RST_STREAM . . . . . . . . . . . . . . . . . . . . . . . . 29 108 6.5. SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . . 30 109 6.5.1. Setting Format . . . . . . . . . . . . . . . . . . . . 31 110 6.5.2. Defined Settings . . . . . . . . . . . . . . . . . . . 32 111 6.5.3. Settings Synchronization . . . . . . . . . . . . . . . 33 112 6.6. PUSH_PROMISE . . . . . . . . . . . . . . . . . . . . . . . 33 113 6.7. PING . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 114 6.8. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . . . 35 115 6.9. WINDOW_UPDATE . . . . . . . . . . . . . . . . . . . . . . 38 116 6.9.1. The Flow Control Window . . . . . . . . . . . . . . . 39 117 6.9.2. Initial Flow Control Window Size . . . . . . . . . . . 40 118 6.9.3. Reducing the Stream Window Size . . . . . . . . . . . 40 119 6.10. CONTINUATION . . . . . . . . . . . . . . . . . . . . . . . 41 120 7. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . 42 121 8. HTTP Message Exchanges . . . . . . . . . . . . . . . . . . . . 44 122 8.1. HTTP Request/Response Exchange . . . . . . . . . . . . . . 44 123 8.1.1. Informational Responses . . . . . . . . . . . . . . . 45 124 8.1.2. Examples . . . . . . . . . . . . . . . . . . . . . . . 46 125 8.1.3. HTTP Header Fields . . . . . . . . . . . . . . . . . . 48 126 8.1.4. Request Reliability Mechanisms in HTTP/2 . . . . . . . 51 127 8.2. Server Push . . . . . . . . . . . . . . . . . . . . . . . 52 128 8.2.1. Push Requests . . . . . . . . . . . . . . . . . . . . 53 129 8.2.2. Push Responses . . . . . . . . . . . . . . . . . . . . 54 130 8.3. The CONNECT Method . . . . . . . . . . . . . . . . . . . . 54 131 9. Additional HTTP Requirements/Considerations . . . . . . . . . 56 132 9.1. Connection Management . . . . . . . . . . . . . . . . . . 56 133 9.2. Use of TLS Features . . . . . . . . . . . . . . . . . . . 56 134 9.3. GZip Content-Encoding . . . . . . . . . . . . . . . . . . 57 135 10. Security Considerations . . . . . . . . . . . . . . . . . . . 57 136 10.1. Server Authority and Same-Origin . . . . . . . . . . . . . 57 137 10.2. Cross-Protocol Attacks . . . . . . . . . . . . . . . . . . 58 138 10.3. Intermediary Encapsulation Attacks . . . . . . . . . . . . 58 139 10.4. Cacheability of Pushed Resources . . . . . . . . . . . . . 58 140 10.5. Denial of Service Considerations . . . . . . . . . . . . . 59 141 10.6. Use of Padding . . . . . . . . . . . . . . . . . . . . . . 60 142 11. Privacy Considerations . . . . . . . . . . . . . . . . . . . . 60 143 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 144 12.1. Registration of HTTP/2 Identification String . . . . . . . 61 145 12.2. Error Code Registry . . . . . . . . . . . . . . . . . . . 61 146 12.3. HTTP2-Settings Header Field Registration . . . . . . . . . 62 147 12.4. PRI Method Registration . . . . . . . . . . . . . . . . . 62 148 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 62 149 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 63 150 14.1. Normative References . . . . . . . . . . . . . . . . . . . 63 151 14.2. Informative References . . . . . . . . . . . . . . . . . . 65 152 Appendix A. Change Log (to be removed by RFC Editor before 153 publication) . . . . . . . . . . . . . . . . . . . . 65 154 A.1. Since draft-ietf-httpbis-http2-09 . . . . . . . . . . . . 65 155 A.2. Since draft-ietf-httpbis-http2-08 . . . . . . . . . . . . 66 156 A.3. Since draft-ietf-httpbis-http2-07 . . . . . . . . . . . . 66 157 A.4. Since draft-ietf-httpbis-http2-06 . . . . . . . . . . . . 66 158 A.5. Since draft-ietf-httpbis-http2-05 . . . . . . . . . . . . 66 159 A.6. Since draft-ietf-httpbis-http2-04 . . . . . . . . . . . . 67 160 A.7. Since draft-ietf-httpbis-http2-03 . . . . . . . . . . . . 67 161 A.8. Since draft-ietf-httpbis-http2-02 . . . . . . . . . . . . 67 162 A.9. Since draft-ietf-httpbis-http2-01 . . . . . . . . . . . . 68 163 A.10. Since draft-ietf-httpbis-http2-00 . . . . . . . . . . . . 68 164 A.11. Since draft-mbelshe-httpbis-spdy-00 . . . . . . . . . . . 69 166 1. Introduction 168 The Hypertext Transfer Protocol (HTTP) is a wildly successful 169 protocol. However, the HTTP/1.1 message format ([HTTP-p1], Section 170 3) is optimized for implementation simplicity and accessibility, not 171 application performance. As such it has several characteristics that 172 have a negative overall effect on application performance. 174 In particular, HTTP/1.0 only allows one request to be outstanding at 175 a time on a given connection. HTTP/1.1 pipelining only partially 176 addressed request concurrency and suffers from head-of-line blocking. 177 Therefore, clients that need to make many requests typically use 178 multiple connections to a server in order to reduce latency. 180 Furthermore, HTTP/1.1 header fields are often repetitive and verbose, 181 which, in addition to generating more or larger network packets, can 182 cause the small initial TCP congestion window to quickly fill. This 183 can result in excessive latency when multiple requests are made on a 184 single new TCP connection. 186 This document addresses these issues by defining an optimized mapping 187 of HTTP's semantics to an underlying connection. Specifically, it 188 allows interleaving of request and response messages on the same 189 connection and uses an efficient coding for HTTP header fields. It 190 also allows prioritization of requests, letting more important 191 requests complete more quickly, further improving performance. 193 The resulting protocol is designed to be more friendly to the 194 network, because fewer TCP connections can be used, in comparison to 195 HTTP/1.x. This means less competition with other flows, and longer- 196 lived connections, which in turn leads to better utilization of 197 available network capacity. 199 Finally, this encapsulation also enables more scalable processing of 200 messages through use of binary message framing. 202 1.1. Document Organization 204 The HTTP/2 specification is split into four parts: 206 o Starting HTTP/2 (Section 3) covers how a HTTP/2 connection is 207 initiated. 209 o The framing (Section 4) and streams (Section 5) layers describe 210 the way HTTP/2 frames are structured and formed into multiplexed 211 streams. 213 o Frame (Section 6) and error (Section 7) definitions include 214 details of the frame and error types used in HTTP/2. 216 o HTTP mappings (Section 8) and additional requirements (Section 9) 217 describe how HTTP semantics are expressed using the mechanisms 218 defined. 220 While some of the frame and stream layer concepts are isolated from 221 HTTP, the intent is not to define a completely generic framing layer. 222 The framing and streams layers are tailored to the needs of the HTTP 223 protocol and server push. 225 1.2. Conventions and Terminology 227 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 228 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 229 document are to be interpreted as described in RFC 2119 [RFC2119]. 231 All numeric values are in network byte order. Values are unsigned 232 unless otherwise indicated. Literal values are provided in decimal 233 or hexadecimal as appropriate. Hexadecimal literals are prefixed 234 with "0x" to distinguish them from decimal literals. 236 The following terms are used: 238 client: The endpoint initiating the HTTP/2 connection. 240 connection: A transport-level connection between two endpoints. 242 connection error: An error that affects the entire HTTP/2 243 connection. 245 endpoint: Either the client or server of the connection. 247 frame: The smallest unit of communication within an HTTP/2 248 connection, consisting of a header and a variable-length sequence 249 of bytes structured according to the frame type. 251 peer: An endpoint. When discussing a particular endpoint, "peer" 252 refers to the endpoint that is remote to the primary subject of 253 discussion. 255 receiver: An endpoint that is receiving frames. 257 sender: An endpoint that is transmitting frames. 259 server: The endpoint which did not initiate the HTTP/2 connection. 261 stream: A bi-directional flow of frames across a virtual channel 262 within the HTTP/2 connection. 264 stream error: An error on the individual HTTP/2 stream. 266 2. HTTP/2 Protocol Overview 268 HTTP/2 provides an optimized transport for HTTP semantics. 270 An HTTP/2 connection is an application level protocol running on top 271 of a TCP connection ([TCP]). The client is the TCP connection 272 initiator. 274 This document describes the HTTP/2 protocol using a logical structure 275 that is formed of three parts: framing, streams, and application 276 mapping. This structure is provided primarily as an aid to 277 specification, implementations are free to diverge from this 278 structure as necessary. 280 2.1. HTTP Frames 282 HTTP/2 provides an efficient serialization of HTTP semantics. HTTP 283 requests and responses are encoded into length-prefixed frames (see 284 Section 4.1). 286 HTTP header fields are compressed into a series of frames that 287 contain header block fragments (see Section 4.3). 289 2.2. HTTP Multiplexing 291 HTTP/2 provides the ability to multiplex HTTP requests and responses 292 over a single connection. Multiple requests or responses can be sent 293 concurrently on a connection using streams (Section 5). In order to 294 maintain independent streams, flow control and prioritization are 295 necessary. 297 2.3. HTTP Semantics 299 HTTP/2 defines how HTTP requests and responses are mapped to streams 300 (see Section 8.1) and introduces a new interaction model, server push 301 (Section 8.2). 303 3. Starting HTTP/2 305 HTTP/2 uses the same "http" and "https" URI schemes used by HTTP/1.1. 306 HTTP/2 shares the same default port numbers: 80 for "http" URIs and 307 443 for "https" URIs. As a result, implementations processing 308 requests for target resource URIs like "http://example.org/foo" or 309 "https://example.com/bar" are required to first discover whether the 310 upstream server (the immediate peer to which the client wishes to 311 establish a connection) supports HTTP/2. 313 The means by which support for HTTP/2 is determined is different for 314 "http" and "https" URIs. Discovery for "http" URIs is described in 315 Section 3.2. Discovery for "https" URIs is described in Section 3.3. 317 3.1. HTTP/2 Version Identification 319 The protocol defined in this document is identified using the string 320 "h2". This identification is used in the HTTP/1.1 Upgrade header 321 field, in the TLS application layer protocol negotiation extension 322 [TLSALPN] field, and other places where protocol identification is 323 required. 325 Negotiating "h2" implies the use of the transport, security, framing 326 and message semantics described in this document. 328 [[anchor6: Editor's Note: please remove the remainder of this section 329 prior to the publication of a final version of this document.]] 331 Only implementations of the final, published RFC can identify 332 themselves as "h2". Until such an RFC exists, implementations MUST 333 NOT identify themselves using "h2". 335 Examples and text throughout the rest of this document use "h2" as a 336 matter of editorial convenience only. Implementations of draft 337 versions MUST NOT identify using this string. 339 Implementations of draft versions of the protocol MUST add the string 340 "-" and the corresponding draft number to the identifier. For 341 example, draft-ietf-httpbis-http2-09 is identified using the string 342 "h2-09". 344 Non-compatible experiments that are based on these draft versions 345 MUST append the string "-" and a experiment name to the identifier. 346 For example, an experimental implementation of packet mood-based 347 encoding based on draft-ietf-httpbis-http2-09 might identify itself 348 as "h2-09-emo". Note that any label MUST conform to the "token" 349 syntax defined in Section 3.2.6 of [HTTP-p1]. Experimenters are 350 encouraged to coordinate their experiments on the ietf-http-wg@w3.org 351 mailing list. 353 3.2. Starting HTTP/2 for "http" URIs 355 A client that makes a request to an "http" URI without prior 356 knowledge about support for HTTP/2 uses the HTTP Upgrade mechanism 357 (Section 6.7 of [HTTP-p1]). The client makes an HTTP/1.1 request 358 that includes an Upgrade header field identifying HTTP/2 with the h2 359 token. The HTTP/1.1 request MUST include exactly one HTTP2-Settings 360 (Section 3.2.1) header field. 362 For example: 364 GET /default.htm HTTP/1.1 365 Host: server.example.com 366 Connection: Upgrade, HTTP2-Settings 367 Upgrade: h2 368 HTTP2-Settings: 370 Requests that contain an entity body MUST be sent in their entirety 371 before the client can send HTTP/2 frames. This means that a large 372 request entity can block the use of the connection until it is 373 completely sent. 375 If concurrency of an initial request with subsequent requests is 376 important, a small request can be used to perform the upgrade to 377 HTTP/2, at the cost of an additional round-trip. 379 A server that does not support HTTP/2 can respond to the request as 380 though the Upgrade header field were absent: 382 HTTP/1.1 200 OK 383 Content-Length: 243 384 Content-Type: text/html 386 ... 388 A server that supports HTTP/2 can accept the upgrade with a 101 389 (Switching Protocols) response. After the empty line that terminates 390 the 101 response, the server can begin sending HTTP/2 frames. These 391 frames MUST include a response to the request that initiated the 392 Upgrade. 394 HTTP/1.1 101 Switching Protocols 395 Connection: Upgrade 396 Upgrade: h2 398 [ HTTP/2 connection ... 400 The first HTTP/2 frame sent by the server is a SETTINGS frame 401 (Section 6.5). Upon receiving the 101 response, the client sends a 402 connection header (Section 3.5), which includes a SETTINGS frame. 404 The HTTP/1.1 request that is sent prior to upgrade is assigned stream 405 identifier 1 and is assigned the highest possible priority. Stream 1 406 is implicitly half closed from the client toward the server, since 407 the request is completed as an HTTP/1.1 request. After commencing 408 the HTTP/2 connection, stream 1 is used for the response. 410 3.2.1. HTTP2-Settings Header Field 412 A request that upgrades from HTTP/1.1 to HTTP/2 MUST include exactly 413 one "HTTP2-Settings" header field. The "HTTP2-Settings" header field 414 is a hop-by-hop header field that includes settings that govern the 415 HTTP/2 connection, provided in anticipation of the server accepting 416 the request to upgrade. A server MUST reject an attempt to upgrade 417 if this header field is not present. 419 HTTP2-Settings = token68 421 The content of the "HTTP2-Settings" header field is the payload of a 422 SETTINGS frame (Section 6.5), encoded as a base64url string (that is, 423 the URL- and filename-safe Base64 encoding described in Section 5 of 424 [RFC4648], with any trailing '=' characters omitted). The ABNF 425 [RFC5234] production for "token68" is defined in Section 2.1 of 426 [HTTP-p7]. 428 The client MUST include values for the following settings 429 (Section 6.5.1): 431 o SETTINGS_MAX_CONCURRENT_STREAMS 433 o SETTINGS_INITIAL_WINDOW_SIZE 435 As a hop-by-hop header field, the "Connection" header field MUST 436 include a value of "HTTP2-Settings" in addition to "Upgrade" when 437 upgrading to HTTP/2. 439 A server decodes and interprets these values as it would any other 440 SETTINGS frame. Acknowledgement of the settings (Section 6.5.3) is 441 not necessary, since a 101 response serves as implicit 442 acknowledgment. Providing these values in the Upgrade request 443 ensures that the protocol does not require default values for the 444 above settings, and gives a client an opportunity to provide other 445 settings prior to receiving any frames from the server. 447 3.3. Starting HTTP/2 for "https" URIs 449 A client that makes a request to an "https" URI without prior 450 knowledge about support for HTTP/2 uses TLS [TLS12] with the 451 application layer protocol negotiation extension [TLSALPN]. 453 Once TLS negotiation is complete, both the client and the server send 454 a connection header (Section 3.5). 456 3.4. Starting HTTP/2 with Prior Knowledge 458 A client can learn that a particular server supports HTTP/2 by other 459 means. For example, [AltSvc] describes a mechanism for advertising 460 this capability in an HTTP header field. A client MAY immediately 461 send HTTP/2 frames to a server that is known to support HTTP/2, after 462 the connection header (Section 3.5). A server can identify such a 463 connection by the use of the "PRI" method in the connection header. 464 This only affects the resolution of "http" URIs; servers supporting 465 HTTP/2 are required to support protocol negotiation in TLS [TLSALPN] 466 for "https" URIs. 468 Prior support for HTTP/2 is not a strong signal that a given server 469 will support HTTP/2 for future connections. It is possible for 470 server configurations to change or for configurations to differ 471 between instances in clustered server. Interception proxies (a.k.a. 472 "transparent" proxies) are another source of variability. 474 3.5. HTTP/2 Connection Header 476 Upon establishment of a TCP connection and determination that HTTP/2 477 will be used by both peers, each endpoint MUST send a connection 478 header as a final confirmation and to establish the initial settings 479 for the HTTP/2 connection. 481 The client connection header starts with a sequence of 24 octets, 482 which in hex notation are: 484 505249202a20485454502f322e300d0a0d0a534d0d0a0d0a 486 (the string "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"). This sequence is 487 followed by a SETTINGS frame (Section 6.5). The client sends the 488 client connection header immediately upon receipt of a 101 Switching 489 Protocols response (indicating a successful upgrade), or as the first 490 application data octets of a TLS connection. If starting an HTTP/2 491 connection with prior knowledge of server support for the protocol, 492 the client connection header is sent upon connection establishment. 494 The client connection header is selected so that a large 495 proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries do 496 not attempt to process further frames. Note that this does not 497 address the concerns raised in [TALKING]. 499 The server connection header consists of just a SETTINGS frame 500 (Section 6.5) that MUST be the first frame the server sends in the 501 HTTP/2 connection. 503 To avoid unnecessary latency, clients are permitted to send 504 additional frames to the server immediately after sending the client 505 connection header, without waiting to receive the server connection 506 header. It is important to note, however, that the server connection 507 header SETTINGS frame might include parameters that necessarily alter 508 how a client is expected to communicate with the server. Upon 509 receiving the SETTINGS frame, the client is expected to honor any 510 parameters established. 512 Clients and servers MUST terminate the TCP connection if either peer 513 does not begin with a valid connection header. A GOAWAY frame 514 (Section 6.8) MAY be omitted if it is clear that the peer is not 515 using HTTP/2. 517 4. HTTP Frames 519 Once the HTTP/2 connection is established, endpoints can begin 520 exchanging frames. 522 4.1. Frame Format 524 All frames begin with an 8-octet header followed by a payload of 525 between 0 and 16,383 octets. 527 0 1 2 3 528 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 529 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 530 | R | Length (14) | Type (8) | Flags (8) | 531 +-+-+-----------+---------------+-------------------------------+ 532 |R| Stream Identifier (31) | 533 +-+-------------------------------------------------------------+ 534 | Frame Payload (0...) ... 535 +---------------------------------------------------------------+ 537 Frame Header 539 The fields of the frame header are defined as: 541 R: A reserved 2-bit field. The semantics of these bits are undefined 542 and the bits MUST remain unset (0) when sending and MUST be 543 ignored when receiving. 545 Length: The length of the frame payload expressed as an unsigned 14- 546 bit integer. The 8 octets of the frame header are not included in 547 this value. 549 Type: The 8-bit type of the frame. The frame type determines how 550 the remainder of the frame header and payload are interpreted. 551 Implementations MUST treat the receipt of an unknown frame type 552 (any frame type not defined in this document) as a connection 553 error (Section 5.4.1) of type PROTOCOL_ERROR. 555 Flags: An 8-bit field reserved for frame-type specific boolean 556 flags. 558 Flags are assigned semantics specific to the indicated frame type. 559 Flags that have no defined semantics for a particular frame type 560 MUST be ignored, and MUST be left unset (0) when sending. 562 R: A reserved 1-bit field. The semantics of this bit are undefined 563 and the bit MUST remain unset (0) when sending and MUST be ignored 564 when receiving. 566 Stream Identifier: A 31-bit stream identifier (see Section 5.1.1). 567 The value 0 is reserved for frames that are associated with the 568 connection as a whole as opposed to an individual stream. 570 The structure and content of the frame payload is dependent entirely 571 on the frame type. 573 4.2. Frame Size 575 The maximum size of a frame payload varies by frame type. The 576 absolute maximum size of a frame is 2^14-1 (16,383) octets. All 577 implementations SHOULD be capable of receiving and minimally 578 processing frames up to this maximum size. 580 Certain frame types, such as PING (see Section 6.7), impose 581 additional limits on the amount of payload data allowed. Likewise, 582 additional size limits can be set by specific application uses (see 583 Section 9). 585 If a frame size exceeds any defined limit, or is too small to contain 586 mandatory frame data, the endpoint MUST send a FRAME_SIZE_ERROR 587 error. A frame size error in a frame that affects connection-level 588 state MUST be treated as a connection error (Section 5.4.1). 590 4.3. Header Compression and Decompression 592 A header field in HTTP/2 is a name-value pair with one or more 593 associated values. They are used within HTTP request and response 594 messages as well as server push operations (see Section 8.2). 596 Header sets are collections of zero or more header fields. When 597 transmitted over a connection, a header set is serialized into a 598 header block using HTTP Header Compression [COMPRESSION]. The 599 serialized header block is then divided into one or more octet 600 sequences, called header block fragments, and transmitted within the 601 payload of HEADERS (Section 6.2), PUSH_PROMISE (Section 6.6) or 602 CONTINUATION (Section 6.10) frames. 604 HTTP Header Compression does not preserve the relative ordering of 605 header fields. Header fields with multiple values are encoded into a 606 single header field using a special delimiter, see Section 8.1.3.3. 608 The Cookie header field [COOKIE] is treated specially by the HTTP 609 mapping, see Section 8.1.3.4. 611 A receiving endpoint reassembles the header block by concatenating 612 the individual fragments, then decompresses the block to reconstruct 613 the header set. 615 A complete header block consists of either: 617 o a single HEADERS or PUSH_PROMISE frame each respectively with the 618 END_HEADERS or END_PUSH_PROMISE flag set, or 620 o a HEADERS or PUSH_PROMISE frame with the END_HEADERS or 621 END_PUSH_PROMISE flag cleared and one or more CONTINUATION frames, 622 where the last CONTINUATION frame has the END_HEADERS flag set. 624 Header blocks MUST be transmitted as a contiguous sequence of frames, 625 with no interleaved frames of any other type, or from any other 626 stream. The last frame in a sequence of HEADERS or CONTINUATION 627 frames MUST have the END_HEADERS flag set. The last frame in a 628 sequence of PUSH_PROMISE or CONTINUATION frames MUST have the 629 END_PUSH_PROMISE or END_HEADERS flag set (respectively). 631 Header block fragments can only be sent as the payload of HEADERS, 632 PUSH_PROMISE or CONTINUATION frames. HEADERS, PUSH_PROMISE and 633 CONTINUATION frames carry data that can modify the compression 634 context maintained by a receiver. An endpoint receiving HEADERS, 635 PUSH_PROMISE or CONTINUATION frames MUST reassemble header blocks and 636 perform decompression even if the frames are to be discarded. A 637 receiver MUST terminate the connection with a connection error 638 (Section 5.4.1) of type COMPRESSION_ERROR, if it does not decompress 639 a header block. 641 5. Streams and Multiplexing 643 A "stream" is an independent, bi-directional sequence of HEADERS and 644 DATA frames exchanged between the client and server within an HTTP/2 645 connection. Streams have several important characteristics: 647 o A single HTTP/2 connection can contain multiple concurrently open 648 streams, with either endpoint interleaving frames from multiple 649 streams. 651 o Streams can be established and used unilaterally or shared by 652 either the client or server. 654 o Streams can be closed by either endpoint. 656 o The order in which frames are sent within a stream is significant. 657 Recipients process frames in the order they are received. 659 o Streams are identified by an integer. Stream identifiers are 660 assigned to streams by the initiating endpoint. 662 5.1. Stream States 664 The lifecycle of a stream is shown in Figure 1. 666 +--------+ 667 PP | | PP 668 ,--------| idle |--------. 669 / | | \ 670 v +--------+ v 671 +----------+ | +----------+ 672 | | | H | | 673 ,---| reserved | | | reserved |---. 674 | | (local) | v | (remote) | | 675 | +----------+ +--------+ +----------+ | 676 | | ES | | ES | | 677 | | H ,-------| open |-------. | H | 678 | | / | | \ | | 679 | v v +--------+ v v | 680 | +----------+ | +----------+ | 681 | | half | | | half | | 682 | | closed | | R | closed | | 683 | | (remote) | | | (local) | | 684 | +----------+ | +----------+ | 685 | | v | | 686 | | ES / R +--------+ ES / R | | 687 | `----------->| |<-----------' | 688 | R | closed | R | 689 `-------------------->| |<--------------------' 690 +--------+ 692 Figure 1: Stream States 694 Both endpoints have a subjective view of the state of a stream that 695 could be different when frames are in transit. Endpoints do not 696 coordinate the creation of streams, they are created unilaterally by 697 either endpoint. The negative consequences of a mismatch in states 698 are limited to the "closed" state after sending RST_STREAM, where 699 frames might be received for some time after closing. 701 Streams have the following states: 703 idle: 704 All streams start in the "idle" state. In this state, no frames 705 have been exchanged. 707 The following transitions are valid from this state: 709 * Sending or receiving a HEADERS frame causes the stream to 710 become "open". The stream identifier is selected as described 711 in Section 5.1.1. The same HEADERS frame can also cause a 712 stream to immediately become "half closed". 714 * Sending a PUSH_PROMISE frame marks the associated stream for 715 later use. The stream state for the reserved stream 716 transitions to "reserved (local)". 718 * Receiving a PUSH_PROMISE frame marks the associated stream as 719 reserved by the remote peer. The state of the stream becomes 720 "reserved (remote)". 722 reserved (local): 723 A stream in the "reserved (local)" state is one that has been 724 promised by sending a PUSH_PROMISE frame. A PUSH_PROMISE frame 725 reserves an idle stream by associating the stream with an open 726 stream that was initiated by the remote peer (see Section 8.2). 728 In this state, only the following transitions are possible: 730 * The endpoint can send a HEADERS frame. This causes the stream 731 to open in a "half closed (remote)" state. 733 * Either endpoint can send a RST_STREAM frame to cause the stream 734 to become "closed". This releases the stream reservation. 736 An endpoint MUST NOT send frames other than than HEADERS or 737 RST_STREAM in this state. 739 A PRIORITY frame MAY be received in this state. Receiving any 740 frame other than RST_STREAM, or PRIORITY MUST be treated as a 741 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 743 reserved (remote): 744 A stream in the "reserved (remote)" state has been reserved by a 745 remote peer. 747 In this state, only the following transitions are possible: 749 * Receiving a HEADERS frame causes the stream to transition to 750 "half closed (local)". 752 * Either endpoint can send a RST_STREAM frame to cause the stream 753 to become "closed". This releases the stream reservation. 755 An endpoint MAY send a PRIORITY frame in this state to 756 reprioritize the reserved stream. An endpoint MUST NOT send any 757 other type of frame other than RST_STREAM or PRIORITY. 759 Receiving any other type of frame other than HEADERS or RST_STREAM 760 MUST be treated as a connection error (Section 5.4.1) of type 761 PROTOCOL_ERROR. 763 open: 764 A stream in the "open" state may be used by both peers to send 765 frames of any type. In this state, sending peers observe 766 advertised stream level flow control limits (Section 5.2). 768 From this state either endpoint can send a frame with an 769 END_STREAM flag set, which causes the stream to transition into 770 one of the "half closed" states: an endpoint sending an END_STREAM 771 flag causes the stream state to become "half closed (local)"; an 772 endpoint receiving an END_STREAM flag causes the stream state to 773 become "half closed (remote)". A HEADERS frame bearing an 774 END_STREAM flag can be followed by CONTINUATION frames. 776 Either endpoint can send a RST_STREAM frame from this state, 777 causing it to transition immediately to "closed". 779 half closed (local): 780 A stream that is in the "half closed (local)" state cannot be used 781 for sending frames. 783 A stream transitions from this state to "closed" when a frame that 784 contains an END_STREAM flag is received, or when either peer sends 785 a RST_STREAM frame. A HEADERS frame bearing an END_STREAM flag 786 can be followed by CONTINUATION frames. 788 A receiver can ignore WINDOW_UPDATE or PRIORITY frames in this 789 state. These frame types might arrive for a short period after a 790 frame bearing the END_STREAM flag is sent. 792 half closed (remote): 793 A stream that is "half closed (remote)" is no longer being used by 794 the peer to send frames. In this state, an endpoint is no longer 795 obligated to maintain a receiver flow control window if it 796 performs flow control. 798 If an endpoint receives additional frames for a stream that is in 799 this state, other than CONTINUATION frames, it MUST respond with a 800 stream error (Section 5.4.2) of type STREAM_CLOSED. 802 A stream can transition from this state to "closed" by sending a 803 frame that contains a END_STREAM flag, or when either peer sends a 804 RST_STREAM frame. 806 closed: 807 The "closed" state is the terminal state. 809 An endpoint MUST NOT send frames on a closed stream. An endpoint 810 that receives any frame after receiving a RST_STREAM MUST treat 811 that as a stream error (Section 5.4.2) of type STREAM_CLOSED. 812 Similarly, an endpoint that receives any frame after receiving a 813 DATA frame with the END_STREAM flag set, or any frame except a 814 CONTINUATION frame after receiving a HEADERS frame with a 815 END_STREAM flag set MUST treat that as a stream error 816 (Section 5.4.2) of type STREAM_CLOSED. 818 WINDOW_UPDATE, PRIORITY, or RST_STREAM frames can be received in 819 this state for a short period after a DATA or HEADERS frame 820 containing an END_STREAM flag is sent. Until the remote peer 821 receives and processes the frame bearing the END_STREAM flag, it 822 might send frame of any of these types. Endpoints MUST ignore 823 WINDOW_UPDATE, PRIORITY, or RST_STREAM frames received in this 824 state, though endpoints MAY choose to treat frames that arrive a 825 significant time after sending END_STREAM as a connection error 826 (Section 5.4.1) of type PROTOCOL_ERROR. 828 If this state is reached as a result of sending a RST_STREAM 829 frame, the peer that receives the RST_STREAM might have already 830 sent - or enqueued for sending - frames on the stream that cannot 831 be withdrawn. An endpoint MUST ignore frames that it receives on 832 closed streams after it has sent a RST_STREAM frame. An endpoint 833 MAY choose to limit the period over which it ignores frames and 834 treat frames that arrive after this time as being in error. 836 Flow controlled frames (i.e., DATA) received after sending 837 RST_STREAM are counted toward the connection flow control window. 838 Even though these frames might be ignored, because they are sent 839 before the sender receives the RST_STREAM, the sender will 840 consider the frames to count against the flow control window. 842 An endpoint might receive a PUSH_PROMISE frame after it sends 843 RST_STREAM. PUSH_PROMISE causes a stream to become "reserved" 844 even if the associated stream has been reset. Therefore, a 845 RST_STREAM is needed to close an unwanted promised streams. 847 In the absence of more specific guidance elsewhere in this document, 848 implementations SHOULD treat the receipt of a message that is not 849 expressly permitted in the description of a state as a connection 850 error (Section 5.4.1) of type PROTOCOL_ERROR. 852 5.1.1. Stream Identifiers 854 Streams are identified with an unsigned 31-bit integer. Streams 855 initiated by a client MUST use odd-numbered stream identifiers; those 856 initiated by the server MUST use even-numbered stream identifiers. A 857 stream identifier of zero (0x0) is used for connection control 858 messages; the stream identifier zero MUST NOT be used to establish a 859 new stream. 861 A stream identifier of one (0x1) is used to respond to the HTTP/1.1 862 request which was specified during Upgrade (see Section 3.2). After 863 the upgrade completes, stream 0x1 is "half closed (local)" to the 864 client. Therefore, stream 0x1 cannot be selected as a new stream 865 identifier by a client that upgrades from HTTP/1.1. 867 The identifier of a newly established stream MUST be numerically 868 greater than all streams that the initiating endpoint has opened or 869 reserved. This governs streams that are opened using a HEADERS frame 870 and streams that are reserved using PUSH_PROMISE. An endpoint that 871 receives an unexpected stream identifier MUST respond with a 872 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 874 The first use of a new stream identifier implicitly closes all 875 streams in the "idle" state that might have been initiated by that 876 peer with a lower-valued stream identifier. For example, if a client 877 sends a HEADERS frame on stream 7 without ever sending a frame on 878 stream 5, then stream 5 transitions to the "closed" state when the 879 first frame for stream 7 is sent or received. 881 Stream identifiers cannot be reused. Long-lived connections can 882 result in endpoint exhausting the available range of stream 883 identifiers. A client that is unable to establish a new stream 884 identifier can establish a new connection for new streams. 886 5.1.2. Stream Concurrency 888 A peer can limit the number of concurrently active streams using the 889 SETTINGS_MAX_CONCURRENT_STREAMS parameters within a SETTINGS frame. 890 The maximum concurrent streams setting is specific to each endpoint 891 and applies only to the peer that receives the setting. That is, 892 clients specify the maximum number of concurrent streams the server 893 can initiate, and servers specify the maximum number of concurrent 894 streams the client can initiate. Endpoints MUST NOT exceed the limit 895 set by their peer. 897 Streams that are in the "open" state, or either of the "half closed" 898 states count toward the maximum number of streams that an endpoint is 899 permitted to open. Streams in any of these three states count toward 900 the limit advertised in the SETTINGS_MAX_CONCURRENT_STREAMS setting 901 (see Section 6.5.2). 903 Streams in either of the "reserved" states do not count as open, even 904 if a small amount of application state is retained to ensure that the 905 promised stream can be successfully used. 907 5.2. Flow Control 909 Using streams for multiplexing introduces contention over use of the 910 TCP connection, resulting in blocked streams. A flow control scheme 911 ensures that streams on the same connection do not destructively 912 interfere with each other. Flow control is used for both individual 913 streams and for the connection as a whole. 915 HTTP/2 provides for flow control through use of the WINDOW_UPDATE 916 frame type. 918 5.2.1. Flow Control Principles 920 HTTP/2 stream flow control aims to allow for future improvements to 921 flow control algorithms without requiring protocol changes. Flow 922 control in HTTP/2 has the following characteristics: 924 1. Flow control is hop-by-hop, not end-to-end. 926 2. Flow control is based on window update frames. Receivers 927 advertise how many bytes they are prepared to receive on a stream 928 and for the entire connection. This is a credit-based scheme. 930 3. Flow control is directional with overall control provided by the 931 receiver. A receiver MAY choose to set any window size that it 932 desires for each stream and for the entire connection. A sender 933 MUST respect flow control limits imposed by a receiver. Clients, 934 servers and intermediaries all independently advertise their flow 935 control window as a receiver and abide by the flow control limits 936 set by their peer when sending. 938 4. The initial value for the flow control window is 65,535 bytes for 939 both new streams and the overall connection. 941 5. The frame type determines whether flow control applies to a 942 frame. Of the frames specified in this document, only DATA 943 frames are subject to flow control; all other frame types do not 944 consume space in the advertised flow control window. This 945 ensures that important control frames are not blocked by flow 946 control. 948 6. Flow control cannot be disabled. 950 7. HTTP/2 standardizes only the format of the WINDOW_UPDATE frame 951 (Section 6.9). This does not stipulate how a receiver decides 952 when to send this frame or the value that it sends. Nor does it 953 specify how a sender chooses to send packets. Implementations 954 are able to select any algorithm that suits their needs. 956 Implementations are also responsible for managing how requests and 957 responses are sent based on priority; choosing how to avoid head of 958 line blocking for requests; and managing the creation of new streams. 959 Algorithm choices for these could interact with any flow control 960 algorithm. 962 5.2.2. Appropriate Use of Flow Control 964 Flow control is defined to protect endpoints that are operating under 965 resource constraints. For example, a proxy needs to share memory 966 between many connections, and also might have a slow upstream 967 connection and a fast downstream one. Flow control addresses cases 968 where the receiver is unable process data on one stream, yet wants to 969 continue to process other streams in the same connection. 971 Deployments that do not require this capability can advertise a flow 972 control of the maximum size, incrementing the available space when 973 new data is received. Sending data is always subject to the flow 974 control window advertised by the receiver. 976 Deployments with constrained resources (for example, memory) MAY 977 employ flow control to limit the amount of memory a peer can consume. 978 Note, however, that this can lead to suboptimal use of available 979 network resources if flow control is enabled without knowledge of the 980 bandwidth-delay product (see [RFC1323]). 982 Even with full awareness of the current bandwidth-delay product, 983 implementation of flow control can be difficult. When using flow 984 control, the receiver MUST read from the TCP receive buffer in a 985 timely fashion. Failure to do so could lead to a deadlock when 986 critical frames, such as WINDOW_UPDATE, are not available to HTTP/2. 987 However, flow control can ensure that constrained resources are 988 protected without any reduction in connection utilization. 990 5.3. Stream priority 992 The endpoint establishing a new stream can assign a priority for the 993 stream. Priority is represented as an unsigned 31-bit integer. 0 994 represents the highest priority and 2^31-1 represents the lowest 995 priority. 997 The purpose of this value is to allow an endpoint to express the 998 relative priority of a stream. An endpoint can use this information 999 to preferentially allocate resources to a stream. Within HTTP/2, 1000 priority can be used to select streams for transmitting frames when 1001 there is limited capacity for sending. For instance, an endpoint 1002 might enqueue frames for all concurrently active streams. As 1003 transmission capacity becomes available, frames from higher priority 1004 streams might be sent before lower priority streams. 1006 Explicitly setting the priority for a stream does not guarantee any 1007 particular processing or transmission order for the stream relative 1008 to any other stream. Nor is there any mechanism provided by which 1009 the initiator of a stream can force or require a receiving endpoint 1010 to process concurrent streams in a particular order. 1012 Unless explicitly specified in the HEADERS frame (Section 6.2) during 1013 stream creation, the default stream priority is 2^30. 1015 Pushed streams (Section 8.2) have a lower priority than their 1016 associated stream. The promised stream inherits the priority value 1017 of the associated stream plus one, up to a maximum of 2^31-1. 1019 5.4. Error Handling 1021 HTTP/2 framing permits two classes of error: 1023 o An error condition that renders the entire connection unusable is 1024 a connection error. 1026 o An error in an individual stream is a stream error. 1028 A list of error codes is included in Section 7. 1030 5.4.1. Connection Error Handling 1032 A connection error is any error which prevents further processing of 1033 the framing layer or which corrupts any connection state. 1035 An endpoint that encounters a connection error SHOULD first send a 1036 GOAWAY frame (Section 6.8) with the stream identifier of the last 1037 stream that it successfully received from its peer. The GOAWAY frame 1038 includes an error code that indicates why the connection is 1039 terminating. After sending the GOAWAY frame, the endpoint MUST close 1040 the TCP connection. 1042 It is possible that the GOAWAY will not be reliably received by the 1043 receiving endpoint. In the event of a connection error, GOAWAY only 1044 provides a best-effort attempt to communicate with the peer about why 1045 the connection is being terminated. 1047 An endpoint can end a connection at any time. In particular, an 1048 endpoint MAY choose to treat a stream error as a connection error. 1049 Endpoints SHOULD send a GOAWAY frame when ending a connection, as 1050 long as circumstances permit it. 1052 5.4.2. Stream Error Handling 1054 A stream error is an error related to a specific stream identifier 1055 that does not affect processing of other streams. 1057 An endpoint that detects a stream error sends a RST_STREAM frame 1058 (Section 6.4) that contains the stream identifier of the stream where 1059 the error occurred. The RST_STREAM frame includes an error code that 1060 indicates the type of error. 1062 A RST_STREAM is the last frame that an endpoint can send on a stream. 1063 The peer that sends the RST_STREAM frame MUST be prepared to receive 1064 any frames that were sent or enqueued for sending by the remote peer. 1065 These frames can be ignored, except where they modify connection 1066 state (such as the state maintained for header compression 1067 (Section 4.3)). 1069 Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame 1070 for any stream. However, an endpoint MAY send additional RST_STREAM 1071 frames if it receives frames on a closed stream after more than a 1072 round-trip time. This behavior is permitted to deal with misbehaving 1073 implementations. 1075 An endpoint MUST NOT send a RST_STREAM in response to an RST_STREAM 1076 frame, to avoid looping. 1078 5.4.3. Connection Termination 1080 If the TCP connection is torn down while streams remain in open or 1081 half closed states, then the endpoint MUST assume that the stream was 1082 abnormally interrupted and could be incomplete. 1084 6. Frame Definitions 1086 This specification defines a number of frame types, each identified 1087 by a unique 8-bit type code. Each frame type serves a distinct 1088 purpose either in the establishment and management of the connection 1089 as a whole, or of individual streams. 1091 The transmission of specific frame types can alter the state of a 1092 connection. If endpoints fail to maintain a synchronized view of the 1093 connection state, successful communication within the connection will 1094 no longer be possible. Therefore, it is important that endpoints 1095 have a shared comprehension of how the state is affected by the use 1096 any given frame. Accordingly, while it is expected that new frame 1097 types will be introduced by extensions to this protocol, only frames 1098 defined by this document are permitted to alter the connection state. 1100 6.1. DATA 1102 DATA frames (type=0x0) convey arbitrary, variable-length sequences of 1103 octets associated with a stream. One or more DATA frames are used, 1104 for instance, to carry HTTP request or response payloads. 1106 DATA frames MAY also contain arbitrary padding. Padding can be added 1107 to DATA frames to hide the size of messages. 1109 0 1 2 3 1110 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1111 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1112 | [Pad High(8)] | [Pad Low (8)] | Data (*) . 1113 +---------------+---------------+-------------------------------+ 1114 . Data (*) ... 1115 +---------------------------------------------------------------+ 1116 | Padding (*) ... 1117 +---------------------------------------------------------------+ 1119 DATA Frame Payload 1121 The DATA frame contains the following fields: 1123 Pad High: An 8-bit field containing an amount of padding in units of 1124 256 octets. This field is optional and is only present if the 1125 PAD_HIGH flag is set. This field, in combination with Pad Low, 1126 determines how much padding there is on a frame. 1128 Pad Low: An 8-bit field containing an amount of padding in units of 1129 single octets. This field is optional and is only present if the 1130 PAD_LOW flag is set. This field, in combination with Pad High, 1131 determines how much padding there is on a frame. 1133 Data: Application data. The amount of data is the remainder of the 1134 frame payload after subtracting the length of the other fields 1135 that are present. 1137 Padding: Padding octets that contain no application semantic value. 1138 Padding octets MUST be set to zero when sending and ignored when 1139 receiving. 1141 The DATA frame defines the following flags: 1143 END_STREAM (0x1): Bit 1 being set indicates that this frame is the 1144 last that the endpoint will send for the identified stream. 1145 Setting this flag causes the stream to enter one of the "half 1146 closed" states or the "closed" state (Section 5.1). 1148 END_SEGMENT (0x2): Bit 2 being set indicates that this frame is the 1149 last for the current segment. Intermediaries MUST NOT coalesce 1150 frames across a segment boundary and MUST preserve segment 1151 boundaries when forwarding frames. 1153 PAD_LOW (0x10): Bit 5 being set indicates that the Pad Low field is 1154 present. 1156 PAD_HIGH (0x20): Bit 6 being set indicates that the Pad High field 1157 is present. This bit MUST NOT be set unless the PAD_LOW flag is 1158 also set. Endpoints that receive a frame with PAD_HIGH set and 1159 PAD_LOW cleared MUST treat this as a connection error 1160 (Section 5.4.1) of type PROTOCOL_ERROR. 1162 DATA frames MUST be associated with a stream. If a DATA frame is 1163 received whose stream identifier field is 0x0, the recipient MUST 1164 respond with a connection error (Section 5.4.1) of type 1165 PROTOCOL_ERROR. 1167 DATA frames are subject to flow control and can only be sent when a 1168 stream is in the "open" or "half closed (remote)" states. Padding is 1169 not excluded from flow control. If a DATA frame is received whose 1170 stream is not in "open" or "half closed (local)" state, the recipient 1171 MUST respond with a stream error (Section 5.4.2) of type 1172 STREAM_CLOSED. 1174 The total number of padding octets is determined by multiplying the 1175 value of the Pad High field by 256 and adding the value of the Pad 1176 Low field. Both Pad High and Pad Low fields assume a value of zero 1177 if absent. If the length of the padding is greater than the length 1178 of the remainder of the frame payload, the recipient MUST treat this 1179 as a connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1181 Note: A frame can be increased in size by one octet by including a 1182 Pad Low field with a value of zero. 1184 Use of padding is a security feature; as such, its use demands some 1185 care, see Section 10.6. 1187 6.2. HEADERS 1189 The HEADERS frame (type=0x1) carries name-value pairs. It is used to 1190 open a stream (Section 5.1). HEADERS frames can be sent on a stream 1191 in the "open" or "half closed (remote)" states. 1193 0 1 2 3 1194 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1195 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1196 | [Pad High(8)] | [Pad Low (8)] |X| [Priority (31)] ... 1197 +---------------+---------------+-+-----------------------------+ 1198 ...[Priority] | Header Block Fragment (*) ... 1199 +-------------------------------+-------------------------------+ 1200 | Header Block Fragment (*) ... 1201 +---------------------------------------------------------------+ 1202 | Padding (*) ... 1203 +---------------------------------------------------------------+ 1205 HEADERS Frame Payload 1207 The HEADERS frame payload has the following fields: 1209 Pad High: Padding size high bits. This field is only present if the 1210 PAD_HIGH flag is set. 1212 Pad Low: Padding size low bits. This field is only present if the 1213 PAD_LOW flag is set. 1215 X: A single reserved bit. This field is optional and is only present 1216 if the PRIORITY flag is set. 1218 Priority: Prioritization information for the stream, see 1219 Section 5.3. This field is optional and is only present if the 1220 PRIORITY flag is set. 1222 Header Block Fragment: A header block fragment (Section 4.3). 1224 Padding: Padding octets. 1226 The HEADERS frame defines the following flags: 1228 END_STREAM (0x1): Bit 1 being set indicates that the header block 1229 (Section 4.3) is the last that the endpoint will send for the 1230 identified stream. Setting this flag causes the stream to enter 1231 one of "half closed" states (Section 5.1). 1233 A HEADERS frame that is followed by CONTINUATION frames carries 1234 the END_STREAM flag that signals the end of a stream. A 1235 CONTINUATION frame cannot be used to terminate a stream. 1237 END_SEGMENT (0x2): Bit 2 being set indicates that this frame is the 1238 last for the current segment. Intermediaries MUST NOT coalesce 1239 frames across a segment boundary and MUST preserve segment 1240 boundaries when forwarding frames. 1242 END_HEADERS (0x4): Bit 3 being set indicates that this frame 1243 contains an entire header block (Section 4.3) and is not followed 1244 by any CONTINUATION frames. 1246 A HEADERS frame without the END_HEADERS flag set MUST be followed 1247 by a CONTINUATION frame for the same stream. A receiver MUST 1248 treat the receipt of any other type of frame or a frame on a 1249 different stream as a connection error (Section 5.4.1) of type 1250 PROTOCOL_ERROR. 1252 PRIORITY (0x8): Bit 4 being set indicates that the first four octets 1253 of this frame contain a single reserved bit and a 31-bit priority; 1254 see Section 5.3. If this bit is not set, the four bytes do not 1255 appear and the frame only contains a header block fragment. 1257 PAD_LOW (0x10): Bit 5 being set indicates that the Pad Low field is 1258 present. 1260 PAD_HIGH (0x20): Bit 6 being set indicates that the Pad High field 1261 is present. This bit MUST NOT be set unless the PAD_LOW flag is 1262 also set. Endpoints that receive a frame with PAD_HIGH set and 1263 PAD_LOW cleared MUST treat this as a connection error 1264 (Section 5.4.1) of type PROTOCOL_ERROR. 1266 The payload of a HEADERS frame contains a header block fragment 1267 (Section 4.3). A header block that does not fit within a HEADERS 1268 frame is continued in a CONTINUATION frame (Section 6.10). 1270 HEADERS frames MUST be associated with a stream. If a HEADERS frame 1271 is received whose stream identifier field is 0x0, the recipient MUST 1272 respond with a connection error (Section 5.4.1) of type 1273 PROTOCOL_ERROR. 1275 The HEADERS frame changes the connection state as described in 1276 Section 4.3. 1278 The HEADERS frame includes optional padding. Padding fields and 1279 flags are identical to those defined for DATA frames (Section 6.1). 1281 6.3. PRIORITY 1283 The PRIORITY frame (type=0x2) specifies the sender-advised priority 1284 of a stream. It can be sent at any time for an existing stream. 1285 This enables reprioritisation of existing streams. 1287 0 1 2 3 1288 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1289 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1290 |X| Priority (31) | 1291 +-+-------------------------------------------------------------+ 1293 PRIORITY Frame Payload 1295 The payload of a PRIORITY frame contains a single reserved bit and a 1296 31-bit priority. 1298 The PRIORITY frame does not define any flags. 1300 The PRIORITY frame is associated with an existing stream. If a 1301 PRIORITY frame is received with a stream identifier of 0x0, the 1302 recipient MUST respond with a connection error (Section 5.4.1) of 1303 type PROTOCOL_ERROR. 1305 The PRIORITY frame can be sent on a stream in any of the "reserved 1306 (remote)", "open", "half-closed (local)", or "half closed (remote)" 1307 states, though it cannot be sent between consecutive frames that 1308 comprise a single header block (Section 4.3). Note that this frame 1309 could arrive after processing or frame sending has completed, which 1310 would cause it to have no effect. For a stream that is in the "half 1311 closed (remote)" state, this frame can only affect processing of the 1312 stream and not frame transmission. 1314 6.4. RST_STREAM 1316 The RST_STREAM frame (type=0x3) allows for abnormal termination of a 1317 stream. When sent by the initiator of a stream, it indicates that 1318 they wish to cancel the stream or that an error condition has 1319 occurred. When sent by the receiver of a stream, it indicates that 1320 either the receiver is rejecting the stream, requesting that the 1321 stream be cancelled or that an error condition has occurred. 1323 0 1 2 3 1324 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1325 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1326 | Error Code (32) | 1327 +---------------------------------------------------------------+ 1328 RST_STREAM Frame Payload 1330 The RST_STREAM frame contains a single unsigned, 32-bit integer 1331 identifying the error code (Section 7). The error code indicates why 1332 the stream is being terminated. 1334 The RST_STREAM frame does not define any flags. 1336 The RST_STREAM frame fully terminates the referenced stream and 1337 causes it to enter the closed state. After receiving a RST_STREAM on 1338 a stream, the receiver MUST NOT send additional frames for that 1339 stream. However, after sending the RST_STREAM, the sending endpoint 1340 MUST be prepared to receive and process additional frames sent on the 1341 stream that might have been sent by the peer prior to the arrival of 1342 the RST_STREAM. 1344 RST_STREAM frames MUST be associated with a stream. If a RST_STREAM 1345 frame is received with a stream identifier of 0x0, the recipient MUST 1346 treat this as a connection error (Section 5.4.1) of type 1347 PROTOCOL_ERROR. 1349 RST_STREAM frames MUST NOT be sent for a stream in the "idle" state. 1350 If a RST_STREAM frame identifying an idle stream is received, the 1351 recipient MUST treat this as a connection error (Section 5.4.1) of 1352 type PROTOCOL_ERROR. 1354 6.5. SETTINGS 1356 The SETTINGS frame (type=0x4) conveys configuration parameters that 1357 affect how endpoints communicate. The parameters are either 1358 constraints on peer behavior or preferences. 1360 Settings are not negotiated. Settings describe characteristics of 1361 the sending peer, which are used by the receiving peer. Different 1362 values for the same setting can be advertised by each peer. For 1363 example, a client might set a high initial flow control window, 1364 whereas a server might set a lower value to conserve resources. 1366 SETTINGS frames MUST be sent at the start of a connection, and MAY be 1367 sent at any other time by either endpoint over the lifetime of the 1368 connection. 1370 Implementations MUST support all of the settings defined by this 1371 specification and MAY support additional settings defined by 1372 extensions to this protocol. Unsupported or unrecognized settings 1373 MUST be ignored. New settings MUST NOT be defined or implemented in 1374 a way that requires endpoints to understand them in order to 1375 communicate successfully. 1377 Each setting in a SETTINGS frame replaces the existing value for that 1378 setting. Settings are processed in the order in which they appear, 1379 and a receiver of a SETTINGS frame does not need to maintain any 1380 state other than the current value of settings. Therefore, the value 1381 of a setting is the last value that is seen by a receiver. This 1382 permits the inclusion of the same settings multiple times in the same 1383 SETTINGS frame, though doing so does nothing other than waste 1384 connection capacity. 1386 The SETTINGS frame defines the following flag: 1388 ACK (0x1): Bit 1 being set indicates that this frame acknowledges 1389 receipt and application of the peer's SETTINGS frame. When this 1390 bit is set, the payload of the SETTINGS frame MUST be empty. 1391 Receipt of a SETTINGS frame with the ACK flag set and a length 1392 field value other than 0 MUST be treated as a connection error 1393 (Section 5.4.1) of type FRAME_SIZE_ERROR. For more info, see 1394 Settings Synchronization (Section 6.5.3). 1396 SETTINGS frames always apply to a connection, never a single stream. 1397 The stream identifier for a settings frame MUST be zero. If an 1398 endpoint receives a SETTINGS frame whose stream identifier field is 1399 anything other than 0x0, the endpoint MUST respond with a connection 1400 error (Section 5.4.1) of type PROTOCOL_ERROR. 1402 The SETTINGS frame affects connection state. A badly formed or 1403 incomplete SETTINGS frame MUST be treated as a connection error 1404 (Section 5.4.1) of type PROTOCOL_ERROR. 1406 6.5.1. Setting Format 1408 The payload of a SETTINGS frame consists of zero or more settings. 1409 Each setting consists of an unsigned 8-bit setting identifier, and an 1410 unsigned 32-bit value. 1412 0 1 2 3 1413 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1414 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1415 |Identifier (8) | Value (32) ... 1416 +---------------+-----------------------------------------------+ 1417 ...Value | 1418 +---------------+ 1420 Setting Format 1422 6.5.2. Defined Settings 1424 The following settings are defined: 1426 SETTINGS_HEADER_TABLE_SIZE (1): Allows the sender to inform the 1427 remote endpoint of the size of the header compression table used 1428 to decode header blocks. The encoder can reduce this size by 1429 using signalling specific to the header compression format inside 1430 a header block. The initial value is 4,096 bytes. 1432 SETTINGS_ENABLE_PUSH (2): This setting can be use to disable server 1433 push (Section 8.2). An endpoint MUST NOT send a PUSH_PROMISE 1434 frame if it receives this setting set to a value of 0. An 1435 endpoint that has set this setting to 0 and had it acknowledged 1436 MUST treat the receipt of a PUSH_PROMISE frame as a connection 1437 error (Section 5.4.1) of type PROTOCOL_ERROR. 1439 The initial value is 1, which indicates that push is permitted. 1440 Any value other than 0 or 1 MUST be treated as a connection error 1441 (Section 5.4.1) of type PROTOCOL_ERROR. 1443 SETTINGS_MAX_CONCURRENT_STREAMS (3): Indicates the maximum number of 1444 concurrent streams that the sender will allow. This limit is 1445 directional: it applies to the number of streams that the sender 1446 permits the receiver to create. Initially there is no limit to 1447 this value. It is recommended that this value be no smaller than 1448 100, so as to not unnecessarily limit parallelism. 1450 A value of 0 for SETTINGS_MAX_CONCURRENT_STREAMS SHOULD NOT be 1451 treated as special by endpoints. A zero value does prevent the 1452 creation of new streams, however this can also happen for any 1453 limit that is exhausted with active streams. Servers SHOULD only 1454 set a zero value for short durations; if a server does not wish to 1455 accept requests, closing the connection could be preferable. 1457 SETTINGS_INITIAL_WINDOW_SIZE (4): Indicates the sender's initial 1458 window size (in bytes) for stream level flow control. 1460 This settings affects the window size of all streams, including 1461 existing streams, see Section 6.9.2. 1463 Values above the maximum flow control window size of 2^31 - 1 MUST 1464 be treated as a connection error (Section 5.4.1) of type 1465 FLOW_CONTROL_ERROR. 1467 An endpoint that receives a SETTINGS frame with any other setting 1468 identifier MUST treat this as a connection error (Section 5.4.1) of 1469 type PROTOCOL_ERROR. 1471 6.5.3. Settings Synchronization 1473 Most values in SETTINGS benefit from or require an understanding of 1474 when the peer has received and applied the changed setting values. 1475 In order to provide such synchronization timepoints, the recipient of 1476 a SETTINGS frame in which the ACK flag is not set MUST apply the 1477 updated settings as soon as possible upon receipt. 1479 The values in the SETTINGS frame MUST be applied in the order they 1480 appear, with no other frame processing between values. Once all 1481 values have been applied, the recipient MUST immediately emit a 1482 SETTINGS frame with the ACK flag set. The sender of altered settings 1483 applies changes upon receiving a SETTINGS frame with the ACK flag 1484 set. 1486 If the sender of a SETTINGS frame does not receive an acknowledgement 1487 within a reasonable amount of time, it MAY issue a connection error 1488 (Section 5.4.1) of type SETTINGS_TIMEOUT. 1490 6.6. PUSH_PROMISE 1492 The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint 1493 in advance of streams the sender intends to initiate. The 1494 PUSH_PROMISE frame includes the unsigned 31-bit identifier of the 1495 stream the endpoint plans to create along with a set of headers that 1496 provide additional context for the stream. Section 8.2 contains a 1497 thorough description of the use of PUSH_PROMISE frames. 1499 PUSH_PROMISE MUST NOT be sent if the SETTINGS_ENABLE_PUSH setting of 1500 the peer endpoint is set to 0. 1502 0 1 2 3 1503 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1504 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1505 |X| Promised-Stream-ID (31) | 1506 +-+-------------------------------------------------------------+ 1507 | Header Block Fragment (*) ... 1508 +---------------------------------------------------------------+ 1510 PUSH_PROMISE Payload Format 1512 The payload of a PUSH_PROMISE includes a "Promised-Stream-ID". This 1513 unsigned 31-bit integer identifies the stream the endpoint intends to 1514 start sending frames for. The promised stream identifier MUST be a 1515 valid choice for the next stream sent by the sender (see new stream 1516 identifier (Section 5.1.1)). 1518 Following the "Promised-Stream-ID" is a header block fragment 1519 (Section 4.3). 1521 PUSH_PROMISE frames MUST be associated with an existing, peer- 1522 initiated stream. If the stream identifier field specifies the value 1523 0x0, a recipient MUST respond with a connection error (Section 5.4.1) 1524 of type PROTOCOL_ERROR. 1526 The PUSH_PROMISE frame defines the following flags: 1528 END_PUSH_PROMISE (0x4): Bit 3 being set indicates that this frame 1529 contains an entire header block (Section 4.3) and is not followed 1530 by any CONTINUATION frames. 1532 A PUSH_PROMISE frame without the END_PUSH_PROMISE flag set MUST be 1533 followed by a CONTINUATION frame for the same stream. A receiver 1534 MUST treat the receipt of any other type of frame or a frame on a 1535 different stream as a connection error (Section 5.4.1) of type 1536 PROTOCOL_ERROR. 1538 Promised streams are not required to be used in order promised. The 1539 PUSH_PROMISE only reserves stream identifiers for later use. 1541 Recipients of PUSH_PROMISE frames can choose to reject promised 1542 streams by returning a RST_STREAM referencing the promised stream 1543 identifier back to the sender of the PUSH_PROMISE. 1545 The PUSH_PROMISE frame modifies the connection state as defined in 1546 Section 4.3. 1548 A PUSH_PROMISE frame modifies the connection state in two ways. The 1549 inclusion of a header block (Section 4.3) potentially modifies the 1550 compression state. PUSH_PROMISE also reserves a stream for later 1551 use, causing the promised stream to enter the "reserved" state. A 1552 sender MUST NOT send a PUSH_PROMISE on a stream unless that stream is 1553 either "open" or "half closed (remote)"; the sender MUST ensure that 1554 the promised stream is a valid choice for a new stream identifier 1555 (Section 5.1.1) (that is, the promised stream MUST be in the "idle" 1556 state). 1558 Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame 1559 causes the stream state to become indeterminate. A receiver MUST 1560 treat the receipt of a PUSH_PROMISE on a stream that is neither 1561 "open" nor "half-closed (local)" as a connection error 1562 (Section 5.4.1) of type PROTOCOL_ERROR. Similarly, a receiver MUST 1563 treat the receipt of a PUSH_PROMISE that promises an illegal stream 1564 identifier (Section 5.1.1) (that is, an identifier for a stream that 1565 is not currently in the "idle" state) as a connection error 1566 (Section 5.4.1) of type PROTOCOL_ERROR. 1568 6.7. PING 1570 The PING frame (type=0x6) is a mechanism for measuring a minimal 1571 round-trip time from the sender, as well as determining whether an 1572 idle connection is still functional. PING frames can be sent from 1573 any endpoint. 1575 0 1 2 3 1576 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1577 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1578 | | 1579 | Opaque Data (64) | 1580 | | 1581 +---------------------------------------------------------------+ 1583 PING Payload Format 1585 In addition to the frame header, PING frames MUST contain 8 octets of 1586 data in the payload. A sender can include any value it chooses and 1587 use those bytes in any fashion. 1589 Receivers of a PING frame that does not include a ACK flag MUST send 1590 a PING frame with the ACK flag set in response, with an identical 1591 payload. PING responses SHOULD be given higher priority than any 1592 other frame. 1594 The PING frame defines the following flags: 1596 ACK (0x1): Bit 1 being set indicates that this PING frame is a PING 1597 response. An endpoint MUST set this flag in PING responses. An 1598 endpoint MUST NOT respond to PING frames containing this flag. 1600 PING frames are not associated with any individual stream. If a PING 1601 frame is received with a stream identifier field value other than 1602 0x0, the recipient MUST respond with a connection error 1603 (Section 5.4.1) of type PROTOCOL_ERROR. 1605 Receipt of a PING frame with a length field value other than 8 MUST 1606 be treated as a connection error (Section 5.4.1) of type 1607 FRAME_SIZE_ERROR. 1609 6.8. GOAWAY 1611 The GOAWAY frame (type=0x7) informs the remote peer to stop creating 1612 streams on this connection. GOAWAY can be sent by either the client 1613 or the server. Once sent, the sender will ignore frames sent on new 1614 streams for the remainder of the connection. Receivers of a GOAWAY 1615 frame MUST NOT open additional streams on the connection, although a 1616 new connection can be established for new streams. The purpose of 1617 this frame is to allow an endpoint to gracefully stop accepting new 1618 streams (perhaps for a reboot or maintenance), while still finishing 1619 processing of previously established streams. 1621 There is an inherent race condition between an endpoint starting new 1622 streams and the remote sending a GOAWAY frame. To deal with this 1623 case, the GOAWAY contains the stream identifier of the last stream 1624 which was processed on the sending endpoint in this connection. If 1625 the receiver of the GOAWAY used streams that are newer than the 1626 indicated stream identifier, they were not processed by the sender 1627 and the receiver may treat the streams as though they had never been 1628 created at all (hence the receiver may want to re-create the streams 1629 later on a new connection). 1631 Endpoints SHOULD always send a GOAWAY frame before closing a 1632 connection so that the remote can know whether a stream has been 1633 partially processed or not. For example, if an HTTP client sends a 1634 POST at the same time that a server closes a connection, the client 1635 cannot know if the server started to process that POST request if the 1636 server does not send a GOAWAY frame to indicate where it stopped 1637 working. An endpoint might choose to close a connection without 1638 sending GOAWAY for misbehaving peers. 1640 After sending a GOAWAY frame, the sender can discard frames for new 1641 streams. However, any frames that alter connection state cannot be 1642 completely ignored. For instance, HEADERS, PUSH_PROMISE and 1643 CONTINUATION frames MUST be minimally processed to ensure a 1644 consistent compression state (see Section 4.3); similarly DATA frames 1645 MUST be counted toward the connection flow control window. 1647 0 1 2 3 1648 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1649 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1650 |X| Last-Stream-ID (31) | 1651 +-+-------------------------------------------------------------+ 1652 | Error Code (32) | 1653 +---------------------------------------------------------------+ 1654 | Additional Debug Data (*) | 1655 +---------------------------------------------------------------+ 1657 GOAWAY Payload Format 1659 The GOAWAY frame does not define any flags. 1661 The GOAWAY frame applies to the connection, not a specific stream. 1662 An endpoint MUST treat a GOAWAY frame with a stream identifier other 1663 than 0x0 as a connection error (Section 5.4.1) of type 1664 PROTOCOL_ERROR. 1666 The last stream identifier in the GOAWAY frame contains the highest 1667 numbered stream identifier for which the sender of the GOAWAY frame 1668 has received frames on and might have taken some action on. All 1669 streams up to and including the identified stream might have been 1670 processed in some way. The last stream identifier is set to 0 if no 1671 streams were processed. 1673 Note: In this case, "processed" means that some data from the 1674 stream was passed to some higher layer of software that might have 1675 taken some action as a result. 1677 If a connection terminates without a GOAWAY frame, this value is 1678 effectively the highest stream identifier. 1680 On streams with lower or equal numbered identifiers that were not 1681 closed completely prior to the connection being closed, re-attempting 1682 requests, transactions, or any protocol activity is not possible 1683 (with the exception of idempotent actions like HTTP GET, PUT, or 1684 DELETE). Any protocol activity that uses higher numbered streams can 1685 be safely retried using a new connection. 1687 Activity on streams numbered lower or equal to the last stream 1688 identifier might still complete successfully. The sender of a GOAWAY 1689 frame might gracefully shut down a connection by sending a GOAWAY 1690 frame, maintaining the connection in an open state until all in- 1691 progress streams complete. 1693 The last stream ID MUST be 0 if no streams were acted upon. 1695 If an endpoint maintains the connection and continues to exchange 1696 frames, ignored frames MUST be counted toward flow control limits 1697 (Section 5.2) or update header compression state (Section 4.3). 1698 Otherwise, flow control or header compression state can become 1699 unsynchronized. 1701 The GOAWAY frame also contains a 32-bit error code (Section 7) that 1702 contains the reason for closing the connection. 1704 Endpoints MAY append opaque data to the payload of any GOAWAY frame. 1705 Additional debug data is intended for diagnostic purposes only and 1706 carries no semantic value. Debug information could contain security- 1707 or privacy-sensitive data. Logged or otherwise persistently stored 1708 debug data MUST have adequate safeguards to prevent unauthorized 1709 access. 1711 6.9. WINDOW_UPDATE 1713 The WINDOW_UPDATE frame (type=0x8) is used to implement flow control. 1715 Flow control operates at two levels: on each individual stream and on 1716 the entire connection. 1718 Both types of flow control are hop by hop; that is, only between the 1719 two endpoints. Intermediaries do not forward WINDOW_UPDATE frames 1720 between dependent connections. However, throttling of data transfer 1721 by any receiver can indirectly cause the propagation of flow control 1722 information toward the original sender. 1724 Flow control only applies to frames that are identified as being 1725 subject to flow control. Of the frame types defined in this 1726 document, this includes only DATA frame. Frames that are exempt from 1727 flow control MUST be accepted and processed, unless the receiver is 1728 unable to assign resources to handling the frame. A receiver MAY 1729 respond with a stream error (Section 5.4.2) or connection error 1730 (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable accept a 1731 frame. 1733 0 1 2 3 1734 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1735 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1736 |X| Window Size Increment (31) | 1737 +-+-------------------------------------------------------------+ 1739 WINDOW_UPDATE Payload Format 1741 The payload of a WINDOW_UPDATE frame is one reserved bit, plus an 1742 unsigned 31-bit integer indicating the number of bytes that the 1743 sender can transmit in addition to the existing flow control window. 1744 The legal range for the increment to the flow control window is 1 to 1745 2^31 - 1 (0x7fffffff) bytes. 1747 The WINDOW_UPDATE frame does not define any flags. 1749 The WINDOW_UPDATE frame can be specific to a stream or to the entire 1750 connection. In the former case, the frame's stream identifier 1751 indicates the affected stream; in the latter, the value "0" indicates 1752 that the entire connection is the subject of the frame. 1754 WINDOW_UPDATE can be sent by a peer that has sent a frame bearing the 1755 END_STREAM flag. This means that a receiver could receive a 1756 WINDOW_UPDATE frame on a "half closed (remote)" or "closed" stream. 1757 A receiver MUST NOT treat this as an error, see Section 5.1. 1759 A receiver that receives a flow controlled frame MUST always account 1760 for its contribution against the connection flow control window, 1761 unless the receiver treats this as a connection error 1762 (Section 5.4.1). This is necessary even if the frame is in error. 1763 Since the sender counts the frame toward the flow control window, if 1764 the receiver does not, the flow control window at sender and receiver 1765 can become different. 1767 6.9.1. The Flow Control Window 1769 Flow control in HTTP/2 is implemented using a window kept by each 1770 sender on every stream. The flow control window is a simple integer 1771 value that indicates how many bytes of data the sender is permitted 1772 to transmit; as such, its size is a measure of the buffering 1773 capability of the receiver. 1775 Two flow control windows are applicable: the stream flow control 1776 window and the connection flow control window. The sender MUST NOT 1777 send a flow controlled frame with a length that exceeds the space 1778 available in either of the flow control windows advertised by the 1779 receiver. Frames with zero length with the END_STREAM flag set (for 1780 example, an empty data frame) MAY be sent if there is no available 1781 space in either flow control window. 1783 For flow control calculations, the 8 byte frame header is not 1784 counted. 1786 After sending a flow controlled frame, the sender reduces the space 1787 available in both windows by the length of the transmitted frame. 1789 The receiver of a frame sends a WINDOW_UPDATE frame as it consumes 1790 data and frees up space in flow control windows. Separate 1791 WINDOW_UPDATE frames are sent for the stream and connection level 1792 flow control windows. 1794 A sender that receives a WINDOW_UPDATE frame updates the 1795 corresponding window by the amount specified in the frame. 1797 A sender MUST NOT allow a flow control window to exceed 2^31 - 1 1798 bytes. If a sender receives a WINDOW_UPDATE that causes a flow 1799 control window to exceed this maximum it MUST terminate either the 1800 stream or the connection, as appropriate. For streams, the sender 1801 sends a RST_STREAM with the error code of FLOW_CONTROL_ERROR code; 1802 for the connection, a GOAWAY frame with a FLOW_CONTROL_ERROR code. 1804 Flow controlled frames from the sender and WINDOW_UPDATE frames from 1805 the receiver are completely asynchronous with respect to each other. 1806 This property allows a receiver to aggressively update the window 1807 size kept by the sender to prevent streams from stalling. 1809 6.9.2. Initial Flow Control Window Size 1811 When a HTTP/2 connection is first established, new streams are 1812 created with an initial flow control window size of 65,535 bytes. 1813 The connection flow control window is 65,535 bytes. Both endpoints 1814 can adjust the initial window size for new streams by including a 1815 value for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS frame that 1816 forms part of the connection header. 1818 Prior to receiving a SETTINGS frame that sets a value for 1819 SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default 1820 initial window size when sending flow controlled frames. Similarly, 1821 the connection flow control window is set to the default initial 1822 window size until a WINDOW_UPDATE frame is received. 1824 A SETTINGS frame can alter the initial flow control window size for 1825 all current streams. When the value of SETTINGS_INITIAL_WINDOW_SIZE 1826 changes, a receiver MUST adjust the size of all stream flow control 1827 windows that it maintains by the difference between the new value and 1828 the old value. A SETTINGS frame cannot alter the connection flow 1829 control window. 1831 An endpoint MUST treat a change to SETTINGS_INITIAL_WINDOW_SIZE that 1832 causes any flow control window to exceed the maximum size as a 1833 connection error (Section 5.4.1) of type FLOW_CONTROL_ERROR. 1835 A change to SETTINGS_INITIAL_WINDOW_SIZE can cause the available 1836 space in a flow control window to become negative. A sender MUST 1837 track the negative flow control window, and MUST NOT send new flow 1838 controlled frames until it receives WINDOW_UPDATE frames that cause 1839 the flow control window to become positive. 1841 For example, if the client sends 60KB immediately on connection 1842 establishment, and the server sets the initial window size to be 1843 16KB, the client will recalculate the available flow control window 1844 to be -44KB on receipt of the SETTINGS frame. The client retains a 1845 negative flow control window until WINDOW_UPDATE frames restore the 1846 window to being positive, after which the client can resume sending. 1848 6.9.3. Reducing the Stream Window Size 1850 A receiver that wishes to use a smaller flow control window than the 1851 current size can send a new SETTINGS frame. However, the receiver 1852 MUST be prepared to receive data that exceeds this window size, since 1853 the sender might send data that exceeds the lower limit prior to 1854 processing the SETTINGS frame. 1856 A receiver has two options for handling streams that exceed flow 1857 control limits: 1859 1. The receiver can immediately send RST_STREAM with 1860 FLOW_CONTROL_ERROR error code for the affected streams. 1862 2. The receiver can accept the streams and tolerate the resulting 1863 head of line blocking, sending WINDOW_UPDATE frames as it 1864 consumes data. 1866 If a receiver decides to accept streams, both sides MUST recompute 1867 the available flow control window based on the initial window size 1868 sent in the SETTINGS. 1870 6.10. CONTINUATION 1872 The CONTINUATION frame (type=0x9) is used to continue a sequence of 1873 header block fragments (Section 4.3). Any number of CONTINUATION 1874 frames can be sent on an existing stream, as long as the preceding 1875 frame on the same stream is one of HEADERS, PUSH_PROMISE or 1876 CONTINUATION without the END_HEADERS or END_PUSH_PROMISE flag set. 1878 0 1 2 3 1879 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1880 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1881 | [Pad High(8)] | [Pad Low (8)] | Header Block Fragment (*) . 1882 +---------------+---------------+-------------------------------+ 1883 | Header Block Fragment (*) ... 1884 +---------------------------------------------------------------+ 1885 | Padding (*) ... 1886 +---------------------------------------------------------------+ 1888 CONTINUATION Frame Payload 1890 The CONTINUATION frame payload has the following fields: 1892 Pad High: Padding size high bits. This field is only present if the 1893 PAD_HIGH flag is set. 1895 Pad Low: Padding size low bits. This field is only present if the 1896 PAD_LOW flag is set. 1898 Header Block Fragment: A header block fragment (Section 4.3). 1900 Padding: Padding octets. 1902 The CONTINUATION frame defines the following flags: 1904 END_HEADERS (0x4): Bit 3 being set indicates that this frame ends a 1905 header block (Section 4.3). 1907 If the END_HEADERS bit is not set, this frame MUST be followed by 1908 another CONTINUATION frame. A receiver MUST treat the receipt of 1909 any other type of frame or a frame on a different stream as a 1910 connection error (Section 5.4.1) of type PROTOCOL_ERROR. 1912 PAD_LOW (0x10): Bit 5 being set indicates that the Pad Low field is 1913 present. 1915 PAD_HIGH (0x20): Bit 6 being set indicates that the Pad High field 1916 is present. This bit MUST NOT be set unless the PAD_LOW flag is 1917 also set. Endpoints that receive a frame with PAD_HIGH set and 1918 PAD_LOW cleared MUST treat this as a connection error 1919 (Section 5.4.1) of type PROTOCOL_ERROR. 1921 The payload of a CONTINUATION frame contains a header block fragment 1922 (Section 4.3). 1924 The CONTINUATION frame changes the connection state as defined in 1925 Section 4.3. 1927 CONTINUATION frames MUST be associated with a stream. If a 1928 CONTINUATION frame is received whose stream identifier field is 0x0, 1929 the recipient MUST respond with a connection error (Section 5.4.1) of 1930 type PROTOCOL_ERROR. 1932 A CONTINUATION frame MUST be preceded by a HEADERS, PUSH_PROMISE or 1933 CONTINUATION frame without the END_HEADERS flag set. A recipient 1934 that observes violation of this rule MUST respond with a connection 1935 error (Section 5.4.1) of type PROTOCOL_ERROR. 1937 The CONTINUATION frame includes optional padding. Padding fields and 1938 flags are identical to those defined for DATA frames (Section 6.1). 1940 7. Error Codes 1942 Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY 1943 frames to convey the reasons for the stream or connection error. 1945 Error codes share a common code space. Some error codes only apply 1946 to specific conditions and have no defined semantics in certain frame 1947 types. 1949 The following error codes are defined: 1951 NO_ERROR (0): The associated condition is not as a result of an 1952 error. For example, a GOAWAY might include this code to indicate 1953 graceful shutdown of a connection. 1955 PROTOCOL_ERROR (1): The endpoint detected an unspecific protocol 1956 error. This error is for use when a more specific error code is 1957 not available. 1959 INTERNAL_ERROR (2): The endpoint encountered an unexpected internal 1960 error. 1962 FLOW_CONTROL_ERROR (3): The endpoint detected that its peer violated 1963 the flow control protocol. 1965 SETTINGS_TIMEOUT (4): The endpoint sent a SETTINGS frame, but did 1966 not receive a response in a timely manner. See Settings 1967 Synchronization (Section 6.5.3). 1969 STREAM_CLOSED (5): The endpoint received a frame after a stream was 1970 half closed. 1972 FRAME_SIZE_ERROR (6): The endpoint received a frame that was larger 1973 than the maximum size that it supports. 1975 REFUSED_STREAM (7): The endpoint refuses the stream prior to 1976 performing any application processing, see Section 8.1.4 for 1977 details. 1979 CANCEL (8): Used by the endpoint to indicate that the stream is no 1980 longer needed. 1982 COMPRESSION_ERROR (9): The endpoint is unable to maintain the 1983 compression context for the connection. 1985 CONNECT_ERROR (10): The connection established in response to a 1986 CONNECT request (Section 8.3) was reset or abnormally closed. 1988 ENHANCE_YOUR_CALM (11): The endpoint detected that its peer is 1989 exhibiting a behavior over a given amount of time that has caused 1990 it to refuse to process further frames. 1992 INADEQUATE_SECURITY (12): The underlying transport has properties 1993 that do not meet the minimum requirements imposed by this document 1994 (see Section 9.2) or the endpoint. 1996 8. HTTP Message Exchanges 1998 HTTP/2 is intended to be as compatible as possible with current web- 1999 based applications. This means that, from the perspective of the 2000 server business logic or application API, the features of HTTP are 2001 unchanged. To achieve this, all of the application request and 2002 response header semantics are preserved, although the syntax of 2003 conveying those semantics has changed. Thus, the rules from HTTP/1.1 2004 ([HTTP-p1], [HTTP-p2], [HTTP-p4], [HTTP-p5], [HTTP-p6], and 2005 [HTTP-p7]) apply with the changes in the sections below. 2007 8.1. HTTP Request/Response Exchange 2009 A client sends an HTTP request on a new stream, using a previously 2010 unused stream identifier (Section 5.1.1). A server sends an HTTP 2011 response on the same stream as the request. 2013 An HTTP request or response each consist of: 2015 1. a HEADERS frame; 2017 2. one contiguous sequence of zero or more CONTINUATION frames; 2019 3. zero or more DATA frames; and 2021 4. optionally, a contiguous sequence that starts with a HEADERS 2022 frame, followed by zero or more CONTINUATION frames. 2024 The last frame in the sequence bears an END_STREAM flag, though a 2025 HEADERS frame bearing the END_STREAM flag can be followed by 2026 CONTINUATION frames that carry any remaining portions of the header 2027 block. 2029 Other frames MAY be interspersed with these frames, but those frames 2030 do not carry HTTP semantics. In particular, HEADERS frames (and any 2031 CONTINUATION frames that follow) other than the first and optional 2032 last frames in this sequence do not carry HTTP semantics. 2034 Trailing header fields are carried in a header block that also 2035 terminates the stream. That is, a sequence starting with a HEADERS 2036 frame, followed by zero or more CONTINUATION frames, where the 2037 HEADERS frame bears an END_STREAM flag. Header blocks after the 2038 first that do not terminate the stream are not part of an HTTP 2039 request or response. 2041 An HTTP request/response exchange fully consumes a single stream. A 2042 request starts with the HEADERS frame that puts the stream into an 2043 "open" state and ends with a frame bearing END_STREAM, which causes 2044 the stream to become "half closed" for the client. A response starts 2045 with a HEADERS frame and ends with a frame bearing END_STREAM, 2046 optionally followed by CONTINUATION frames, which places the stream 2047 in the "closed" state. 2049 8.1.1. Informational Responses 2051 The 1xx series of HTTP response status codes ([HTTP-p2], Section 6.2) 2052 are not supported in HTTP/2. 2054 The most common use case for 1xx is using a Expect header field with 2055 a "100-continue" token (colloquially, "Expect/continue") to indicate 2056 that the client expects a 100 (Continue) non-final response status 2057 code, receipt of which indicates that the client should continue 2058 sending the request body if it has not already done so. 2060 Typically, Expect/continue is used by clients wishing to avoid 2061 sending a large amount of data in a request body, only to have the 2062 request rejected by the origin server. 2064 HTTP/2 does not enable the Expect/continue mechanism; if the server 2065 sends a final status code to reject the request, it can do so without 2066 making the underlying connection unusable. 2068 Note that this means HTTP/2 clients sending requests with bodies may 2069 waste at least one round trip of sent data when the request is 2070 rejected. This can be mitigated by restricting the amount of data 2071 sent for the first round trip by bandwidth-constrained clients, in 2072 anticipation of a final status code. 2074 Other defined 1xx status codes are not applicable to HTTP/2; the 2075 semantics of 101 (Switching Protocols) is better expressed using a 2076 distinct frame type, since they apply to the entire connection, not 2077 just one stream. Likewise, 102 (Processing) is no longer necessary, 2078 because HTTP/2 has a separate means of keeping the connection alive. 2080 This difference between protocol versions necessitates special 2081 handling by intermediaries that translate between them: 2083 o An intermediary that gateways HTTP/1.1 to HTTP/2 MUST generate a 2084 100 (Continue) response if a received request includes and Expect 2085 header field with a "100-continue" token ([HTTP-p2], Section 2086 5.1.1), unless it can immediately generate a final status code. 2087 It MUST NOT forward the "100-continue" expectation in the request 2088 header fields. 2090 o An intermediary that gateways HTTP/2 to HTTP/1.1 MAY add an Expect 2091 header field with a "100-continue" expectation when forwarding a 2092 request that has a body; see [HTTP-p2], Section 5.1.1 for specific 2093 requirements. 2095 o An intermediary that gateways HTTP/2 to HTTP/1.1 MUST discard all 2096 other 1xx informational responses. 2098 8.1.2. Examples 2100 This section shows HTTP/1.1 requests and responses, with 2101 illustrations of equivalent HTTP/2 requests and responses. 2103 An HTTP GET request includes request header fields and no body and is 2104 therefore transmitted as a single contiguous sequence of HEADERS and 2105 CONTINUATION frames containing the serialized block of request header 2106 fields. The last HEADERS frame in the sequence has both the 2107 END_HEADERS and END_STREAM flags set: 2109 GET /resource HTTP/1.1 HEADERS 2110 Host: example.org ==> + END_STREAM 2111 Accept: image/jpeg + END_HEADERS 2112 :method = GET 2113 :scheme = https 2114 :authority = example.org 2115 :path = /resource 2116 accept = image/jpeg 2118 Similarly, a response that includes only response header fields is 2119 transmitted as a sequence of HEADERS frames containing the serialized 2120 block of response header fields. The last HEADERS frame in the 2121 sequence has both the END_HEADERS and END_STREAM flag set: 2123 HTTP/1.1 304 Not Modified HEADERS 2124 ETag: "xyzzy" ===> + END_STREAM 2125 Expires: Thu, 23 Jan ... + END_HEADERS 2126 :status = 304 2127 etag: "xyzzy" 2128 expires: Thu, 23 Jan ... 2130 An HTTP POST request that includes request header fields and payload 2131 data is transmitted as one HEADERS frame, followed by zero or more 2132 CONTINUATION frames containing the request header fields, followed by 2133 one or more DATA frames, with the last CONTINUATION (or HEADERS) 2134 frame having the END_HEADERS flag set and the final DATA frame having 2135 the END_STREAM flag set: 2137 POST /resource HTTP/1.1 HEADERS 2138 Host: example.org ==> - END_STREAM 2139 Content-Type: image/jpeg + END_HEADERS 2140 Content-Length: 123 :method = POST 2141 :scheme = https 2142 {binary data} :authority = example.org 2143 :path = /resource 2144 content-type = image/jpeg 2145 content-length = 123 2147 DATA 2148 + END_STREAM 2149 {binary data} 2151 A response that includes header fields and payload data is 2152 transmitted as a HEADERS frame, followed by zero or more CONTINUATION 2153 frames, followed by one or more DATA frames, with the last DATA frame 2154 in the sequence having the END_STREAM flag set: 2156 HTTP/1.1 200 OK HEADERS 2157 Content-Type: image/jpeg ==> - END_STREAM 2158 Content-Length: 123 + END_HEADERS 2159 :status = 200 2160 {binary data} content-type = image/jpeg 2161 content-length = 123 2163 DATA 2164 + END_STREAM 2165 {binary data} 2167 Trailing header fields are sent as a header block after both the 2168 request or response header block and all the DATA frames have been 2169 sent. The sequence of HEADERS/CONTINUATION frames that bears the 2170 trailers includes a terminal frame that has both END_HEADERS and 2171 END_STREAM flags set. 2173 HTTP/1.1 200 OK HEADERS 2174 Content-Type: image/jpeg ===> - END_STREAM 2175 Transfer-Encoding: chunked + END_HEADERS 2176 TE: trailers :status = 200 2177 content-length = 123 2178 123 content-type = image/jpeg 2179 {binary data} 2180 0 DATA 2181 Foo: bar - END_STREAM 2182 {binary data} 2184 HEADERS 2185 + END_STREAM 2186 + END_HEADERS 2187 foo: bar 2189 8.1.3. HTTP Header Fields 2191 HTTP/2 request and response header fields carry information as a 2192 series of key-value pairs. This includes the target URI for the 2193 request, the status code for the response, as well as HTTP header 2194 fields. 2196 HTTP header field names are strings of ASCII characters that are 2197 compared in a case-insensitive fashion. Header field names MUST be 2198 converted to lowercase prior to their encoding in HTTP/2. A request 2199 or response containing uppercase header field names MUST be treated 2200 as malformed (Section 8.1.3.5). 2202 HTTP/2 does not use the Connection header field to indicate "hop-by- 2203 hop" header fields; in this protocol, connection-specific metadata is 2204 conveyed by other means. As such, a HTTP/2 message containing 2205 Connection MUST be treated as malformed (Section 8.1.3.5). 2207 This means that an intermediary transforming a HTTP/1.x message to 2208 HTTP/2 will need to remove any header fields nominated by the 2209 Connection header field, along with the Connection header field 2210 itself. Such intermediaries SHOULD also remove other connection- 2211 specific header fields, such as Keep-Alive, Proxy-Connection, 2212 Transfer-Encoding and Upgrade, even if they are not nominated by 2213 Connection. 2215 One exception to this is the TE header field, which MAY be present in 2216 a HTTP/2 request, but when it is MUST NOT contain any value other 2217 than "trailers". 2219 Note: HTTP/2 purposefully does not support upgrade to another 2220 protocol. The handshake methods described in Section 3 are 2221 believed sufficient to negotiate the use of alternative protocols. 2223 8.1.3.1. Request Header Fields 2225 HTTP/2 defines a number of header fields starting with a colon ':' 2226 character that carry information about the request target: 2228 o The ":method" header field includes the HTTP method ([HTTP-p2], 2229 Section 4). 2231 o The ":scheme" header field includes the scheme portion of the 2232 target URI ([RFC3986], Section 3.1). 2234 o The ":authority" header field includes the authority portion of 2235 the target URI ([RFC3986], Section 3.2). The authority MUST NOT 2236 include the deprecated "userinfo" subcomponent for "http:" or 2237 "https:" URIs. 2239 To ensure that the HTTP/1.1 request line can be reproduced 2240 accurately, this header field MUST be omitted when translating 2241 from an HTTP/1.1 request that has a request target in origin or 2242 asterisk form (see [HTTP-p1], Section 5.3). Clients that generate 2243 HTTP/2 requests directly SHOULD instead omit the "Host" header 2244 field. An intermediary that converts a request to HTTP/1.1 MUST 2245 create a "Host" header field if one is not present in a request by 2246 copying the value of the ":authority" header field. 2248 o The ":path" header field includes the path and query parts of the 2249 target URI (the "path-absolute" production from [RFC3986] and 2250 optionally a '?' character followed by the "query" production, see 2251 [RFC3986], Section 3.3 and [RFC3986], Section 3.4). This field 2252 MUST NOT be empty; URIs that do not contain a path component MUST 2253 include a value of '/', unless the request is an OPTIONS request 2254 in asterisk form, in which case the ":path" header field MUST 2255 include '*'. 2257 All HTTP/2 requests MUST include exactly one valid value for the 2258 ":method", ":scheme", and ":path" header fields, unless this is a 2259 CONNECT request (Section 8.3). An HTTP request that omits mandatory 2260 header fields is malformed (Section 8.1.3.5). 2262 Header field names that start with a colon are only valid in the 2263 HTTP/2 context. These are not HTTP header fields. Implementations 2264 MUST NOT generate header fields that start with a colon, but they 2265 MUST ignore any header field that starts with a colon. In 2266 particular, header fields with names starting with a colon MUST NOT 2267 be exposed as HTTP header fields. 2269 HTTP/2 does not define a way to carry the version identifier that is 2270 included in the HTTP/1.1 request line. 2272 8.1.3.2. Response Header Fields 2274 A single ":status" header field is defined that carries the HTTP 2275 status code field (see [HTTP-p2], Section 6). This header field MUST 2276 be included in all responses, otherwise the response is malformed 2277 (Section 8.1.3.5). 2279 HTTP/2 does not define a way to carry the version or reason phrase 2280 that is included in an HTTP/1.1 status line. 2282 8.1.3.3. Header Field Ordering 2284 HTTP Header Compression [COMPRESSION] does not preserve the order of 2285 header fields. The relative order of header fields with different 2286 names is not important. However, the same header field can be 2287 repeated to form a comma-separated list (see [HTTP-p1], Section 2288 3.2.2), where the relative order of header field values is 2289 significant. This repetition can occur either as a single header 2290 field with a comma-separated list of values, or as several header 2291 fields with a single value, or any combination thereof. 2293 To preserve the order of a comma-separated list, the ordered values 2294 for a single header field name appearing in different header fields 2295 are concatenated into a single value. A zero-valued octet (0x0) is 2296 used to delimit multiple values. 2298 After decompression, header fields that have values containing zero 2299 octets (0x0) MUST be split into multiple header fields before being 2300 processed. 2302 Header fields containing multiple values MUST be concatenated into a 2303 single value unless the ordering of that header field is known to be 2304 not significant. 2306 The special case of "set-cookie" - which does not form a comma- 2307 separated list, but can have multiple values - does not depend on 2308 ordering. The "set-cookie" header field MAY be encoded as multiple 2309 header field values, or as a single concatenated value. 2311 8.1.3.4. Compressing the Cookie Header Field 2313 The Cookie header field [COOKIE] can carry a significant amount of 2314 redundant data. 2316 The Cookie header field uses a semi-colon (";") to delimit cookie- 2317 pairs (or "crumbs"). This header field doesn't follow the list 2318 construction rules in HTTP (see [HTTP-p1], Section 3.2.2), which 2319 prevents cookie-pairs from being separated into different name-value 2320 pairs. This can significantly reduce compression efficiency as 2321 individual cookie-pairs are updated. 2323 To allow for better compression efficiency, the Cookie header field 2324 MAY be split into separate header fields, each with one or more 2325 cookie-pairs. If there are multiple Cookie header fields after 2326 decompression, these MUST be concatenated into a single octet string 2327 using the two octet delimiter of 0x3B, 0x20 (the ASCII string "; "). 2329 The Cookie header field MAY be split using a zero octet (0x0), as 2330 defined in Section 8.1.3.3. When decoding, zero octets MUST be 2331 replaced with the cookie delimiter ("; "). 2333 8.1.3.5. Malformed Requests and Responses 2335 A malformed request or response is one that uses a valid sequence of 2336 HTTP/2 frames, but is otherwise invalid due to the presence of 2337 prohibited header fields, the absence of mandatory header fields, or 2338 the inclusion of uppercase header field names. 2340 A request or response that includes an entity body can include a 2341 "content-length" header field. A request or response is also 2342 malformed if the value of a "content-length" header field does not 2343 equal the sum of the DATA frame payload lengths that form the body. 2345 Intermediaries that process HTTP requests or responses (i.e., all 2346 intermediaries other than those acting as tunnels) MUST NOT forward a 2347 malformed request or response. 2349 Implementations that detect malformed requests or responses need to 2350 ensure that the stream ends. For malformed requests, a server MAY 2351 send an HTTP response prior to closing or resetting the stream. 2352 Clients MUST NOT accept a malformed response. 2354 8.1.4. Request Reliability Mechanisms in HTTP/2 2356 In HTTP/1.1, an HTTP client is unable to retry a non-idempotent 2357 request when an error occurs, because there is no means to determine 2358 the nature of the error. It is possible that some server processing 2359 occurred prior to the error, which could result in undesirable 2360 effects if the request were reattempted. 2362 HTTP/2 provides two mechanisms for providing a guarantee to a client 2363 that a request has not been processed: 2365 o The GOAWAY frame indicates the highest stream number that might 2366 have been processed. Requests on streams with higher numbers are 2367 therefore guaranteed to be safe to retry. 2369 o The REFUSED_STREAM error code can be included in a RST_STREAM 2370 frame to indicate that the stream is being closed prior to any 2371 processing having occurred. Any request that was sent on the 2372 reset stream can be safely retried. 2374 Clients MUST NOT treat requests that have not been processed as 2375 having failed. Clients MAY automatically retry these requests, 2376 including those with non-idempotent methods. 2378 A server MUST NOT indicate that a stream has not been processed 2379 unless it can guarantee that fact. If frames that are on a stream 2380 are passed to the application layer for any stream, then 2381 REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame 2382 MUST include a stream identifier that is greater than or equal to the 2383 given stream identifier. 2385 In addition to these mechanisms, the PING frame provides a way for a 2386 client to easily test a connection. Connections that remain idle can 2387 become broken as some middleboxes (for instance, network address 2388 translators, or load balancers) silently discard connection bindings. 2389 The PING frame allows a client to safely test whether a connection is 2390 still active without sending a request. 2392 8.2. Server Push 2394 HTTP/2 enables a server to pre-emptively send (or "push") multiple 2395 associated resources to a client in response to a single request. 2396 This feature becomes particularly helpful when the server knows the 2397 client will need to have those resources available in order to fully 2398 process the originally requested resource. 2400 Pushing additional resources is optional, and is negotiated only 2401 between individual endpoints. The SETTINGS_ENABLE_PUSH setting can 2402 be set to 0 to indicate that server push is disabled. Even if 2403 enabled, an intermediary could receive pushed resources from the 2404 server but could choose not to forward those on to the client. How 2405 to make use of the pushed resources is up to that intermediary. 2406 Equally, the intermediary might choose to push additional resources 2407 to the client, without any action taken by the server. 2409 A client cannot push resources. Clients and servers MUST operate as 2410 though the server has disabled PUSH_PROMISE by setting the 2411 SETTINGS_ENABLE_PUSH to 0. As a consequence, servers MUST treat the 2412 receipt of a PUSH_PROMISE frame as a connection error 2413 (Section 5.4.1). Clients MUST reject any attempt to change this 2414 setting by treating the message as a connection error (Section 5.4.1) 2415 of type PROTOCOL_ERROR. 2417 A server can only push requests that are safe (see [HTTP-p2], Section 2418 4.2.1), cacheable (see [HTTP-p6], Section 3) and do not include a 2419 request body. 2421 8.2.1. Push Requests 2423 Server push is semantically equivalent to a server responding to a 2424 request. The PUSH_PROMISE frame, or frames, sent by the server 2425 includes a header block that contains a complete set of request 2426 header fields that the server attributes to the request. It is not 2427 possible to push a response to a request that includes a request 2428 body. 2430 Pushed resources are always associated with an explicit request from 2431 a client. The PUSH_PROMISE frames sent by the server are sent on the 2432 stream created for the original request. The PUSH_PROMISE frame 2433 includes a promised stream identifier, chosen from the stream 2434 identifiers available to the server (see Section 5.1.1). 2436 The header fields in PUSH_PROMISE and any subsequent CONTINUATION 2437 frames MUST be a valid and complete set of request header fields 2438 (Section 8.1.3.1). The server MUST include a method in the ":method" 2439 header field that is safe and cacheable. If a client receives a 2440 PUSH_PROMISE that does not include a complete and valid set of header 2441 fields, or the ":method" header field identifies a method that is not 2442 safe, it MUST respond with a stream error (Section 5.4.2) of type 2443 PROTOCOL_ERROR. 2445 The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to 2446 sending any frames that reference the promised resources. This 2447 avoids a race where clients issue requests for resources prior to 2448 receiving any PUSH_PROMISE frames. 2450 For example, if the server receives a request for a document 2451 containing embedded links to multiple image files, and the server 2452 chooses to push those additional images to the client, sending push 2453 promises before the DATA frames that contain the image links ensures 2454 that the client is able to see the promises before discovering the 2455 resources. Similarly, if the server pushes resources referenced by 2456 the header block (for instance, in Link header fields), sending the 2457 push promises before sending the header block ensures that clients do 2458 not request those resources. 2460 PUSH_PROMISE frames MUST NOT be sent by the client. PUSH_PROMISE 2461 frames can be sent by the server on any stream that was opened by the 2462 client. They MUST be sent on a stream that is in either the "open" 2463 or "half closed (remote)" state to the server. PUSH_PROMISE frames 2464 are interspersed with the frames that comprise a response, though 2465 they cannot be interspersed with HEADERS and CONTINUATION frames that 2466 comprise a single header block. 2468 8.2.2. Push Responses 2470 After sending the PUSH_PROMISE frame, the server can begin delivering 2471 the pushed resource as a response (Section 8.1.3.2) on a server- 2472 initiated stream that uses the promised stream identifier. The 2473 server uses this stream to transmit an HTTP response, using the same 2474 sequence of frames as defined in Section 8.1. This stream becomes 2475 "half closed" to the client (Section 5.1) after the initial HEADERS 2476 frame is sent. 2478 Once a client receives a PUSH_PROMISE frame and chooses to accept the 2479 pushed resource, the client SHOULD NOT issue any requests for the 2480 promised resource until after the promised stream has closed. 2482 If the client determines, for any reason, that it does not wish to 2483 receive the pushed resource from the server, or if the server takes 2484 too long to begin sending the promised resource, the client can send 2485 an RST_STREAM frame, using either the CANCEL or REFUSED_STREAM codes, 2486 and referencing the pushed stream's identifier. 2488 A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit 2489 the number of resources that can be concurrently pushed by a server. 2490 Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero disables 2491 server push by preventing the server from creating the necessary 2492 streams. This does not prohibit a server from sending PUSH_PROMISE 2493 frames; clients need to reset any promised streams that are not 2494 wanted. 2496 Clients receiving a pushed response MUST validate that the server is 2497 authorized to push the resource using the same-origin policy 2498 ([RFC6454], Section 3). For example, a HTTP/2 connection to 2499 "example.com" is generally [[anchor15: Ed: weaselly use of 2500 "generally", needs better definition]] not permitted to push a 2501 response for "www.example.org". 2503 8.3. The CONNECT Method 2505 The HTTP pseudo-method CONNECT ([HTTP-p2], Section 4.3.6) is used to 2506 convert an HTTP/1.1 connection into a tunnel to a remote host. 2507 CONNECT is primarily used with HTTP proxies to establish a TLS 2508 session with a server for the purposes of interacting with "https" 2509 resources. 2511 In HTTP/2, the CONNECT method is used to establish a tunnel over a 2512 single HTTP/2 stream to a remote host. The HTTP header field mapping 2513 works as mostly as defined in Request Header Fields 2514 (Section 8.1.3.1), with a few differences. Specifically: 2516 o The ":method" header field is set to "CONNECT". 2518 o The ":scheme" and ":path" header fields MUST be omitted. 2520 o The ":authority" header field contains the host and port to 2521 connect to (equivalent to the authority-form of the request-target 2522 of CONNECT requests, see [HTTP-p1], Section 5.3). 2524 A proxy that supports CONNECT, establishes a TCP connection [TCP] to 2525 the server identified in the ":authority" header field. Once this 2526 connection is successfully established, the proxy sends a HEADERS 2527 frame containing a 2xx series status code, as defined in [HTTP-p2], 2528 Section 4.3.6. 2530 After the initial HEADERS frame sent by each peer, all subsequent 2531 DATA frames correspond to data sent on the TCP connection. The 2532 payload of any DATA frames sent by the client are transmitted by the 2533 proxy to the TCP server; data received from the TCP server is 2534 assembled into DATA frames by the proxy. Frame types other than DATA 2535 or stream management frames (RST_STREAM, WINDOW_UPDATE, and PRIORITY) 2536 MUST NOT be sent on a connected stream, and MUST be treated as a 2537 stream error (Section 5.4.2) if received. 2539 The TCP connection can be closed by either peer. The END_STREAM flag 2540 on a DATA frame is treated as being equivalent to the TCP FIN bit. A 2541 client is expected to send a DATA frame with the END_STREAM flag set 2542 after receiving a frame bearing the END_STREAM flag. A proxy that 2543 receives a DATA frame with the END_STREAM flag set sends the attached 2544 data with the FIN bit set on the last TCP segment. A proxy that 2545 receives a TCP segment with the FIN bit set sends a DATA frame with 2546 the END_STREAM flag set. Note that the final TCP segment or DATA 2547 frame could be empty. 2549 A TCP connection error is signaled with RST_STREAM. A proxy treats 2550 any error in the TCP connection, which includes receiving a TCP 2551 segment with the RST bit set, as a stream error (Section 5.4.2) of 2552 type CONNECT_ERROR. Correspondingly, a proxy MUST send a TCP segment 2553 with the RST bit set if it detects an error with the stream or the 2554 HTTP/2 connection. 2556 9. Additional HTTP Requirements/Considerations 2558 This section outlines attributes of the HTTP protocol that improve 2559 interoperability, reduce exposure to known security vulnerabilities, 2560 or reduce the potential for implementation variation. 2562 9.1. Connection Management 2564 HTTP/2 connections are persistent. For best performance, it is 2565 expected clients will not close connections until it is determined 2566 that no further communication with a server is necessary (for 2567 example, when a user navigates away from a particular web page), or 2568 until the server closes the connection. 2570 Clients SHOULD NOT open more than one HTTP/2 connection to a given 2571 origin ([RFC6454]) concurrently. A client can create additional 2572 connections as replacements, either to replace connections that are 2573 near to exhausting the available stream identifiers (Section 5.1.1), 2574 or to replace connections that have encountered errors 2575 (Section 5.4.1). 2577 Clients MAY use a single connection for more than one origin when 2578 each origin's hostname resolves to the same IP address, and they 2579 share the same port. For "https" scheme origins, the server's 2580 certificate MUST be valid for each origin's hostname. The 2581 considerations in RFC 6125 [RFC6125] for verification of identity 2582 apply. 2584 Servers are encouraged to maintain open connections for as long as 2585 possible, but are permitted to terminate idle connections if 2586 necessary. When either endpoint chooses to close the transport-level 2587 TCP connection, the terminating endpoint SHOULD first send a GOAWAY 2588 (Section 6.8) frame so that both endpoints can reliably determine 2589 whether previously sent frames have been processed and gracefully 2590 complete or terminate any necessary remaining tasks. 2592 9.2. Use of TLS Features 2594 Implementations of HTTP/2 MUST support TLS 1.2 [TLS12]. The general 2595 TLS usage guidance in [TLSBCP] SHOULD be followed, with some 2596 additional restrictions that are specific to HTTP/2. 2598 The TLS implementation MUST support the Server Name Indication (SNI) 2599 [TLS-EXT] extension to TLS. HTTP/2 clients MUST indicate the target 2600 domain name when negotiating TLS. 2602 The TLS implementation MUST disable compression. TLS compression can 2603 lead to the exposure of information that would not otherwise be 2604 revealed [RFC3749]. Generic compression is unnecessary since HTTP/2 2605 provides compression features that are more aware of context and 2606 therefore likely to be more appropriate for use for performance, 2607 security or other reasons. 2609 Implementations MUST negotiate ephemeral cipher suites (DHE or ECDHE) 2610 with a minimum size of 2048 bits (DHE) or security level of 128 bits 2611 (ECDHE). Clients MUST accept DHE sizes of up to 4096 bits. 2613 An implementation that negotiates a TLS connection that does not meet 2614 the requirements in this section, or any policy-based constraints, 2615 SHOULD NOT negotiate HTTP/2. Removing HTTP/2 protocols from 2616 consideration could result in the removal of all protocols from the 2617 set of protocols offered by the client. This causes protocol 2618 negotiation failure, as described in Section 3.2 of [TLSALPN]. 2620 Due to implementation limitations, it might not be possible to fail 2621 TLS negotiation based on all of these requirements. An endpoint MUST 2622 terminate a HTTP/2 connection that is opened on a TLS session that 2623 does not meet these minimum requirements with a connection error 2624 (Section 5.4.1) of type INADEQUATE_SECURITY. 2626 Implementations are encouraged not to negotiate TLS cipher suites 2627 with known vulnerabilities, such as [RC4]. 2629 9.3. GZip Content-Encoding 2631 Clients MUST support gzip compression for HTTP response bodies. 2632 Regardless of the value of the accept-encoding header field, a server 2633 MAY send responses with gzip or deflate encoding. A compressed 2634 response MUST still bear an appropriate content-encoding header 2635 field. 2637 10. Security Considerations 2639 10.1. Server Authority and Same-Origin 2641 This specification uses the same-origin policy ([RFC6454], Section 3) 2642 to determine whether an origin server is permitted to provide 2643 content. 2645 A server that is contacted using TLS is authenticated based on the 2646 certificate that it offers in the TLS handshake (see [RFC2818], 2647 Section 3). A server is considered authoritative for an "https" 2648 resource if it has been successfully authenticated for the domain 2649 part of the origin of the resource that it is providing. 2651 A server is considered authoritative for an "http" resource if the 2652 connection is established to a resolved IP address for the domain in 2653 the origin of the resource. 2655 A client MUST NOT use, in any way, resources provided by a server 2656 that is not authoritative for those resources. 2658 10.2. Cross-Protocol Attacks 2660 When using TLS, we believe that HTTP/2 introduces no new cross- 2661 protocol attacks. TLS encrypts the contents of all transmission 2662 (except the handshake itself), making it difficult for attackers to 2663 control the data which could be used in a cross-protocol attack. 2664 [[anchor19: Issue: This is no longer true]] 2666 10.3. Intermediary Encapsulation Attacks 2668 HTTP/2 header field names and values are encoded as sequences of 2669 octets with a length prefix. This enables HTTP/2 to carry any string 2670 of octets as the name or value of a header field. An intermediary 2671 that translates HTTP/2 requests or responses into HTTP/1.1 directly 2672 could permit the creation of corrupted HTTP/1.1 messages. An 2673 attacker might exploit this behavior to cause the intermediary to 2674 create HTTP/1.1 messages with illegal header fields, extra header 2675 fields, or even new messages that are entirely falsified. 2677 An intermediary that performs translation into HTTP/1.1 cannot alter 2678 the semantics of requests or responses. In particular, header field 2679 names or values that contain characters not permitted by HTTP/1.1, 2680 including carriage return (U+000D) or line feed (U+000A) MUST NOT be 2681 translated verbatim, as stipulated in [HTTP-p1], Section 3.2.4. 2683 Translation from HTTP/1.x to HTTP/2 does not produce the same 2684 opportunity to an attacker. Intermediaries that perform translation 2685 to HTTP/2 MUST remove any instances of the "obs-fold" production from 2686 header field values. 2688 10.4. Cacheability of Pushed Resources 2690 Pushed resources are responses without an explicit request from the 2691 client. Request header fields are provided by the server in the 2692 PUSH_PROMISE frame. These header fields are provided so that 2693 existing HTTP semantics can be applied. 2695 Caching resources that are pushed is possible based on the guidance 2696 provided by the origin server in the Cache-Control header field. 2697 However, this can cause issues if a single server hosts more than one 2698 tenant. For example, a server might offer multiple users each a 2699 small portion of its URI space. 2701 Where multiple tenants share space on the same server, that server 2702 MUST ensure that tenants are not able to push representations of 2703 resources that they do not have authority over. Failure to enforce 2704 this would allow a tenant to provide a representation that would be 2705 served out of cache, overriding the actual representation that the 2706 authoritative tenant provides. 2708 Pushed resources for which an origin server is not authoritative are 2709 never cached or used. 2711 10.5. Denial of Service Considerations 2713 An HTTP/2 connection can demand a greater commitment of resources to 2714 operate than a HTTP/1.1 connection. The use of header compression 2715 and flow control depend on a commitment of resources for storing a 2716 greater amount of state. Settings for these features ensure that 2717 memory commitments for these features are strictly bounded. 2718 Processing capacity cannot be guarded in the same fashion. 2720 The SETTINGS frame can be abused to cause a peer to expend additional 2721 processing time. This might be done by pointlessly changing 2722 settings, setting multiple undefined settings, or changing the same 2723 setting multiple times in the same frame. Similarly, WINDOW_UPDATE 2724 or PRIORITY frames can be abused to cause an unnecessary waste of 2725 resources. 2727 Large numbers of small or empty frames can be abused to cause a peer 2728 to expend time processing frame headers. Note however that some uses 2729 are entirely legitimate, such as the sending of an empty DATA frame 2730 to end a stream. 2732 Header compression also offers some opportunities to waste processing 2733 resources, see [COMPRESSION] for more details on potential abuses. 2735 Limits in settings cannot be reduced instantaneously, which leaves an 2736 endpoint exposed to behavior from a peer that could exceed the new 2737 limits. In particular, immediately after establishing a connection, 2738 limits set by a server are not known to clients and could be exceeded 2739 without being an obvious protocol violation. 2741 In all these cases, there are legitimate reasons to use these 2742 protocol mechanisms. These features become a burden only when they 2743 are used unnecessarily or to excess. 2745 An endpoint that doesn't monitor this behavior exposes itself to a 2746 risk of denial of service attack. Implementations SHOULD track the 2747 use of these features and set limits on their use. An endpoint MAY 2748 treat activity that is suspicious as a connection error 2749 (Section 5.4.1) of type ENHANCE_YOUR_CALM. 2751 10.6. Use of Padding 2753 Padding within HTTP/2 is not intended as a replacement for general 2754 purpose padding, such as might be provided by TLS [TLS12]. Redundant 2755 padding could even be counterproductive. Correct application can 2756 depend on having specific knowledge of the data that is being padded. 2758 To mitigate attacks that rely on compression, disabling compression 2759 might be preferable to padding as a countermeasure. 2761 Padding can be used to obscure the exact size of frame content. 2762 Padding is provided to mitigate specific attacks within HTTP. For 2763 example, attacks where compressed content includes both attacker- 2764 controlled plaintext and secret data (see for example, [BREACH]). 2766 Use of padding can result in less protection than might seem 2767 immediately obvious. At best, padding only makes it more difficult 2768 for an attacker to infer length information by increasing the number 2769 of frames an attacker has to observe. Incorrectly implemented 2770 padding schemes can be easily defeated. In particular, randomized 2771 padding with a predictable distribution provides very little 2772 protection; or padding payloads to a fixed size exposes information 2773 as payload sizes cross the fixed size boundary, which could be 2774 possible if an attacker can control plaintext. 2776 Intermediaries SHOULD NOT remove padding; though an intermediary 2777 could remove padding and add differing amounts if the intent is to 2778 improve the protections padding affords. 2780 11. Privacy Considerations 2782 HTTP/2 aims to keep connections open longer between clients and 2783 servers in order to reduce the latency when a user makes a request. 2784 The maintenance of these connections over time could be used to 2785 expose private information. For example, a user using a browser 2786 hours after the previous user stopped using that browser may be able 2787 to learn about what the previous user was doing. This is a problem 2788 with HTTP in its current form as well, however the short lived 2789 connections make it less of a risk. 2791 12. IANA Considerations 2793 A string for identifying HTTP/2 is entered into the "Application 2794 Layer Protocol Negotiation (ALPN) Protocol IDs" registry established 2795 in [TLSALPN]. 2797 This document establishes registries for error codes. This new 2798 registry is entered into a new "Hypertext Transfer Protocol (HTTP) 2 2799 Parameters" section. 2801 This document registers the "HTTP2-Settings" header field for use in 2802 HTTP. 2804 This document registers the "PRI" method for use in HTTP, to avoid 2805 collisions with the connection header (Section 3.5). 2807 12.1. Registration of HTTP/2 Identification String 2809 This document creates a registration for the identification of HTTP/2 2810 in the "Application Layer Protocol Negotiation (ALPN) Protocol IDs" 2811 registry established in [TLSALPN]. 2813 Protocol: HTTP/2 2815 Identification Sequence: 0x68 0x32 ("h2") 2817 Specification: This document (RFCXXXX) 2819 12.2. Error Code Registry 2821 This document establishes a registry for HTTP/2 error codes. The 2822 "HTTP/2 Error Code" registry manages a 32-bit space. The "HTTP/2 2823 Error Code" registry operates under the "Expert Review" policy 2824 [RFC5226]. 2826 Registrations for error codes are required to include a description 2827 of the error code. An expert reviewer is advised to examine new 2828 registrations for possible duplication with existing error codes. 2829 Use of existing registrations is to be encouraged, but not mandated. 2831 New registrations are advised to provide the following information: 2833 Error Code: The 32-bit error code value. 2835 Name: A name for the error code. Specifying an error code name is 2836 optional. 2838 Description: A description of the conditions where the error code is 2839 applicable. 2841 Specification: An optional reference for a specification that 2842 defines the error code. 2844 An initial set of error code registrations can be found in Section 7. 2846 12.3. HTTP2-Settings Header Field Registration 2848 This section registers the "HTTP2-Settings" header field in the 2849 Permanent Message Header Field Registry [BCP90]. 2851 Header field name: HTTP2-Settings 2853 Applicable protocol: http 2855 Status: standard 2857 Author/Change controller: IETF 2859 Specification document(s): Section 3.2.1 of this document 2861 Related information: This header field is only used by an HTTP/2 2862 client for Upgrade-based negotiation. 2864 12.4. PRI Method Registration 2866 This section registers the "PRI" method in the HTTP Method Registry 2867 [HTTP-p2]. 2869 Method Name: PRI 2871 Safe No 2873 Idempotent No 2875 Specification document(s) Section 3.5 of this document 2877 Related information: This method is never used by an actual client. 2878 This method will appear to be used when an HTTP/1.1 server or 2879 intermediary attempts to parse an HTTP/2 connection header. 2881 13. Acknowledgements 2883 This document includes substantial input from the following 2884 individuals: 2886 o Adam Langley, Wan-Teh Chang, Jim Morrison, Mark Nottingham, Alyssa 2887 Wilk, Costin Manolache, William Chan, Vitaliy Lvin, Joe Chan, Adam 2888 Barth, Ryan Hamilton, Gavin Peters, Kent Alstad, Kevin Lindsay, 2889 Paul Amer, Fan Yang, Jonathan Leighton (SPDY contributors). 2891 o Gabriel Montenegro and Willy Tarreau (Upgrade mechanism). 2893 o William Chan, Salvatore Loreto, Osama Mazahir, Gabriel Montenegro, 2894 Jitu Padhye, Roberto Peon, Rob Trace (Flow control). 2896 o Mark Nottingham, Julian Reschke, James Snell, Jeff Pinner, Mike 2897 Bishop, Herve Ruellan (Substantial editorial contributions). 2899 o Alexey Melnikov was an editor of this document during 2013. 2901 o A substantial proportion of Martin's contribution was supported by 2902 Microsoft during his employment there. 2904 14. References 2906 14.1. Normative References 2908 [COMPRESSION] Ruellan, H. and R. Peon, "HPACK - Header Compression 2909 for HTTP/2", draft-ietf-httpbis-header-compression-06 2910 (work in progress), February 2014. 2912 [COOKIE] Barth, A., "HTTP State Management Mechanism", 2913 RFC 6265, April 2011. 2915 [HTTP-p1] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 2916 Transfer Protocol (HTTP/1.1): Message Syntax and 2917 Routing", draft-ietf-httpbis-p1-messaging-26 (work in 2918 progress), February 2014. 2920 [HTTP-p2] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 2921 Transfer Protocol (HTTP/1.1): Semantics and Content", 2922 draft-ietf-httpbis-p2-semantics-26 (work in progress), 2923 February 2014. 2925 [HTTP-p4] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 2926 Transfer Protocol (HTTP/1.1): Conditional Requests", 2927 draft-ietf-httpbis-p4-conditional-26 (work in 2928 progress), February 2014. 2930 [HTTP-p5] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, 2931 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Range 2932 Requests", draft-ietf-httpbis-p5-range-26 (work in 2933 progress), February 2014. 2935 [HTTP-p6] Fielding, R., Ed., Nottingham, M., Ed., and J. 2936 Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): 2937 Caching", draft-ietf-httpbis-p6-cache-26 (work in 2938 progress), February 2014. 2940 [HTTP-p7] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext 2941 Transfer Protocol (HTTP/1.1): Authentication", 2942 draft-ietf-httpbis-p7-auth-26 (work in progress), 2943 February 2014. 2945 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2946 Requirement Levels", BCP 14, RFC 2119, March 1997. 2948 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2950 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, 2951 "Uniform Resource Identifier (URI): Generic Syntax", 2952 STD 66, RFC 3986, January 2005. 2954 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2955 Encodings", RFC 4648, October 2006. 2957 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing 2958 an IANA Considerations Section in RFCs", BCP 26, 2959 RFC 5226, May 2008. 2961 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2962 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2964 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2965 Verification of Domain-Based Application Service 2966 Identity within Internet Public Key Infrastructure 2967 Using X.509 (PKIX) Certificates in the Context of 2968 Transport Layer Security (TLS)", RFC 6125, March 2011. 2970 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 2971 December 2011. 2973 [TCP] Postel, J., "Transmission Control Protocol", STD 7, 2974 RFC 793, September 1981. 2976 [TLS-EXT] Eastlake, D., "Transport Layer Security (TLS) 2977 Extensions: Extension Definitions", RFC 6066, 2978 January 2011. 2980 [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer 2981 Security (TLS) Protocol Version 1.2", RFC 5246, 2982 August 2008. 2984 [TLSALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan, 2985 "Transport Layer Security (TLS) Application Layer 2986 Protocol Negotiation Extension", 2987 draft-ietf-tls-applayerprotoneg-04 (work in progress), 2988 January 2014. 2990 14.2. Informative References 2992 [AltSvc] Nottingham, M., "HTTP Alternate Services", 2993 draft-nottingham-httpbis-alt-svc-01 (work in 2994 progress), December 2013. 2996 [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration 2997 Procedures for Message Header Fields", BCP 90, 2998 RFC 3864, September 2004. 3000 [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving 3001 the CRIME Attack", July 2013, . 3005 [RC4] Rivest, R., "The RC4 encryption algorithm", RSA Data 3006 Security, Inc. , March 1992. 3008 [RFC1323] Jacobson, V., Braden, B., and D. Borman, "TCP 3009 Extensions for High Performance", RFC 1323, May 1992. 3011 [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol 3012 Compression Methods", RFC 3749, May 2004. 3014 [TALKING] Huang, L-S., Chen, E., Barth, A., Rescorla, E., and C. 3015 Jackson, "Talking to Yourself for Fun and Profit", 3016 2011, . 3018 [TLSBCP] Sheffer, Y. and R. Holz, "Recommendations for Secure 3019 Use of TLS and DTLS", draft-sheffer-tls-bcp-01 (work 3020 in progress), September 2013. 3022 Appendix A. Change Log (to be removed by RFC Editor before publication) 3024 A.1. Since draft-ietf-httpbis-http2-09 3026 Adding padding for data frames. 3028 Renumbering frame types, error codes, and settings. 3030 Adding INADEQUATE_SECURITY error code. 3032 Updating TLS usage requirements to 1.2; forbidding TLS compression. 3034 Removing extensibility for frames and settings. 3036 Changing setting identifier size. 3038 Removing the ability to disable flow control. 3040 Changing the protocol identification token to "h2". 3042 Changing the use of :authority to make it optional and to allow 3043 userinfo in non-HTTP cases. 3045 Allowing split on 0x0 for Cookie. 3047 Reserved PRI method in HTTP/1.1 to avoid possible future collisions. 3049 A.2. Since draft-ietf-httpbis-http2-08 3051 Added cookie crumbling for more efficient header compression. 3053 Added header field ordering with the value-concatenation mechanism. 3055 A.3. Since draft-ietf-httpbis-http2-07 3057 Marked draft for implementation. 3059 A.4. Since draft-ietf-httpbis-http2-06 3061 Adding definition for CONNECT method. 3063 Constraining the use of push to safe, cacheable methods with no 3064 request body. 3066 Changing from :host to :authority to remove any potential confusion. 3068 Adding setting for header compression table size. 3070 Adding settings acknowledgement. 3072 Removing unnecessary and potentially problematic flags from 3073 CONTINUATION. 3075 Added denial of service considerations. 3077 A.5. Since draft-ietf-httpbis-http2-05 3079 Marking the draft ready for implementation. 3081 Renumbering END_PUSH_PROMISE flag. 3083 Editorial clarifications and changes. 3085 A.6. Since draft-ietf-httpbis-http2-04 3087 Added CONTINUATION frame for HEADERS and PUSH_PROMISE. 3089 PUSH_PROMISE is no longer implicitly prohibited if 3090 SETTINGS_MAX_CONCURRENT_STREAMS is zero. 3092 Push expanded to allow all safe methods without a request body. 3094 Clarified the use of HTTP header fields in requests and responses. 3095 Prohibited HTTP/1.1 hop-by-hop header fields. 3097 Requiring that intermediaries not forward requests with missing or 3098 illegal routing :-headers. 3100 Clarified requirements around handling different frames after stream 3101 close, stream reset and GOAWAY. 3103 Added more specific prohibitions for sending of different frame types 3104 in various stream states. 3106 Making the last received setting value the effective value. 3108 Clarified requirements on TLS version, extension and ciphers. 3110 A.7. Since draft-ietf-httpbis-http2-03 3112 Committed major restructuring atrocities. 3114 Added reference to first header compression draft. 3116 Added more formal description of frame lifecycle. 3118 Moved END_STREAM (renamed from FINAL) back to HEADERS/DATA. 3120 Removed HEADERS+PRIORITY, added optional priority to HEADERS frame. 3122 Added PRIORITY frame. 3124 A.8. Since draft-ietf-httpbis-http2-02 3126 Added continuations to frames carrying header blocks. 3128 Replaced use of "session" with "connection" to avoid confusion with 3129 other HTTP stateful concepts, like cookies. 3131 Removed "message". 3133 Switched to TLS ALPN from NPN. 3135 Editorial changes. 3137 A.9. Since draft-ietf-httpbis-http2-01 3139 Added IANA considerations section for frame types, error codes and 3140 settings. 3142 Removed data frame compression. 3144 Added PUSH_PROMISE. 3146 Added globally applicable flags to framing. 3148 Removed zlib-based header compression mechanism. 3150 Updated references. 3152 Clarified stream identifier reuse. 3154 Removed CREDENTIALS frame and associated mechanisms. 3156 Added advice against naive implementation of flow control. 3158 Added session header section. 3160 Restructured frame header. Removed distinction between data and 3161 control frames. 3163 Altered flow control properties to include session-level limits. 3165 Added note on cacheability of pushed resources and multiple tenant 3166 servers. 3168 Changed protocol label form based on discussions. 3170 A.10. Since draft-ietf-httpbis-http2-00 3172 Changed title throughout. 3174 Removed section on Incompatibilities with SPDY draft#2. 3176 Changed INTERNAL_ERROR on GOAWAY to have a value of 2 . 3179 Replaced abstract and introduction. 3181 Added section on starting HTTP/2.0, including upgrade mechanism. 3183 Removed unused references. 3185 Added flow control principles (Section 5.2.1) based on . 3188 A.11. Since draft-mbelshe-httpbis-spdy-00 3190 Adopted as base for draft-ietf-httpbis-http2. 3192 Updated authors/editors list. 3194 Added status note. 3196 Authors' Addresses 3198 Mike Belshe 3199 Twist 3201 EMail: mbelshe@chromium.org 3203 Roberto Peon 3204 Google, Inc 3206 EMail: fenix@google.com 3208 Martin Thomson (editor) 3209 Mozilla 3210 Suite 300 3211 650 Castro Street 3212 Mountain View, CA 94041 3213 US 3215 EMail: martin.thomson@gmail.com