| 1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | Internet Engineering Task Force (IETF) M. Belshe |
| 8 | Request for Comments: 7540 BitGo |
| 9 | Category: Standards Track R. Peon |
| 10 | ISSN: 2070-1721 Google, Inc |
| 11 | M. Thomson, Ed. |
| 12 | Mozilla |
| 13 | May 2015 |
| 14 | |
| 15 | |
| 16 | Hypertext Transfer Protocol Version 2 (HTTP/2) |
| 17 | |
| 18 | Abstract |
| 19 | |
| 20 | This specification describes an optimized expression of the semantics |
| 21 | of the Hypertext Transfer Protocol (HTTP), referred to as HTTP |
| 22 | version 2 (HTTP/2). HTTP/2 enables a more efficient use of network |
| 23 | resources and a reduced perception of latency by introducing header |
| 24 | field compression and allowing multiple concurrent exchanges on the |
| 25 | same connection. It also introduces unsolicited push of |
| 26 | representations from servers to clients. |
| 27 | |
| 28 | This specification is an alternative to, but does not obsolete, the |
| 29 | HTTP/1.1 message syntax. HTTP's existing semantics remain unchanged. |
| 30 | |
| 31 | Status of This Memo |
| 32 | |
| 33 | This is an Internet Standards Track document. |
| 34 | |
| 35 | This document is a product of the Internet Engineering Task Force |
| 36 | (IETF). It represents the consensus of the IETF community. It has |
| 37 | received public review and has been approved for publication by the |
| 38 | Internet Engineering Steering Group (IESG). Further information on |
| 39 | Internet Standards is available in Section 2 of RFC 5741. |
| 40 | |
| 41 | Information about the current status of this document, any errata, |
| 42 | and how to provide feedback on it may be obtained at |
| 43 | http://www.rfc-editor.org/info/rfc7540. |
| 44 | |
| 45 | |
| 46 | |
| 47 | |
| 48 | |
| 49 | |
| 50 | |
| 51 | |
| 52 | |
| 53 | |
| 54 | |
| 55 | |
| 56 | |
| 57 | |
| 58 | Belshe, et al. Standards Track [Page 1] |
| 59 | \f |
| 60 | RFC 7540 HTTP/2 May 2015 |
| 61 | |
| 62 | |
| 63 | Copyright Notice |
| 64 | |
| 65 | Copyright (c) 2015 IETF Trust and the persons identified as the |
| 66 | document authors. All rights reserved. |
| 67 | |
| 68 | This document is subject to BCP 78 and the IETF Trust's Legal |
| 69 | Provisions Relating to IETF Documents |
| 70 | (http://trustee.ietf.org/license-info) in effect on the date of |
| 71 | publication of this document. Please review these documents |
| 72 | carefully, as they describe your rights and restrictions with respect |
| 73 | to this document. Code Components extracted from this document must |
| 74 | include Simplified BSD License text as described in Section 4.e of |
| 75 | the Trust Legal Provisions and are provided without warranty as |
| 76 | described in the Simplified BSD License. |
| 77 | |
| 78 | Table of Contents |
| 79 | |
| 80 | 1. Introduction ....................................................4 |
| 81 | 2. HTTP/2 Protocol Overview ........................................5 |
| 82 | 2.1. Document Organization ......................................6 |
| 83 | 2.2. Conventions and Terminology ................................6 |
| 84 | 3. Starting HTTP/2 .................................................7 |
| 85 | 3.1. HTTP/2 Version Identification ..............................8 |
| 86 | 3.2. Starting HTTP/2 for "http" URIs ............................8 |
| 87 | 3.2.1. HTTP2-Settings Header Field .........................9 |
| 88 | 3.3. Starting HTTP/2 for "https" URIs ..........................10 |
| 89 | 3.4. Starting HTTP/2 with Prior Knowledge ......................10 |
| 90 | 3.5. HTTP/2 Connection Preface .................................11 |
| 91 | 4. HTTP Frames ....................................................12 |
| 92 | 4.1. Frame Format ..............................................12 |
| 93 | 4.2. Frame Size ................................................13 |
| 94 | 4.3. Header Compression and Decompression ......................14 |
| 95 | 5. Streams and Multiplexing .......................................15 |
| 96 | 5.1. Stream States .............................................16 |
| 97 | 5.1.1. Stream Identifiers .................................21 |
| 98 | 5.1.2. Stream Concurrency .................................22 |
| 99 | 5.2. Flow Control ..............................................22 |
| 100 | 5.2.1. Flow-Control Principles ............................23 |
| 101 | 5.2.2. Appropriate Use of Flow Control ....................24 |
| 102 | 5.3. Stream Priority ...........................................24 |
| 103 | 5.3.1. Stream Dependencies ................................25 |
| 104 | 5.3.2. Dependency Weighting ...............................26 |
| 105 | 5.3.3. Reprioritization ...................................26 |
| 106 | 5.3.4. Prioritization State Management ....................27 |
| 107 | 5.3.5. Default Priorities .................................28 |
| 108 | 5.4. Error Handling ............................................28 |
| 109 | 5.4.1. Connection Error Handling ..........................29 |
| 110 | 5.4.2. Stream Error Handling ..............................29 |
| 111 | |
| 112 | |
| 113 | |
| 114 | Belshe, et al. Standards Track [Page 2] |
| 115 | \f |
| 116 | RFC 7540 HTTP/2 May 2015 |
| 117 | |
| 118 | |
| 119 | 5.4.3. Connection Termination .............................30 |
| 120 | 5.5. Extending HTTP/2 ..........................................30 |
| 121 | 6. Frame Definitions ..............................................31 |
| 122 | 6.1. DATA ......................................................31 |
| 123 | 6.2. HEADERS ...................................................32 |
| 124 | 6.3. PRIORITY ..................................................34 |
| 125 | 6.4. RST_STREAM ................................................36 |
| 126 | 6.5. SETTINGS ..................................................36 |
| 127 | 6.5.1. SETTINGS Format ....................................38 |
| 128 | 6.5.2. Defined SETTINGS Parameters ........................38 |
| 129 | 6.5.3. Settings Synchronization ...........................39 |
| 130 | 6.6. PUSH_PROMISE ..............................................40 |
| 131 | 6.7. PING ......................................................42 |
| 132 | 6.8. GOAWAY ....................................................43 |
| 133 | 6.9. WINDOW_UPDATE .............................................46 |
| 134 | 6.9.1. The Flow-Control Window ............................47 |
| 135 | 6.9.2. Initial Flow-Control Window Size ...................48 |
| 136 | 6.9.3. Reducing the Stream Window Size ....................49 |
| 137 | 6.10. CONTINUATION .............................................49 |
| 138 | 7. Error Codes ....................................................50 |
| 139 | 8. HTTP Message Exchanges .........................................51 |
| 140 | 8.1. HTTP Request/Response Exchange ............................52 |
| 141 | 8.1.1. Upgrading from HTTP/2 ..............................53 |
| 142 | 8.1.2. HTTP Header Fields .................................53 |
| 143 | 8.1.3. Examples ...........................................57 |
| 144 | 8.1.4. Request Reliability Mechanisms in HTTP/2 ...........60 |
| 145 | 8.2. Server Push ...............................................60 |
| 146 | 8.2.1. Push Requests ......................................61 |
| 147 | 8.2.2. Push Responses .....................................63 |
| 148 | 8.3. The CONNECT Method ........................................64 |
| 149 | 9. Additional HTTP Requirements/Considerations ....................65 |
| 150 | 9.1. Connection Management .....................................65 |
| 151 | 9.1.1. Connection Reuse ...................................66 |
| 152 | 9.1.2. The 421 (Misdirected Request) Status Code ..........66 |
| 153 | 9.2. Use of TLS Features .......................................67 |
| 154 | 9.2.1. TLS 1.2 Features ...................................67 |
| 155 | 9.2.2. TLS 1.2 Cipher Suites ..............................68 |
| 156 | 10. Security Considerations .......................................69 |
| 157 | 10.1. Server Authority .........................................69 |
| 158 | 10.2. Cross-Protocol Attacks ...................................69 |
| 159 | 10.3. Intermediary Encapsulation Attacks .......................70 |
| 160 | 10.4. Cacheability of Pushed Responses .........................70 |
| 161 | 10.5. Denial-of-Service Considerations .........................70 |
| 162 | 10.5.1. Limits on Header Block Size .......................71 |
| 163 | 10.5.2. CONNECT Issues ....................................72 |
| 164 | 10.6. Use of Compression .......................................72 |
| 165 | 10.7. Use of Padding ...........................................73 |
| 166 | 10.8. Privacy Considerations ...................................73 |
| 167 | |
| 168 | |
| 169 | |
| 170 | Belshe, et al. Standards Track [Page 3] |
| 171 | \f |
| 172 | RFC 7540 HTTP/2 May 2015 |
| 173 | |
| 174 | |
| 175 | 11. IANA Considerations ...........................................74 |
| 176 | 11.1. Registration of HTTP/2 Identification Strings ............74 |
| 177 | 11.2. Frame Type Registry ......................................75 |
| 178 | 11.3. Settings Registry ........................................75 |
| 179 | 11.4. Error Code Registry ......................................76 |
| 180 | 11.5. HTTP2-Settings Header Field Registration .................77 |
| 181 | 11.6. PRI Method Registration ..................................78 |
| 182 | 11.7. The 421 (Misdirected Request) HTTP Status Code ...........78 |
| 183 | 11.8. The h2c Upgrade Token ....................................78 |
| 184 | 12. References ....................................................79 |
| 185 | 12.1. Normative References .....................................79 |
| 186 | 12.2. Informative References ...................................81 |
| 187 | Appendix A. TLS 1.2 Cipher Suite Black List .......................83 |
| 188 | Acknowledgements ..................................................95 |
| 189 | Authors' Addresses ................................................96 |
| 190 | |
| 191 | 1. Introduction |
| 192 | |
| 193 | The Hypertext Transfer Protocol (HTTP) is a wildly successful |
| 194 | protocol. However, the way HTTP/1.1 uses the underlying transport |
| 195 | ([RFC7230], Section 6) has several characteristics that have a |
| 196 | negative overall effect on application performance today. |
| 197 | |
| 198 | In particular, HTTP/1.0 allowed only one request to be outstanding at |
| 199 | a time on a given TCP connection. HTTP/1.1 added request pipelining, |
| 200 | but this only partially addressed request concurrency and still |
| 201 | suffers from head-of-line blocking. Therefore, HTTP/1.0 and HTTP/1.1 |
| 202 | clients that need to make many requests use multiple connections to a |
| 203 | server in order to achieve concurrency and thereby reduce latency. |
| 204 | |
| 205 | Furthermore, HTTP header fields are often repetitive and verbose, |
| 206 | causing unnecessary network traffic as well as causing the initial |
| 207 | TCP [TCP] congestion window to quickly fill. This can result in |
| 208 | excessive latency when multiple requests are made on a new TCP |
| 209 | connection. |
| 210 | |
| 211 | HTTP/2 addresses these issues by defining an optimized mapping of |
| 212 | HTTP's semantics to an underlying connection. Specifically, it |
| 213 | allows interleaving of request and response messages on the same |
| 214 | connection and uses an efficient coding for HTTP header fields. It |
| 215 | also allows prioritization of requests, letting more important |
| 216 | requests complete more quickly, further improving performance. |
| 217 | |
| 218 | |
| 219 | |
| 220 | |
| 221 | |
| 222 | |
| 223 | |
| 224 | |
| 225 | |
| 226 | Belshe, et al. Standards Track [Page 4] |
| 227 | \f |
| 228 | RFC 7540 HTTP/2 May 2015 |
| 229 | |
| 230 | |
| 231 | The resulting protocol is more friendly to the network because fewer |
| 232 | TCP connections can be used in comparison to HTTP/1.x. This means |
| 233 | less competition with other flows and longer-lived connections, which |
| 234 | in turn lead to better utilization of available network capacity. |
| 235 | |
| 236 | Finally, HTTP/2 also enables more efficient processing of messages |
| 237 | through use of binary message framing. |
| 238 | |
| 239 | 2. HTTP/2 Protocol Overview |
| 240 | |
| 241 | HTTP/2 provides an optimized transport for HTTP semantics. HTTP/2 |
| 242 | supports all of the core features of HTTP/1.1 but aims to be more |
| 243 | efficient in several ways. |
| 244 | |
| 245 | The basic protocol unit in HTTP/2 is a frame (Section 4.1). Each |
| 246 | frame type serves a different purpose. For example, HEADERS and DATA |
| 247 | frames form the basis of HTTP requests and responses (Section 8.1); |
| 248 | other frame types like SETTINGS, WINDOW_UPDATE, and PUSH_PROMISE are |
| 249 | used in support of other HTTP/2 features. |
| 250 | |
| 251 | Multiplexing of requests is achieved by having each HTTP request/ |
| 252 | response exchange associated with its own stream (Section 5). |
| 253 | Streams are largely independent of each other, so a blocked or |
| 254 | stalled request or response does not prevent progress on other |
| 255 | streams. |
| 256 | |
| 257 | Flow control and prioritization ensure that it is possible to |
| 258 | efficiently use multiplexed streams. Flow control (Section 5.2) |
| 259 | helps to ensure that only data that can be used by a receiver is |
| 260 | transmitted. Prioritization (Section 5.3) ensures that limited |
| 261 | resources can be directed to the most important streams first. |
| 262 | |
| 263 | HTTP/2 adds a new interaction mode whereby a server can push |
| 264 | responses to a client (Section 8.2). Server push allows a server to |
| 265 | speculatively send data to a client that the server anticipates the |
| 266 | client will need, trading off some network usage against a potential |
| 267 | latency gain. The server does this by synthesizing a request, which |
| 268 | it sends as a PUSH_PROMISE frame. The server is then able to send a |
| 269 | response to the synthetic request on a separate stream. |
| 270 | |
| 271 | Because HTTP header fields used in a connection can contain large |
| 272 | amounts of redundant data, frames that contain them are compressed |
| 273 | (Section 4.3). This has especially advantageous impact upon request |
| 274 | sizes in the common case, allowing many requests to be compressed |
| 275 | into one packet. |
| 276 | |
| 277 | |
| 278 | |
| 279 | |
| 280 | |
| 281 | |
| 282 | Belshe, et al. Standards Track [Page 5] |
| 283 | \f |
| 284 | RFC 7540 HTTP/2 May 2015 |
| 285 | |
| 286 | |
| 287 | 2.1. Document Organization |
| 288 | |
| 289 | The HTTP/2 specification is split into four parts: |
| 290 | |
| 291 | o Starting HTTP/2 (Section 3) covers how an HTTP/2 connection is |
| 292 | initiated. |
| 293 | |
| 294 | o The frame (Section 4) and stream (Section 5) layers describe the |
| 295 | way HTTP/2 frames are structured and formed into multiplexed |
| 296 | streams. |
| 297 | |
| 298 | o Frame (Section 6) and error (Section 7) definitions include |
| 299 | details of the frame and error types used in HTTP/2. |
| 300 | |
| 301 | o HTTP mappings (Section 8) and additional requirements (Section 9) |
| 302 | describe how HTTP semantics are expressed using frames and |
| 303 | streams. |
| 304 | |
| 305 | While some of the frame and stream layer concepts are isolated from |
| 306 | HTTP, this specification does not define a completely generic frame |
| 307 | layer. The frame and stream layers are tailored to the needs of the |
| 308 | HTTP protocol and server push. |
| 309 | |
| 310 | 2.2. Conventions and Terminology |
| 311 | |
| 312 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
| 313 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
| 314 | document are to be interpreted as described in RFC 2119 [RFC2119]. |
| 315 | |
| 316 | All numeric values are in network byte order. Values are unsigned |
| 317 | unless otherwise indicated. Literal values are provided in decimal |
| 318 | or hexadecimal as appropriate. Hexadecimal literals are prefixed |
| 319 | with "0x" to distinguish them from decimal literals. |
| 320 | |
| 321 | The following terms are used: |
| 322 | |
| 323 | client: The endpoint that initiates an HTTP/2 connection. Clients |
| 324 | send HTTP requests and receive HTTP responses. |
| 325 | |
| 326 | connection: A transport-layer connection between two endpoints. |
| 327 | |
| 328 | connection error: An error that affects the entire HTTP/2 |
| 329 | connection. |
| 330 | |
| 331 | endpoint: Either the client or server of the connection. |
| 332 | |
| 333 | |
| 334 | |
| 335 | |
| 336 | |
| 337 | |
| 338 | Belshe, et al. Standards Track [Page 6] |
| 339 | \f |
| 340 | RFC 7540 HTTP/2 May 2015 |
| 341 | |
| 342 | |
| 343 | frame: The smallest unit of communication within an HTTP/2 |
| 344 | connection, consisting of a header and a variable-length sequence |
| 345 | of octets structured according to the frame type. |
| 346 | |
| 347 | peer: An endpoint. When discussing a particular endpoint, "peer" |
| 348 | refers to the endpoint that is remote to the primary subject of |
| 349 | discussion. |
| 350 | |
| 351 | receiver: An endpoint that is receiving frames. |
| 352 | |
| 353 | sender: An endpoint that is transmitting frames. |
| 354 | |
| 355 | server: The endpoint that accepts an HTTP/2 connection. Servers |
| 356 | receive HTTP requests and send HTTP responses. |
| 357 | |
| 358 | stream: A bidirectional flow of frames within the HTTP/2 connection. |
| 359 | |
| 360 | stream error: An error on the individual HTTP/2 stream. |
| 361 | |
| 362 | Finally, the terms "gateway", "intermediary", "proxy", and "tunnel" |
| 363 | are defined in Section 2.3 of [RFC7230]. Intermediaries act as both |
| 364 | client and server at different times. |
| 365 | |
| 366 | The term "payload body" is defined in Section 3.3 of [RFC7230]. |
| 367 | |
| 368 | 3. Starting HTTP/2 |
| 369 | |
| 370 | An HTTP/2 connection is an application-layer protocol running on top |
| 371 | of a TCP connection ([TCP]). The client is the TCP connection |
| 372 | initiator. |
| 373 | |
| 374 | HTTP/2 uses the same "http" and "https" URI schemes used by HTTP/1.1. |
| 375 | HTTP/2 shares the same default port numbers: 80 for "http" URIs and |
| 376 | 443 for "https" URIs. As a result, implementations processing |
| 377 | requests for target resource URIs like "http://example.org/foo" or |
| 378 | "https://example.com/bar" are required to first discover whether the |
| 379 | upstream server (the immediate peer to which the client wishes to |
| 380 | establish a connection) supports HTTP/2. |
| 381 | |
| 382 | The means by which support for HTTP/2 is determined is different for |
| 383 | "http" and "https" URIs. Discovery for "http" URIs is described in |
| 384 | Section 3.2. Discovery for "https" URIs is described in Section 3.3. |
| 385 | |
| 386 | |
| 387 | |
| 388 | |
| 389 | |
| 390 | |
| 391 | |
| 392 | |
| 393 | |
| 394 | Belshe, et al. Standards Track [Page 7] |
| 395 | \f |
| 396 | RFC 7540 HTTP/2 May 2015 |
| 397 | |
| 398 | |
| 399 | 3.1. HTTP/2 Version Identification |
| 400 | |
| 401 | The protocol defined in this document has two identifiers. |
| 402 | |
| 403 | o The string "h2" identifies the protocol where HTTP/2 uses |
| 404 | Transport Layer Security (TLS) [TLS12]. This identifier is used |
| 405 | in the TLS application-layer protocol negotiation (ALPN) extension |
| 406 | [TLS-ALPN] field and in any place where HTTP/2 over TLS is |
| 407 | identified. |
| 408 | |
| 409 | The "h2" string is serialized into an ALPN protocol identifier as |
| 410 | the two-octet sequence: 0x68, 0x32. |
| 411 | |
| 412 | o The string "h2c" identifies the protocol where HTTP/2 is run over |
| 413 | cleartext TCP. This identifier is used in the HTTP/1.1 Upgrade |
| 414 | header field and in any place where HTTP/2 over TCP is identified. |
| 415 | |
| 416 | The "h2c" string is reserved from the ALPN identifier space but |
| 417 | describes a protocol that does not use TLS. |
| 418 | |
| 419 | Negotiating "h2" or "h2c" implies the use of the transport, security, |
| 420 | framing, and message semantics described in this document. |
| 421 | |
| 422 | 3.2. Starting HTTP/2 for "http" URIs |
| 423 | |
| 424 | A client that makes a request for an "http" URI without prior |
| 425 | knowledge about support for HTTP/2 on the next hop uses the HTTP |
| 426 | Upgrade mechanism (Section 6.7 of [RFC7230]). The client does so by |
| 427 | making an HTTP/1.1 request that includes an Upgrade header field with |
| 428 | the "h2c" token. Such an HTTP/1.1 request MUST include exactly one |
| 429 | HTTP2-Settings (Section 3.2.1) header field. |
| 430 | |
| 431 | For example: |
| 432 | |
| 433 | GET / HTTP/1.1 |
| 434 | Host: server.example.com |
| 435 | Connection: Upgrade, HTTP2-Settings |
| 436 | Upgrade: h2c |
| 437 | HTTP2-Settings: <base64url encoding of HTTP/2 SETTINGS payload> |
| 438 | |
| 439 | Requests that contain a payload body MUST be sent in their entirety |
| 440 | before the client can send HTTP/2 frames. This means that a large |
| 441 | request can block the use of the connection until it is completely |
| 442 | sent. |
| 443 | |
| 444 | If concurrency of an initial request with subsequent requests is |
| 445 | important, an OPTIONS request can be used to perform the upgrade to |
| 446 | HTTP/2, at the cost of an additional round trip. |
| 447 | |
| 448 | |
| 449 | |
| 450 | Belshe, et al. Standards Track [Page 8] |
| 451 | \f |
| 452 | RFC 7540 HTTP/2 May 2015 |
| 453 | |
| 454 | |
| 455 | A server that does not support HTTP/2 can respond to the request as |
| 456 | though the Upgrade header field were absent: |
| 457 | |
| 458 | HTTP/1.1 200 OK |
| 459 | Content-Length: 243 |
| 460 | Content-Type: text/html |
| 461 | |
| 462 | ... |
| 463 | |
| 464 | A server MUST ignore an "h2" token in an Upgrade header field. |
| 465 | Presence of a token with "h2" implies HTTP/2 over TLS, which is |
| 466 | instead negotiated as described in Section 3.3. |
| 467 | |
| 468 | A server that supports HTTP/2 accepts the upgrade with a 101 |
| 469 | (Switching Protocols) response. After the empty line that terminates |
| 470 | the 101 response, the server can begin sending HTTP/2 frames. These |
| 471 | frames MUST include a response to the request that initiated the |
| 472 | upgrade. |
| 473 | |
| 474 | For example: |
| 475 | |
| 476 | HTTP/1.1 101 Switching Protocols |
| 477 | Connection: Upgrade |
| 478 | Upgrade: h2c |
| 479 | |
| 480 | [ HTTP/2 connection ... |
| 481 | |
| 482 | The first HTTP/2 frame sent by the server MUST be a server connection |
| 483 | preface (Section 3.5) consisting of a SETTINGS frame (Section 6.5). |
| 484 | Upon receiving the 101 response, the client MUST send a connection |
| 485 | preface (Section 3.5), which includes a SETTINGS frame. |
| 486 | |
| 487 | The HTTP/1.1 request that is sent prior to upgrade is assigned a |
| 488 | stream identifier of 1 (see Section 5.1.1) with default priority |
| 489 | values (Section 5.3.5). Stream 1 is implicitly "half-closed" from |
| 490 | the client toward the server (see Section 5.1), since the request is |
| 491 | completed as an HTTP/1.1 request. After commencing the HTTP/2 |
| 492 | connection, stream 1 is used for the response. |
| 493 | |
| 494 | 3.2.1. HTTP2-Settings Header Field |
| 495 | |
| 496 | A request that upgrades from HTTP/1.1 to HTTP/2 MUST include exactly |
| 497 | one "HTTP2-Settings" header field. The HTTP2-Settings header field |
| 498 | is a connection-specific header field that includes parameters that |
| 499 | govern the HTTP/2 connection, provided in anticipation of the server |
| 500 | accepting the request to upgrade. |
| 501 | |
| 502 | HTTP2-Settings = token68 |
| 503 | |
| 504 | |
| 505 | |
| 506 | Belshe, et al. Standards Track [Page 9] |
| 507 | \f |
| 508 | RFC 7540 HTTP/2 May 2015 |
| 509 | |
| 510 | |
| 511 | A server MUST NOT upgrade the connection to HTTP/2 if this header |
| 512 | field is not present or if more than one is present. A server MUST |
| 513 | NOT send this header field. |
| 514 | |
| 515 | The content of the HTTP2-Settings header field is the payload of a |
| 516 | SETTINGS frame (Section 6.5), encoded as a base64url string (that is, |
| 517 | the URL- and filename-safe Base64 encoding described in Section 5 of |
| 518 | [RFC4648], with any trailing '=' characters omitted). The ABNF |
| 519 | [RFC5234] production for "token68" is defined in Section 2.1 of |
| 520 | [RFC7235]. |
| 521 | |
| 522 | Since the upgrade is only intended to apply to the immediate |
| 523 | connection, a client sending the HTTP2-Settings header field MUST |
| 524 | also send "HTTP2-Settings" as a connection option in the Connection |
| 525 | header field to prevent it from being forwarded (see Section 6.1 of |
| 526 | [RFC7230]). |
| 527 | |
| 528 | A server decodes and interprets these values as it would any other |
| 529 | SETTINGS frame. Explicit acknowledgement of these settings |
| 530 | (Section 6.5.3) is not necessary, since a 101 response serves as |
| 531 | implicit acknowledgement. Providing these values in the upgrade |
| 532 | request gives a client an opportunity to provide parameters prior to |
| 533 | receiving any frames from the server. |
| 534 | |
| 535 | 3.3. Starting HTTP/2 for "https" URIs |
| 536 | |
| 537 | A client that makes a request to an "https" URI uses TLS [TLS12] with |
| 538 | the application-layer protocol negotiation (ALPN) extension |
| 539 | [TLS-ALPN]. |
| 540 | |
| 541 | HTTP/2 over TLS uses the "h2" protocol identifier. The "h2c" |
| 542 | protocol identifier MUST NOT be sent by a client or selected by a |
| 543 | server; the "h2c" protocol identifier describes a protocol that does |
| 544 | not use TLS. |
| 545 | |
| 546 | Once TLS negotiation is complete, both the client and the server MUST |
| 547 | send a connection preface (Section 3.5). |
| 548 | |
| 549 | 3.4. Starting HTTP/2 with Prior Knowledge |
| 550 | |
| 551 | A client can learn that a particular server supports HTTP/2 by other |
| 552 | means. For example, [ALT-SVC] describes a mechanism for advertising |
| 553 | this capability. |
| 554 | |
| 555 | A client MUST send the connection preface (Section 3.5) and then MAY |
| 556 | immediately send HTTP/2 frames to such a server; servers can identify |
| 557 | these connections by the presence of the connection preface. This |
| 558 | |
| 559 | |
| 560 | |
| 561 | |
| 562 | Belshe, et al. Standards Track [Page 10] |
| 563 | \f |
| 564 | RFC 7540 HTTP/2 May 2015 |
| 565 | |
| 566 | |
| 567 | only affects the establishment of HTTP/2 connections over cleartext |
| 568 | TCP; implementations that support HTTP/2 over TLS MUST use protocol |
| 569 | negotiation in TLS [TLS-ALPN]. |
| 570 | |
| 571 | Likewise, the server MUST send a connection preface (Section 3.5). |
| 572 | |
| 573 | Without additional information, prior support for HTTP/2 is not a |
| 574 | strong signal that a given server will support HTTP/2 for future |
| 575 | connections. For example, it is possible for server configurations |
| 576 | to change, for configurations to differ between instances in |
| 577 | clustered servers, or for network conditions to change. |
| 578 | |
| 579 | 3.5. HTTP/2 Connection Preface |
| 580 | |
| 581 | In HTTP/2, each endpoint is required to send a connection preface as |
| 582 | a final confirmation of the protocol in use and to establish the |
| 583 | initial settings for the HTTP/2 connection. The client and server |
| 584 | each send a different connection preface. |
| 585 | |
| 586 | The client connection preface starts with a sequence of 24 octets, |
| 587 | which in hex notation is: |
| 588 | |
| 589 | 0x505249202a20485454502f322e300d0a0d0a534d0d0a0d0a |
| 590 | |
| 591 | That is, the connection preface starts with the string "PRI * |
| 592 | HTTP/2.0\r\n\r\nSM\r\n\r\n"). This sequence MUST be followed by a |
| 593 | SETTINGS frame (Section 6.5), which MAY be empty. The client sends |
| 594 | the client connection preface immediately upon receipt of a 101 |
| 595 | (Switching Protocols) response (indicating a successful upgrade) or |
| 596 | as the first application data octets of a TLS connection. If |
| 597 | starting an HTTP/2 connection with prior knowledge of server support |
| 598 | for the protocol, the client connection preface is sent upon |
| 599 | connection establishment. |
| 600 | |
| 601 | Note: The client connection preface is selected so that a large |
| 602 | proportion of HTTP/1.1 or HTTP/1.0 servers and intermediaries do |
| 603 | not attempt to process further frames. Note that this does not |
| 604 | address the concerns raised in [TALKING]. |
| 605 | |
| 606 | The server connection preface consists of a potentially empty |
| 607 | SETTINGS frame (Section 6.5) that MUST be the first frame the server |
| 608 | sends in the HTTP/2 connection. |
| 609 | |
| 610 | The SETTINGS frames received from a peer as part of the connection |
| 611 | preface MUST be acknowledged (see Section 6.5.3) after sending the |
| 612 | connection preface. |
| 613 | |
| 614 | |
| 615 | |
| 616 | |
| 617 | |
| 618 | Belshe, et al. Standards Track [Page 11] |
| 619 | \f |
| 620 | RFC 7540 HTTP/2 May 2015 |
| 621 | |
| 622 | |
| 623 | To avoid unnecessary latency, clients are permitted to send |
| 624 | additional frames to the server immediately after sending the client |
| 625 | connection preface, without waiting to receive the server connection |
| 626 | preface. It is important to note, however, that the server |
| 627 | connection preface SETTINGS frame might include parameters that |
| 628 | necessarily alter how a client is expected to communicate with the |
| 629 | server. Upon receiving the SETTINGS frame, the client is expected to |
| 630 | honor any parameters established. In some configurations, it is |
| 631 | possible for the server to transmit SETTINGS before the client sends |
| 632 | additional frames, providing an opportunity to avoid this issue. |
| 633 | |
| 634 | Clients and servers MUST treat an invalid connection preface as a |
| 635 | connection error (Section 5.4.1) of type PROTOCOL_ERROR. A GOAWAY |
| 636 | frame (Section 6.8) MAY be omitted in this case, since an invalid |
| 637 | preface indicates that the peer is not using HTTP/2. |
| 638 | |
| 639 | 4. HTTP Frames |
| 640 | |
| 641 | Once the HTTP/2 connection is established, endpoints can begin |
| 642 | exchanging frames. |
| 643 | |
| 644 | 4.1. Frame Format |
| 645 | |
| 646 | All frames begin with a fixed 9-octet header followed by a variable- |
| 647 | length payload. |
| 648 | |
| 649 | +-----------------------------------------------+ |
| 650 | | Length (24) | |
| 651 | +---------------+---------------+---------------+ |
| 652 | | Type (8) | Flags (8) | |
| 653 | +-+-------------+---------------+-------------------------------+ |
| 654 | |R| Stream Identifier (31) | |
| 655 | +=+=============================================================+ |
| 656 | | Frame Payload (0...) ... |
| 657 | +---------------------------------------------------------------+ |
| 658 | |
| 659 | Figure 1: Frame Layout |
| 660 | |
| 661 | The fields of the frame header are defined as: |
| 662 | |
| 663 | Length: The length of the frame payload expressed as an unsigned |
| 664 | 24-bit integer. Values greater than 2^14 (16,384) MUST NOT be |
| 665 | sent unless the receiver has set a larger value for |
| 666 | SETTINGS_MAX_FRAME_SIZE. |
| 667 | |
| 668 | The 9 octets of the frame header are not included in this value. |
| 669 | |
| 670 | |
| 671 | |
| 672 | |
| 673 | |
| 674 | Belshe, et al. Standards Track [Page 12] |
| 675 | \f |
| 676 | RFC 7540 HTTP/2 May 2015 |
| 677 | |
| 678 | |
| 679 | Type: The 8-bit type of the frame. The frame type determines the |
| 680 | format and semantics of the frame. Implementations MUST ignore |
| 681 | and discard any frame that has a type that is unknown. |
| 682 | |
| 683 | Flags: An 8-bit field reserved for boolean flags specific to the |
| 684 | frame type. |
| 685 | |
| 686 | Flags are assigned semantics specific to the indicated frame type. |
| 687 | Flags that have no defined semantics for a particular frame type |
| 688 | MUST be ignored and MUST be left unset (0x0) when sending. |
| 689 | |
| 690 | R: A reserved 1-bit field. The semantics of this bit are undefined, |
| 691 | and the bit MUST remain unset (0x0) when sending and MUST be |
| 692 | ignored when receiving. |
| 693 | |
| 694 | Stream Identifier: A stream identifier (see Section 5.1.1) expressed |
| 695 | as an unsigned 31-bit integer. The value 0x0 is reserved for |
| 696 | frames that are associated with the connection as a whole as |
| 697 | opposed to an individual stream. |
| 698 | |
| 699 | The structure and content of the frame payload is dependent entirely |
| 700 | on the frame type. |
| 701 | |
| 702 | 4.2. Frame Size |
| 703 | |
| 704 | The size of a frame payload is limited by the maximum size that a |
| 705 | receiver advertises in the SETTINGS_MAX_FRAME_SIZE setting. This |
| 706 | setting can have any value between 2^14 (16,384) and 2^24-1 |
| 707 | (16,777,215) octets, inclusive. |
| 708 | |
| 709 | All implementations MUST be capable of receiving and minimally |
| 710 | processing frames up to 2^14 octets in length, plus the 9-octet frame |
| 711 | header (Section 4.1). The size of the frame header is not included |
| 712 | when describing frame sizes. |
| 713 | |
| 714 | Note: Certain frame types, such as PING (Section 6.7), impose |
| 715 | additional limits on the amount of payload data allowed. |
| 716 | |
| 717 | An endpoint MUST send an error code of FRAME_SIZE_ERROR if a frame |
| 718 | exceeds the size defined in SETTINGS_MAX_FRAME_SIZE, exceeds any |
| 719 | limit defined for the frame type, or is too small to contain |
| 720 | mandatory frame data. A frame size error in a frame that could alter |
| 721 | the state of the entire connection MUST be treated as a connection |
| 722 | error (Section 5.4.1); this includes any frame carrying a header |
| 723 | block (Section 4.3) (that is, HEADERS, PUSH_PROMISE, and |
| 724 | CONTINUATION), SETTINGS, and any frame with a stream identifier of 0. |
| 725 | |
| 726 | |
| 727 | |
| 728 | |
| 729 | |
| 730 | Belshe, et al. Standards Track [Page 13] |
| 731 | \f |
| 732 | RFC 7540 HTTP/2 May 2015 |
| 733 | |
| 734 | |
| 735 | Endpoints are not obligated to use all available space in a frame. |
| 736 | Responsiveness can be improved by using frames that are smaller than |
| 737 | the permitted maximum size. Sending large frames can result in |
| 738 | delays in sending time-sensitive frames (such as RST_STREAM, |
| 739 | WINDOW_UPDATE, or PRIORITY), which, if blocked by the transmission of |
| 740 | a large frame, could affect performance. |
| 741 | |
| 742 | 4.3. Header Compression and Decompression |
| 743 | |
| 744 | Just as in HTTP/1, a header field in HTTP/2 is a name with one or |
| 745 | more associated values. Header fields are used within HTTP request |
| 746 | and response messages as well as in server push operations (see |
| 747 | Section 8.2). |
| 748 | |
| 749 | Header lists are collections of zero or more header fields. When |
| 750 | transmitted over a connection, a header list is serialized into a |
| 751 | header block using HTTP header compression [COMPRESSION]. The |
| 752 | serialized header block is then divided into one or more octet |
| 753 | sequences, called header block fragments, and transmitted within the |
| 754 | payload of HEADERS (Section 6.2), PUSH_PROMISE (Section 6.6), or |
| 755 | CONTINUATION (Section 6.10) frames. |
| 756 | |
| 757 | The Cookie header field [COOKIE] is treated specially by the HTTP |
| 758 | mapping (see Section 8.1.2.5). |
| 759 | |
| 760 | A receiving endpoint reassembles the header block by concatenating |
| 761 | its fragments and then decompresses the block to reconstruct the |
| 762 | header list. |
| 763 | |
| 764 | A complete header block consists of either: |
| 765 | |
| 766 | o a single HEADERS or PUSH_PROMISE frame, with the END_HEADERS flag |
| 767 | set, or |
| 768 | |
| 769 | o a HEADERS or PUSH_PROMISE frame with the END_HEADERS flag cleared |
| 770 | and one or more CONTINUATION frames, where the last CONTINUATION |
| 771 | frame has the END_HEADERS flag set. |
| 772 | |
| 773 | Header compression is stateful. One compression context and one |
| 774 | decompression context are used for the entire connection. A decoding |
| 775 | error in a header block MUST be treated as a connection error |
| 776 | (Section 5.4.1) of type COMPRESSION_ERROR. |
| 777 | |
| 778 | Each header block is processed as a discrete unit. Header blocks |
| 779 | MUST be transmitted as a contiguous sequence of frames, with no |
| 780 | interleaved frames of any other type or from any other stream. The |
| 781 | last frame in a sequence of HEADERS or CONTINUATION frames has the |
| 782 | |
| 783 | |
| 784 | |
| 785 | |
| 786 | Belshe, et al. Standards Track [Page 14] |
| 787 | \f |
| 788 | RFC 7540 HTTP/2 May 2015 |
| 789 | |
| 790 | |
| 791 | END_HEADERS flag set. The last frame in a sequence of PUSH_PROMISE |
| 792 | or CONTINUATION frames has the END_HEADERS flag set. This allows a |
| 793 | header block to be logically equivalent to a single frame. |
| 794 | |
| 795 | Header block fragments can only be sent as the payload of HEADERS, |
| 796 | PUSH_PROMISE, or CONTINUATION frames because these frames carry data |
| 797 | that can modify the compression context maintained by a receiver. An |
| 798 | endpoint receiving HEADERS, PUSH_PROMISE, or CONTINUATION frames |
| 799 | needs to reassemble header blocks and perform decompression even if |
| 800 | the frames are to be discarded. A receiver MUST terminate the |
| 801 | connection with a connection error (Section 5.4.1) of type |
| 802 | COMPRESSION_ERROR if it does not decompress a header block. |
| 803 | |
| 804 | 5. Streams and Multiplexing |
| 805 | |
| 806 | A "stream" is an independent, bidirectional sequence of frames |
| 807 | exchanged between the client and server within an HTTP/2 connection. |
| 808 | Streams have several important characteristics: |
| 809 | |
| 810 | o A single HTTP/2 connection can contain multiple concurrently open |
| 811 | streams, with either endpoint interleaving frames from multiple |
| 812 | streams. |
| 813 | |
| 814 | o Streams can be established and used unilaterally or shared by |
| 815 | either the client or server. |
| 816 | |
| 817 | o Streams can be closed by either endpoint. |
| 818 | |
| 819 | o The order in which frames are sent on a stream is significant. |
| 820 | Recipients process frames in the order they are received. In |
| 821 | particular, the order of HEADERS and DATA frames is semantically |
| 822 | significant. |
| 823 | |
| 824 | o Streams are identified by an integer. Stream identifiers are |
| 825 | assigned to streams by the endpoint initiating the stream. |
| 826 | |
| 827 | |
| 828 | |
| 829 | |
| 830 | |
| 831 | |
| 832 | |
| 833 | |
| 834 | |
| 835 | |
| 836 | |
| 837 | |
| 838 | |
| 839 | |
| 840 | |
| 841 | |
| 842 | Belshe, et al. Standards Track [Page 15] |
| 843 | \f |
| 844 | RFC 7540 HTTP/2 May 2015 |
| 845 | |
| 846 | |
| 847 | 5.1. Stream States |
| 848 | |
| 849 | The lifecycle of a stream is shown in Figure 2. |
| 850 | |
| 851 | +--------+ |
| 852 | send PP | | recv PP |
| 853 | ,--------| idle |--------. |
| 854 | / | | \ |
| 855 | v +--------+ v |
| 856 | +----------+ | +----------+ |
| 857 | | | | send H / | | |
| 858 | ,------| reserved | | recv H | reserved |------. |
| 859 | | | (local) | | | (remote) | | |
| 860 | | +----------+ v +----------+ | |
| 861 | | | +--------+ | | |
| 862 | | | recv ES | | send ES | | |
| 863 | | send H | ,-------| open |-------. | recv H | |
| 864 | | | / | | \ | | |
| 865 | | v v +--------+ v v | |
| 866 | | +----------+ | +----------+ | |
| 867 | | | half | | | half | | |
| 868 | | | closed | | send R / | closed | | |
| 869 | | | (remote) | | recv R | (local) | | |
| 870 | | +----------+ | +----------+ | |
| 871 | | | | | | |
| 872 | | | send ES / | recv ES / | | |
| 873 | | | send R / v send R / | | |
| 874 | | | recv R +--------+ recv R | | |
| 875 | | send R / `----------->| |<-----------' send R / | |
| 876 | | recv R | closed | recv R | |
| 877 | `----------------------->| |<----------------------' |
| 878 | +--------+ |
| 879 | |
| 880 | send: endpoint sends this frame |
| 881 | recv: endpoint receives this frame |
| 882 | |
| 883 | H: HEADERS frame (with implied CONTINUATIONs) |
| 884 | PP: PUSH_PROMISE frame (with implied CONTINUATIONs) |
| 885 | ES: END_STREAM flag |
| 886 | R: RST_STREAM frame |
| 887 | |
| 888 | Figure 2: Stream States |
| 889 | |
| 890 | Note that this diagram shows stream state transitions and the frames |
| 891 | and flags that affect those transitions only. In this regard, |
| 892 | CONTINUATION frames do not result in state transitions; they are |
| 893 | effectively part of the HEADERS or PUSH_PROMISE that they follow. |
| 894 | |
| 895 | |
| 896 | |
| 897 | |
| 898 | Belshe, et al. Standards Track [Page 16] |
| 899 | \f |
| 900 | RFC 7540 HTTP/2 May 2015 |
| 901 | |
| 902 | |
| 903 | For the purpose of state transitions, the END_STREAM flag is |
| 904 | processed as a separate event to the frame that bears it; a HEADERS |
| 905 | frame with the END_STREAM flag set can cause two state transitions. |
| 906 | |
| 907 | Both endpoints have a subjective view of the state of a stream that |
| 908 | could be different when frames are in transit. Endpoints do not |
| 909 | coordinate the creation of streams; they are created unilaterally by |
| 910 | either endpoint. The negative consequences of a mismatch in states |
| 911 | are limited to the "closed" state after sending RST_STREAM, where |
| 912 | frames might be received for some time after closing. |
| 913 | |
| 914 | Streams have the following states: |
| 915 | |
| 916 | idle: |
| 917 | All streams start in the "idle" state. |
| 918 | |
| 919 | The following transitions are valid from this state: |
| 920 | |
| 921 | * Sending or receiving a HEADERS frame causes the stream to |
| 922 | become "open". The stream identifier is selected as described |
| 923 | in Section 5.1.1. The same HEADERS frame can also cause a |
| 924 | stream to immediately become "half-closed". |
| 925 | |
| 926 | * Sending a PUSH_PROMISE frame on another stream reserves the |
| 927 | idle stream that is identified for later use. The stream state |
| 928 | for the reserved stream transitions to "reserved (local)". |
| 929 | |
| 930 | * Receiving a PUSH_PROMISE frame on another stream reserves an |
| 931 | idle stream that is identified for later use. The stream state |
| 932 | for the reserved stream transitions to "reserved (remote)". |
| 933 | |
| 934 | * Note that the PUSH_PROMISE frame is not sent on the idle stream |
| 935 | but references the newly reserved stream in the Promised Stream |
| 936 | ID field. |
| 937 | |
| 938 | Receiving any frame other than HEADERS or PRIORITY on a stream in |
| 939 | this state MUST be treated as a connection error (Section 5.4.1) |
| 940 | of type PROTOCOL_ERROR. |
| 941 | |
| 942 | reserved (local): |
| 943 | A stream in the "reserved (local)" state is one that has been |
| 944 | promised by sending a PUSH_PROMISE frame. A PUSH_PROMISE frame |
| 945 | reserves an idle stream by associating the stream with an open |
| 946 | stream that was initiated by the remote peer (see Section 8.2). |
| 947 | |
| 948 | |
| 949 | |
| 950 | |
| 951 | |
| 952 | |
| 953 | |
| 954 | Belshe, et al. Standards Track [Page 17] |
| 955 | \f |
| 956 | RFC 7540 HTTP/2 May 2015 |
| 957 | |
| 958 | |
| 959 | In this state, only the following transitions are possible: |
| 960 | |
| 961 | * The endpoint can send a HEADERS frame. This causes the stream |
| 962 | to open in a "half-closed (remote)" state. |
| 963 | |
| 964 | * Either endpoint can send a RST_STREAM frame to cause the stream |
| 965 | to become "closed". This releases the stream reservation. |
| 966 | |
| 967 | |
| 968 | An endpoint MUST NOT send any type of frame other than HEADERS, |
| 969 | RST_STREAM, or PRIORITY in this state. |
| 970 | |
| 971 | A PRIORITY or WINDOW_UPDATE frame MAY be received in this state. |
| 972 | Receiving any type of frame other than RST_STREAM, PRIORITY, or |
| 973 | WINDOW_UPDATE on a stream in this state MUST be treated as a |
| 974 | connection error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 975 | |
| 976 | reserved (remote): |
| 977 | A stream in the "reserved (remote)" state has been reserved by a |
| 978 | remote peer. |
| 979 | |
| 980 | In this state, only the following transitions are possible: |
| 981 | |
| 982 | * Receiving a HEADERS frame causes the stream to transition to |
| 983 | "half-closed (local)". |
| 984 | |
| 985 | * Either endpoint can send a RST_STREAM frame to cause the stream |
| 986 | to become "closed". This releases the stream reservation. |
| 987 | |
| 988 | An endpoint MAY send a PRIORITY frame in this state to |
| 989 | reprioritize the reserved stream. An endpoint MUST NOT send any |
| 990 | type of frame other than RST_STREAM, WINDOW_UPDATE, or PRIORITY in |
| 991 | this state. |
| 992 | |
| 993 | Receiving any type of frame other than HEADERS, RST_STREAM, or |
| 994 | PRIORITY on a stream in this state MUST be treated as a connection |
| 995 | error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 996 | |
| 997 | open: |
| 998 | A stream in the "open" state may be used by both peers to send |
| 999 | frames of any type. In this state, sending peers observe |
| 1000 | advertised stream-level flow-control limits (Section 5.2). |
| 1001 | |
| 1002 | From this state, either endpoint can send a frame with an |
| 1003 | END_STREAM flag set, which causes the stream to transition into |
| 1004 | one of the "half-closed" states. An endpoint sending an |
| 1005 | |
| 1006 | |
| 1007 | |
| 1008 | |
| 1009 | |
| 1010 | Belshe, et al. Standards Track [Page 18] |
| 1011 | \f |
| 1012 | RFC 7540 HTTP/2 May 2015 |
| 1013 | |
| 1014 | |
| 1015 | END_STREAM flag causes the stream state to become "half-closed |
| 1016 | (local)"; an endpoint receiving an END_STREAM flag causes the |
| 1017 | stream state to become "half-closed (remote)". |
| 1018 | |
| 1019 | Either endpoint can send a RST_STREAM frame from this state, |
| 1020 | causing it to transition immediately to "closed". |
| 1021 | |
| 1022 | half-closed (local): |
| 1023 | A stream that is in the "half-closed (local)" state cannot be used |
| 1024 | for sending frames other than WINDOW_UPDATE, PRIORITY, and |
| 1025 | RST_STREAM. |
| 1026 | |
| 1027 | A stream transitions from this state to "closed" when a frame that |
| 1028 | contains an END_STREAM flag is received or when either peer sends |
| 1029 | a RST_STREAM frame. |
| 1030 | |
| 1031 | An endpoint can receive any type of frame in this state. |
| 1032 | Providing flow-control credit using WINDOW_UPDATE frames is |
| 1033 | necessary to continue receiving flow-controlled frames. In this |
| 1034 | state, a receiver can ignore WINDOW_UPDATE frames, which might |
| 1035 | arrive for a short period after a frame bearing the END_STREAM |
| 1036 | flag is sent. |
| 1037 | |
| 1038 | PRIORITY frames received in this state are used to reprioritize |
| 1039 | streams that depend on the identified stream. |
| 1040 | |
| 1041 | half-closed (remote): |
| 1042 | A stream that is "half-closed (remote)" is no longer being used by |
| 1043 | the peer to send frames. In this state, an endpoint is no longer |
| 1044 | obligated to maintain a receiver flow-control window. |
| 1045 | |
| 1046 | If an endpoint receives additional frames, other than |
| 1047 | WINDOW_UPDATE, PRIORITY, or RST_STREAM, for a stream that is in |
| 1048 | this state, it MUST respond with a stream error (Section 5.4.2) of |
| 1049 | type STREAM_CLOSED. |
| 1050 | |
| 1051 | A stream that is "half-closed (remote)" can be used by the |
| 1052 | endpoint to send frames of any type. In this state, the endpoint |
| 1053 | continues to observe advertised stream-level flow-control limits |
| 1054 | (Section 5.2). |
| 1055 | |
| 1056 | A stream can transition from this state to "closed" by sending a |
| 1057 | frame that contains an END_STREAM flag or when either peer sends a |
| 1058 | RST_STREAM frame. |
| 1059 | |
| 1060 | |
| 1061 | |
| 1062 | |
| 1063 | |
| 1064 | |
| 1065 | |
| 1066 | Belshe, et al. Standards Track [Page 19] |
| 1067 | \f |
| 1068 | RFC 7540 HTTP/2 May 2015 |
| 1069 | |
| 1070 | |
| 1071 | closed: |
| 1072 | The "closed" state is the terminal state. |
| 1073 | |
| 1074 | An endpoint MUST NOT send frames other than PRIORITY on a closed |
| 1075 | stream. An endpoint that receives any frame other than PRIORITY |
| 1076 | after receiving a RST_STREAM MUST treat that as a stream error |
| 1077 | (Section 5.4.2) of type STREAM_CLOSED. Similarly, an endpoint |
| 1078 | that receives any frames after receiving a frame with the |
| 1079 | END_STREAM flag set MUST treat that as a connection error |
| 1080 | (Section 5.4.1) of type STREAM_CLOSED, unless the frame is |
| 1081 | permitted as described below. |
| 1082 | |
| 1083 | WINDOW_UPDATE or RST_STREAM frames can be received in this state |
| 1084 | for a short period after a DATA or HEADERS frame containing an |
| 1085 | END_STREAM flag is sent. Until the remote peer receives and |
| 1086 | processes RST_STREAM or the frame bearing the END_STREAM flag, it |
| 1087 | might send frames of these types. Endpoints MUST ignore |
| 1088 | WINDOW_UPDATE or RST_STREAM frames received in this state, though |
| 1089 | endpoints MAY choose to treat frames that arrive a significant |
| 1090 | time after sending END_STREAM as a connection error |
| 1091 | (Section 5.4.1) of type PROTOCOL_ERROR. |
| 1092 | |
| 1093 | PRIORITY frames can be sent on closed streams to prioritize |
| 1094 | streams that are dependent on the closed stream. Endpoints SHOULD |
| 1095 | process PRIORITY frames, though they can be ignored if the stream |
| 1096 | has been removed from the dependency tree (see Section 5.3.4). |
| 1097 | |
| 1098 | If this state is reached as a result of sending a RST_STREAM |
| 1099 | frame, the peer that receives the RST_STREAM might have already |
| 1100 | sent -- or enqueued for sending -- frames on the stream that |
| 1101 | cannot be withdrawn. An endpoint MUST ignore frames that it |
| 1102 | receives on closed streams after it has sent a RST_STREAM frame. |
| 1103 | An endpoint MAY choose to limit the period over which it ignores |
| 1104 | frames and treat frames that arrive after this time as being in |
| 1105 | error. |
| 1106 | |
| 1107 | Flow-controlled frames (i.e., DATA) received after sending |
| 1108 | RST_STREAM are counted toward the connection flow-control window. |
| 1109 | Even though these frames might be ignored, because they are sent |
| 1110 | before the sender receives the RST_STREAM, the sender will |
| 1111 | consider the frames to count against the flow-control window. |
| 1112 | |
| 1113 | An endpoint might receive a PUSH_PROMISE frame after it sends |
| 1114 | RST_STREAM. PUSH_PROMISE causes a stream to become "reserved" |
| 1115 | even if the associated stream has been reset. Therefore, a |
| 1116 | RST_STREAM is needed to close an unwanted promised stream. |
| 1117 | |
| 1118 | |
| 1119 | |
| 1120 | |
| 1121 | |
| 1122 | Belshe, et al. Standards Track [Page 20] |
| 1123 | \f |
| 1124 | RFC 7540 HTTP/2 May 2015 |
| 1125 | |
| 1126 | |
| 1127 | In the absence of more specific guidance elsewhere in this document, |
| 1128 | implementations SHOULD treat the receipt of a frame that is not |
| 1129 | expressly permitted in the description of a state as a connection |
| 1130 | error (Section 5.4.1) of type PROTOCOL_ERROR. Note that PRIORITY can |
| 1131 | be sent and received in any stream state. Frames of unknown types |
| 1132 | are ignored. |
| 1133 | |
| 1134 | An example of the state transitions for an HTTP request/response |
| 1135 | exchange can be found in Section 8.1. An example of the state |
| 1136 | transitions for server push can be found in Sections 8.2.1 and 8.2.2. |
| 1137 | |
| 1138 | 5.1.1. Stream Identifiers |
| 1139 | |
| 1140 | Streams are identified with an unsigned 31-bit integer. Streams |
| 1141 | initiated by a client MUST use odd-numbered stream identifiers; those |
| 1142 | initiated by the server MUST use even-numbered stream identifiers. A |
| 1143 | stream identifier of zero (0x0) is used for connection control |
| 1144 | messages; the stream identifier of zero cannot be used to establish a |
| 1145 | new stream. |
| 1146 | |
| 1147 | HTTP/1.1 requests that are upgraded to HTTP/2 (see Section 3.2) are |
| 1148 | responded to with a stream identifier of one (0x1). After the |
| 1149 | upgrade completes, stream 0x1 is "half-closed (local)" to the client. |
| 1150 | Therefore, stream 0x1 cannot be selected as a new stream identifier |
| 1151 | by a client that upgrades from HTTP/1.1. |
| 1152 | |
| 1153 | The identifier of a newly established stream MUST be numerically |
| 1154 | greater than all streams that the initiating endpoint has opened or |
| 1155 | reserved. This governs streams that are opened using a HEADERS frame |
| 1156 | and streams that are reserved using PUSH_PROMISE. An endpoint that |
| 1157 | receives an unexpected stream identifier MUST respond with a |
| 1158 | connection error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 1159 | |
| 1160 | The first use of a new stream identifier implicitly closes all |
| 1161 | streams in the "idle" state that might have been initiated by that |
| 1162 | peer with a lower-valued stream identifier. For example, if a client |
| 1163 | sends a HEADERS frame on stream 7 without ever sending a frame on |
| 1164 | stream 5, then stream 5 transitions to the "closed" state when the |
| 1165 | first frame for stream 7 is sent or received. |
| 1166 | |
| 1167 | Stream identifiers cannot be reused. Long-lived connections can |
| 1168 | result in an endpoint exhausting the available range of stream |
| 1169 | identifiers. A client that is unable to establish a new stream |
| 1170 | identifier can establish a new connection for new streams. A server |
| 1171 | that is unable to establish a new stream identifier can send a GOAWAY |
| 1172 | frame so that the client is forced to open a new connection for new |
| 1173 | streams. |
| 1174 | |
| 1175 | |
| 1176 | |
| 1177 | |
| 1178 | Belshe, et al. Standards Track [Page 21] |
| 1179 | \f |
| 1180 | RFC 7540 HTTP/2 May 2015 |
| 1181 | |
| 1182 | |
| 1183 | 5.1.2. Stream Concurrency |
| 1184 | |
| 1185 | A peer can limit the number of concurrently active streams using the |
| 1186 | SETTINGS_MAX_CONCURRENT_STREAMS parameter (see Section 6.5.2) within |
| 1187 | a SETTINGS frame. The maximum concurrent streams setting is specific |
| 1188 | to each endpoint and applies only to the peer that receives the |
| 1189 | setting. That is, clients specify the maximum number of concurrent |
| 1190 | streams the server can initiate, and servers specify the maximum |
| 1191 | number of concurrent streams the client can initiate. |
| 1192 | |
| 1193 | Streams that are in the "open" state or in either of the "half- |
| 1194 | closed" states count toward the maximum number of streams that an |
| 1195 | endpoint is permitted to open. Streams in any of these three states |
| 1196 | count toward the limit advertised in the |
| 1197 | SETTINGS_MAX_CONCURRENT_STREAMS setting. Streams in either of the |
| 1198 | "reserved" states do not count toward the stream limit. |
| 1199 | |
| 1200 | Endpoints MUST NOT exceed the limit set by their peer. An endpoint |
| 1201 | that receives a HEADERS frame that causes its advertised concurrent |
| 1202 | stream limit to be exceeded MUST treat this as a stream error |
| 1203 | (Section 5.4.2) of type PROTOCOL_ERROR or REFUSED_STREAM. The choice |
| 1204 | of error code determines whether the endpoint wishes to enable |
| 1205 | automatic retry (see Section 8.1.4) for details). |
| 1206 | |
| 1207 | An endpoint that wishes to reduce the value of |
| 1208 | SETTINGS_MAX_CONCURRENT_STREAMS to a value that is below the current |
| 1209 | number of open streams can either close streams that exceed the new |
| 1210 | value or allow streams to complete. |
| 1211 | |
| 1212 | 5.2. Flow Control |
| 1213 | |
| 1214 | Using streams for multiplexing introduces contention over use of the |
| 1215 | TCP connection, resulting in blocked streams. A flow-control scheme |
| 1216 | ensures that streams on the same connection do not destructively |
| 1217 | interfere with each other. Flow control is used for both individual |
| 1218 | streams and for the connection as a whole. |
| 1219 | |
| 1220 | HTTP/2 provides for flow control through use of the WINDOW_UPDATE |
| 1221 | frame (Section 6.9). |
| 1222 | |
| 1223 | |
| 1224 | |
| 1225 | |
| 1226 | |
| 1227 | |
| 1228 | |
| 1229 | |
| 1230 | |
| 1231 | |
| 1232 | |
| 1233 | |
| 1234 | Belshe, et al. Standards Track [Page 22] |
| 1235 | \f |
| 1236 | RFC 7540 HTTP/2 May 2015 |
| 1237 | |
| 1238 | |
| 1239 | 5.2.1. Flow-Control Principles |
| 1240 | |
| 1241 | HTTP/2 stream flow control aims to allow a variety of flow-control |
| 1242 | algorithms to be used without requiring protocol changes. Flow |
| 1243 | control in HTTP/2 has the following characteristics: |
| 1244 | |
| 1245 | 1. Flow control is specific to a connection. Both types of flow |
| 1246 | control are between the endpoints of a single hop and not over |
| 1247 | the entire end-to-end path. |
| 1248 | |
| 1249 | 2. Flow control is based on WINDOW_UPDATE frames. Receivers |
| 1250 | advertise how many octets they are prepared to receive on a |
| 1251 | stream and for the entire connection. This is a credit-based |
| 1252 | scheme. |
| 1253 | |
| 1254 | 3. Flow control is directional with overall control provided by the |
| 1255 | receiver. A receiver MAY choose to set any window size that it |
| 1256 | desires for each stream and for the entire connection. A sender |
| 1257 | MUST respect flow-control limits imposed by a receiver. Clients, |
| 1258 | servers, and intermediaries all independently advertise their |
| 1259 | flow-control window as a receiver and abide by the flow-control |
| 1260 | limits set by their peer when sending. |
| 1261 | |
| 1262 | 4. The initial value for the flow-control window is 65,535 octets |
| 1263 | for both new streams and the overall connection. |
| 1264 | |
| 1265 | 5. The frame type determines whether flow control applies to a |
| 1266 | frame. Of the frames specified in this document, only DATA |
| 1267 | frames are subject to flow control; all other frame types do not |
| 1268 | consume space in the advertised flow-control window. This |
| 1269 | ensures that important control frames are not blocked by flow |
| 1270 | control. |
| 1271 | |
| 1272 | 6. Flow control cannot be disabled. |
| 1273 | |
| 1274 | 7. HTTP/2 defines only the format and semantics of the WINDOW_UPDATE |
| 1275 | frame (Section 6.9). This document does not stipulate how a |
| 1276 | receiver decides when to send this frame or the value that it |
| 1277 | sends, nor does it specify how a sender chooses to send packets. |
| 1278 | Implementations are able to select any algorithm that suits their |
| 1279 | needs. |
| 1280 | |
| 1281 | Implementations are also responsible for managing how requests and |
| 1282 | responses are sent based on priority, choosing how to avoid head-of- |
| 1283 | line blocking for requests, and managing the creation of new streams. |
| 1284 | Algorithm choices for these could interact with any flow-control |
| 1285 | algorithm. |
| 1286 | |
| 1287 | |
| 1288 | |
| 1289 | |
| 1290 | Belshe, et al. Standards Track [Page 23] |
| 1291 | \f |
| 1292 | RFC 7540 HTTP/2 May 2015 |
| 1293 | |
| 1294 | |
| 1295 | 5.2.2. Appropriate Use of Flow Control |
| 1296 | |
| 1297 | Flow control is defined to protect endpoints that are operating under |
| 1298 | resource constraints. For example, a proxy needs to share memory |
| 1299 | between many connections and also might have a slow upstream |
| 1300 | connection and a fast downstream one. Flow-control addresses cases |
| 1301 | where the receiver is unable to process data on one stream yet wants |
| 1302 | to continue to process other streams in the same connection. |
| 1303 | |
| 1304 | Deployments that do not require this capability can advertise a flow- |
| 1305 | control window of the maximum size (2^31-1) and can maintain this |
| 1306 | window by sending a WINDOW_UPDATE frame when any data is received. |
| 1307 | This effectively disables flow control for that receiver. |
| 1308 | Conversely, a sender is always subject to the flow-control window |
| 1309 | advertised by the receiver. |
| 1310 | |
| 1311 | Deployments with constrained resources (for example, memory) can |
| 1312 | employ flow control to limit the amount of memory a peer can consume. |
| 1313 | Note, however, that this can lead to suboptimal use of available |
| 1314 | network resources if flow control is enabled without knowledge of the |
| 1315 | bandwidth-delay product (see [RFC7323]). |
| 1316 | |
| 1317 | Even with full awareness of the current bandwidth-delay product, |
| 1318 | implementation of flow control can be difficult. When using flow |
| 1319 | control, the receiver MUST read from the TCP receive buffer in a |
| 1320 | timely fashion. Failure to do so could lead to a deadlock when |
| 1321 | critical frames, such as WINDOW_UPDATE, are not read and acted upon. |
| 1322 | |
| 1323 | 5.3. Stream Priority |
| 1324 | |
| 1325 | A client can assign a priority for a new stream by including |
| 1326 | prioritization information in the HEADERS frame (Section 6.2) that |
| 1327 | opens the stream. At any other time, the PRIORITY frame |
| 1328 | (Section 6.3) can be used to change the priority of a stream. |
| 1329 | |
| 1330 | The purpose of prioritization is to allow an endpoint to express how |
| 1331 | it would prefer its peer to allocate resources when managing |
| 1332 | concurrent streams. Most importantly, priority can be used to select |
| 1333 | streams for transmitting frames when there is limited capacity for |
| 1334 | sending. |
| 1335 | |
| 1336 | Streams can be prioritized by marking them as dependent on the |
| 1337 | completion of other streams (Section 5.3.1). Each dependency is |
| 1338 | assigned a relative weight, a number that is used to determine the |
| 1339 | relative proportion of available resources that are assigned to |
| 1340 | streams dependent on the same stream. |
| 1341 | |
| 1342 | |
| 1343 | |
| 1344 | |
| 1345 | |
| 1346 | Belshe, et al. Standards Track [Page 24] |
| 1347 | \f |
| 1348 | RFC 7540 HTTP/2 May 2015 |
| 1349 | |
| 1350 | |
| 1351 | Explicitly setting the priority for a stream is input to a |
| 1352 | prioritization process. It does not guarantee any particular |
| 1353 | processing or transmission order for the stream relative to any other |
| 1354 | stream. An endpoint cannot force a peer to process concurrent |
| 1355 | streams in a particular order using priority. Expressing priority is |
| 1356 | therefore only a suggestion. |
| 1357 | |
| 1358 | Prioritization information can be omitted from messages. Defaults |
| 1359 | are used prior to any explicit values being provided (Section 5.3.5). |
| 1360 | |
| 1361 | 5.3.1. Stream Dependencies |
| 1362 | |
| 1363 | Each stream can be given an explicit dependency on another stream. |
| 1364 | Including a dependency expresses a preference to allocate resources |
| 1365 | to the identified stream rather than to the dependent stream. |
| 1366 | |
| 1367 | A stream that is not dependent on any other stream is given a stream |
| 1368 | dependency of 0x0. In other words, the non-existent stream 0 forms |
| 1369 | the root of the tree. |
| 1370 | |
| 1371 | A stream that depends on another stream is a dependent stream. The |
| 1372 | stream upon which a stream is dependent is a parent stream. A |
| 1373 | dependency on a stream that is not currently in the tree -- such as a |
| 1374 | stream in the "idle" state -- results in that stream being given a |
| 1375 | default priority (Section 5.3.5). |
| 1376 | |
| 1377 | When assigning a dependency on another stream, the stream is added as |
| 1378 | a new dependency of the parent stream. Dependent streams that share |
| 1379 | the same parent are not ordered with respect to each other. For |
| 1380 | example, if streams B and C are dependent on stream A, and if stream |
| 1381 | D is created with a dependency on stream A, this results in a |
| 1382 | dependency order of A followed by B, C, and D in any order. |
| 1383 | |
| 1384 | A A |
| 1385 | / \ ==> /|\ |
| 1386 | B C B D C |
| 1387 | |
| 1388 | Figure 3: Example of Default Dependency Creation |
| 1389 | |
| 1390 | An exclusive flag allows for the insertion of a new level of |
| 1391 | dependencies. The exclusive flag causes the stream to become the |
| 1392 | sole dependency of its parent stream, causing other dependencies to |
| 1393 | become dependent on the exclusive stream. In the previous example, |
| 1394 | if stream D is created with an exclusive dependency on stream A, this |
| 1395 | results in D becoming the dependency parent of B and C. |
| 1396 | |
| 1397 | |
| 1398 | |
| 1399 | |
| 1400 | |
| 1401 | |
| 1402 | Belshe, et al. Standards Track [Page 25] |
| 1403 | \f |
| 1404 | RFC 7540 HTTP/2 May 2015 |
| 1405 | |
| 1406 | |
| 1407 | A |
| 1408 | A | |
| 1409 | / \ ==> D |
| 1410 | B C / \ |
| 1411 | B C |
| 1412 | |
| 1413 | Figure 4: Example of Exclusive Dependency Creation |
| 1414 | |
| 1415 | Inside the dependency tree, a dependent stream SHOULD only be |
| 1416 | allocated resources if either all of the streams that it depends on |
| 1417 | (the chain of parent streams up to 0x0) are closed or it is not |
| 1418 | possible to make progress on them. |
| 1419 | |
| 1420 | A stream cannot depend on itself. An endpoint MUST treat this as a |
| 1421 | stream error (Section 5.4.2) of type PROTOCOL_ERROR. |
| 1422 | |
| 1423 | 5.3.2. Dependency Weighting |
| 1424 | |
| 1425 | All dependent streams are allocated an integer weight between 1 and |
| 1426 | 256 (inclusive). |
| 1427 | |
| 1428 | Streams with the same parent SHOULD be allocated resources |
| 1429 | proportionally based on their weight. Thus, if stream B depends on |
| 1430 | stream A with weight 4, stream C depends on stream A with weight 12, |
| 1431 | and no progress can be made on stream A, stream B ideally receives |
| 1432 | one-third of the resources allocated to stream C. |
| 1433 | |
| 1434 | 5.3.3. Reprioritization |
| 1435 | |
| 1436 | Stream priorities are changed using the PRIORITY frame. Setting a |
| 1437 | dependency causes a stream to become dependent on the identified |
| 1438 | parent stream. |
| 1439 | |
| 1440 | Dependent streams move with their parent stream if the parent is |
| 1441 | reprioritized. Setting a dependency with the exclusive flag for a |
| 1442 | reprioritized stream causes all the dependencies of the new parent |
| 1443 | stream to become dependent on the reprioritized stream. |
| 1444 | |
| 1445 | If a stream is made dependent on one of its own dependencies, the |
| 1446 | formerly dependent stream is first moved to be dependent on the |
| 1447 | reprioritized stream's previous parent. The moved dependency retains |
| 1448 | its weight. |
| 1449 | |
| 1450 | For example, consider an original dependency tree where B and C |
| 1451 | depend on A, D and E depend on C, and F depends on D. If A is made |
| 1452 | dependent on D, then D takes the place of A. All other dependency |
| 1453 | relationships stay the same, except for F, which becomes dependent on |
| 1454 | A if the reprioritization is exclusive. |
| 1455 | |
| 1456 | |
| 1457 | |
| 1458 | Belshe, et al. Standards Track [Page 26] |
| 1459 | \f |
| 1460 | RFC 7540 HTTP/2 May 2015 |
| 1461 | |
| 1462 | |
| 1463 | x x x x |
| 1464 | | / \ | | |
| 1465 | A D A D D |
| 1466 | / \ / / \ / \ | |
| 1467 | B C ==> F B C ==> F A OR A |
| 1468 | / \ | / \ /|\ |
| 1469 | D E E B C B C F |
| 1470 | | | | |
| 1471 | F E E |
| 1472 | (intermediate) (non-exclusive) (exclusive) |
| 1473 | |
| 1474 | Figure 5: Example of Dependency Reordering |
| 1475 | |
| 1476 | 5.3.4. Prioritization State Management |
| 1477 | |
| 1478 | When a stream is removed from the dependency tree, its dependencies |
| 1479 | can be moved to become dependent on the parent of the closed stream. |
| 1480 | The weights of new dependencies are recalculated by distributing the |
| 1481 | weight of the dependency of the closed stream proportionally based on |
| 1482 | the weights of its dependencies. |
| 1483 | |
| 1484 | Streams that are removed from the dependency tree cause some |
| 1485 | prioritization information to be lost. Resources are shared between |
| 1486 | streams with the same parent stream, which means that if a stream in |
| 1487 | that set closes or becomes blocked, any spare capacity allocated to a |
| 1488 | stream is distributed to the immediate neighbors of the stream. |
| 1489 | However, if the common dependency is removed from the tree, those |
| 1490 | streams share resources with streams at the next highest level. |
| 1491 | |
| 1492 | For example, assume streams A and B share a parent, and streams C and |
| 1493 | D both depend on stream A. Prior to the removal of stream A, if |
| 1494 | streams A and D are unable to proceed, then stream C receives all the |
| 1495 | resources dedicated to stream A. If stream A is removed from the |
| 1496 | tree, the weight of stream A is divided between streams C and D. If |
| 1497 | stream D is still unable to proceed, this results in stream C |
| 1498 | receiving a reduced proportion of resources. For equal starting |
| 1499 | weights, C receives one third, rather than one half, of available |
| 1500 | resources. |
| 1501 | |
| 1502 | It is possible for a stream to become closed while prioritization |
| 1503 | information that creates a dependency on that stream is in transit. |
| 1504 | If a stream identified in a dependency has no associated priority |
| 1505 | information, then the dependent stream is instead assigned a default |
| 1506 | priority (Section 5.3.5). This potentially creates suboptimal |
| 1507 | prioritization, since the stream could be given a priority that is |
| 1508 | different from what is intended. |
| 1509 | |
| 1510 | |
| 1511 | |
| 1512 | |
| 1513 | |
| 1514 | Belshe, et al. Standards Track [Page 27] |
| 1515 | \f |
| 1516 | RFC 7540 HTTP/2 May 2015 |
| 1517 | |
| 1518 | |
| 1519 | To avoid these problems, an endpoint SHOULD retain stream |
| 1520 | prioritization state for a period after streams become closed. The |
| 1521 | longer state is retained, the lower the chance that streams are |
| 1522 | assigned incorrect or default priority values. |
| 1523 | |
| 1524 | Similarly, streams that are in the "idle" state can be assigned |
| 1525 | priority or become a parent of other streams. This allows for the |
| 1526 | creation of a grouping node in the dependency tree, which enables |
| 1527 | more flexible expressions of priority. Idle streams begin with a |
| 1528 | default priority (Section 5.3.5). |
| 1529 | |
| 1530 | The retention of priority information for streams that are not |
| 1531 | counted toward the limit set by SETTINGS_MAX_CONCURRENT_STREAMS could |
| 1532 | create a large state burden for an endpoint. Therefore, the amount |
| 1533 | of prioritization state that is retained MAY be limited. |
| 1534 | |
| 1535 | The amount of additional state an endpoint maintains for |
| 1536 | prioritization could be dependent on load; under high load, |
| 1537 | prioritization state can be discarded to limit resource commitments. |
| 1538 | In extreme cases, an endpoint could even discard prioritization state |
| 1539 | for active or reserved streams. If a limit is applied, endpoints |
| 1540 | SHOULD maintain state for at least as many streams as allowed by |
| 1541 | their setting for SETTINGS_MAX_CONCURRENT_STREAMS. Implementations |
| 1542 | SHOULD also attempt to retain state for streams that are in active |
| 1543 | use in the priority tree. |
| 1544 | |
| 1545 | If it has retained enough state to do so, an endpoint receiving a |
| 1546 | PRIORITY frame that changes the priority of a closed stream SHOULD |
| 1547 | alter the dependencies of the streams that depend on it. |
| 1548 | |
| 1549 | 5.3.5. Default Priorities |
| 1550 | |
| 1551 | All streams are initially assigned a non-exclusive dependency on |
| 1552 | stream 0x0. Pushed streams (Section 8.2) initially depend on their |
| 1553 | associated stream. In both cases, streams are assigned a default |
| 1554 | weight of 16. |
| 1555 | |
| 1556 | 5.4. Error Handling |
| 1557 | |
| 1558 | HTTP/2 framing permits two classes of error: |
| 1559 | |
| 1560 | o An error condition that renders the entire connection unusable is |
| 1561 | a connection error. |
| 1562 | |
| 1563 | o An error in an individual stream is a stream error. |
| 1564 | |
| 1565 | A list of error codes is included in Section 7. |
| 1566 | |
| 1567 | |
| 1568 | |
| 1569 | |
| 1570 | Belshe, et al. Standards Track [Page 28] |
| 1571 | \f |
| 1572 | RFC 7540 HTTP/2 May 2015 |
| 1573 | |
| 1574 | |
| 1575 | 5.4.1. Connection Error Handling |
| 1576 | |
| 1577 | A connection error is any error that prevents further processing of |
| 1578 | the frame layer or corrupts any connection state. |
| 1579 | |
| 1580 | An endpoint that encounters a connection error SHOULD first send a |
| 1581 | GOAWAY frame (Section 6.8) with the stream identifier of the last |
| 1582 | stream that it successfully received from its peer. The GOAWAY frame |
| 1583 | includes an error code that indicates why the connection is |
| 1584 | terminating. After sending the GOAWAY frame for an error condition, |
| 1585 | the endpoint MUST close the TCP connection. |
| 1586 | |
| 1587 | It is possible that the GOAWAY will not be reliably received by the |
| 1588 | receiving endpoint ([RFC7230], Section 6.6 describes how an immediate |
| 1589 | connection close can result in data loss). In the event of a |
| 1590 | connection error, GOAWAY only provides a best-effort attempt to |
| 1591 | communicate with the peer about why the connection is being |
| 1592 | terminated. |
| 1593 | |
| 1594 | An endpoint can end a connection at any time. In particular, an |
| 1595 | endpoint MAY choose to treat a stream error as a connection error. |
| 1596 | Endpoints SHOULD send a GOAWAY frame when ending a connection, |
| 1597 | providing that circumstances permit it. |
| 1598 | |
| 1599 | 5.4.2. Stream Error Handling |
| 1600 | |
| 1601 | A stream error is an error related to a specific stream that does not |
| 1602 | affect processing of other streams. |
| 1603 | |
| 1604 | An endpoint that detects a stream error sends a RST_STREAM frame |
| 1605 | (Section 6.4) that contains the stream identifier of the stream where |
| 1606 | the error occurred. The RST_STREAM frame includes an error code that |
| 1607 | indicates the type of error. |
| 1608 | |
| 1609 | A RST_STREAM is the last frame that an endpoint can send on a stream. |
| 1610 | The peer that sends the RST_STREAM frame MUST be prepared to receive |
| 1611 | any frames that were sent or enqueued for sending by the remote peer. |
| 1612 | These frames can be ignored, except where they modify connection |
| 1613 | state (such as the state maintained for header compression |
| 1614 | (Section 4.3) or flow control). |
| 1615 | |
| 1616 | Normally, an endpoint SHOULD NOT send more than one RST_STREAM frame |
| 1617 | for any stream. However, an endpoint MAY send additional RST_STREAM |
| 1618 | frames if it receives frames on a closed stream after more than a |
| 1619 | round-trip time. This behavior is permitted to deal with misbehaving |
| 1620 | implementations. |
| 1621 | |
| 1622 | |
| 1623 | |
| 1624 | |
| 1625 | |
| 1626 | Belshe, et al. Standards Track [Page 29] |
| 1627 | \f |
| 1628 | RFC 7540 HTTP/2 May 2015 |
| 1629 | |
| 1630 | |
| 1631 | To avoid looping, an endpoint MUST NOT send a RST_STREAM in response |
| 1632 | to a RST_STREAM frame. |
| 1633 | |
| 1634 | 5.4.3. Connection Termination |
| 1635 | |
| 1636 | If the TCP connection is closed or reset while streams remain in |
| 1637 | "open" or "half-closed" state, then the affected streams cannot be |
| 1638 | automatically retried (see Section 8.1.4 for details). |
| 1639 | |
| 1640 | 5.5. Extending HTTP/2 |
| 1641 | |
| 1642 | HTTP/2 permits extension of the protocol. Within the limitations |
| 1643 | described in this section, protocol extensions can be used to provide |
| 1644 | additional services or alter any aspect of the protocol. Extensions |
| 1645 | are effective only within the scope of a single HTTP/2 connection. |
| 1646 | |
| 1647 | This applies to the protocol elements defined in this document. This |
| 1648 | does not affect the existing options for extending HTTP, such as |
| 1649 | defining new methods, status codes, or header fields. |
| 1650 | |
| 1651 | Extensions are permitted to use new frame types (Section 4.1), new |
| 1652 | settings (Section 6.5.2), or new error codes (Section 7). Registries |
| 1653 | are established for managing these extension points: frame types |
| 1654 | (Section 11.2), settings (Section 11.3), and error codes |
| 1655 | (Section 11.4). |
| 1656 | |
| 1657 | Implementations MUST ignore unknown or unsupported values in all |
| 1658 | extensible protocol elements. Implementations MUST discard frames |
| 1659 | that have unknown or unsupported types. This means that any of these |
| 1660 | extension points can be safely used by extensions without prior |
| 1661 | arrangement or negotiation. However, extension frames that appear in |
| 1662 | the middle of a header block (Section 4.3) are not permitted; these |
| 1663 | MUST be treated as a connection error (Section 5.4.1) of type |
| 1664 | PROTOCOL_ERROR. |
| 1665 | |
| 1666 | Extensions that could change the semantics of existing protocol |
| 1667 | components MUST be negotiated before being used. For example, an |
| 1668 | extension that changes the layout of the HEADERS frame cannot be used |
| 1669 | until the peer has given a positive signal that this is acceptable. |
| 1670 | In this case, it could also be necessary to coordinate when the |
| 1671 | revised layout comes into effect. Note that treating any frames |
| 1672 | other than DATA frames as flow controlled is such a change in |
| 1673 | semantics and can only be done through negotiation. |
| 1674 | |
| 1675 | This document doesn't mandate a specific method for negotiating the |
| 1676 | use of an extension but notes that a setting (Section 6.5.2) could be |
| 1677 | used for that purpose. If both peers set a value that indicates |
| 1678 | willingness to use the extension, then the extension can be used. If |
| 1679 | |
| 1680 | |
| 1681 | |
| 1682 | Belshe, et al. Standards Track [Page 30] |
| 1683 | \f |
| 1684 | RFC 7540 HTTP/2 May 2015 |
| 1685 | |
| 1686 | |
| 1687 | a setting is used for extension negotiation, the initial value MUST |
| 1688 | be defined in such a fashion that the extension is initially |
| 1689 | disabled. |
| 1690 | |
| 1691 | 6. Frame Definitions |
| 1692 | |
| 1693 | This specification defines a number of frame types, each identified |
| 1694 | by a unique 8-bit type code. Each frame type serves a distinct |
| 1695 | purpose in the establishment and management either of the connection |
| 1696 | as a whole or of individual streams. |
| 1697 | |
| 1698 | The transmission of specific frame types can alter the state of a |
| 1699 | connection. If endpoints fail to maintain a synchronized view of the |
| 1700 | connection state, successful communication within the connection will |
| 1701 | no longer be possible. Therefore, it is important that endpoints |
| 1702 | have a shared comprehension of how the state is affected by the use |
| 1703 | any given frame. |
| 1704 | |
| 1705 | 6.1. DATA |
| 1706 | |
| 1707 | DATA frames (type=0x0) convey arbitrary, variable-length sequences of |
| 1708 | octets associated with a stream. One or more DATA frames are used, |
| 1709 | for instance, to carry HTTP request or response payloads. |
| 1710 | |
| 1711 | DATA frames MAY also contain padding. Padding can be added to DATA |
| 1712 | frames to obscure the size of messages. Padding is a security |
| 1713 | feature; see Section 10.7. |
| 1714 | |
| 1715 | +---------------+ |
| 1716 | |Pad Length? (8)| |
| 1717 | +---------------+-----------------------------------------------+ |
| 1718 | | Data (*) ... |
| 1719 | +---------------------------------------------------------------+ |
| 1720 | | Padding (*) ... |
| 1721 | +---------------------------------------------------------------+ |
| 1722 | |
| 1723 | Figure 6: DATA Frame Payload |
| 1724 | |
| 1725 | The DATA frame contains the following fields: |
| 1726 | |
| 1727 | Pad Length: An 8-bit field containing the length of the frame |
| 1728 | padding in units of octets. This field is conditional (as |
| 1729 | signified by a "?" in the diagram) and is only present if the |
| 1730 | PADDED flag is set. |
| 1731 | |
| 1732 | Data: Application data. The amount of data is the remainder of the |
| 1733 | frame payload after subtracting the length of the other fields |
| 1734 | that are present. |
| 1735 | |
| 1736 | |
| 1737 | |
| 1738 | Belshe, et al. Standards Track [Page 31] |
| 1739 | \f |
| 1740 | RFC 7540 HTTP/2 May 2015 |
| 1741 | |
| 1742 | |
| 1743 | Padding: Padding octets that contain no application semantic value. |
| 1744 | Padding octets MUST be set to zero when sending. A receiver is |
| 1745 | not obligated to verify padding but MAY treat non-zero padding as |
| 1746 | a connection error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 1747 | |
| 1748 | The DATA frame defines the following flags: |
| 1749 | |
| 1750 | END_STREAM (0x1): When set, bit 0 indicates that this frame is the |
| 1751 | last that the endpoint will send for the identified stream. |
| 1752 | Setting this flag causes the stream to enter one of the "half- |
| 1753 | closed" states or the "closed" state (Section 5.1). |
| 1754 | |
| 1755 | PADDED (0x8): When set, bit 3 indicates that the Pad Length field |
| 1756 | and any padding that it describes are present. |
| 1757 | |
| 1758 | DATA frames MUST be associated with a stream. If a DATA frame is |
| 1759 | received whose stream identifier field is 0x0, the recipient MUST |
| 1760 | respond with a connection error (Section 5.4.1) of type |
| 1761 | PROTOCOL_ERROR. |
| 1762 | |
| 1763 | DATA frames are subject to flow control and can only be sent when a |
| 1764 | stream is in the "open" or "half-closed (remote)" state. The entire |
| 1765 | DATA frame payload is included in flow control, including the Pad |
| 1766 | Length and Padding fields if present. If a DATA frame is received |
| 1767 | whose stream is not in "open" or "half-closed (local)" state, the |
| 1768 | recipient MUST respond with a stream error (Section 5.4.2) of type |
| 1769 | STREAM_CLOSED. |
| 1770 | |
| 1771 | The total number of padding octets is determined by the value of the |
| 1772 | Pad Length field. If the length of the padding is the length of the |
| 1773 | frame payload or greater, the recipient MUST treat this as a |
| 1774 | connection error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 1775 | |
| 1776 | Note: A frame can be increased in size by one octet by including a |
| 1777 | Pad Length field with a value of zero. |
| 1778 | |
| 1779 | 6.2. HEADERS |
| 1780 | |
| 1781 | The HEADERS frame (type=0x1) is used to open a stream (Section 5.1), |
| 1782 | and additionally carries a header block fragment. HEADERS frames can |
| 1783 | be sent on a stream in the "idle", "reserved (local)", "open", or |
| 1784 | "half-closed (remote)" state. |
| 1785 | |
| 1786 | |
| 1787 | |
| 1788 | |
| 1789 | |
| 1790 | |
| 1791 | |
| 1792 | |
| 1793 | |
| 1794 | Belshe, et al. Standards Track [Page 32] |
| 1795 | \f |
| 1796 | RFC 7540 HTTP/2 May 2015 |
| 1797 | |
| 1798 | |
| 1799 | +---------------+ |
| 1800 | |Pad Length? (8)| |
| 1801 | +-+-------------+-----------------------------------------------+ |
| 1802 | |E| Stream Dependency? (31) | |
| 1803 | +-+-------------+-----------------------------------------------+ |
| 1804 | | Weight? (8) | |
| 1805 | +-+-------------+-----------------------------------------------+ |
| 1806 | | Header Block Fragment (*) ... |
| 1807 | +---------------------------------------------------------------+ |
| 1808 | | Padding (*) ... |
| 1809 | +---------------------------------------------------------------+ |
| 1810 | |
| 1811 | Figure 7: HEADERS Frame Payload |
| 1812 | |
| 1813 | The HEADERS frame payload has the following fields: |
| 1814 | |
| 1815 | Pad Length: An 8-bit field containing the length of the frame |
| 1816 | padding in units of octets. This field is only present if the |
| 1817 | PADDED flag is set. |
| 1818 | |
| 1819 | E: A single-bit flag indicating that the stream dependency is |
| 1820 | exclusive (see Section 5.3). This field is only present if the |
| 1821 | PRIORITY flag is set. |
| 1822 | |
| 1823 | Stream Dependency: A 31-bit stream identifier for the stream that |
| 1824 | this stream depends on (see Section 5.3). This field is only |
| 1825 | present if the PRIORITY flag is set. |
| 1826 | |
| 1827 | Weight: An unsigned 8-bit integer representing a priority weight for |
| 1828 | the stream (see Section 5.3). Add one to the value to obtain a |
| 1829 | weight between 1 and 256. This field is only present if the |
| 1830 | PRIORITY flag is set. |
| 1831 | |
| 1832 | Header Block Fragment: A header block fragment (Section 4.3). |
| 1833 | |
| 1834 | Padding: Padding octets. |
| 1835 | |
| 1836 | The HEADERS frame defines the following flags: |
| 1837 | |
| 1838 | END_STREAM (0x1): When set, bit 0 indicates that the header block |
| 1839 | (Section 4.3) is the last that the endpoint will send for the |
| 1840 | identified stream. |
| 1841 | |
| 1842 | A HEADERS frame carries the END_STREAM flag that signals the end |
| 1843 | of a stream. However, a HEADERS frame with the END_STREAM flag |
| 1844 | set can be followed by CONTINUATION frames on the same stream. |
| 1845 | Logically, the CONTINUATION frames are part of the HEADERS frame. |
| 1846 | |
| 1847 | |
| 1848 | |
| 1849 | |
| 1850 | Belshe, et al. Standards Track [Page 33] |
| 1851 | \f |
| 1852 | RFC 7540 HTTP/2 May 2015 |
| 1853 | |
| 1854 | |
| 1855 | END_HEADERS (0x4): When set, bit 2 indicates that this frame |
| 1856 | contains an entire header block (Section 4.3) and is not followed |
| 1857 | by any CONTINUATION frames. |
| 1858 | |
| 1859 | A HEADERS frame without the END_HEADERS flag set MUST be followed |
| 1860 | by a CONTINUATION frame for the same stream. A receiver MUST |
| 1861 | treat the receipt of any other type of frame or a frame on a |
| 1862 | different stream as a connection error (Section 5.4.1) of type |
| 1863 | PROTOCOL_ERROR. |
| 1864 | |
| 1865 | PADDED (0x8): When set, bit 3 indicates that the Pad Length field |
| 1866 | and any padding that it describes are present. |
| 1867 | |
| 1868 | PRIORITY (0x20): When set, bit 5 indicates that the Exclusive Flag |
| 1869 | (E), Stream Dependency, and Weight fields are present; see |
| 1870 | Section 5.3. |
| 1871 | |
| 1872 | The payload of a HEADERS frame contains a header block fragment |
| 1873 | (Section 4.3). A header block that does not fit within a HEADERS |
| 1874 | frame is continued in a CONTINUATION frame (Section 6.10). |
| 1875 | |
| 1876 | HEADERS frames MUST be associated with a stream. If a HEADERS frame |
| 1877 | is received whose stream identifier field is 0x0, the recipient MUST |
| 1878 | respond with a connection error (Section 5.4.1) of type |
| 1879 | PROTOCOL_ERROR. |
| 1880 | |
| 1881 | The HEADERS frame changes the connection state as described in |
| 1882 | Section 4.3. |
| 1883 | |
| 1884 | The HEADERS frame can include padding. Padding fields and flags are |
| 1885 | identical to those defined for DATA frames (Section 6.1). Padding |
| 1886 | that exceeds the size remaining for the header block fragment MUST be |
| 1887 | treated as a PROTOCOL_ERROR. |
| 1888 | |
| 1889 | Prioritization information in a HEADERS frame is logically equivalent |
| 1890 | to a separate PRIORITY frame, but inclusion in HEADERS avoids the |
| 1891 | potential for churn in stream prioritization when new streams are |
| 1892 | created. Prioritization fields in HEADERS frames subsequent to the |
| 1893 | first on a stream reprioritize the stream (Section 5.3.3). |
| 1894 | |
| 1895 | 6.3. PRIORITY |
| 1896 | |
| 1897 | The PRIORITY frame (type=0x2) specifies the sender-advised priority |
| 1898 | of a stream (Section 5.3). It can be sent in any stream state, |
| 1899 | including idle or closed streams. |
| 1900 | |
| 1901 | |
| 1902 | |
| 1903 | |
| 1904 | |
| 1905 | |
| 1906 | Belshe, et al. Standards Track [Page 34] |
| 1907 | \f |
| 1908 | RFC 7540 HTTP/2 May 2015 |
| 1909 | |
| 1910 | |
| 1911 | +-+-------------------------------------------------------------+ |
| 1912 | |E| Stream Dependency (31) | |
| 1913 | +-+-------------+-----------------------------------------------+ |
| 1914 | | Weight (8) | |
| 1915 | +-+-------------+ |
| 1916 | |
| 1917 | Figure 8: PRIORITY Frame Payload |
| 1918 | |
| 1919 | The payload of a PRIORITY frame contains the following fields: |
| 1920 | |
| 1921 | E: A single-bit flag indicating that the stream dependency is |
| 1922 | exclusive (see Section 5.3). |
| 1923 | |
| 1924 | Stream Dependency: A 31-bit stream identifier for the stream that |
| 1925 | this stream depends on (see Section 5.3). |
| 1926 | |
| 1927 | Weight: An unsigned 8-bit integer representing a priority weight for |
| 1928 | the stream (see Section 5.3). Add one to the value to obtain a |
| 1929 | weight between 1 and 256. |
| 1930 | |
| 1931 | The PRIORITY frame does not define any flags. |
| 1932 | |
| 1933 | The PRIORITY frame always identifies a stream. If a PRIORITY frame |
| 1934 | is received with a stream identifier of 0x0, the recipient MUST |
| 1935 | respond with a connection error (Section 5.4.1) of type |
| 1936 | PROTOCOL_ERROR. |
| 1937 | |
| 1938 | The PRIORITY frame can be sent on a stream in any state, though it |
| 1939 | cannot be sent between consecutive frames that comprise a single |
| 1940 | header block (Section 4.3). Note that this frame could arrive after |
| 1941 | processing or frame sending has completed, which would cause it to |
| 1942 | have no effect on the identified stream. For a stream that is in the |
| 1943 | "half-closed (remote)" or "closed" state, this frame can only affect |
| 1944 | processing of the identified stream and its dependent streams; it |
| 1945 | does not affect frame transmission on that stream. |
| 1946 | |
| 1947 | The PRIORITY frame can be sent for a stream in the "idle" or "closed" |
| 1948 | state. This allows for the reprioritization of a group of dependent |
| 1949 | streams by altering the priority of an unused or closed parent |
| 1950 | stream. |
| 1951 | |
| 1952 | A PRIORITY frame with a length other than 5 octets MUST be treated as |
| 1953 | a stream error (Section 5.4.2) of type FRAME_SIZE_ERROR. |
| 1954 | |
| 1955 | |
| 1956 | |
| 1957 | |
| 1958 | |
| 1959 | |
| 1960 | |
| 1961 | |
| 1962 | Belshe, et al. Standards Track [Page 35] |
| 1963 | \f |
| 1964 | RFC 7540 HTTP/2 May 2015 |
| 1965 | |
| 1966 | |
| 1967 | 6.4. RST_STREAM |
| 1968 | |
| 1969 | The RST_STREAM frame (type=0x3) allows for immediate termination of a |
| 1970 | stream. RST_STREAM is sent to request cancellation of a stream or to |
| 1971 | indicate that an error condition has occurred. |
| 1972 | |
| 1973 | +---------------------------------------------------------------+ |
| 1974 | | Error Code (32) | |
| 1975 | +---------------------------------------------------------------+ |
| 1976 | |
| 1977 | Figure 9: RST_STREAM Frame Payload |
| 1978 | |
| 1979 | The RST_STREAM frame contains a single unsigned, 32-bit integer |
| 1980 | identifying the error code (Section 7). The error code indicates why |
| 1981 | the stream is being terminated. |
| 1982 | |
| 1983 | The RST_STREAM frame does not define any flags. |
| 1984 | |
| 1985 | The RST_STREAM frame fully terminates the referenced stream and |
| 1986 | causes it to enter the "closed" state. After receiving a RST_STREAM |
| 1987 | on a stream, the receiver MUST NOT send additional frames for that |
| 1988 | stream, with the exception of PRIORITY. However, after sending the |
| 1989 | RST_STREAM, the sending endpoint MUST be prepared to receive and |
| 1990 | process additional frames sent on the stream that might have been |
| 1991 | sent by the peer prior to the arrival of the RST_STREAM. |
| 1992 | |
| 1993 | RST_STREAM frames MUST be associated with a stream. If a RST_STREAM |
| 1994 | frame is received with a stream identifier of 0x0, the recipient MUST |
| 1995 | treat this as a connection error (Section 5.4.1) of type |
| 1996 | PROTOCOL_ERROR. |
| 1997 | |
| 1998 | RST_STREAM frames MUST NOT be sent for a stream in the "idle" state. |
| 1999 | If a RST_STREAM frame identifying an idle stream is received, the |
| 2000 | recipient MUST treat this as a connection error (Section 5.4.1) of |
| 2001 | type PROTOCOL_ERROR. |
| 2002 | |
| 2003 | A RST_STREAM frame with a length other than 4 octets MUST be treated |
| 2004 | as a connection error (Section 5.4.1) of type FRAME_SIZE_ERROR. |
| 2005 | |
| 2006 | 6.5. SETTINGS |
| 2007 | |
| 2008 | The SETTINGS frame (type=0x4) conveys configuration parameters that |
| 2009 | affect how endpoints communicate, such as preferences and constraints |
| 2010 | on peer behavior. The SETTINGS frame is also used to acknowledge the |
| 2011 | receipt of those parameters. Individually, a SETTINGS parameter can |
| 2012 | also be referred to as a "setting". |
| 2013 | |
| 2014 | |
| 2015 | |
| 2016 | |
| 2017 | |
| 2018 | Belshe, et al. Standards Track [Page 36] |
| 2019 | \f |
| 2020 | RFC 7540 HTTP/2 May 2015 |
| 2021 | |
| 2022 | |
| 2023 | SETTINGS parameters are not negotiated; they describe characteristics |
| 2024 | of the sending peer, which are used by the receiving peer. Different |
| 2025 | values for the same parameter can be advertised by each peer. For |
| 2026 | example, a client might set a high initial flow-control window, |
| 2027 | whereas a server might set a lower value to conserve resources. |
| 2028 | |
| 2029 | A SETTINGS frame MUST be sent by both endpoints at the start of a |
| 2030 | connection and MAY be sent at any other time by either endpoint over |
| 2031 | the lifetime of the connection. Implementations MUST support all of |
| 2032 | the parameters defined by this specification. |
| 2033 | |
| 2034 | Each parameter in a SETTINGS frame replaces any existing value for |
| 2035 | that parameter. Parameters are processed in the order in which they |
| 2036 | appear, and a receiver of a SETTINGS frame does not need to maintain |
| 2037 | any state other than the current value of its parameters. Therefore, |
| 2038 | the value of a SETTINGS parameter is the last value that is seen by a |
| 2039 | receiver. |
| 2040 | |
| 2041 | SETTINGS parameters are acknowledged by the receiving peer. To |
| 2042 | enable this, the SETTINGS frame defines the following flag: |
| 2043 | |
| 2044 | ACK (0x1): When set, bit 0 indicates that this frame acknowledges |
| 2045 | receipt and application of the peer's SETTINGS frame. When this |
| 2046 | bit is set, the payload of the SETTINGS frame MUST be empty. |
| 2047 | Receipt of a SETTINGS frame with the ACK flag set and a length |
| 2048 | field value other than 0 MUST be treated as a connection error |
| 2049 | (Section 5.4.1) of type FRAME_SIZE_ERROR. For more information, |
| 2050 | see Section 6.5.3 ("Settings Synchronization"). |
| 2051 | |
| 2052 | SETTINGS frames always apply to a connection, never a single stream. |
| 2053 | The stream identifier for a SETTINGS frame MUST be zero (0x0). If an |
| 2054 | endpoint receives a SETTINGS frame whose stream identifier field is |
| 2055 | anything other than 0x0, the endpoint MUST respond with a connection |
| 2056 | error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 2057 | |
| 2058 | The SETTINGS frame affects connection state. A badly formed or |
| 2059 | incomplete SETTINGS frame MUST be treated as a connection error |
| 2060 | (Section 5.4.1) of type PROTOCOL_ERROR. |
| 2061 | |
| 2062 | A SETTINGS frame with a length other than a multiple of 6 octets MUST |
| 2063 | be treated as a connection error (Section 5.4.1) of type |
| 2064 | FRAME_SIZE_ERROR. |
| 2065 | |
| 2066 | |
| 2067 | |
| 2068 | |
| 2069 | |
| 2070 | |
| 2071 | |
| 2072 | |
| 2073 | |
| 2074 | Belshe, et al. Standards Track [Page 37] |
| 2075 | \f |
| 2076 | RFC 7540 HTTP/2 May 2015 |
| 2077 | |
| 2078 | |
| 2079 | 6.5.1. SETTINGS Format |
| 2080 | |
| 2081 | The payload of a SETTINGS frame consists of zero or more parameters, |
| 2082 | each consisting of an unsigned 16-bit setting identifier and an |
| 2083 | unsigned 32-bit value. |
| 2084 | |
| 2085 | +-------------------------------+ |
| 2086 | | Identifier (16) | |
| 2087 | +-------------------------------+-------------------------------+ |
| 2088 | | Value (32) | |
| 2089 | +---------------------------------------------------------------+ |
| 2090 | |
| 2091 | Figure 10: Setting Format |
| 2092 | |
| 2093 | 6.5.2. Defined SETTINGS Parameters |
| 2094 | |
| 2095 | The following parameters are defined: |
| 2096 | |
| 2097 | SETTINGS_HEADER_TABLE_SIZE (0x1): Allows the sender to inform the |
| 2098 | remote endpoint of the maximum size of the header compression |
| 2099 | table used to decode header blocks, in octets. The encoder can |
| 2100 | select any size equal to or less than this value by using |
| 2101 | signaling specific to the header compression format inside a |
| 2102 | header block (see [COMPRESSION]). The initial value is 4,096 |
| 2103 | octets. |
| 2104 | |
| 2105 | SETTINGS_ENABLE_PUSH (0x2): This setting can be used to disable |
| 2106 | server push (Section 8.2). An endpoint MUST NOT send a |
| 2107 | PUSH_PROMISE frame if it receives this parameter set to a value of |
| 2108 | 0. An endpoint that has both set this parameter to 0 and had it |
| 2109 | acknowledged MUST treat the receipt of a PUSH_PROMISE frame as a |
| 2110 | connection error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 2111 | |
| 2112 | The initial value is 1, which indicates that server push is |
| 2113 | permitted. Any value other than 0 or 1 MUST be treated as a |
| 2114 | connection error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 2115 | |
| 2116 | SETTINGS_MAX_CONCURRENT_STREAMS (0x3): Indicates the maximum number |
| 2117 | of concurrent streams that the sender will allow. This limit is |
| 2118 | directional: it applies to the number of streams that the sender |
| 2119 | permits the receiver to create. Initially, there is no limit to |
| 2120 | this value. It is recommended that this value be no smaller than |
| 2121 | 100, so as to not unnecessarily limit parallelism. |
| 2122 | |
| 2123 | A value of 0 for SETTINGS_MAX_CONCURRENT_STREAMS SHOULD NOT be |
| 2124 | treated as special by endpoints. A zero value does prevent the |
| 2125 | creation of new streams; however, this can also happen for any |
| 2126 | |
| 2127 | |
| 2128 | |
| 2129 | |
| 2130 | Belshe, et al. Standards Track [Page 38] |
| 2131 | \f |
| 2132 | RFC 7540 HTTP/2 May 2015 |
| 2133 | |
| 2134 | |
| 2135 | limit that is exhausted with active streams. Servers SHOULD only |
| 2136 | set a zero value for short durations; if a server does not wish to |
| 2137 | accept requests, closing the connection is more appropriate. |
| 2138 | |
| 2139 | SETTINGS_INITIAL_WINDOW_SIZE (0x4): Indicates the sender's initial |
| 2140 | window size (in octets) for stream-level flow control. The |
| 2141 | initial value is 2^16-1 (65,535) octets. |
| 2142 | |
| 2143 | This setting affects the window size of all streams (see |
| 2144 | Section 6.9.2). |
| 2145 | |
| 2146 | Values above the maximum flow-control window size of 2^31-1 MUST |
| 2147 | be treated as a connection error (Section 5.4.1) of type |
| 2148 | FLOW_CONTROL_ERROR. |
| 2149 | |
| 2150 | SETTINGS_MAX_FRAME_SIZE (0x5): Indicates the size of the largest |
| 2151 | frame payload that the sender is willing to receive, in octets. |
| 2152 | |
| 2153 | The initial value is 2^14 (16,384) octets. The value advertised |
| 2154 | by an endpoint MUST be between this initial value and the maximum |
| 2155 | allowed frame size (2^24-1 or 16,777,215 octets), inclusive. |
| 2156 | Values outside this range MUST be treated as a connection error |
| 2157 | (Section 5.4.1) of type PROTOCOL_ERROR. |
| 2158 | |
| 2159 | SETTINGS_MAX_HEADER_LIST_SIZE (0x6): This advisory setting informs a |
| 2160 | peer of the maximum size of header list that the sender is |
| 2161 | prepared to accept, in octets. The value is based on the |
| 2162 | uncompressed size of header fields, including the length of the |
| 2163 | name and value in octets plus an overhead of 32 octets for each |
| 2164 | header field. |
| 2165 | |
| 2166 | For any given request, a lower limit than what is advertised MAY |
| 2167 | be enforced. The initial value of this setting is unlimited. |
| 2168 | |
| 2169 | An endpoint that receives a SETTINGS frame with any unknown or |
| 2170 | unsupported identifier MUST ignore that setting. |
| 2171 | |
| 2172 | 6.5.3. Settings Synchronization |
| 2173 | |
| 2174 | Most values in SETTINGS benefit from or require an understanding of |
| 2175 | when the peer has received and applied the changed parameter values. |
| 2176 | In order to provide such synchronization timepoints, the recipient of |
| 2177 | a SETTINGS frame in which the ACK flag is not set MUST apply the |
| 2178 | updated parameters as soon as possible upon receipt. |
| 2179 | |
| 2180 | The values in the SETTINGS frame MUST be processed in the order they |
| 2181 | appear, with no other frame processing between values. Unsupported |
| 2182 | parameters MUST be ignored. Once all values have been processed, the |
| 2183 | |
| 2184 | |
| 2185 | |
| 2186 | Belshe, et al. Standards Track [Page 39] |
| 2187 | \f |
| 2188 | RFC 7540 HTTP/2 May 2015 |
| 2189 | |
| 2190 | |
| 2191 | recipient MUST immediately emit a SETTINGS frame with the ACK flag |
| 2192 | set. Upon receiving a SETTINGS frame with the ACK flag set, the |
| 2193 | sender of the altered parameters can rely on the setting having been |
| 2194 | applied. |
| 2195 | |
| 2196 | If the sender of a SETTINGS frame does not receive an acknowledgement |
| 2197 | within a reasonable amount of time, it MAY issue a connection error |
| 2198 | (Section 5.4.1) of type SETTINGS_TIMEOUT. |
| 2199 | |
| 2200 | 6.6. PUSH_PROMISE |
| 2201 | |
| 2202 | The PUSH_PROMISE frame (type=0x5) is used to notify the peer endpoint |
| 2203 | in advance of streams the sender intends to initiate. The |
| 2204 | PUSH_PROMISE frame includes the unsigned 31-bit identifier of the |
| 2205 | stream the endpoint plans to create along with a set of headers that |
| 2206 | provide additional context for the stream. Section 8.2 contains a |
| 2207 | thorough description of the use of PUSH_PROMISE frames. |
| 2208 | |
| 2209 | +---------------+ |
| 2210 | |Pad Length? (8)| |
| 2211 | +-+-------------+-----------------------------------------------+ |
| 2212 | |R| Promised Stream ID (31) | |
| 2213 | +-+-----------------------------+-------------------------------+ |
| 2214 | | Header Block Fragment (*) ... |
| 2215 | +---------------------------------------------------------------+ |
| 2216 | | Padding (*) ... |
| 2217 | +---------------------------------------------------------------+ |
| 2218 | |
| 2219 | Figure 11: PUSH_PROMISE Payload Format |
| 2220 | |
| 2221 | The PUSH_PROMISE frame payload has the following fields: |
| 2222 | |
| 2223 | Pad Length: An 8-bit field containing the length of the frame |
| 2224 | padding in units of octets. This field is only present if the |
| 2225 | PADDED flag is set. |
| 2226 | |
| 2227 | R: A single reserved bit. |
| 2228 | |
| 2229 | Promised Stream ID: An unsigned 31-bit integer that identifies the |
| 2230 | stream that is reserved by the PUSH_PROMISE. The promised stream |
| 2231 | identifier MUST be a valid choice for the next stream sent by the |
| 2232 | sender (see "new stream identifier" in Section 5.1.1). |
| 2233 | |
| 2234 | Header Block Fragment: A header block fragment (Section 4.3) |
| 2235 | containing request header fields. |
| 2236 | |
| 2237 | Padding: Padding octets. |
| 2238 | |
| 2239 | |
| 2240 | |
| 2241 | |
| 2242 | Belshe, et al. Standards Track [Page 40] |
| 2243 | \f |
| 2244 | RFC 7540 HTTP/2 May 2015 |
| 2245 | |
| 2246 | |
| 2247 | The PUSH_PROMISE frame defines the following flags: |
| 2248 | |
| 2249 | END_HEADERS (0x4): When set, bit 2 indicates that this frame |
| 2250 | contains an entire header block (Section 4.3) and is not followed |
| 2251 | by any CONTINUATION frames. |
| 2252 | |
| 2253 | A PUSH_PROMISE frame without the END_HEADERS flag set MUST be |
| 2254 | followed by a CONTINUATION frame for the same stream. A receiver |
| 2255 | MUST treat the receipt of any other type of frame or a frame on a |
| 2256 | different stream as a connection error (Section 5.4.1) of type |
| 2257 | PROTOCOL_ERROR. |
| 2258 | |
| 2259 | PADDED (0x8): When set, bit 3 indicates that the Pad Length field |
| 2260 | and any padding that it describes are present. |
| 2261 | |
| 2262 | PUSH_PROMISE frames MUST only be sent on a peer-initiated stream that |
| 2263 | is in either the "open" or "half-closed (remote)" state. The stream |
| 2264 | identifier of a PUSH_PROMISE frame indicates the stream it is |
| 2265 | associated with. If the stream identifier field specifies the value |
| 2266 | 0x0, a recipient MUST respond with a connection error (Section 5.4.1) |
| 2267 | of type PROTOCOL_ERROR. |
| 2268 | |
| 2269 | Promised streams are not required to be used in the order they are |
| 2270 | promised. The PUSH_PROMISE only reserves stream identifiers for |
| 2271 | later use. |
| 2272 | |
| 2273 | PUSH_PROMISE MUST NOT be sent if the SETTINGS_ENABLE_PUSH setting of |
| 2274 | the peer endpoint is set to 0. An endpoint that has set this setting |
| 2275 | and has received acknowledgement MUST treat the receipt of a |
| 2276 | PUSH_PROMISE frame as a connection error (Section 5.4.1) of type |
| 2277 | PROTOCOL_ERROR. |
| 2278 | |
| 2279 | Recipients of PUSH_PROMISE frames can choose to reject promised |
| 2280 | streams by returning a RST_STREAM referencing the promised stream |
| 2281 | identifier back to the sender of the PUSH_PROMISE. |
| 2282 | |
| 2283 | A PUSH_PROMISE frame modifies the connection state in two ways. |
| 2284 | First, the inclusion of a header block (Section 4.3) potentially |
| 2285 | modifies the state maintained for header compression. Second, |
| 2286 | PUSH_PROMISE also reserves a stream for later use, causing the |
| 2287 | promised stream to enter the "reserved" state. A sender MUST NOT |
| 2288 | send a PUSH_PROMISE on a stream unless that stream is either "open" |
| 2289 | or "half-closed (remote)"; the sender MUST ensure that the promised |
| 2290 | stream is a valid choice for a new stream identifier (Section 5.1.1) |
| 2291 | (that is, the promised stream MUST be in the "idle" state). |
| 2292 | |
| 2293 | |
| 2294 | |
| 2295 | |
| 2296 | |
| 2297 | |
| 2298 | Belshe, et al. Standards Track [Page 41] |
| 2299 | \f |
| 2300 | RFC 7540 HTTP/2 May 2015 |
| 2301 | |
| 2302 | |
| 2303 | Since PUSH_PROMISE reserves a stream, ignoring a PUSH_PROMISE frame |
| 2304 | causes the stream state to become indeterminate. A receiver MUST |
| 2305 | treat the receipt of a PUSH_PROMISE on a stream that is neither |
| 2306 | "open" nor "half-closed (local)" as a connection error |
| 2307 | (Section 5.4.1) of type PROTOCOL_ERROR. However, an endpoint that |
| 2308 | has sent RST_STREAM on the associated stream MUST handle PUSH_PROMISE |
| 2309 | frames that might have been created before the RST_STREAM frame is |
| 2310 | received and processed. |
| 2311 | |
| 2312 | A receiver MUST treat the receipt of a PUSH_PROMISE that promises an |
| 2313 | illegal stream identifier (Section 5.1.1) as a connection error |
| 2314 | (Section 5.4.1) of type PROTOCOL_ERROR. Note that an illegal stream |
| 2315 | identifier is an identifier for a stream that is not currently in the |
| 2316 | "idle" state. |
| 2317 | |
| 2318 | The PUSH_PROMISE frame can include padding. Padding fields and flags |
| 2319 | are identical to those defined for DATA frames (Section 6.1). |
| 2320 | |
| 2321 | 6.7. PING |
| 2322 | |
| 2323 | The PING frame (type=0x6) is a mechanism for measuring a minimal |
| 2324 | round-trip time from the sender, as well as determining whether an |
| 2325 | idle connection is still functional. PING frames can be sent from |
| 2326 | any endpoint. |
| 2327 | |
| 2328 | +---------------------------------------------------------------+ |
| 2329 | | | |
| 2330 | | Opaque Data (64) | |
| 2331 | | | |
| 2332 | +---------------------------------------------------------------+ |
| 2333 | |
| 2334 | Figure 12: PING Payload Format |
| 2335 | |
| 2336 | In addition to the frame header, PING frames MUST contain 8 octets of |
| 2337 | opaque data in the payload. A sender can include any value it |
| 2338 | chooses and use those octets in any fashion. |
| 2339 | |
| 2340 | Receivers of a PING frame that does not include an ACK flag MUST send |
| 2341 | a PING frame with the ACK flag set in response, with an identical |
| 2342 | payload. PING responses SHOULD be given higher priority than any |
| 2343 | other frame. |
| 2344 | |
| 2345 | The PING frame defines the following flags: |
| 2346 | |
| 2347 | ACK (0x1): When set, bit 0 indicates that this PING frame is a PING |
| 2348 | response. An endpoint MUST set this flag in PING responses. An |
| 2349 | endpoint MUST NOT respond to PING frames containing this flag. |
| 2350 | |
| 2351 | |
| 2352 | |
| 2353 | |
| 2354 | Belshe, et al. Standards Track [Page 42] |
| 2355 | \f |
| 2356 | RFC 7540 HTTP/2 May 2015 |
| 2357 | |
| 2358 | |
| 2359 | PING frames are not associated with any individual stream. If a PING |
| 2360 | frame is received with a stream identifier field value other than |
| 2361 | 0x0, the recipient MUST respond with a connection error |
| 2362 | (Section 5.4.1) of type PROTOCOL_ERROR. |
| 2363 | |
| 2364 | Receipt of a PING frame with a length field value other than 8 MUST |
| 2365 | be treated as a connection error (Section 5.4.1) of type |
| 2366 | FRAME_SIZE_ERROR. |
| 2367 | |
| 2368 | 6.8. GOAWAY |
| 2369 | |
| 2370 | The GOAWAY frame (type=0x7) is used to initiate shutdown of a |
| 2371 | connection or to signal serious error conditions. GOAWAY allows an |
| 2372 | endpoint to gracefully stop accepting new streams while still |
| 2373 | finishing processing of previously established streams. This enables |
| 2374 | administrative actions, like server maintenance. |
| 2375 | |
| 2376 | There is an inherent race condition between an endpoint starting new |
| 2377 | streams and the remote sending a GOAWAY frame. To deal with this |
| 2378 | case, the GOAWAY contains the stream identifier of the last peer- |
| 2379 | initiated stream that was or might be processed on the sending |
| 2380 | endpoint in this connection. For instance, if the server sends a |
| 2381 | GOAWAY frame, the identified stream is the highest-numbered stream |
| 2382 | initiated by the client. |
| 2383 | |
| 2384 | Once sent, the sender will ignore frames sent on streams initiated by |
| 2385 | the receiver if the stream has an identifier higher than the included |
| 2386 | last stream identifier. Receivers of a GOAWAY frame MUST NOT open |
| 2387 | additional streams on the connection, although a new connection can |
| 2388 | be established for new streams. |
| 2389 | |
| 2390 | If the receiver of the GOAWAY has sent data on streams with a higher |
| 2391 | stream identifier than what is indicated in the GOAWAY frame, those |
| 2392 | streams are not or will not be processed. The receiver of the GOAWAY |
| 2393 | frame can treat the streams as though they had never been created at |
| 2394 | all, thereby allowing those streams to be retried later on a new |
| 2395 | connection. |
| 2396 | |
| 2397 | Endpoints SHOULD always send a GOAWAY frame before closing a |
| 2398 | connection so that the remote peer can know whether a stream has been |
| 2399 | partially processed or not. For example, if an HTTP client sends a |
| 2400 | POST at the same time that a server closes a connection, the client |
| 2401 | cannot know if the server started to process that POST request if the |
| 2402 | server does not send a GOAWAY frame to indicate what streams it might |
| 2403 | have acted on. |
| 2404 | |
| 2405 | An endpoint might choose to close a connection without sending a |
| 2406 | GOAWAY for misbehaving peers. |
| 2407 | |
| 2408 | |
| 2409 | |
| 2410 | Belshe, et al. Standards Track [Page 43] |
| 2411 | \f |
| 2412 | RFC 7540 HTTP/2 May 2015 |
| 2413 | |
| 2414 | |
| 2415 | A GOAWAY frame might not immediately precede closing of the |
| 2416 | connection; a receiver of a GOAWAY that has no more use for the |
| 2417 | connection SHOULD still send a GOAWAY frame before terminating the |
| 2418 | connection. |
| 2419 | |
| 2420 | +-+-------------------------------------------------------------+ |
| 2421 | |R| Last-Stream-ID (31) | |
| 2422 | +-+-------------------------------------------------------------+ |
| 2423 | | Error Code (32) | |
| 2424 | +---------------------------------------------------------------+ |
| 2425 | | Additional Debug Data (*) | |
| 2426 | +---------------------------------------------------------------+ |
| 2427 | |
| 2428 | Figure 13: GOAWAY Payload Format |
| 2429 | |
| 2430 | The GOAWAY frame does not define any flags. |
| 2431 | |
| 2432 | The GOAWAY frame applies to the connection, not a specific stream. |
| 2433 | An endpoint MUST treat a GOAWAY frame with a stream identifier other |
| 2434 | than 0x0 as a connection error (Section 5.4.1) of type |
| 2435 | PROTOCOL_ERROR. |
| 2436 | |
| 2437 | The last stream identifier in the GOAWAY frame contains the highest- |
| 2438 | numbered stream identifier for which the sender of the GOAWAY frame |
| 2439 | might have taken some action on or might yet take action on. All |
| 2440 | streams up to and including the identified stream might have been |
| 2441 | processed in some way. The last stream identifier can be set to 0 if |
| 2442 | no streams were processed. |
| 2443 | |
| 2444 | Note: In this context, "processed" means that some data from the |
| 2445 | stream was passed to some higher layer of software that might have |
| 2446 | taken some action as a result. |
| 2447 | |
| 2448 | If a connection terminates without a GOAWAY frame, the last stream |
| 2449 | identifier is effectively the highest possible stream identifier. |
| 2450 | |
| 2451 | On streams with lower- or equal-numbered identifiers that were not |
| 2452 | closed completely prior to the connection being closed, reattempting |
| 2453 | requests, transactions, or any protocol activity is not possible, |
| 2454 | with the exception of idempotent actions like HTTP GET, PUT, or |
| 2455 | DELETE. Any protocol activity that uses higher-numbered streams can |
| 2456 | be safely retried using a new connection. |
| 2457 | |
| 2458 | Activity on streams numbered lower or equal to the last stream |
| 2459 | identifier might still complete successfully. The sender of a GOAWAY |
| 2460 | frame might gracefully shut down a connection by sending a GOAWAY |
| 2461 | frame, maintaining the connection in an "open" state until all in- |
| 2462 | progress streams complete. |
| 2463 | |
| 2464 | |
| 2465 | |
| 2466 | Belshe, et al. Standards Track [Page 44] |
| 2467 | \f |
| 2468 | RFC 7540 HTTP/2 May 2015 |
| 2469 | |
| 2470 | |
| 2471 | An endpoint MAY send multiple GOAWAY frames if circumstances change. |
| 2472 | For instance, an endpoint that sends GOAWAY with NO_ERROR during |
| 2473 | graceful shutdown could subsequently encounter a condition that |
| 2474 | requires immediate termination of the connection. The last stream |
| 2475 | identifier from the last GOAWAY frame received indicates which |
| 2476 | streams could have been acted upon. Endpoints MUST NOT increase the |
| 2477 | value they send in the last stream identifier, since the peers might |
| 2478 | already have retried unprocessed requests on another connection. |
| 2479 | |
| 2480 | A client that is unable to retry requests loses all requests that are |
| 2481 | in flight when the server closes the connection. This is especially |
| 2482 | true for intermediaries that might not be serving clients using |
| 2483 | HTTP/2. A server that is attempting to gracefully shut down a |
| 2484 | connection SHOULD send an initial GOAWAY frame with the last stream |
| 2485 | identifier set to 2^31-1 and a NO_ERROR code. This signals to the |
| 2486 | client that a shutdown is imminent and that initiating further |
| 2487 | requests is prohibited. After allowing time for any in-flight stream |
| 2488 | creation (at least one round-trip time), the server can send another |
| 2489 | GOAWAY frame with an updated last stream identifier. This ensures |
| 2490 | that a connection can be cleanly shut down without losing requests. |
| 2491 | |
| 2492 | After sending a GOAWAY frame, the sender can discard frames for |
| 2493 | streams initiated by the receiver with identifiers higher than the |
| 2494 | identified last stream. However, any frames that alter connection |
| 2495 | state cannot be completely ignored. For instance, HEADERS, |
| 2496 | PUSH_PROMISE, and CONTINUATION frames MUST be minimally processed to |
| 2497 | ensure the state maintained for header compression is consistent (see |
| 2498 | Section 4.3); similarly, DATA frames MUST be counted toward the |
| 2499 | connection flow-control window. Failure to process these frames can |
| 2500 | cause flow control or header compression state to become |
| 2501 | unsynchronized. |
| 2502 | |
| 2503 | The GOAWAY frame also contains a 32-bit error code (Section 7) that |
| 2504 | contains the reason for closing the connection. |
| 2505 | |
| 2506 | Endpoints MAY append opaque data to the payload of any GOAWAY frame. |
| 2507 | Additional debug data is intended for diagnostic purposes only and |
| 2508 | carries no semantic value. Debug information could contain security- |
| 2509 | or privacy-sensitive data. Logged or otherwise persistently stored |
| 2510 | debug data MUST have adequate safeguards to prevent unauthorized |
| 2511 | access. |
| 2512 | |
| 2513 | |
| 2514 | |
| 2515 | |
| 2516 | |
| 2517 | |
| 2518 | |
| 2519 | |
| 2520 | |
| 2521 | |
| 2522 | Belshe, et al. Standards Track [Page 45] |
| 2523 | \f |
| 2524 | RFC 7540 HTTP/2 May 2015 |
| 2525 | |
| 2526 | |
| 2527 | 6.9. WINDOW_UPDATE |
| 2528 | |
| 2529 | The WINDOW_UPDATE frame (type=0x8) is used to implement flow control; |
| 2530 | see Section 5.2 for an overview. |
| 2531 | |
| 2532 | Flow control operates at two levels: on each individual stream and on |
| 2533 | the entire connection. |
| 2534 | |
| 2535 | Both types of flow control are hop by hop, that is, only between the |
| 2536 | two endpoints. Intermediaries do not forward WINDOW_UPDATE frames |
| 2537 | between dependent connections. However, throttling of data transfer |
| 2538 | by any receiver can indirectly cause the propagation of flow-control |
| 2539 | information toward the original sender. |
| 2540 | |
| 2541 | Flow control only applies to frames that are identified as being |
| 2542 | subject to flow control. Of the frame types defined in this |
| 2543 | document, this includes only DATA frames. Frames that are exempt |
| 2544 | from flow control MUST be accepted and processed, unless the receiver |
| 2545 | is unable to assign resources to handling the frame. A receiver MAY |
| 2546 | respond with a stream error (Section 5.4.2) or connection error |
| 2547 | (Section 5.4.1) of type FLOW_CONTROL_ERROR if it is unable to accept |
| 2548 | a frame. |
| 2549 | |
| 2550 | +-+-------------------------------------------------------------+ |
| 2551 | |R| Window Size Increment (31) | |
| 2552 | +-+-------------------------------------------------------------+ |
| 2553 | |
| 2554 | Figure 14: WINDOW_UPDATE Payload Format |
| 2555 | |
| 2556 | The payload of a WINDOW_UPDATE frame is one reserved bit plus an |
| 2557 | unsigned 31-bit integer indicating the number of octets that the |
| 2558 | sender can transmit in addition to the existing flow-control window. |
| 2559 | The legal range for the increment to the flow-control window is 1 to |
| 2560 | 2^31-1 (2,147,483,647) octets. |
| 2561 | |
| 2562 | The WINDOW_UPDATE frame does not define any flags. |
| 2563 | |
| 2564 | The WINDOW_UPDATE frame can be specific to a stream or to the entire |
| 2565 | connection. In the former case, the frame's stream identifier |
| 2566 | indicates the affected stream; in the latter, the value "0" indicates |
| 2567 | that the entire connection is the subject of the frame. |
| 2568 | |
| 2569 | A receiver MUST treat the receipt of a WINDOW_UPDATE frame with an |
| 2570 | flow-control window increment of 0 as a stream error (Section 5.4.2) |
| 2571 | of type PROTOCOL_ERROR; errors on the connection flow-control window |
| 2572 | MUST be treated as a connection error (Section 5.4.1). |
| 2573 | |
| 2574 | |
| 2575 | |
| 2576 | |
| 2577 | |
| 2578 | Belshe, et al. Standards Track [Page 46] |
| 2579 | \f |
| 2580 | RFC 7540 HTTP/2 May 2015 |
| 2581 | |
| 2582 | |
| 2583 | WINDOW_UPDATE can be sent by a peer that has sent a frame bearing the |
| 2584 | END_STREAM flag. This means that a receiver could receive a |
| 2585 | WINDOW_UPDATE frame on a "half-closed (remote)" or "closed" stream. |
| 2586 | A receiver MUST NOT treat this as an error (see Section 5.1). |
| 2587 | |
| 2588 | A receiver that receives a flow-controlled frame MUST always account |
| 2589 | for its contribution against the connection flow-control window, |
| 2590 | unless the receiver treats this as a connection error |
| 2591 | (Section 5.4.1). This is necessary even if the frame is in error. |
| 2592 | The sender counts the frame toward the flow-control window, but if |
| 2593 | the receiver does not, the flow-control window at the sender and |
| 2594 | receiver can become different. |
| 2595 | |
| 2596 | A WINDOW_UPDATE frame with a length other than 4 octets MUST be |
| 2597 | treated as a connection error (Section 5.4.1) of type |
| 2598 | FRAME_SIZE_ERROR. |
| 2599 | |
| 2600 | 6.9.1. The Flow-Control Window |
| 2601 | |
| 2602 | Flow control in HTTP/2 is implemented using a window kept by each |
| 2603 | sender on every stream. The flow-control window is a simple integer |
| 2604 | value that indicates how many octets of data the sender is permitted |
| 2605 | to transmit; as such, its size is a measure of the buffering capacity |
| 2606 | of the receiver. |
| 2607 | |
| 2608 | Two flow-control windows are applicable: the stream flow-control |
| 2609 | window and the connection flow-control window. The sender MUST NOT |
| 2610 | send a flow-controlled frame with a length that exceeds the space |
| 2611 | available in either of the flow-control windows advertised by the |
| 2612 | receiver. Frames with zero length with the END_STREAM flag set (that |
| 2613 | is, an empty DATA frame) MAY be sent if there is no available space |
| 2614 | in either flow-control window. |
| 2615 | |
| 2616 | For flow-control calculations, the 9-octet frame header is not |
| 2617 | counted. |
| 2618 | |
| 2619 | After sending a flow-controlled frame, the sender reduces the space |
| 2620 | available in both windows by the length of the transmitted frame. |
| 2621 | |
| 2622 | The receiver of a frame sends a WINDOW_UPDATE frame as it consumes |
| 2623 | data and frees up space in flow-control windows. Separate |
| 2624 | WINDOW_UPDATE frames are sent for the stream- and connection-level |
| 2625 | flow-control windows. |
| 2626 | |
| 2627 | A sender that receives a WINDOW_UPDATE frame updates the |
| 2628 | corresponding window by the amount specified in the frame. |
| 2629 | |
| 2630 | |
| 2631 | |
| 2632 | |
| 2633 | |
| 2634 | Belshe, et al. Standards Track [Page 47] |
| 2635 | \f |
| 2636 | RFC 7540 HTTP/2 May 2015 |
| 2637 | |
| 2638 | |
| 2639 | A sender MUST NOT allow a flow-control window to exceed 2^31-1 |
| 2640 | octets. If a sender receives a WINDOW_UPDATE that causes a flow- |
| 2641 | control window to exceed this maximum, it MUST terminate either the |
| 2642 | stream or the connection, as appropriate. For streams, the sender |
| 2643 | sends a RST_STREAM with an error code of FLOW_CONTROL_ERROR; for the |
| 2644 | connection, a GOAWAY frame with an error code of FLOW_CONTROL_ERROR |
| 2645 | is sent. |
| 2646 | |
| 2647 | Flow-controlled frames from the sender and WINDOW_UPDATE frames from |
| 2648 | the receiver are completely asynchronous with respect to each other. |
| 2649 | This property allows a receiver to aggressively update the window |
| 2650 | size kept by the sender to prevent streams from stalling. |
| 2651 | |
| 2652 | 6.9.2. Initial Flow-Control Window Size |
| 2653 | |
| 2654 | When an HTTP/2 connection is first established, new streams are |
| 2655 | created with an initial flow-control window size of 65,535 octets. |
| 2656 | The connection flow-control window is also 65,535 octets. Both |
| 2657 | endpoints can adjust the initial window size for new streams by |
| 2658 | including a value for SETTINGS_INITIAL_WINDOW_SIZE in the SETTINGS |
| 2659 | frame that forms part of the connection preface. The connection |
| 2660 | flow-control window can only be changed using WINDOW_UPDATE frames. |
| 2661 | |
| 2662 | Prior to receiving a SETTINGS frame that sets a value for |
| 2663 | SETTINGS_INITIAL_WINDOW_SIZE, an endpoint can only use the default |
| 2664 | initial window size when sending flow-controlled frames. Similarly, |
| 2665 | the connection flow-control window is set to the default initial |
| 2666 | window size until a WINDOW_UPDATE frame is received. |
| 2667 | |
| 2668 | In addition to changing the flow-control window for streams that are |
| 2669 | not yet active, a SETTINGS frame can alter the initial flow-control |
| 2670 | window size for streams with active flow-control windows (that is, |
| 2671 | streams in the "open" or "half-closed (remote)" state). When the |
| 2672 | value of SETTINGS_INITIAL_WINDOW_SIZE changes, a receiver MUST adjust |
| 2673 | the size of all stream flow-control windows that it maintains by the |
| 2674 | difference between the new value and the old value. |
| 2675 | |
| 2676 | A change to SETTINGS_INITIAL_WINDOW_SIZE can cause the available |
| 2677 | space in a flow-control window to become negative. A sender MUST |
| 2678 | track the negative flow-control window and MUST NOT send new flow- |
| 2679 | controlled frames until it receives WINDOW_UPDATE frames that cause |
| 2680 | the flow-control window to become positive. |
| 2681 | |
| 2682 | For example, if the client sends 60 KB immediately on connection |
| 2683 | establishment and the server sets the initial window size to be 16 |
| 2684 | KB, the client will recalculate the available flow-control window to |
| 2685 | |
| 2686 | |
| 2687 | |
| 2688 | |
| 2689 | |
| 2690 | Belshe, et al. Standards Track [Page 48] |
| 2691 | \f |
| 2692 | RFC 7540 HTTP/2 May 2015 |
| 2693 | |
| 2694 | |
| 2695 | be -44 KB on receipt of the SETTINGS frame. The client retains a |
| 2696 | negative flow-control window until WINDOW_UPDATE frames restore the |
| 2697 | window to being positive, after which the client can resume sending. |
| 2698 | |
| 2699 | A SETTINGS frame cannot alter the connection flow-control window. |
| 2700 | |
| 2701 | An endpoint MUST treat a change to SETTINGS_INITIAL_WINDOW_SIZE that |
| 2702 | causes any flow-control window to exceed the maximum size as a |
| 2703 | connection error (Section 5.4.1) of type FLOW_CONTROL_ERROR. |
| 2704 | |
| 2705 | 6.9.3. Reducing the Stream Window Size |
| 2706 | |
| 2707 | A receiver that wishes to use a smaller flow-control window than the |
| 2708 | current size can send a new SETTINGS frame. However, the receiver |
| 2709 | MUST be prepared to receive data that exceeds this window size, since |
| 2710 | the sender might send data that exceeds the lower limit prior to |
| 2711 | processing the SETTINGS frame. |
| 2712 | |
| 2713 | After sending a SETTINGS frame that reduces the initial flow-control |
| 2714 | window size, a receiver MAY continue to process streams that exceed |
| 2715 | flow-control limits. Allowing streams to continue does not allow the |
| 2716 | receiver to immediately reduce the space it reserves for flow-control |
| 2717 | windows. Progress on these streams can also stall, since |
| 2718 | WINDOW_UPDATE frames are needed to allow the sender to resume |
| 2719 | sending. The receiver MAY instead send a RST_STREAM with an error |
| 2720 | code of FLOW_CONTROL_ERROR for the affected streams. |
| 2721 | |
| 2722 | 6.10. CONTINUATION |
| 2723 | |
| 2724 | The CONTINUATION frame (type=0x9) is used to continue a sequence of |
| 2725 | header block fragments (Section 4.3). Any number of CONTINUATION |
| 2726 | frames can be sent, as long as the preceding frame is on the same |
| 2727 | stream and is a HEADERS, PUSH_PROMISE, or CONTINUATION frame without |
| 2728 | the END_HEADERS flag set. |
| 2729 | |
| 2730 | +---------------------------------------------------------------+ |
| 2731 | | Header Block Fragment (*) ... |
| 2732 | +---------------------------------------------------------------+ |
| 2733 | |
| 2734 | Figure 15: CONTINUATION Frame Payload |
| 2735 | |
| 2736 | The CONTINUATION frame payload contains a header block fragment |
| 2737 | (Section 4.3). |
| 2738 | |
| 2739 | |
| 2740 | |
| 2741 | |
| 2742 | |
| 2743 | |
| 2744 | |
| 2745 | |
| 2746 | Belshe, et al. Standards Track [Page 49] |
| 2747 | \f |
| 2748 | RFC 7540 HTTP/2 May 2015 |
| 2749 | |
| 2750 | |
| 2751 | The CONTINUATION frame defines the following flag: |
| 2752 | |
| 2753 | END_HEADERS (0x4): When set, bit 2 indicates that this frame ends a |
| 2754 | header block (Section 4.3). |
| 2755 | |
| 2756 | If the END_HEADERS bit is not set, this frame MUST be followed by |
| 2757 | another CONTINUATION frame. A receiver MUST treat the receipt of |
| 2758 | any other type of frame or a frame on a different stream as a |
| 2759 | connection error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 2760 | |
| 2761 | The CONTINUATION frame changes the connection state as defined in |
| 2762 | Section 4.3. |
| 2763 | |
| 2764 | CONTINUATION frames MUST be associated with a stream. If a |
| 2765 | CONTINUATION frame is received whose stream identifier field is 0x0, |
| 2766 | the recipient MUST respond with a connection error (Section 5.4.1) of |
| 2767 | type PROTOCOL_ERROR. |
| 2768 | |
| 2769 | A CONTINUATION frame MUST be preceded by a HEADERS, PUSH_PROMISE or |
| 2770 | CONTINUATION frame without the END_HEADERS flag set. A recipient |
| 2771 | that observes violation of this rule MUST respond with a connection |
| 2772 | error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 2773 | |
| 2774 | 7. Error Codes |
| 2775 | |
| 2776 | Error codes are 32-bit fields that are used in RST_STREAM and GOAWAY |
| 2777 | frames to convey the reasons for the stream or connection error. |
| 2778 | |
| 2779 | Error codes share a common code space. Some error codes apply only |
| 2780 | to either streams or the entire connection and have no defined |
| 2781 | semantics in the other context. |
| 2782 | |
| 2783 | The following error codes are defined: |
| 2784 | |
| 2785 | NO_ERROR (0x0): The associated condition is not a result of an |
| 2786 | error. For example, a GOAWAY might include this code to indicate |
| 2787 | graceful shutdown of a connection. |
| 2788 | |
| 2789 | PROTOCOL_ERROR (0x1): The endpoint detected an unspecific protocol |
| 2790 | error. This error is for use when a more specific error code is |
| 2791 | not available. |
| 2792 | |
| 2793 | INTERNAL_ERROR (0x2): The endpoint encountered an unexpected |
| 2794 | internal error. |
| 2795 | |
| 2796 | FLOW_CONTROL_ERROR (0x3): The endpoint detected that its peer |
| 2797 | violated the flow-control protocol. |
| 2798 | |
| 2799 | |
| 2800 | |
| 2801 | |
| 2802 | Belshe, et al. Standards Track [Page 50] |
| 2803 | \f |
| 2804 | RFC 7540 HTTP/2 May 2015 |
| 2805 | |
| 2806 | |
| 2807 | SETTINGS_TIMEOUT (0x4): The endpoint sent a SETTINGS frame but did |
| 2808 | not receive a response in a timely manner. See Section 6.5.3 |
| 2809 | ("Settings Synchronization"). |
| 2810 | |
| 2811 | STREAM_CLOSED (0x5): The endpoint received a frame after a stream |
| 2812 | was half-closed. |
| 2813 | |
| 2814 | FRAME_SIZE_ERROR (0x6): The endpoint received a frame with an |
| 2815 | invalid size. |
| 2816 | |
| 2817 | REFUSED_STREAM (0x7): The endpoint refused the stream prior to |
| 2818 | performing any application processing (see Section 8.1.4 for |
| 2819 | details). |
| 2820 | |
| 2821 | CANCEL (0x8): Used by the endpoint to indicate that the stream is no |
| 2822 | longer needed. |
| 2823 | |
| 2824 | COMPRESSION_ERROR (0x9): The endpoint is unable to maintain the |
| 2825 | header compression context for the connection. |
| 2826 | |
| 2827 | CONNECT_ERROR (0xa): The connection established in response to a |
| 2828 | CONNECT request (Section 8.3) was reset or abnormally closed. |
| 2829 | |
| 2830 | ENHANCE_YOUR_CALM (0xb): The endpoint detected that its peer is |
| 2831 | exhibiting a behavior that might be generating excessive load. |
| 2832 | |
| 2833 | INADEQUATE_SECURITY (0xc): The underlying transport has properties |
| 2834 | that do not meet minimum security requirements (see Section 9.2). |
| 2835 | |
| 2836 | HTTP_1_1_REQUIRED (0xd): The endpoint requires that HTTP/1.1 be used |
| 2837 | instead of HTTP/2. |
| 2838 | |
| 2839 | Unknown or unsupported error codes MUST NOT trigger any special |
| 2840 | behavior. These MAY be treated by an implementation as being |
| 2841 | equivalent to INTERNAL_ERROR. |
| 2842 | |
| 2843 | 8. HTTP Message Exchanges |
| 2844 | |
| 2845 | HTTP/2 is intended to be as compatible as possible with current uses |
| 2846 | of HTTP. This means that, from the application perspective, the |
| 2847 | features of the protocol are largely unchanged. To achieve this, all |
| 2848 | request and response semantics are preserved, although the syntax of |
| 2849 | conveying those semantics has changed. |
| 2850 | |
| 2851 | Thus, the specification and requirements of HTTP/1.1 Semantics and |
| 2852 | Content [RFC7231], Conditional Requests [RFC7232], Range Requests |
| 2853 | [RFC7233], Caching [RFC7234], and Authentication [RFC7235] are |
| 2854 | applicable to HTTP/2. Selected portions of HTTP/1.1 Message Syntax |
| 2855 | |
| 2856 | |
| 2857 | |
| 2858 | Belshe, et al. Standards Track [Page 51] |
| 2859 | \f |
| 2860 | RFC 7540 HTTP/2 May 2015 |
| 2861 | |
| 2862 | |
| 2863 | and Routing [RFC7230], such as the HTTP and HTTPS URI schemes, are |
| 2864 | also applicable in HTTP/2, but the expression of those semantics for |
| 2865 | this protocol are defined in the sections below. |
| 2866 | |
| 2867 | 8.1. HTTP Request/Response Exchange |
| 2868 | |
| 2869 | A client sends an HTTP request on a new stream, using a previously |
| 2870 | unused stream identifier (Section 5.1.1). A server sends an HTTP |
| 2871 | response on the same stream as the request. |
| 2872 | |
| 2873 | An HTTP message (request or response) consists of: |
| 2874 | |
| 2875 | 1. for a response only, zero or more HEADERS frames (each followed |
| 2876 | by zero or more CONTINUATION frames) containing the message |
| 2877 | headers of informational (1xx) HTTP responses (see [RFC7230], |
| 2878 | Section 3.2 and [RFC7231], Section 6.2), |
| 2879 | |
| 2880 | 2. one HEADERS frame (followed by zero or more CONTINUATION frames) |
| 2881 | containing the message headers (see [RFC7230], Section 3.2), |
| 2882 | |
| 2883 | 3. zero or more DATA frames containing the payload body (see |
| 2884 | [RFC7230], Section 3.3), and |
| 2885 | |
| 2886 | 4. optionally, one HEADERS frame, followed by zero or more |
| 2887 | CONTINUATION frames containing the trailer-part, if present (see |
| 2888 | [RFC7230], Section 4.1.2). |
| 2889 | |
| 2890 | The last frame in the sequence bears an END_STREAM flag, noting that |
| 2891 | a HEADERS frame bearing the END_STREAM flag can be followed by |
| 2892 | CONTINUATION frames that carry any remaining portions of the header |
| 2893 | block. |
| 2894 | |
| 2895 | Other frames (from any stream) MUST NOT occur between the HEADERS |
| 2896 | frame and any CONTINUATION frames that might follow. |
| 2897 | |
| 2898 | HTTP/2 uses DATA frames to carry message payloads. The "chunked" |
| 2899 | transfer encoding defined in Section 4.1 of [RFC7230] MUST NOT be |
| 2900 | used in HTTP/2. |
| 2901 | |
| 2902 | Trailing header fields are carried in a header block that also |
| 2903 | terminates the stream. Such a header block is a sequence starting |
| 2904 | with a HEADERS frame, followed by zero or more CONTINUATION frames, |
| 2905 | where the HEADERS frame bears an END_STREAM flag. Header blocks |
| 2906 | after the first that do not terminate the stream are not part of an |
| 2907 | HTTP request or response. |
| 2908 | |
| 2909 | |
| 2910 | |
| 2911 | |
| 2912 | |
| 2913 | |
| 2914 | Belshe, et al. Standards Track [Page 52] |
| 2915 | \f |
| 2916 | RFC 7540 HTTP/2 May 2015 |
| 2917 | |
| 2918 | |
| 2919 | A HEADERS frame (and associated CONTINUATION frames) can only appear |
| 2920 | at the start or end of a stream. An endpoint that receives a HEADERS |
| 2921 | frame without the END_STREAM flag set after receiving a final (non- |
| 2922 | informational) status code MUST treat the corresponding request or |
| 2923 | response as malformed (Section 8.1.2.6). |
| 2924 | |
| 2925 | An HTTP request/response exchange fully consumes a single stream. A |
| 2926 | request starts with the HEADERS frame that puts the stream into an |
| 2927 | "open" state. The request ends with a frame bearing END_STREAM, |
| 2928 | which causes the stream to become "half-closed (local)" for the |
| 2929 | client and "half-closed (remote)" for the server. A response starts |
| 2930 | with a HEADERS frame and ends with a frame bearing END_STREAM, which |
| 2931 | places the stream in the "closed" state. |
| 2932 | |
| 2933 | An HTTP response is complete after the server sends -- or the client |
| 2934 | receives -- a frame with the END_STREAM flag set (including any |
| 2935 | CONTINUATION frames needed to complete a header block). A server can |
| 2936 | send a complete response prior to the client sending an entire |
| 2937 | request if the response does not depend on any portion of the request |
| 2938 | that has not been sent and received. When this is true, a server MAY |
| 2939 | request that the client abort transmission of a request without error |
| 2940 | by sending a RST_STREAM with an error code of NO_ERROR after sending |
| 2941 | a complete response (i.e., a frame with the END_STREAM flag). |
| 2942 | Clients MUST NOT discard responses as a result of receiving such a |
| 2943 | RST_STREAM, though clients can always discard responses at their |
| 2944 | discretion for other reasons. |
| 2945 | |
| 2946 | 8.1.1. Upgrading from HTTP/2 |
| 2947 | |
| 2948 | HTTP/2 removes support for the 101 (Switching Protocols) |
| 2949 | informational status code ([RFC7231], Section 6.2.2). |
| 2950 | |
| 2951 | The semantics of 101 (Switching Protocols) aren't applicable to a |
| 2952 | multiplexed protocol. Alternative protocols are able to use the same |
| 2953 | mechanisms that HTTP/2 uses to negotiate their use (see Section 3). |
| 2954 | |
| 2955 | 8.1.2. HTTP Header Fields |
| 2956 | |
| 2957 | HTTP header fields carry information as a series of key-value pairs. |
| 2958 | For a listing of registered HTTP headers, see the "Message Header |
| 2959 | Field" registry maintained at <https://www.iana.org/assignments/ |
| 2960 | message-headers>. |
| 2961 | |
| 2962 | Just as in HTTP/1.x, header field names are strings of ASCII |
| 2963 | characters that are compared in a case-insensitive fashion. However, |
| 2964 | header field names MUST be converted to lowercase prior to their |
| 2965 | encoding in HTTP/2. A request or response containing uppercase |
| 2966 | header field names MUST be treated as malformed (Section 8.1.2.6). |
| 2967 | |
| 2968 | |
| 2969 | |
| 2970 | Belshe, et al. Standards Track [Page 53] |
| 2971 | \f |
| 2972 | RFC 7540 HTTP/2 May 2015 |
| 2973 | |
| 2974 | |
| 2975 | 8.1.2.1. Pseudo-Header Fields |
| 2976 | |
| 2977 | While HTTP/1.x used the message start-line (see [RFC7230], |
| 2978 | Section 3.1) to convey the target URI, the method of the request, and |
| 2979 | the status code for the response, HTTP/2 uses special pseudo-header |
| 2980 | fields beginning with ':' character (ASCII 0x3a) for this purpose. |
| 2981 | |
| 2982 | Pseudo-header fields are not HTTP header fields. Endpoints MUST NOT |
| 2983 | generate pseudo-header fields other than those defined in this |
| 2984 | document. |
| 2985 | |
| 2986 | Pseudo-header fields are only valid in the context in which they are |
| 2987 | defined. Pseudo-header fields defined for requests MUST NOT appear |
| 2988 | in responses; pseudo-header fields defined for responses MUST NOT |
| 2989 | appear in requests. Pseudo-header fields MUST NOT appear in |
| 2990 | trailers. Endpoints MUST treat a request or response that contains |
| 2991 | undefined or invalid pseudo-header fields as malformed |
| 2992 | (Section 8.1.2.6). |
| 2993 | |
| 2994 | All pseudo-header fields MUST appear in the header block before |
| 2995 | regular header fields. Any request or response that contains a |
| 2996 | pseudo-header field that appears in a header block after a regular |
| 2997 | header field MUST be treated as malformed (Section 8.1.2.6). |
| 2998 | |
| 2999 | 8.1.2.2. Connection-Specific Header Fields |
| 3000 | |
| 3001 | HTTP/2 does not use the Connection header field to indicate |
| 3002 | connection-specific header fields; in this protocol, connection- |
| 3003 | specific metadata is conveyed by other means. An endpoint MUST NOT |
| 3004 | generate an HTTP/2 message containing connection-specific header |
| 3005 | fields; any message containing connection-specific header fields MUST |
| 3006 | be treated as malformed (Section 8.1.2.6). |
| 3007 | |
| 3008 | The only exception to this is the TE header field, which MAY be |
| 3009 | present in an HTTP/2 request; when it is, it MUST NOT contain any |
| 3010 | value other than "trailers". |
| 3011 | |
| 3012 | This means that an intermediary transforming an HTTP/1.x message to |
| 3013 | HTTP/2 will need to remove any header fields nominated by the |
| 3014 | Connection header field, along with the Connection header field |
| 3015 | itself. Such intermediaries SHOULD also remove other connection- |
| 3016 | specific header fields, such as Keep-Alive, Proxy-Connection, |
| 3017 | Transfer-Encoding, and Upgrade, even if they are not nominated by the |
| 3018 | Connection header field. |
| 3019 | |
| 3020 | Note: HTTP/2 purposefully does not support upgrade to another |
| 3021 | protocol. The handshake methods described in Section 3 are |
| 3022 | believed sufficient to negotiate the use of alternative protocols. |
| 3023 | |
| 3024 | |
| 3025 | |
| 3026 | Belshe, et al. Standards Track [Page 54] |
| 3027 | \f |
| 3028 | RFC 7540 HTTP/2 May 2015 |
| 3029 | |
| 3030 | |
| 3031 | 8.1.2.3. Request Pseudo-Header Fields |
| 3032 | |
| 3033 | The following pseudo-header fields are defined for HTTP/2 requests: |
| 3034 | |
| 3035 | o The ":method" pseudo-header field includes the HTTP method |
| 3036 | ([RFC7231], Section 4). |
| 3037 | |
| 3038 | o The ":scheme" pseudo-header field includes the scheme portion of |
| 3039 | the target URI ([RFC3986], Section 3.1). |
| 3040 | |
| 3041 | ":scheme" is not restricted to "http" and "https" schemed URIs. A |
| 3042 | proxy or gateway can translate requests for non-HTTP schemes, |
| 3043 | enabling the use of HTTP to interact with non-HTTP services. |
| 3044 | |
| 3045 | o The ":authority" pseudo-header field includes the authority |
| 3046 | portion of the target URI ([RFC3986], Section 3.2). The authority |
| 3047 | MUST NOT include the deprecated "userinfo" subcomponent for "http" |
| 3048 | or "https" schemed URIs. |
| 3049 | |
| 3050 | To ensure that the HTTP/1.1 request line can be reproduced |
| 3051 | accurately, this pseudo-header field MUST be omitted when |
| 3052 | translating from an HTTP/1.1 request that has a request target in |
| 3053 | origin or asterisk form (see [RFC7230], Section 5.3). Clients |
| 3054 | that generate HTTP/2 requests directly SHOULD use the ":authority" |
| 3055 | pseudo-header field instead of the Host header field. An |
| 3056 | intermediary that converts an HTTP/2 request to HTTP/1.1 MUST |
| 3057 | create a Host header field if one is not present in a request by |
| 3058 | copying the value of the ":authority" pseudo-header field. |
| 3059 | |
| 3060 | o The ":path" pseudo-header field includes the path and query parts |
| 3061 | of the target URI (the "path-absolute" production and optionally a |
| 3062 | '?' character followed by the "query" production (see Sections 3.3 |
| 3063 | and 3.4 of [RFC3986]). A request in asterisk form includes the |
| 3064 | value '*' for the ":path" pseudo-header field. |
| 3065 | |
| 3066 | This pseudo-header field MUST NOT be empty for "http" or "https" |
| 3067 | URIs; "http" or "https" URIs that do not contain a path component |
| 3068 | MUST include a value of '/'. The exception to this rule is an |
| 3069 | OPTIONS request for an "http" or "https" URI that does not include |
| 3070 | a path component; these MUST include a ":path" pseudo-header field |
| 3071 | with a value of '*' (see [RFC7230], Section 5.3.4). |
| 3072 | |
| 3073 | |
| 3074 | |
| 3075 | |
| 3076 | |
| 3077 | |
| 3078 | |
| 3079 | |
| 3080 | |
| 3081 | |
| 3082 | Belshe, et al. Standards Track [Page 55] |
| 3083 | \f |
| 3084 | RFC 7540 HTTP/2 May 2015 |
| 3085 | |
| 3086 | |
| 3087 | All HTTP/2 requests MUST include exactly one valid value for the |
| 3088 | ":method", ":scheme", and ":path" pseudo-header fields, unless it is |
| 3089 | a CONNECT request (Section 8.3). An HTTP request that omits |
| 3090 | mandatory pseudo-header fields is malformed (Section 8.1.2.6). |
| 3091 | |
| 3092 | HTTP/2 does not define a way to carry the version identifier that is |
| 3093 | included in the HTTP/1.1 request line. |
| 3094 | |
| 3095 | 8.1.2.4. Response Pseudo-Header Fields |
| 3096 | |
| 3097 | For HTTP/2 responses, a single ":status" pseudo-header field is |
| 3098 | defined that carries the HTTP status code field (see [RFC7231], |
| 3099 | Section 6). This pseudo-header field MUST be included in all |
| 3100 | responses; otherwise, the response is malformed (Section 8.1.2.6). |
| 3101 | |
| 3102 | HTTP/2 does not define a way to carry the version or reason phrase |
| 3103 | that is included in an HTTP/1.1 status line. |
| 3104 | |
| 3105 | 8.1.2.5. Compressing the Cookie Header Field |
| 3106 | |
| 3107 | The Cookie header field [COOKIE] uses a semi-colon (";") to delimit |
| 3108 | cookie-pairs (or "crumbs"). This header field doesn't follow the |
| 3109 | list construction rules in HTTP (see [RFC7230], Section 3.2.2), which |
| 3110 | prevents cookie-pairs from being separated into different name-value |
| 3111 | pairs. This can significantly reduce compression efficiency as |
| 3112 | individual cookie-pairs are updated. |
| 3113 | |
| 3114 | To allow for better compression efficiency, the Cookie header field |
| 3115 | MAY be split into separate header fields, each with one or more |
| 3116 | cookie-pairs. If there are multiple Cookie header fields after |
| 3117 | decompression, these MUST be concatenated into a single octet string |
| 3118 | using the two-octet delimiter of 0x3B, 0x20 (the ASCII string "; ") |
| 3119 | before being passed into a non-HTTP/2 context, such as an HTTP/1.1 |
| 3120 | connection, or a generic HTTP server application. |
| 3121 | |
| 3122 | Therefore, the following two lists of Cookie header fields are |
| 3123 | semantically equivalent. |
| 3124 | |
| 3125 | cookie: a=b; c=d; e=f |
| 3126 | |
| 3127 | cookie: a=b |
| 3128 | cookie: c=d |
| 3129 | cookie: e=f |
| 3130 | |
| 3131 | |
| 3132 | |
| 3133 | |
| 3134 | |
| 3135 | |
| 3136 | |
| 3137 | |
| 3138 | Belshe, et al. Standards Track [Page 56] |
| 3139 | \f |
| 3140 | RFC 7540 HTTP/2 May 2015 |
| 3141 | |
| 3142 | |
| 3143 | 8.1.2.6. Malformed Requests and Responses |
| 3144 | |
| 3145 | A malformed request or response is one that is an otherwise valid |
| 3146 | sequence of HTTP/2 frames but is invalid due to the presence of |
| 3147 | extraneous frames, prohibited header fields, the absence of mandatory |
| 3148 | header fields, or the inclusion of uppercase header field names. |
| 3149 | |
| 3150 | A request or response that includes a payload body can include a |
| 3151 | content-length header field. A request or response is also malformed |
| 3152 | if the value of a content-length header field does not equal the sum |
| 3153 | of the DATA frame payload lengths that form the body. A response |
| 3154 | that is defined to have no payload, as described in [RFC7230], |
| 3155 | Section 3.3.2, can have a non-zero content-length header field, even |
| 3156 | though no content is included in DATA frames. |
| 3157 | |
| 3158 | Intermediaries that process HTTP requests or responses (i.e., any |
| 3159 | intermediary not acting as a tunnel) MUST NOT forward a malformed |
| 3160 | request or response. Malformed requests or responses that are |
| 3161 | detected MUST be treated as a stream error (Section 5.4.2) of type |
| 3162 | PROTOCOL_ERROR. |
| 3163 | |
| 3164 | For malformed requests, a server MAY send an HTTP response prior to |
| 3165 | closing or resetting the stream. Clients MUST NOT accept a malformed |
| 3166 | response. Note that these requirements are intended to protect |
| 3167 | against several types of common attacks against HTTP; they are |
| 3168 | deliberately strict because being permissive can expose |
| 3169 | implementations to these vulnerabilities. |
| 3170 | |
| 3171 | 8.1.3. Examples |
| 3172 | |
| 3173 | This section shows HTTP/1.1 requests and responses, with |
| 3174 | illustrations of equivalent HTTP/2 requests and responses. |
| 3175 | |
| 3176 | An HTTP GET request includes request header fields and no payload |
| 3177 | body and is therefore transmitted as a single HEADERS frame, followed |
| 3178 | by zero or more CONTINUATION frames containing the serialized block |
| 3179 | of request header fields. The HEADERS frame in the following has |
| 3180 | both the END_HEADERS and END_STREAM flags set; no CONTINUATION frames |
| 3181 | are sent. |
| 3182 | |
| 3183 | GET /resource HTTP/1.1 HEADERS |
| 3184 | Host: example.org ==> + END_STREAM |
| 3185 | Accept: image/jpeg + END_HEADERS |
| 3186 | :method = GET |
| 3187 | :scheme = https |
| 3188 | :path = /resource |
| 3189 | host = example.org |
| 3190 | accept = image/jpeg |
| 3191 | |
| 3192 | |
| 3193 | |
| 3194 | Belshe, et al. Standards Track [Page 57] |
| 3195 | \f |
| 3196 | RFC 7540 HTTP/2 May 2015 |
| 3197 | |
| 3198 | |
| 3199 | Similarly, a response that includes only response header fields is |
| 3200 | transmitted as a HEADERS frame (again, followed by zero or more |
| 3201 | CONTINUATION frames) containing the serialized block of response |
| 3202 | header fields. |
| 3203 | |
| 3204 | HTTP/1.1 304 Not Modified HEADERS |
| 3205 | ETag: "xyzzy" ==> + END_STREAM |
| 3206 | Expires: Thu, 23 Jan ... + END_HEADERS |
| 3207 | :status = 304 |
| 3208 | etag = "xyzzy" |
| 3209 | expires = Thu, 23 Jan ... |
| 3210 | |
| 3211 | An HTTP POST request that includes request header fields and payload |
| 3212 | data is transmitted as one HEADERS frame, followed by zero or more |
| 3213 | CONTINUATION frames containing the request header fields, followed by |
| 3214 | one or more DATA frames, with the last CONTINUATION (or HEADERS) |
| 3215 | frame having the END_HEADERS flag set and the final DATA frame having |
| 3216 | the END_STREAM flag set: |
| 3217 | |
| 3218 | POST /resource HTTP/1.1 HEADERS |
| 3219 | Host: example.org ==> - END_STREAM |
| 3220 | Content-Type: image/jpeg - END_HEADERS |
| 3221 | Content-Length: 123 :method = POST |
| 3222 | :path = /resource |
| 3223 | {binary data} :scheme = https |
| 3224 | |
| 3225 | CONTINUATION |
| 3226 | + END_HEADERS |
| 3227 | content-type = image/jpeg |
| 3228 | host = example.org |
| 3229 | content-length = 123 |
| 3230 | |
| 3231 | DATA |
| 3232 | + END_STREAM |
| 3233 | {binary data} |
| 3234 | |
| 3235 | Note that data contributing to any given header field could be spread |
| 3236 | between header block fragments. The allocation of header fields to |
| 3237 | frames in this example is illustrative only. |
| 3238 | |
| 3239 | A response that includes header fields and payload data is |
| 3240 | transmitted as a HEADERS frame, followed by zero or more CONTINUATION |
| 3241 | frames, followed by one or more DATA frames, with the last DATA frame |
| 3242 | in the sequence having the END_STREAM flag set: |
| 3243 | |
| 3244 | |
| 3245 | |
| 3246 | |
| 3247 | |
| 3248 | |
| 3249 | |
| 3250 | Belshe, et al. Standards Track [Page 58] |
| 3251 | \f |
| 3252 | RFC 7540 HTTP/2 May 2015 |
| 3253 | |
| 3254 | |
| 3255 | HTTP/1.1 200 OK HEADERS |
| 3256 | Content-Type: image/jpeg ==> - END_STREAM |
| 3257 | Content-Length: 123 + END_HEADERS |
| 3258 | :status = 200 |
| 3259 | {binary data} content-type = image/jpeg |
| 3260 | content-length = 123 |
| 3261 | |
| 3262 | DATA |
| 3263 | + END_STREAM |
| 3264 | {binary data} |
| 3265 | |
| 3266 | An informational response using a 1xx status code other than 101 is |
| 3267 | transmitted as a HEADERS frame, followed by zero or more CONTINUATION |
| 3268 | frames. |
| 3269 | |
| 3270 | Trailing header fields are sent as a header block after both the |
| 3271 | request or response header block and all the DATA frames have been |
| 3272 | sent. The HEADERS frame starting the trailers header block has the |
| 3273 | END_STREAM flag set. |
| 3274 | |
| 3275 | The following example includes both a 100 (Continue) status code, |
| 3276 | which is sent in response to a request containing a "100-continue" |
| 3277 | token in the Expect header field, and trailing header fields: |
| 3278 | |
| 3279 | HTTP/1.1 100 Continue HEADERS |
| 3280 | Extension-Field: bar ==> - END_STREAM |
| 3281 | + END_HEADERS |
| 3282 | :status = 100 |
| 3283 | extension-field = bar |
| 3284 | |
| 3285 | HTTP/1.1 200 OK HEADERS |
| 3286 | Content-Type: image/jpeg ==> - END_STREAM |
| 3287 | Transfer-Encoding: chunked + END_HEADERS |
| 3288 | Trailer: Foo :status = 200 |
| 3289 | content-length = 123 |
| 3290 | 123 content-type = image/jpeg |
| 3291 | {binary data} trailer = Foo |
| 3292 | 0 |
| 3293 | Foo: bar DATA |
| 3294 | - END_STREAM |
| 3295 | {binary data} |
| 3296 | |
| 3297 | HEADERS |
| 3298 | + END_STREAM |
| 3299 | + END_HEADERS |
| 3300 | foo = bar |
| 3301 | |
| 3302 | |
| 3303 | |
| 3304 | |
| 3305 | |
| 3306 | Belshe, et al. Standards Track [Page 59] |
| 3307 | \f |
| 3308 | RFC 7540 HTTP/2 May 2015 |
| 3309 | |
| 3310 | |
| 3311 | 8.1.4. Request Reliability Mechanisms in HTTP/2 |
| 3312 | |
| 3313 | In HTTP/1.1, an HTTP client is unable to retry a non-idempotent |
| 3314 | request when an error occurs because there is no means to determine |
| 3315 | the nature of the error. It is possible that some server processing |
| 3316 | occurred prior to the error, which could result in undesirable |
| 3317 | effects if the request were reattempted. |
| 3318 | |
| 3319 | HTTP/2 provides two mechanisms for providing a guarantee to a client |
| 3320 | that a request has not been processed: |
| 3321 | |
| 3322 | o The GOAWAY frame indicates the highest stream number that might |
| 3323 | have been processed. Requests on streams with higher numbers are |
| 3324 | therefore guaranteed to be safe to retry. |
| 3325 | |
| 3326 | o The REFUSED_STREAM error code can be included in a RST_STREAM |
| 3327 | frame to indicate that the stream is being closed prior to any |
| 3328 | processing having occurred. Any request that was sent on the |
| 3329 | reset stream can be safely retried. |
| 3330 | |
| 3331 | Requests that have not been processed have not failed; clients MAY |
| 3332 | automatically retry them, even those with non-idempotent methods. |
| 3333 | |
| 3334 | A server MUST NOT indicate that a stream has not been processed |
| 3335 | unless it can guarantee that fact. If frames that are on a stream |
| 3336 | are passed to the application layer for any stream, then |
| 3337 | REFUSED_STREAM MUST NOT be used for that stream, and a GOAWAY frame |
| 3338 | MUST include a stream identifier that is greater than or equal to the |
| 3339 | given stream identifier. |
| 3340 | |
| 3341 | In addition to these mechanisms, the PING frame provides a way for a |
| 3342 | client to easily test a connection. Connections that remain idle can |
| 3343 | become broken as some middleboxes (for instance, network address |
| 3344 | translators or load balancers) silently discard connection bindings. |
| 3345 | The PING frame allows a client to safely test whether a connection is |
| 3346 | still active without sending a request. |
| 3347 | |
| 3348 | 8.2. Server Push |
| 3349 | |
| 3350 | HTTP/2 allows a server to pre-emptively send (or "push") responses |
| 3351 | (along with corresponding "promised" requests) to a client in |
| 3352 | association with a previous client-initiated request. This can be |
| 3353 | useful when the server knows the client will need to have those |
| 3354 | responses available in order to fully process the response to the |
| 3355 | original request. |
| 3356 | |
| 3357 | |
| 3358 | |
| 3359 | |
| 3360 | |
| 3361 | |
| 3362 | Belshe, et al. Standards Track [Page 60] |
| 3363 | \f |
| 3364 | RFC 7540 HTTP/2 May 2015 |
| 3365 | |
| 3366 | |
| 3367 | A client can request that server push be disabled, though this is |
| 3368 | negotiated for each hop independently. The SETTINGS_ENABLE_PUSH |
| 3369 | setting can be set to 0 to indicate that server push is disabled. |
| 3370 | |
| 3371 | Promised requests MUST be cacheable (see [RFC7231], Section 4.2.3), |
| 3372 | MUST be safe (see [RFC7231], Section 4.2.1), and MUST NOT include a |
| 3373 | request body. Clients that receive a promised request that is not |
| 3374 | cacheable, that is not known to be safe, or that indicates the |
| 3375 | presence of a request body MUST reset the promised stream with a |
| 3376 | stream error (Section 5.4.2) of type PROTOCOL_ERROR. Note this could |
| 3377 | result in the promised stream being reset if the client does not |
| 3378 | recognize a newly defined method as being safe. |
| 3379 | |
| 3380 | Pushed responses that are cacheable (see [RFC7234], Section 3) can be |
| 3381 | stored by the client, if it implements an HTTP cache. Pushed |
| 3382 | responses are considered successfully validated on the origin server |
| 3383 | (e.g., if the "no-cache" cache response directive is present |
| 3384 | ([RFC7234], Section 5.2.2)) while the stream identified by the |
| 3385 | promised stream ID is still open. |
| 3386 | |
| 3387 | Pushed responses that are not cacheable MUST NOT be stored by any |
| 3388 | HTTP cache. They MAY be made available to the application |
| 3389 | separately. |
| 3390 | |
| 3391 | The server MUST include a value in the ":authority" pseudo-header |
| 3392 | field for which the server is authoritative (see Section 10.1). A |
| 3393 | client MUST treat a PUSH_PROMISE for which the server is not |
| 3394 | authoritative as a stream error (Section 5.4.2) of type |
| 3395 | PROTOCOL_ERROR. |
| 3396 | |
| 3397 | An intermediary can receive pushes from the server and choose not to |
| 3398 | forward them on to the client. In other words, how to make use of |
| 3399 | the pushed information is up to that intermediary. Equally, the |
| 3400 | intermediary might choose to make additional pushes to the client, |
| 3401 | without any action taken by the server. |
| 3402 | |
| 3403 | A client cannot push. Thus, servers MUST treat the receipt of a |
| 3404 | PUSH_PROMISE frame as a connection error (Section 5.4.1) of type |
| 3405 | PROTOCOL_ERROR. Clients MUST reject any attempt to change the |
| 3406 | SETTINGS_ENABLE_PUSH setting to a value other than 0 by treating the |
| 3407 | message as a connection error (Section 5.4.1) of type PROTOCOL_ERROR. |
| 3408 | |
| 3409 | 8.2.1. Push Requests |
| 3410 | |
| 3411 | Server push is semantically equivalent to a server responding to a |
| 3412 | request; however, in this case, that request is also sent by the |
| 3413 | server, as a PUSH_PROMISE frame. |
| 3414 | |
| 3415 | |
| 3416 | |
| 3417 | |
| 3418 | Belshe, et al. Standards Track [Page 61] |
| 3419 | \f |
| 3420 | RFC 7540 HTTP/2 May 2015 |
| 3421 | |
| 3422 | |
| 3423 | The PUSH_PROMISE frame includes a header block that contains a |
| 3424 | complete set of request header fields that the server attributes to |
| 3425 | the request. It is not possible to push a response to a request that |
| 3426 | includes a request body. |
| 3427 | |
| 3428 | Pushed responses are always associated with an explicit request from |
| 3429 | the client. The PUSH_PROMISE frames sent by the server are sent on |
| 3430 | that explicit request's stream. The PUSH_PROMISE frame also includes |
| 3431 | a promised stream identifier, chosen from the stream identifiers |
| 3432 | available to the server (see Section 5.1.1). |
| 3433 | |
| 3434 | The header fields in PUSH_PROMISE and any subsequent CONTINUATION |
| 3435 | frames MUST be a valid and complete set of request header fields |
| 3436 | (Section 8.1.2.3). The server MUST include a method in the ":method" |
| 3437 | pseudo-header field that is safe and cacheable. If a client receives |
| 3438 | a PUSH_PROMISE that does not include a complete and valid set of |
| 3439 | header fields or the ":method" pseudo-header field identifies a |
| 3440 | method that is not safe, it MUST respond with a stream error |
| 3441 | (Section 5.4.2) of type PROTOCOL_ERROR. |
| 3442 | |
| 3443 | The server SHOULD send PUSH_PROMISE (Section 6.6) frames prior to |
| 3444 | sending any frames that reference the promised responses. This |
| 3445 | avoids a race where clients issue requests prior to receiving any |
| 3446 | PUSH_PROMISE frames. |
| 3447 | |
| 3448 | For example, if the server receives a request for a document |
| 3449 | containing embedded links to multiple image files and the server |
| 3450 | chooses to push those additional images to the client, sending |
| 3451 | PUSH_PROMISE frames before the DATA frames that contain the image |
| 3452 | links ensures that the client is able to see that a resource will be |
| 3453 | pushed before discovering embedded links. Similarly, if the server |
| 3454 | pushes responses referenced by the header block (for instance, in |
| 3455 | Link header fields), sending a PUSH_PROMISE before sending the header |
| 3456 | block ensures that clients do not request those resources. |
| 3457 | |
| 3458 | PUSH_PROMISE frames MUST NOT be sent by the client. |
| 3459 | |
| 3460 | PUSH_PROMISE frames can be sent by the server in response to any |
| 3461 | client-initiated stream, but the stream MUST be in either the "open" |
| 3462 | or "half-closed (remote)" state with respect to the server. |
| 3463 | PUSH_PROMISE frames are interspersed with the frames that comprise a |
| 3464 | response, though they cannot be interspersed with HEADERS and |
| 3465 | CONTINUATION frames that comprise a single header block. |
| 3466 | |
| 3467 | Sending a PUSH_PROMISE frame creates a new stream and puts the stream |
| 3468 | into the "reserved (local)" state for the server and the "reserved |
| 3469 | (remote)" state for the client. |
| 3470 | |
| 3471 | |
| 3472 | |
| 3473 | |
| 3474 | Belshe, et al. Standards Track [Page 62] |
| 3475 | \f |
| 3476 | RFC 7540 HTTP/2 May 2015 |
| 3477 | |
| 3478 | |
| 3479 | 8.2.2. Push Responses |
| 3480 | |
| 3481 | After sending the PUSH_PROMISE frame, the server can begin delivering |
| 3482 | the pushed response as a response (Section 8.1.2.4) on a server- |
| 3483 | initiated stream that uses the promised stream identifier. The |
| 3484 | server uses this stream to transmit an HTTP response, using the same |
| 3485 | sequence of frames as defined in Section 8.1. This stream becomes |
| 3486 | "half-closed" to the client (Section 5.1) after the initial HEADERS |
| 3487 | frame is sent. |
| 3488 | |
| 3489 | Once a client receives a PUSH_PROMISE frame and chooses to accept the |
| 3490 | pushed response, the client SHOULD NOT issue any requests for the |
| 3491 | promised response until after the promised stream has closed. |
| 3492 | |
| 3493 | If the client determines, for any reason, that it does not wish to |
| 3494 | receive the pushed response from the server or if the server takes |
| 3495 | too long to begin sending the promised response, the client can send |
| 3496 | a RST_STREAM frame, using either the CANCEL or REFUSED_STREAM code |
| 3497 | and referencing the pushed stream's identifier. |
| 3498 | |
| 3499 | A client can use the SETTINGS_MAX_CONCURRENT_STREAMS setting to limit |
| 3500 | the number of responses that can be concurrently pushed by a server. |
| 3501 | Advertising a SETTINGS_MAX_CONCURRENT_STREAMS value of zero disables |
| 3502 | server push by preventing the server from creating the necessary |
| 3503 | streams. This does not prohibit a server from sending PUSH_PROMISE |
| 3504 | frames; clients need to reset any promised streams that are not |
| 3505 | wanted. |
| 3506 | |
| 3507 | Clients receiving a pushed response MUST validate that either the |
| 3508 | server is authoritative (see Section 10.1) or the proxy that provided |
| 3509 | the pushed response is configured for the corresponding request. For |
| 3510 | example, a server that offers a certificate for only the |
| 3511 | "example.com" DNS-ID or Common Name is not permitted to push a |
| 3512 | response for "https://www.example.org/doc". |
| 3513 | |
| 3514 | The response for a PUSH_PROMISE stream begins with a HEADERS frame, |
| 3515 | which immediately puts the stream into the "half-closed (remote)" |
| 3516 | state for the server and "half-closed (local)" state for the client, |
| 3517 | and ends with a frame bearing END_STREAM, which places the stream in |
| 3518 | the "closed" state. |
| 3519 | |
| 3520 | Note: The client never sends a frame with the END_STREAM flag for |
| 3521 | a server push. |
| 3522 | |
| 3523 | |
| 3524 | |
| 3525 | |
| 3526 | |
| 3527 | |
| 3528 | |
| 3529 | |
| 3530 | Belshe, et al. Standards Track [Page 63] |
| 3531 | \f |
| 3532 | RFC 7540 HTTP/2 May 2015 |
| 3533 | |
| 3534 | |
| 3535 | 8.3. The CONNECT Method |
| 3536 | |
| 3537 | In HTTP/1.x, the pseudo-method CONNECT ([RFC7231], Section 4.3.6) is |
| 3538 | used to convert an HTTP connection into a tunnel to a remote host. |
| 3539 | CONNECT is primarily used with HTTP proxies to establish a TLS |
| 3540 | session with an origin server for the purposes of interacting with |
| 3541 | "https" resources. |
| 3542 | |
| 3543 | In HTTP/2, the CONNECT method is used to establish a tunnel over a |
| 3544 | single HTTP/2 stream to a remote host for similar purposes. The HTTP |
| 3545 | header field mapping works as defined in Section 8.1.2.3 ("Request |
| 3546 | Pseudo-Header Fields"), with a few differences. Specifically: |
| 3547 | |
| 3548 | o The ":method" pseudo-header field is set to "CONNECT". |
| 3549 | |
| 3550 | o The ":scheme" and ":path" pseudo-header fields MUST be omitted. |
| 3551 | |
| 3552 | o The ":authority" pseudo-header field contains the host and port to |
| 3553 | connect to (equivalent to the authority-form of the request-target |
| 3554 | of CONNECT requests (see [RFC7230], Section 5.3)). |
| 3555 | |
| 3556 | A CONNECT request that does not conform to these restrictions is |
| 3557 | malformed (Section 8.1.2.6). |
| 3558 | |
| 3559 | A proxy that supports CONNECT establishes a TCP connection [TCP] to |
| 3560 | the server identified in the ":authority" pseudo-header field. Once |
| 3561 | this connection is successfully established, the proxy sends a |
| 3562 | HEADERS frame containing a 2xx series status code to the client, as |
| 3563 | defined in [RFC7231], Section 4.3.6. |
| 3564 | |
| 3565 | After the initial HEADERS frame sent by each peer, all subsequent |
| 3566 | DATA frames correspond to data sent on the TCP connection. The |
| 3567 | payload of any DATA frames sent by the client is transmitted by the |
| 3568 | proxy to the TCP server; data received from the TCP server is |
| 3569 | assembled into DATA frames by the proxy. Frame types other than DATA |
| 3570 | or stream management frames (RST_STREAM, WINDOW_UPDATE, and PRIORITY) |
| 3571 | MUST NOT be sent on a connected stream and MUST be treated as a |
| 3572 | stream error (Section 5.4.2) if received. |
| 3573 | |
| 3574 | The TCP connection can be closed by either peer. The END_STREAM flag |
| 3575 | on a DATA frame is treated as being equivalent to the TCP FIN bit. A |
| 3576 | client is expected to send a DATA frame with the END_STREAM flag set |
| 3577 | after receiving a frame bearing the END_STREAM flag. A proxy that |
| 3578 | receives a DATA frame with the END_STREAM flag set sends the attached |
| 3579 | data with the FIN bit set on the last TCP segment. A proxy that |
| 3580 | receives a TCP segment with the FIN bit set sends a DATA frame with |
| 3581 | the END_STREAM flag set. Note that the final TCP segment or DATA |
| 3582 | frame could be empty. |
| 3583 | |
| 3584 | |
| 3585 | |
| 3586 | Belshe, et al. Standards Track [Page 64] |
| 3587 | \f |
| 3588 | RFC 7540 HTTP/2 May 2015 |
| 3589 | |
| 3590 | |
| 3591 | A TCP connection error is signaled with RST_STREAM. A proxy treats |
| 3592 | any error in the TCP connection, which includes receiving a TCP |
| 3593 | segment with the RST bit set, as a stream error (Section 5.4.2) of |
| 3594 | type CONNECT_ERROR. Correspondingly, a proxy MUST send a TCP segment |
| 3595 | with the RST bit set if it detects an error with the stream or the |
| 3596 | HTTP/2 connection. |
| 3597 | |
| 3598 | 9. Additional HTTP Requirements/Considerations |
| 3599 | |
| 3600 | This section outlines attributes of the HTTP protocol that improve |
| 3601 | interoperability, reduce exposure to known security vulnerabilities, |
| 3602 | or reduce the potential for implementation variation. |
| 3603 | |
| 3604 | 9.1. Connection Management |
| 3605 | |
| 3606 | HTTP/2 connections are persistent. For best performance, it is |
| 3607 | expected that clients will not close connections until it is |
| 3608 | determined that no further communication with a server is necessary |
| 3609 | (for example, when a user navigates away from a particular web page) |
| 3610 | or until the server closes the connection. |
| 3611 | |
| 3612 | Clients SHOULD NOT open more than one HTTP/2 connection to a given |
| 3613 | host and port pair, where the host is derived from a URI, a selected |
| 3614 | alternative service [ALT-SVC], or a configured proxy. |
| 3615 | |
| 3616 | A client can create additional connections as replacements, either to |
| 3617 | replace connections that are near to exhausting the available stream |
| 3618 | identifier space (Section 5.1.1), to refresh the keying material for |
| 3619 | a TLS connection, or to replace connections that have encountered |
| 3620 | errors (Section 5.4.1). |
| 3621 | |
| 3622 | A client MAY open multiple connections to the same IP address and TCP |
| 3623 | port using different Server Name Indication [TLS-EXT] values or to |
| 3624 | provide different TLS client certificates but SHOULD avoid creating |
| 3625 | multiple connections with the same configuration. |
| 3626 | |
| 3627 | Servers are encouraged to maintain open connections for as long as |
| 3628 | possible but are permitted to terminate idle connections if |
| 3629 | necessary. When either endpoint chooses to close the transport-layer |
| 3630 | TCP connection, the terminating endpoint SHOULD first send a GOAWAY |
| 3631 | (Section 6.8) frame so that both endpoints can reliably determine |
| 3632 | whether previously sent frames have been processed and gracefully |
| 3633 | complete or terminate any necessary remaining tasks. |
| 3634 | |
| 3635 | |
| 3636 | |
| 3637 | |
| 3638 | |
| 3639 | |
| 3640 | |
| 3641 | |
| 3642 | Belshe, et al. Standards Track [Page 65] |
| 3643 | \f |
| 3644 | RFC 7540 HTTP/2 May 2015 |
| 3645 | |
| 3646 | |
| 3647 | 9.1.1. Connection Reuse |
| 3648 | |
| 3649 | Connections that are made to an origin server, either directly or |
| 3650 | through a tunnel created using the CONNECT method (Section 8.3), MAY |
| 3651 | be reused for requests with multiple different URI authority |
| 3652 | components. A connection can be reused as long as the origin server |
| 3653 | is authoritative (Section 10.1). For TCP connections without TLS, |
| 3654 | this depends on the host having resolved to the same IP address. |
| 3655 | |
| 3656 | For "https" resources, connection reuse additionally depends on |
| 3657 | having a certificate that is valid for the host in the URI. The |
| 3658 | certificate presented by the server MUST satisfy any checks that the |
| 3659 | client would perform when forming a new TLS connection for the host |
| 3660 | in the URI. |
| 3661 | |
| 3662 | An origin server might offer a certificate with multiple |
| 3663 | "subjectAltName" attributes or names with wildcards, one of which is |
| 3664 | valid for the authority in the URI. For example, a certificate with |
| 3665 | a "subjectAltName" of "*.example.com" might permit the use of the |
| 3666 | same connection for requests to URIs starting with |
| 3667 | "https://a.example.com/" and "https://b.example.com/". |
| 3668 | |
| 3669 | In some deployments, reusing a connection for multiple origins can |
| 3670 | result in requests being directed to the wrong origin server. For |
| 3671 | example, TLS termination might be performed by a middlebox that uses |
| 3672 | the TLS Server Name Indication (SNI) [TLS-EXT] extension to select an |
| 3673 | origin server. This means that it is possible for clients to send |
| 3674 | confidential information to servers that might not be the intended |
| 3675 | target for the request, even though the server is otherwise |
| 3676 | authoritative. |
| 3677 | |
| 3678 | A server that does not wish clients to reuse connections can indicate |
| 3679 | that it is not authoritative for a request by sending a 421 |
| 3680 | (Misdirected Request) status code in response to the request (see |
| 3681 | Section 9.1.2). |
| 3682 | |
| 3683 | A client that is configured to use a proxy over HTTP/2 directs |
| 3684 | requests to that proxy through a single connection. That is, all |
| 3685 | requests sent via a proxy reuse the connection to the proxy. |
| 3686 | |
| 3687 | 9.1.2. The 421 (Misdirected Request) Status Code |
| 3688 | |
| 3689 | The 421 (Misdirected Request) status code indicates that the request |
| 3690 | was directed at a server that is not able to produce a response. |
| 3691 | This can be sent by a server that is not configured to produce |
| 3692 | responses for the combination of scheme and authority that are |
| 3693 | included in the request URI. |
| 3694 | |
| 3695 | |
| 3696 | |
| 3697 | |
| 3698 | Belshe, et al. Standards Track [Page 66] |
| 3699 | \f |
| 3700 | RFC 7540 HTTP/2 May 2015 |
| 3701 | |
| 3702 | |
| 3703 | Clients receiving a 421 (Misdirected Request) response from a server |
| 3704 | MAY retry the request -- whether the request method is idempotent or |
| 3705 | not -- over a different connection. This is possible if a connection |
| 3706 | is reused (Section 9.1.1) or if an alternative service is selected |
| 3707 | [ALT-SVC]. |
| 3708 | |
| 3709 | This status code MUST NOT be generated by proxies. |
| 3710 | |
| 3711 | A 421 response is cacheable by default, i.e., unless otherwise |
| 3712 | indicated by the method definition or explicit cache controls (see |
| 3713 | Section 4.2.2 of [RFC7234]). |
| 3714 | |
| 3715 | 9.2. Use of TLS Features |
| 3716 | |
| 3717 | Implementations of HTTP/2 MUST use TLS version 1.2 [TLS12] or higher |
| 3718 | for HTTP/2 over TLS. The general TLS usage guidance in [TLSBCP] |
| 3719 | SHOULD be followed, with some additional restrictions that are |
| 3720 | specific to HTTP/2. |
| 3721 | |
| 3722 | The TLS implementation MUST support the Server Name Indication (SNI) |
| 3723 | [TLS-EXT] extension to TLS. HTTP/2 clients MUST indicate the target |
| 3724 | domain name when negotiating TLS. |
| 3725 | |
| 3726 | Deployments of HTTP/2 that negotiate TLS 1.3 or higher need only |
| 3727 | support and use the SNI extension; deployments of TLS 1.2 are subject |
| 3728 | to the requirements in the following sections. Implementations are |
| 3729 | encouraged to provide defaults that comply, but it is recognized that |
| 3730 | deployments are ultimately responsible for compliance. |
| 3731 | |
| 3732 | 9.2.1. TLS 1.2 Features |
| 3733 | |
| 3734 | This section describes restrictions on the TLS 1.2 feature set that |
| 3735 | can be used with HTTP/2. Due to deployment limitations, it might not |
| 3736 | be possible to fail TLS negotiation when these restrictions are not |
| 3737 | met. An endpoint MAY immediately terminate an HTTP/2 connection that |
| 3738 | does not meet these TLS requirements with a connection error |
| 3739 | (Section 5.4.1) of type INADEQUATE_SECURITY. |
| 3740 | |
| 3741 | A deployment of HTTP/2 over TLS 1.2 MUST disable compression. TLS |
| 3742 | compression can lead to the exposure of information that would not |
| 3743 | otherwise be revealed [RFC3749]. Generic compression is unnecessary |
| 3744 | since HTTP/2 provides compression features that are more aware of |
| 3745 | context and therefore likely to be more appropriate for use for |
| 3746 | performance, security, or other reasons. |
| 3747 | |
| 3748 | A deployment of HTTP/2 over TLS 1.2 MUST disable renegotiation. An |
| 3749 | endpoint MUST treat a TLS renegotiation as a connection error |
| 3750 | (Section 5.4.1) of type PROTOCOL_ERROR. Note that disabling |
| 3751 | |
| 3752 | |
| 3753 | |
| 3754 | Belshe, et al. Standards Track [Page 67] |
| 3755 | \f |
| 3756 | RFC 7540 HTTP/2 May 2015 |
| 3757 | |
| 3758 | |
| 3759 | renegotiation can result in long-lived connections becoming unusable |
| 3760 | due to limits on the number of messages the underlying cipher suite |
| 3761 | can encipher. |
| 3762 | |
| 3763 | An endpoint MAY use renegotiation to provide confidentiality |
| 3764 | protection for client credentials offered in the handshake, but any |
| 3765 | renegotiation MUST occur prior to sending the connection preface. A |
| 3766 | server SHOULD request a client certificate if it sees a renegotiation |
| 3767 | request immediately after establishing a connection. |
| 3768 | |
| 3769 | This effectively prevents the use of renegotiation in response to a |
| 3770 | request for a specific protected resource. A future specification |
| 3771 | might provide a way to support this use case. Alternatively, a |
| 3772 | server might use an error (Section 5.4) of type HTTP_1_1_REQUIRED to |
| 3773 | request the client use a protocol that supports renegotiation. |
| 3774 | |
| 3775 | Implementations MUST support ephemeral key exchange sizes of at least |
| 3776 | 2048 bits for cipher suites that use ephemeral finite field Diffie- |
| 3777 | Hellman (DHE) [TLS12] and 224 bits for cipher suites that use |
| 3778 | ephemeral elliptic curve Diffie-Hellman (ECDHE) [RFC4492]. Clients |
| 3779 | MUST accept DHE sizes of up to 4096 bits. Endpoints MAY treat |
| 3780 | negotiation of key sizes smaller than the lower limits as a |
| 3781 | connection error (Section 5.4.1) of type INADEQUATE_SECURITY. |
| 3782 | |
| 3783 | 9.2.2. TLS 1.2 Cipher Suites |
| 3784 | |
| 3785 | A deployment of HTTP/2 over TLS 1.2 SHOULD NOT use any of the cipher |
| 3786 | suites that are listed in the cipher suite black list (Appendix A). |
| 3787 | |
| 3788 | Endpoints MAY choose to generate a connection error (Section 5.4.1) |
| 3789 | of type INADEQUATE_SECURITY if one of the cipher suites from the |
| 3790 | black list is negotiated. A deployment that chooses to use a black- |
| 3791 | listed cipher suite risks triggering a connection error unless the |
| 3792 | set of potential peers is known to accept that cipher suite. |
| 3793 | |
| 3794 | Implementations MUST NOT generate this error in reaction to the |
| 3795 | negotiation of a cipher suite that is not on the black list. |
| 3796 | Consequently, when clients offer a cipher suite that is not on the |
| 3797 | black list, they have to be prepared to use that cipher suite with |
| 3798 | HTTP/2. |
| 3799 | |
| 3800 | The black list includes the cipher suite that TLS 1.2 makes |
| 3801 | mandatory, which means that TLS 1.2 deployments could have non- |
| 3802 | intersecting sets of permitted cipher suites. To avoid this problem |
| 3803 | causing TLS handshake failures, deployments of HTTP/2 that use TLS |
| 3804 | 1.2 MUST support TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] |
| 3805 | with the P-256 elliptic curve [FIPS186]. |
| 3806 | |
| 3807 | |
| 3808 | |
| 3809 | |
| 3810 | Belshe, et al. Standards Track [Page 68] |
| 3811 | \f |
| 3812 | RFC 7540 HTTP/2 May 2015 |
| 3813 | |
| 3814 | |
| 3815 | Note that clients might advertise support of cipher suites that are |
| 3816 | on the black list in order to allow for connection to servers that do |
| 3817 | not support HTTP/2. This allows servers to select HTTP/1.1 with a |
| 3818 | cipher suite that is on the HTTP/2 black list. However, this can |
| 3819 | result in HTTP/2 being negotiated with a black-listed cipher suite if |
| 3820 | the application protocol and cipher suite are independently selected. |
| 3821 | |
| 3822 | 10. Security Considerations |
| 3823 | |
| 3824 | 10.1. Server Authority |
| 3825 | |
| 3826 | HTTP/2 relies on the HTTP/1.1 definition of authority for determining |
| 3827 | whether a server is authoritative in providing a given response (see |
| 3828 | [RFC7230], Section 9.1). This relies on local name resolution for |
| 3829 | the "http" URI scheme and the authenticated server identity for the |
| 3830 | "https" scheme (see [RFC2818], Section 3). |
| 3831 | |
| 3832 | 10.2. Cross-Protocol Attacks |
| 3833 | |
| 3834 | In a cross-protocol attack, an attacker causes a client to initiate a |
| 3835 | transaction in one protocol toward a server that understands a |
| 3836 | different protocol. An attacker might be able to cause the |
| 3837 | transaction to appear as a valid transaction in the second protocol. |
| 3838 | In combination with the capabilities of the web context, this can be |
| 3839 | used to interact with poorly protected servers in private networks. |
| 3840 | |
| 3841 | Completing a TLS handshake with an ALPN identifier for HTTP/2 can be |
| 3842 | considered sufficient protection against cross-protocol attacks. |
| 3843 | ALPN provides a positive indication that a server is willing to |
| 3844 | proceed with HTTP/2, which prevents attacks on other TLS-based |
| 3845 | protocols. |
| 3846 | |
| 3847 | The encryption in TLS makes it difficult for attackers to control the |
| 3848 | data that could be used in a cross-protocol attack on a cleartext |
| 3849 | protocol. |
| 3850 | |
| 3851 | The cleartext version of HTTP/2 has minimal protection against cross- |
| 3852 | protocol attacks. The connection preface (Section 3.5) contains a |
| 3853 | string that is designed to confuse HTTP/1.1 servers, but no special |
| 3854 | protection is offered for other protocols. A server that is willing |
| 3855 | to ignore parts of an HTTP/1.1 request containing an Upgrade header |
| 3856 | field in addition to the client connection preface could be exposed |
| 3857 | to a cross-protocol attack. |
| 3858 | |
| 3859 | |
| 3860 | |
| 3861 | |
| 3862 | |
| 3863 | |
| 3864 | |
| 3865 | |
| 3866 | Belshe, et al. Standards Track [Page 69] |
| 3867 | \f |
| 3868 | RFC 7540 HTTP/2 May 2015 |
| 3869 | |
| 3870 | |
| 3871 | 10.3. Intermediary Encapsulation Attacks |
| 3872 | |
| 3873 | The HTTP/2 header field encoding allows the expression of names that |
| 3874 | are not valid field names in the Internet Message Syntax used by |
| 3875 | HTTP/1.1. Requests or responses containing invalid header field |
| 3876 | names MUST be treated as malformed (Section 8.1.2.6). An |
| 3877 | intermediary therefore cannot translate an HTTP/2 request or response |
| 3878 | containing an invalid field name into an HTTP/1.1 message. |
| 3879 | |
| 3880 | Similarly, HTTP/2 allows header field values that are not valid. |
| 3881 | While most of the values that can be encoded will not alter header |
| 3882 | field parsing, carriage return (CR, ASCII 0xd), line feed (LF, ASCII |
| 3883 | 0xa), and the zero character (NUL, ASCII 0x0) might be exploited by |
| 3884 | an attacker if they are translated verbatim. Any request or response |
| 3885 | that contains a character not permitted in a header field value MUST |
| 3886 | be treated as malformed (Section 8.1.2.6). Valid characters are |
| 3887 | defined by the "field-content" ABNF rule in Section 3.2 of [RFC7230]. |
| 3888 | |
| 3889 | 10.4. Cacheability of Pushed Responses |
| 3890 | |
| 3891 | Pushed responses do not have an explicit request from the client; the |
| 3892 | request is provided by the server in the PUSH_PROMISE frame. |
| 3893 | |
| 3894 | Caching responses that are pushed is possible based on the guidance |
| 3895 | provided by the origin server in the Cache-Control header field. |
| 3896 | However, this can cause issues if a single server hosts more than one |
| 3897 | tenant. For example, a server might offer multiple users each a |
| 3898 | small portion of its URI space. |
| 3899 | |
| 3900 | Where multiple tenants share space on the same server, that server |
| 3901 | MUST ensure that tenants are not able to push representations of |
| 3902 | resources that they do not have authority over. Failure to enforce |
| 3903 | this would allow a tenant to provide a representation that would be |
| 3904 | served out of cache, overriding the actual representation that the |
| 3905 | authoritative tenant provides. |
| 3906 | |
| 3907 | Pushed responses for which an origin server is not authoritative (see |
| 3908 | Section 10.1) MUST NOT be used or cached. |
| 3909 | |
| 3910 | 10.5. Denial-of-Service Considerations |
| 3911 | |
| 3912 | An HTTP/2 connection can demand a greater commitment of resources to |
| 3913 | operate than an HTTP/1.1 connection. The use of header compression |
| 3914 | and flow control depend on a commitment of resources for storing a |
| 3915 | greater amount of state. Settings for these features ensure that |
| 3916 | memory commitments for these features are strictly bounded. |
| 3917 | |
| 3918 | |
| 3919 | |
| 3920 | |
| 3921 | |
| 3922 | Belshe, et al. Standards Track [Page 70] |
| 3923 | \f |
| 3924 | RFC 7540 HTTP/2 May 2015 |
| 3925 | |
| 3926 | |
| 3927 | The number of PUSH_PROMISE frames is not constrained in the same |
| 3928 | fashion. A client that accepts server push SHOULD limit the number |
| 3929 | of streams it allows to be in the "reserved (remote)" state. An |
| 3930 | excessive number of server push streams can be treated as a stream |
| 3931 | error (Section 5.4.2) of type ENHANCE_YOUR_CALM. |
| 3932 | |
| 3933 | Processing capacity cannot be guarded as effectively as state |
| 3934 | capacity. |
| 3935 | |
| 3936 | The SETTINGS frame can be abused to cause a peer to expend additional |
| 3937 | processing time. This might be done by pointlessly changing SETTINGS |
| 3938 | parameters, setting multiple undefined parameters, or changing the |
| 3939 | same setting multiple times in the same frame. WINDOW_UPDATE or |
| 3940 | PRIORITY frames can be abused to cause an unnecessary waste of |
| 3941 | resources. |
| 3942 | |
| 3943 | Large numbers of small or empty frames can be abused to cause a peer |
| 3944 | to expend time processing frame headers. Note, however, that some |
| 3945 | uses are entirely legitimate, such as the sending of an empty DATA or |
| 3946 | CONTINUATION frame at the end of a stream. |
| 3947 | |
| 3948 | Header compression also offers some opportunities to waste processing |
| 3949 | resources; see Section 7 of [COMPRESSION] for more details on |
| 3950 | potential abuses. |
| 3951 | |
| 3952 | Limits in SETTINGS parameters cannot be reduced instantaneously, |
| 3953 | which leaves an endpoint exposed to behavior from a peer that could |
| 3954 | exceed the new limits. In particular, immediately after establishing |
| 3955 | a connection, limits set by a server are not known to clients and |
| 3956 | could be exceeded without being an obvious protocol violation. |
| 3957 | |
| 3958 | All these features -- i.e., SETTINGS changes, small frames, header |
| 3959 | compression -- have legitimate uses. These features become a burden |
| 3960 | only when they are used unnecessarily or to excess. |
| 3961 | |
| 3962 | An endpoint that doesn't monitor this behavior exposes itself to a |
| 3963 | risk of denial-of-service attack. Implementations SHOULD track the |
| 3964 | use of these features and set limits on their use. An endpoint MAY |
| 3965 | treat activity that is suspicious as a connection error |
| 3966 | (Section 5.4.1) of type ENHANCE_YOUR_CALM. |
| 3967 | |
| 3968 | 10.5.1. Limits on Header Block Size |
| 3969 | |
| 3970 | A large header block (Section 4.3) can cause an implementation to |
| 3971 | commit a large amount of state. Header fields that are critical for |
| 3972 | routing can appear toward the end of a header block, which prevents |
| 3973 | streaming of header fields to their ultimate destination. This |
| 3974 | ordering and other reasons, such as ensuring cache correctness, mean |
| 3975 | |
| 3976 | |
| 3977 | |
| 3978 | Belshe, et al. Standards Track [Page 71] |
| 3979 | \f |
| 3980 | RFC 7540 HTTP/2 May 2015 |
| 3981 | |
| 3982 | |
| 3983 | that an endpoint might need to buffer the entire header block. Since |
| 3984 | there is no hard limit to the size of a header block, some endpoints |
| 3985 | could be forced to commit a large amount of available memory for |
| 3986 | header fields. |
| 3987 | |
| 3988 | An endpoint can use the SETTINGS_MAX_HEADER_LIST_SIZE to advise peers |
| 3989 | of limits that might apply on the size of header blocks. This |
| 3990 | setting is only advisory, so endpoints MAY choose to send header |
| 3991 | blocks that exceed this limit and risk having the request or response |
| 3992 | being treated as malformed. This setting is specific to a |
| 3993 | connection, so any request or response could encounter a hop with a |
| 3994 | lower, unknown limit. An intermediary can attempt to avoid this |
| 3995 | problem by passing on values presented by different peers, but they |
| 3996 | are not obligated to do so. |
| 3997 | |
| 3998 | A server that receives a larger header block than it is willing to |
| 3999 | handle can send an HTTP 431 (Request Header Fields Too Large) status |
| 4000 | code [RFC6585]. A client can discard responses that it cannot |
| 4001 | process. The header block MUST be processed to ensure a consistent |
| 4002 | connection state, unless the connection is closed. |
| 4003 | |
| 4004 | 10.5.2. CONNECT Issues |
| 4005 | |
| 4006 | The CONNECT method can be used to create disproportionate load on an |
| 4007 | proxy, since stream creation is relatively inexpensive when compared |
| 4008 | to the creation and maintenance of a TCP connection. A proxy might |
| 4009 | also maintain some resources for a TCP connection beyond the closing |
| 4010 | of the stream that carries the CONNECT request, since the outgoing |
| 4011 | TCP connection remains in the TIME_WAIT state. Therefore, a proxy |
| 4012 | cannot rely on SETTINGS_MAX_CONCURRENT_STREAMS alone to limit the |
| 4013 | resources consumed by CONNECT requests. |
| 4014 | |
| 4015 | 10.6. Use of Compression |
| 4016 | |
| 4017 | Compression can allow an attacker to recover secret data when it is |
| 4018 | compressed in the same context as data under attacker control. |
| 4019 | HTTP/2 enables compression of header fields (Section 4.3); the |
| 4020 | following concerns also apply to the use of HTTP compressed content- |
| 4021 | codings ([RFC7231], Section 3.1.2.1). |
| 4022 | |
| 4023 | There are demonstrable attacks on compression that exploit the |
| 4024 | characteristics of the web (e.g., [BREACH]). The attacker induces |
| 4025 | multiple requests containing varying plaintext, observing the length |
| 4026 | of the resulting ciphertext in each, which reveals a shorter length |
| 4027 | when a guess about the secret is correct. |
| 4028 | |
| 4029 | |
| 4030 | |
| 4031 | |
| 4032 | |
| 4033 | |
| 4034 | Belshe, et al. Standards Track [Page 72] |
| 4035 | \f |
| 4036 | RFC 7540 HTTP/2 May 2015 |
| 4037 | |
| 4038 | |
| 4039 | Implementations communicating on a secure channel MUST NOT compress |
| 4040 | content that includes both confidential and attacker-controlled data |
| 4041 | unless separate compression dictionaries are used for each source of |
| 4042 | data. Compression MUST NOT be used if the source of data cannot be |
| 4043 | reliably determined. Generic stream compression, such as that |
| 4044 | provided by TLS, MUST NOT be used with HTTP/2 (see Section 9.2). |
| 4045 | |
| 4046 | Further considerations regarding the compression of header fields are |
| 4047 | described in [COMPRESSION]. |
| 4048 | |
| 4049 | 10.7. Use of Padding |
| 4050 | |
| 4051 | Padding within HTTP/2 is not intended as a replacement for general |
| 4052 | purpose padding, such as might be provided by TLS [TLS12]. Redundant |
| 4053 | padding could even be counterproductive. Correct application can |
| 4054 | depend on having specific knowledge of the data that is being padded. |
| 4055 | |
| 4056 | To mitigate attacks that rely on compression, disabling or limiting |
| 4057 | compression might be preferable to padding as a countermeasure. |
| 4058 | |
| 4059 | Padding can be used to obscure the exact size of frame content and is |
| 4060 | provided to mitigate specific attacks within HTTP, for example, |
| 4061 | attacks where compressed content includes both attacker-controlled |
| 4062 | plaintext and secret data (e.g., [BREACH]). |
| 4063 | |
| 4064 | Use of padding can result in less protection than might seem |
| 4065 | immediately obvious. At best, padding only makes it more difficult |
| 4066 | for an attacker to infer length information by increasing the number |
| 4067 | of frames an attacker has to observe. Incorrectly implemented |
| 4068 | padding schemes can be easily defeated. In particular, randomized |
| 4069 | padding with a predictable distribution provides very little |
| 4070 | protection; similarly, padding payloads to a fixed size exposes |
| 4071 | information as payload sizes cross the fixed-sized boundary, which |
| 4072 | could be possible if an attacker can control plaintext. |
| 4073 | |
| 4074 | Intermediaries SHOULD retain padding for DATA frames but MAY drop |
| 4075 | padding for HEADERS and PUSH_PROMISE frames. A valid reason for an |
| 4076 | intermediary to change the amount of padding of frames is to improve |
| 4077 | the protections that padding provides. |
| 4078 | |
| 4079 | 10.8. Privacy Considerations |
| 4080 | |
| 4081 | Several characteristics of HTTP/2 provide an observer an opportunity |
| 4082 | to correlate actions of a single client or server over time. These |
| 4083 | include the value of settings, the manner in which flow-control |
| 4084 | windows are managed, the way priorities are allocated to streams, the |
| 4085 | timing of reactions to stimulus, and the handling of any features |
| 4086 | that are controlled by settings. |
| 4087 | |
| 4088 | |
| 4089 | |
| 4090 | Belshe, et al. Standards Track [Page 73] |
| 4091 | \f |
| 4092 | RFC 7540 HTTP/2 May 2015 |
| 4093 | |
| 4094 | |
| 4095 | As far as these create observable differences in behavior, they could |
| 4096 | be used as a basis for fingerprinting a specific client, as defined |
| 4097 | in Section 1.8 of [HTML5]. |
| 4098 | |
| 4099 | HTTP/2's preference for using a single TCP connection allows |
| 4100 | correlation of a user's activity on a site. Reusing connections for |
| 4101 | different origins allows tracking across those origins. |
| 4102 | |
| 4103 | Because the PING and SETTINGS frames solicit immediate responses, |
| 4104 | they can be used by an endpoint to measure latency to their peer. |
| 4105 | This might have privacy implications in certain scenarios. |
| 4106 | |
| 4107 | 11. IANA Considerations |
| 4108 | |
| 4109 | A string for identifying HTTP/2 is entered into the "Application- |
| 4110 | Layer Protocol Negotiation (ALPN) Protocol IDs" registry established |
| 4111 | in [TLS-ALPN]. |
| 4112 | |
| 4113 | This document establishes a registry for frame types, settings, and |
| 4114 | error codes. These new registries appear in the new "Hypertext |
| 4115 | Transfer Protocol version 2 (HTTP/2) Parameters" section. |
| 4116 | |
| 4117 | This document registers the HTTP2-Settings header field for use in |
| 4118 | HTTP; it also registers the 421 (Misdirected Request) status code. |
| 4119 | |
| 4120 | This document registers the "PRI" method for use in HTTP to avoid |
| 4121 | collisions with the connection preface (Section 3.5). |
| 4122 | |
| 4123 | 11.1. Registration of HTTP/2 Identification Strings |
| 4124 | |
| 4125 | This document creates two registrations for the identification of |
| 4126 | HTTP/2 (see Section 3.3) in the "Application-Layer Protocol |
| 4127 | Negotiation (ALPN) Protocol IDs" registry established in [TLS-ALPN]. |
| 4128 | |
| 4129 | The "h2" string identifies HTTP/2 when used over TLS: |
| 4130 | |
| 4131 | Protocol: HTTP/2 over TLS |
| 4132 | |
| 4133 | Identification Sequence: 0x68 0x32 ("h2") |
| 4134 | |
| 4135 | Specification: This document |
| 4136 | |
| 4137 | The "h2c" string identifies HTTP/2 when used over cleartext TCP: |
| 4138 | |
| 4139 | Protocol: HTTP/2 over TCP |
| 4140 | |
| 4141 | |
| 4142 | |
| 4143 | |
| 4144 | |
| 4145 | |
| 4146 | Belshe, et al. Standards Track [Page 74] |
| 4147 | \f |
| 4148 | RFC 7540 HTTP/2 May 2015 |
| 4149 | |
| 4150 | |
| 4151 | Identification Sequence: 0x68 0x32 0x63 ("h2c") |
| 4152 | |
| 4153 | Specification: This document |
| 4154 | |
| 4155 | 11.2. Frame Type Registry |
| 4156 | |
| 4157 | This document establishes a registry for HTTP/2 frame type codes. |
| 4158 | The "HTTP/2 Frame Type" registry manages an 8-bit space. The "HTTP/2 |
| 4159 | Frame Type" registry operates under either of the "IETF Review" or |
| 4160 | "IESG Approval" policies [RFC5226] for values between 0x00 and 0xef, |
| 4161 | with values between 0xf0 and 0xff being reserved for Experimental |
| 4162 | Use. |
| 4163 | |
| 4164 | New entries in this registry require the following information: |
| 4165 | |
| 4166 | Frame Type: A name or label for the frame type. |
| 4167 | |
| 4168 | Code: The 8-bit code assigned to the frame type. |
| 4169 | |
| 4170 | Specification: A reference to a specification that includes a |
| 4171 | description of the frame layout, its semantics, and flags that the |
| 4172 | frame type uses, including any parts of the frame that are |
| 4173 | conditionally present based on the value of flags. |
| 4174 | |
| 4175 | The entries in the following table are registered by this document. |
| 4176 | |
| 4177 | +---------------+------+--------------+ |
| 4178 | | Frame Type | Code | Section | |
| 4179 | +---------------+------+--------------+ |
| 4180 | | DATA | 0x0 | Section 6.1 | |
| 4181 | | HEADERS | 0x1 | Section 6.2 | |
| 4182 | | PRIORITY | 0x2 | Section 6.3 | |
| 4183 | | RST_STREAM | 0x3 | Section 6.4 | |
| 4184 | | SETTINGS | 0x4 | Section 6.5 | |
| 4185 | | PUSH_PROMISE | 0x5 | Section 6.6 | |
| 4186 | | PING | 0x6 | Section 6.7 | |
| 4187 | | GOAWAY | 0x7 | Section 6.8 | |
| 4188 | | WINDOW_UPDATE | 0x8 | Section 6.9 | |
| 4189 | | CONTINUATION | 0x9 | Section 6.10 | |
| 4190 | +---------------+------+--------------+ |
| 4191 | |
| 4192 | 11.3. Settings Registry |
| 4193 | |
| 4194 | This document establishes a registry for HTTP/2 settings. The |
| 4195 | "HTTP/2 Settings" registry manages a 16-bit space. The "HTTP/2 |
| 4196 | Settings" registry operates under the "Expert Review" policy |
| 4197 | [RFC5226] for values in the range from 0x0000 to 0xefff, with values |
| 4198 | between and 0xf000 and 0xffff being reserved for Experimental Use. |
| 4199 | |
| 4200 | |
| 4201 | |
| 4202 | Belshe, et al. Standards Track [Page 75] |
| 4203 | \f |
| 4204 | RFC 7540 HTTP/2 May 2015 |
| 4205 | |
| 4206 | |
| 4207 | New registrations are advised to provide the following information: |
| 4208 | |
| 4209 | Name: A symbolic name for the setting. Specifying a setting name is |
| 4210 | optional. |
| 4211 | |
| 4212 | Code: The 16-bit code assigned to the setting. |
| 4213 | |
| 4214 | Initial Value: An initial value for the setting. |
| 4215 | |
| 4216 | Specification: An optional reference to a specification that |
| 4217 | describes the use of the setting. |
| 4218 | |
| 4219 | The entries in the following table are registered by this document. |
| 4220 | |
| 4221 | +------------------------+------+---------------+---------------+ |
| 4222 | | Name | Code | Initial Value | Specification | |
| 4223 | +------------------------+------+---------------+---------------+ |
| 4224 | | HEADER_TABLE_SIZE | 0x1 | 4096 | Section 6.5.2 | |
| 4225 | | ENABLE_PUSH | 0x2 | 1 | Section 6.5.2 | |
| 4226 | | MAX_CONCURRENT_STREAMS | 0x3 | (infinite) | Section 6.5.2 | |
| 4227 | | INITIAL_WINDOW_SIZE | 0x4 | 65535 | Section 6.5.2 | |
| 4228 | | MAX_FRAME_SIZE | 0x5 | 16384 | Section 6.5.2 | |
| 4229 | | MAX_HEADER_LIST_SIZE | 0x6 | (infinite) | Section 6.5.2 | |
| 4230 | +------------------------+------+---------------+---------------+ |
| 4231 | |
| 4232 | 11.4. Error Code Registry |
| 4233 | |
| 4234 | This document establishes a registry for HTTP/2 error codes. The |
| 4235 | "HTTP/2 Error Code" registry manages a 32-bit space. The "HTTP/2 |
| 4236 | Error Code" registry operates under the "Expert Review" policy |
| 4237 | [RFC5226]. |
| 4238 | |
| 4239 | Registrations for error codes are required to include a description |
| 4240 | of the error code. An expert reviewer is advised to examine new |
| 4241 | registrations for possible duplication with existing error codes. |
| 4242 | Use of existing registrations is to be encouraged, but not mandated. |
| 4243 | |
| 4244 | New registrations are advised to provide the following information: |
| 4245 | |
| 4246 | Name: A name for the error code. Specifying an error code name is |
| 4247 | optional. |
| 4248 | |
| 4249 | Code: The 32-bit error code value. |
| 4250 | |
| 4251 | Description: A brief description of the error code semantics, longer |
| 4252 | if no detailed specification is provided. |
| 4253 | |
| 4254 | |
| 4255 | |
| 4256 | |
| 4257 | |
| 4258 | Belshe, et al. Standards Track [Page 76] |
| 4259 | \f |
| 4260 | RFC 7540 HTTP/2 May 2015 |
| 4261 | |
| 4262 | |
| 4263 | Specification: An optional reference for a specification that |
| 4264 | defines the error code. |
| 4265 | |
| 4266 | The entries in the following table are registered by this document. |
| 4267 | |
| 4268 | +---------------------+------+----------------------+---------------+ |
| 4269 | | Name | Code | Description | Specification | |
| 4270 | +---------------------+------+----------------------+---------------+ |
| 4271 | | NO_ERROR | 0x0 | Graceful shutdown | Section 7 | |
| 4272 | | PROTOCOL_ERROR | 0x1 | Protocol error | Section 7 | |
| 4273 | | | | detected | | |
| 4274 | | INTERNAL_ERROR | 0x2 | Implementation fault | Section 7 | |
| 4275 | | FLOW_CONTROL_ERROR | 0x3 | Flow-control limits | Section 7 | |
| 4276 | | | | exceeded | | |
| 4277 | | SETTINGS_TIMEOUT | 0x4 | Settings not | Section 7 | |
| 4278 | | | | acknowledged | | |
| 4279 | | STREAM_CLOSED | 0x5 | Frame received for | Section 7 | |
| 4280 | | | | closed stream | | |
| 4281 | | FRAME_SIZE_ERROR | 0x6 | Frame size incorrect | Section 7 | |
| 4282 | | REFUSED_STREAM | 0x7 | Stream not processed | Section 7 | |
| 4283 | | CANCEL | 0x8 | Stream cancelled | Section 7 | |
| 4284 | | COMPRESSION_ERROR | 0x9 | Compression state | Section 7 | |
| 4285 | | | | not updated | | |
| 4286 | | CONNECT_ERROR | 0xa | TCP connection error | Section 7 | |
| 4287 | | | | for CONNECT method | | |
| 4288 | | ENHANCE_YOUR_CALM | 0xb | Processing capacity | Section 7 | |
| 4289 | | | | exceeded | | |
| 4290 | | INADEQUATE_SECURITY | 0xc | Negotiated TLS | Section 7 | |
| 4291 | | | | parameters not | | |
| 4292 | | | | acceptable | | |
| 4293 | | HTTP_1_1_REQUIRED | 0xd | Use HTTP/1.1 for the | Section 7 | |
| 4294 | | | | request | | |
| 4295 | +---------------------+------+----------------------+---------------+ |
| 4296 | |
| 4297 | 11.5. HTTP2-Settings Header Field Registration |
| 4298 | |
| 4299 | This section registers the HTTP2-Settings header field in the |
| 4300 | "Permanent Message Header Field Names" registry [BCP90]. |
| 4301 | |
| 4302 | Header field name: HTTP2-Settings |
| 4303 | |
| 4304 | Applicable protocol: http |
| 4305 | |
| 4306 | Status: standard |
| 4307 | |
| 4308 | Author/Change controller: IETF |
| 4309 | |
| 4310 | |
| 4311 | |
| 4312 | |
| 4313 | |
| 4314 | Belshe, et al. Standards Track [Page 77] |
| 4315 | \f |
| 4316 | RFC 7540 HTTP/2 May 2015 |
| 4317 | |
| 4318 | |
| 4319 | Specification document(s): Section 3.2.1 of this document |
| 4320 | |
| 4321 | Related information: This header field is only used by an HTTP/2 |
| 4322 | client for Upgrade-based negotiation. |
| 4323 | |
| 4324 | 11.6. PRI Method Registration |
| 4325 | |
| 4326 | This section registers the "PRI" method in the "HTTP Method Registry" |
| 4327 | ([RFC7231], Section 8.1). |
| 4328 | |
| 4329 | Method Name: PRI |
| 4330 | |
| 4331 | Safe: Yes |
| 4332 | |
| 4333 | Idempotent: Yes |
| 4334 | |
| 4335 | Specification document(s): Section 3.5 of this document |
| 4336 | |
| 4337 | Related information: This method is never used by an actual client. |
| 4338 | This method will appear to be used when an HTTP/1.1 server or |
| 4339 | intermediary attempts to parse an HTTP/2 connection preface. |
| 4340 | |
| 4341 | 11.7. The 421 (Misdirected Request) HTTP Status Code |
| 4342 | |
| 4343 | This document registers the 421 (Misdirected Request) HTTP status |
| 4344 | code in the "HTTP Status Codes" registry ([RFC7231], Section 8.2). |
| 4345 | |
| 4346 | Status Code: 421 |
| 4347 | |
| 4348 | Short Description: Misdirected Request |
| 4349 | |
| 4350 | Specification: Section 9.1.2 of this document |
| 4351 | |
| 4352 | 11.8. The h2c Upgrade Token |
| 4353 | |
| 4354 | This document registers the "h2c" upgrade token in the "HTTP Upgrade |
| 4355 | Tokens" registry ([RFC7230], Section 8.6). |
| 4356 | |
| 4357 | Value: h2c |
| 4358 | |
| 4359 | Description: Hypertext Transfer Protocol version 2 (HTTP/2) |
| 4360 | |
| 4361 | Expected Version Tokens: None |
| 4362 | |
| 4363 | Reference: Section 3.2 of this document |
| 4364 | |
| 4365 | |
| 4366 | |
| 4367 | |
| 4368 | |
| 4369 | |
| 4370 | Belshe, et al. Standards Track [Page 78] |
| 4371 | \f |
| 4372 | RFC 7540 HTTP/2 May 2015 |
| 4373 | |
| 4374 | |
| 4375 | 12. References |
| 4376 | |
| 4377 | 12.1. Normative References |
| 4378 | |
| 4379 | [COMPRESSION] Peon, R. and H. Ruellan, "HPACK: Header Compression for |
| 4380 | HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, |
| 4381 | <http://www.rfc-editor.org/info/rfc7541>. |
| 4382 | |
| 4383 | [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, |
| 4384 | DOI 10.17487/RFC6265, April 2011, |
| 4385 | <http://www.rfc-editor.org/info/rfc6265>. |
| 4386 | |
| 4387 | [FIPS186] NIST, "Digital Signature Standard (DSS)", FIPS PUB |
| 4388 | 186-4, July 2013, |
| 4389 | <http://dx.doi.org/10.6028/NIST.FIPS.186-4>. |
| 4390 | |
| 4391 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate |
| 4392 | Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ |
| 4393 | RFC2119, March 1997, |
| 4394 | <http://www.rfc-editor.org/info/rfc2119>. |
| 4395 | |
| 4396 | [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/ |
| 4397 | RFC2818, May 2000, |
| 4398 | <http://www.rfc-editor.org/info/rfc2818>. |
| 4399 | |
| 4400 | [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, |
| 4401 | "Uniform Resource Identifier (URI): Generic Syntax", |
| 4402 | STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, |
| 4403 | <http://www.rfc-editor.org/info/rfc3986>. |
| 4404 | |
| 4405 | [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data |
| 4406 | Encodings", RFC 4648, DOI 10.17487/RFC4648, October |
| 4407 | 2006, <http://www.rfc-editor.org/info/rfc4648>. |
| 4408 | |
| 4409 | [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing |
| 4410 | an IANA Considerations Section in RFCs", BCP 26, |
| 4411 | RFC 5226, DOI 10.17487/RFC5226, May 2008, |
| 4412 | <http://www.rfc-editor.org/info/rfc5226>. |
| 4413 | |
| 4414 | [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for |
| 4415 | Syntax Specifications: ABNF", STD 68, RFC 5234, |
| 4416 | DOI 10.17487/ RFC5234, January 2008, |
| 4417 | <http://www.rfc-editor.org/info/rfc5234>. |
| 4418 | |
| 4419 | [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext |
| 4420 | Transfer Protocol (HTTP/1.1): Message Syntax and |
| 4421 | Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014, |
| 4422 | <http://www.rfc-editor.org/info/rfc7230>. |
| 4423 | |
| 4424 | |
| 4425 | |
| 4426 | Belshe, et al. Standards Track [Page 79] |
| 4427 | \f |
| 4428 | RFC 7540 HTTP/2 May 2015 |
| 4429 | |
| 4430 | |
| 4431 | [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext |
| 4432 | Transfer Protocol (HTTP/1.1): Semantics and Content", |
| 4433 | RFC 7231, DOI 10.17487/RFC7231, June 2014, |
| 4434 | <http://www.rfc-editor.org/info/rfc7231>. |
| 4435 | |
| 4436 | [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext |
| 4437 | Transfer Protocol (HTTP/1.1): Conditional Requests", |
| 4438 | RFC 7232, DOI 10.17487/RFC7232, June 2014, |
| 4439 | <http://www.rfc-editor.org/info/rfc7232>. |
| 4440 | |
| 4441 | [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., |
| 4442 | "Hypertext Transfer Protocol (HTTP/1.1): Range |
| 4443 | Requests", RFC 7233, DOI 10.17487/RFC7233, June 2014, |
| 4444 | <http://www.rfc-editor.org/info/rfc7233>. |
| 4445 | |
| 4446 | [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, |
| 4447 | Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", |
| 4448 | RFC 7234, DOI 10.17487/RFC7234, June 2014, |
| 4449 | <http://www.rfc-editor.org/info/rfc7234>. |
| 4450 | |
| 4451 | [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext |
| 4452 | Transfer Protocol (HTTP/1.1): Authentication", |
| 4453 | RFC 7235, DOI 10.17487/RFC7235, June 2014, |
| 4454 | <http://www.rfc-editor.org/info/rfc7235>. |
| 4455 | |
| 4456 | [TCP] Postel, J., "Transmission Control Protocol", STD 7, RFC |
| 4457 | 793, DOI 10.17487/RFC0793, September 1981, |
| 4458 | <http://www.rfc-editor.org/info/rfc793>. |
| 4459 | |
| 4460 | [TLS-ALPN] Friedl, S., Popov, A., Langley, A., and E. Stephan, |
| 4461 | "Transport Layer Security (TLS) Application-Layer |
| 4462 | Protocol Negotiation Extension", RFC 7301, |
| 4463 | DOI 10.17487/RFC7301, July 2014, |
| 4464 | <http://www.rfc-editor.org/info/rfc7301>. |
| 4465 | |
| 4466 | [TLS-ECDHE] Rescorla, E., "TLS Elliptic Curve Cipher Suites with |
| 4467 | SHA-256/384 and AES Galois Counter Mode (GCM)", |
| 4468 | RFC 5289, DOI 10.17487/RFC5289, August 2008, |
| 4469 | <http://www.rfc-editor.org/info/rfc5289>. |
| 4470 | |
| 4471 | [TLS-EXT] Eastlake 3rd, D., "Transport Layer Security (TLS) |
| 4472 | Extensions: Extension Definitions", RFC 6066, |
| 4473 | DOI 10.17487/RFC6066, January 2011, |
| 4474 | <http://www.rfc-editor.org/info/rfc6066>. |
| 4475 | |
| 4476 | |
| 4477 | |
| 4478 | |
| 4479 | |
| 4480 | |
| 4481 | |
| 4482 | Belshe, et al. Standards Track [Page 80] |
| 4483 | \f |
| 4484 | RFC 7540 HTTP/2 May 2015 |
| 4485 | |
| 4486 | |
| 4487 | [TLS12] Dierks, T. and E. Rescorla, "The Transport Layer |
| 4488 | Security (TLS) Protocol Version 1.2", RFC 5246, |
| 4489 | DOI 10.17487/ RFC5246, August 2008, |
| 4490 | <http://www.rfc-editor.org/info/rfc5246>. |
| 4491 | |
| 4492 | 12.2. Informative References |
| 4493 | |
| 4494 | [ALT-SVC] Nottingham, M., McManus, P., and J. Reschke, "HTTP |
| 4495 | Alternative Services", Work in Progress, draft-ietf- |
| 4496 | httpbis-alt-svc-06, February 2015. |
| 4497 | |
| 4498 | [BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration |
| 4499 | Procedures for Message Header Fields", BCP 90, |
| 4500 | RFC 3864, September 2004, |
| 4501 | <http://www.rfc-editor.org/info/bcp90>. |
| 4502 | |
| 4503 | [BREACH] Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving |
| 4504 | the CRIME Attack", July 2013, |
| 4505 | <http://breachattack.com/resources/ |
| 4506 | BREACH%20-%20SSL,%20gone%20in%2030%20seconds.pdf>. |
| 4507 | |
| 4508 | [HTML5] Hickson, I., Berjon, R., Faulkner, S., Leithead, T., |
| 4509 | Doyle Navara, E., O'Connor, E., and S. Pfeiffer, |
| 4510 | "HTML5", W3C Recommendation REC-html5-20141028, October |
| 4511 | 2014, <http://www.w3.org/TR/2014/REC-html5-20141028/>. |
| 4512 | |
| 4513 | [RFC3749] Hollenbeck, S., "Transport Layer Security Protocol |
| 4514 | Compression Methods", RFC 3749, DOI 10.17487/RFC3749, |
| 4515 | May 2004, <http://www.rfc-editor.org/info/rfc3749>. |
| 4516 | |
| 4517 | [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and |
| 4518 | B. Moeller, "Elliptic Curve Cryptography (ECC) Cipher |
| 4519 | Suites for Transport Layer Security (TLS)", RFC 4492, |
| 4520 | DOI 10.17487/RFC4492, May 2006, |
| 4521 | <http://www.rfc-editor.org/info/rfc4492>. |
| 4522 | |
| 4523 | [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status |
| 4524 | Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, |
| 4525 | <http://www.rfc-editor.org/info/rfc6585>. |
| 4526 | |
| 4527 | [RFC7323] Borman, D., Braden, B., Jacobson, V., and R. |
| 4528 | Scheffenegger, Ed., "TCP Extensions for High |
| 4529 | Performance", RFC 7323, DOI 10.17487/RFC7323, September |
| 4530 | 2014, <http://www.rfc-editor.org/info/rfc7323>. |
| 4531 | |
| 4532 | [TALKING] Huang, L., Chen, E., Barth, A., Rescorla, E., and C. |
| 4533 | Jackson, "Talking to Yourself for Fun and Profit", |
| 4534 | 2011, <http://w2spconf.com/2011/papers/websocket.pdf>. |
| 4535 | |
| 4536 | |
| 4537 | |
| 4538 | Belshe, et al. Standards Track [Page 81] |
| 4539 | \f |
| 4540 | RFC 7540 HTTP/2 May 2015 |
| 4541 | |
| 4542 | |
| 4543 | [TLSBCP] Sheffer, Y., Holz, R., and P. Saint-Andre, |
| 4544 | "Recommendations for Secure Use of Transport Layer |
| 4545 | Security (TLS) and Datagram Transport Layer Security |
| 4546 | (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May |
| 4547 | 2015, <http://www.rfc-editor.org/info/rfc7525>. |
| 4548 | |
| 4549 | |
| 4550 | |
| 4551 | |
| 4552 | |
| 4553 | |
| 4554 | |
| 4555 | |
| 4556 | |
| 4557 | |
| 4558 | |
| 4559 | |
| 4560 | |
| 4561 | |
| 4562 | |
| 4563 | |
| 4564 | |
| 4565 | |
| 4566 | |
| 4567 | |
| 4568 | |
| 4569 | |
| 4570 | |
| 4571 | |
| 4572 | |
| 4573 | |
| 4574 | |
| 4575 | |
| 4576 | |
| 4577 | |
| 4578 | |
| 4579 | |
| 4580 | |
| 4581 | |
| 4582 | |
| 4583 | |
| 4584 | |
| 4585 | |
| 4586 | |
| 4587 | |
| 4588 | |
| 4589 | |
| 4590 | |
| 4591 | |
| 4592 | |
| 4593 | |
| 4594 | Belshe, et al. Standards Track [Page 82] |
| 4595 | \f |
| 4596 | RFC 7540 HTTP/2 May 2015 |
| 4597 | |
| 4598 | |
| 4599 | Appendix A. TLS 1.2 Cipher Suite Black List |
| 4600 | |
| 4601 | An HTTP/2 implementation MAY treat the negotiation of any of the |
| 4602 | following cipher suites with TLS 1.2 as a connection error |
| 4603 | (Section 5.4.1) of type INADEQUATE_SECURITY: |
| 4604 | |
| 4605 | o TLS_NULL_WITH_NULL_NULL |
| 4606 | |
| 4607 | o TLS_RSA_WITH_NULL_MD5 |
| 4608 | |
| 4609 | o TLS_RSA_WITH_NULL_SHA |
| 4610 | |
| 4611 | o TLS_RSA_EXPORT_WITH_RC4_40_MD5 |
| 4612 | |
| 4613 | o TLS_RSA_WITH_RC4_128_MD5 |
| 4614 | |
| 4615 | o TLS_RSA_WITH_RC4_128_SHA |
| 4616 | |
| 4617 | o TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 |
| 4618 | |
| 4619 | o TLS_RSA_WITH_IDEA_CBC_SHA |
| 4620 | |
| 4621 | o TLS_RSA_EXPORT_WITH_DES40_CBC_SHA |
| 4622 | |
| 4623 | o TLS_RSA_WITH_DES_CBC_SHA |
| 4624 | |
| 4625 | o TLS_RSA_WITH_3DES_EDE_CBC_SHA |
| 4626 | |
| 4627 | o TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA |
| 4628 | |
| 4629 | o TLS_DH_DSS_WITH_DES_CBC_SHA |
| 4630 | |
| 4631 | o TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA |
| 4632 | |
| 4633 | o TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA |
| 4634 | |
| 4635 | o TLS_DH_RSA_WITH_DES_CBC_SHA |
| 4636 | |
| 4637 | o TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA |
| 4638 | |
| 4639 | o TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA |
| 4640 | |
| 4641 | o TLS_DHE_DSS_WITH_DES_CBC_SHA |
| 4642 | |
| 4643 | o TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA |
| 4644 | |
| 4645 | o TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA |
| 4646 | |
| 4647 | |
| 4648 | |
| 4649 | |
| 4650 | Belshe, et al. Standards Track [Page 83] |
| 4651 | \f |
| 4652 | RFC 7540 HTTP/2 May 2015 |
| 4653 | |
| 4654 | |
| 4655 | o TLS_DHE_RSA_WITH_DES_CBC_SHA |
| 4656 | |
| 4657 | o TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA |
| 4658 | |
| 4659 | o TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 |
| 4660 | |
| 4661 | o TLS_DH_anon_WITH_RC4_128_MD5 |
| 4662 | |
| 4663 | o TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA |
| 4664 | |
| 4665 | o TLS_DH_anon_WITH_DES_CBC_SHA |
| 4666 | |
| 4667 | o TLS_DH_anon_WITH_3DES_EDE_CBC_SHA |
| 4668 | |
| 4669 | o TLS_KRB5_WITH_DES_CBC_SHA |
| 4670 | |
| 4671 | o TLS_KRB5_WITH_3DES_EDE_CBC_SHA |
| 4672 | |
| 4673 | o TLS_KRB5_WITH_RC4_128_SHA |
| 4674 | |
| 4675 | o TLS_KRB5_WITH_IDEA_CBC_SHA |
| 4676 | |
| 4677 | o TLS_KRB5_WITH_DES_CBC_MD5 |
| 4678 | |
| 4679 | o TLS_KRB5_WITH_3DES_EDE_CBC_MD5 |
| 4680 | |
| 4681 | o TLS_KRB5_WITH_RC4_128_MD5 |
| 4682 | |
| 4683 | o TLS_KRB5_WITH_IDEA_CBC_MD5 |
| 4684 | |
| 4685 | o TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA |
| 4686 | |
| 4687 | o TLS_KRB5_EXPORT_WITH_RC2_CBC_40_SHA |
| 4688 | |
| 4689 | o TLS_KRB5_EXPORT_WITH_RC4_40_SHA |
| 4690 | |
| 4691 | o TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 |
| 4692 | |
| 4693 | o TLS_KRB5_EXPORT_WITH_RC2_CBC_40_MD5 |
| 4694 | |
| 4695 | o TLS_KRB5_EXPORT_WITH_RC4_40_MD5 |
| 4696 | |
| 4697 | o TLS_PSK_WITH_NULL_SHA |
| 4698 | |
| 4699 | o TLS_DHE_PSK_WITH_NULL_SHA |
| 4700 | |
| 4701 | o TLS_RSA_PSK_WITH_NULL_SHA |
| 4702 | |
| 4703 | |
| 4704 | |
| 4705 | |
| 4706 | Belshe, et al. Standards Track [Page 84] |
| 4707 | \f |
| 4708 | RFC 7540 HTTP/2 May 2015 |
| 4709 | |
| 4710 | |
| 4711 | o TLS_RSA_WITH_AES_128_CBC_SHA |
| 4712 | |
| 4713 | o TLS_DH_DSS_WITH_AES_128_CBC_SHA |
| 4714 | |
| 4715 | o TLS_DH_RSA_WITH_AES_128_CBC_SHA |
| 4716 | |
| 4717 | o TLS_DHE_DSS_WITH_AES_128_CBC_SHA |
| 4718 | |
| 4719 | o TLS_DHE_RSA_WITH_AES_128_CBC_SHA |
| 4720 | |
| 4721 | o TLS_DH_anon_WITH_AES_128_CBC_SHA |
| 4722 | |
| 4723 | o TLS_RSA_WITH_AES_256_CBC_SHA |
| 4724 | |
| 4725 | o TLS_DH_DSS_WITH_AES_256_CBC_SHA |
| 4726 | |
| 4727 | o TLS_DH_RSA_WITH_AES_256_CBC_SHA |
| 4728 | |
| 4729 | o TLS_DHE_DSS_WITH_AES_256_CBC_SHA |
| 4730 | |
| 4731 | o TLS_DHE_RSA_WITH_AES_256_CBC_SHA |
| 4732 | |
| 4733 | o TLS_DH_anon_WITH_AES_256_CBC_SHA |
| 4734 | |
| 4735 | o TLS_RSA_WITH_NULL_SHA256 |
| 4736 | |
| 4737 | o TLS_RSA_WITH_AES_128_CBC_SHA256 |
| 4738 | |
| 4739 | o TLS_RSA_WITH_AES_256_CBC_SHA256 |
| 4740 | |
| 4741 | o TLS_DH_DSS_WITH_AES_128_CBC_SHA256 |
| 4742 | |
| 4743 | o TLS_DH_RSA_WITH_AES_128_CBC_SHA256 |
| 4744 | |
| 4745 | o TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 |
| 4746 | |
| 4747 | o TLS_RSA_WITH_CAMELLIA_128_CBC_SHA |
| 4748 | |
| 4749 | o TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA |
| 4750 | |
| 4751 | o TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA |
| 4752 | |
| 4753 | o TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA |
| 4754 | |
| 4755 | o TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA |
| 4756 | |
| 4757 | o TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA |
| 4758 | |
| 4759 | |
| 4760 | |
| 4761 | |
| 4762 | Belshe, et al. Standards Track [Page 85] |
| 4763 | \f |
| 4764 | RFC 7540 HTTP/2 May 2015 |
| 4765 | |
| 4766 | |
| 4767 | o TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 |
| 4768 | |
| 4769 | o TLS_DH_DSS_WITH_AES_256_CBC_SHA256 |
| 4770 | |
| 4771 | o TLS_DH_RSA_WITH_AES_256_CBC_SHA256 |
| 4772 | |
| 4773 | o TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 |
| 4774 | |
| 4775 | o TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 |
| 4776 | |
| 4777 | o TLS_DH_anon_WITH_AES_128_CBC_SHA256 |
| 4778 | |
| 4779 | o TLS_DH_anon_WITH_AES_256_CBC_SHA256 |
| 4780 | |
| 4781 | o TLS_RSA_WITH_CAMELLIA_256_CBC_SHA |
| 4782 | |
| 4783 | o TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA |
| 4784 | |
| 4785 | o TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA |
| 4786 | |
| 4787 | o TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA |
| 4788 | |
| 4789 | o TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA |
| 4790 | |
| 4791 | o TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA |
| 4792 | |
| 4793 | o TLS_PSK_WITH_RC4_128_SHA |
| 4794 | |
| 4795 | o TLS_PSK_WITH_3DES_EDE_CBC_SHA |
| 4796 | |
| 4797 | o TLS_PSK_WITH_AES_128_CBC_SHA |
| 4798 | |
| 4799 | o TLS_PSK_WITH_AES_256_CBC_SHA |
| 4800 | |
| 4801 | o TLS_DHE_PSK_WITH_RC4_128_SHA |
| 4802 | |
| 4803 | o TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA |
| 4804 | |
| 4805 | o TLS_DHE_PSK_WITH_AES_128_CBC_SHA |
| 4806 | |
| 4807 | o TLS_DHE_PSK_WITH_AES_256_CBC_SHA |
| 4808 | |
| 4809 | o TLS_RSA_PSK_WITH_RC4_128_SHA |
| 4810 | |
| 4811 | o TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA |
| 4812 | |
| 4813 | o TLS_RSA_PSK_WITH_AES_128_CBC_SHA |
| 4814 | |
| 4815 | |
| 4816 | |
| 4817 | |
| 4818 | Belshe, et al. Standards Track [Page 86] |
| 4819 | \f |
| 4820 | RFC 7540 HTTP/2 May 2015 |
| 4821 | |
| 4822 | |
| 4823 | o TLS_RSA_PSK_WITH_AES_256_CBC_SHA |
| 4824 | |
| 4825 | o TLS_RSA_WITH_SEED_CBC_SHA |
| 4826 | |
| 4827 | o TLS_DH_DSS_WITH_SEED_CBC_SHA |
| 4828 | |
| 4829 | o TLS_DH_RSA_WITH_SEED_CBC_SHA |
| 4830 | |
| 4831 | o TLS_DHE_DSS_WITH_SEED_CBC_SHA |
| 4832 | |
| 4833 | o TLS_DHE_RSA_WITH_SEED_CBC_SHA |
| 4834 | |
| 4835 | o TLS_DH_anon_WITH_SEED_CBC_SHA |
| 4836 | |
| 4837 | o TLS_RSA_WITH_AES_128_GCM_SHA256 |
| 4838 | |
| 4839 | o TLS_RSA_WITH_AES_256_GCM_SHA384 |
| 4840 | |
| 4841 | o TLS_DH_RSA_WITH_AES_128_GCM_SHA256 |
| 4842 | |
| 4843 | o TLS_DH_RSA_WITH_AES_256_GCM_SHA384 |
| 4844 | |
| 4845 | o TLS_DH_DSS_WITH_AES_128_GCM_SHA256 |
| 4846 | |
| 4847 | o TLS_DH_DSS_WITH_AES_256_GCM_SHA384 |
| 4848 | |
| 4849 | o TLS_DH_anon_WITH_AES_128_GCM_SHA256 |
| 4850 | |
| 4851 | o TLS_DH_anon_WITH_AES_256_GCM_SHA384 |
| 4852 | |
| 4853 | o TLS_PSK_WITH_AES_128_GCM_SHA256 |
| 4854 | |
| 4855 | o TLS_PSK_WITH_AES_256_GCM_SHA384 |
| 4856 | |
| 4857 | o TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 |
| 4858 | |
| 4859 | o TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 |
| 4860 | |
| 4861 | o TLS_PSK_WITH_AES_128_CBC_SHA256 |
| 4862 | |
| 4863 | o TLS_PSK_WITH_AES_256_CBC_SHA384 |
| 4864 | |
| 4865 | o TLS_PSK_WITH_NULL_SHA256 |
| 4866 | |
| 4867 | o TLS_PSK_WITH_NULL_SHA384 |
| 4868 | |
| 4869 | o TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 |
| 4870 | |
| 4871 | |
| 4872 | |
| 4873 | |
| 4874 | Belshe, et al. Standards Track [Page 87] |
| 4875 | \f |
| 4876 | RFC 7540 HTTP/2 May 2015 |
| 4877 | |
| 4878 | |
| 4879 | o TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 |
| 4880 | |
| 4881 | o TLS_DHE_PSK_WITH_NULL_SHA256 |
| 4882 | |
| 4883 | o TLS_DHE_PSK_WITH_NULL_SHA384 |
| 4884 | |
| 4885 | o TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 |
| 4886 | |
| 4887 | o TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 |
| 4888 | |
| 4889 | o TLS_RSA_PSK_WITH_NULL_SHA256 |
| 4890 | |
| 4891 | o TLS_RSA_PSK_WITH_NULL_SHA384 |
| 4892 | |
| 4893 | o TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 |
| 4894 | |
| 4895 | o TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA256 |
| 4896 | |
| 4897 | o TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA256 |
| 4898 | |
| 4899 | o TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA256 |
| 4900 | |
| 4901 | o TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 |
| 4902 | |
| 4903 | o TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA256 |
| 4904 | |
| 4905 | o TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 |
| 4906 | |
| 4907 | o TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA256 |
| 4908 | |
| 4909 | o TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA256 |
| 4910 | |
| 4911 | o TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA256 |
| 4912 | |
| 4913 | o TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 |
| 4914 | |
| 4915 | o TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA256 |
| 4916 | |
| 4917 | o TLS_EMPTY_RENEGOTIATION_INFO_SCSV |
| 4918 | |
| 4919 | o TLS_ECDH_ECDSA_WITH_NULL_SHA |
| 4920 | |
| 4921 | o TLS_ECDH_ECDSA_WITH_RC4_128_SHA |
| 4922 | |
| 4923 | o TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA |
| 4924 | |
| 4925 | o TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA |
| 4926 | |
| 4927 | |
| 4928 | |
| 4929 | |
| 4930 | Belshe, et al. Standards Track [Page 88] |
| 4931 | \f |
| 4932 | RFC 7540 HTTP/2 May 2015 |
| 4933 | |
| 4934 | |
| 4935 | o TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA |
| 4936 | |
| 4937 | o TLS_ECDHE_ECDSA_WITH_NULL_SHA |
| 4938 | |
| 4939 | o TLS_ECDHE_ECDSA_WITH_RC4_128_SHA |
| 4940 | |
| 4941 | o TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA |
| 4942 | |
| 4943 | o TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA |
| 4944 | |
| 4945 | o TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA |
| 4946 | |
| 4947 | o TLS_ECDH_RSA_WITH_NULL_SHA |
| 4948 | |
| 4949 | o TLS_ECDH_RSA_WITH_RC4_128_SHA |
| 4950 | |
| 4951 | o TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA |
| 4952 | |
| 4953 | o TLS_ECDH_RSA_WITH_AES_128_CBC_SHA |
| 4954 | |
| 4955 | o TLS_ECDH_RSA_WITH_AES_256_CBC_SHA |
| 4956 | |
| 4957 | o TLS_ECDHE_RSA_WITH_NULL_SHA |
| 4958 | |
| 4959 | o TLS_ECDHE_RSA_WITH_RC4_128_SHA |
| 4960 | |
| 4961 | o TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA |
| 4962 | |
| 4963 | o TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA |
| 4964 | |
| 4965 | o TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA |
| 4966 | |
| 4967 | o TLS_ECDH_anon_WITH_NULL_SHA |
| 4968 | |
| 4969 | o TLS_ECDH_anon_WITH_RC4_128_SHA |
| 4970 | |
| 4971 | o TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA |
| 4972 | |
| 4973 | o TLS_ECDH_anon_WITH_AES_128_CBC_SHA |
| 4974 | |
| 4975 | o TLS_ECDH_anon_WITH_AES_256_CBC_SHA |
| 4976 | |
| 4977 | o TLS_SRP_SHA_WITH_3DES_EDE_CBC_SHA |
| 4978 | |
| 4979 | o TLS_SRP_SHA_RSA_WITH_3DES_EDE_CBC_SHA |
| 4980 | |
| 4981 | o TLS_SRP_SHA_DSS_WITH_3DES_EDE_CBC_SHA |
| 4982 | |
| 4983 | |
| 4984 | |
| 4985 | |
| 4986 | Belshe, et al. Standards Track [Page 89] |
| 4987 | \f |
| 4988 | RFC 7540 HTTP/2 May 2015 |
| 4989 | |
| 4990 | |
| 4991 | o TLS_SRP_SHA_WITH_AES_128_CBC_SHA |
| 4992 | |
| 4993 | o TLS_SRP_SHA_RSA_WITH_AES_128_CBC_SHA |
| 4994 | |
| 4995 | o TLS_SRP_SHA_DSS_WITH_AES_128_CBC_SHA |
| 4996 | |
| 4997 | o TLS_SRP_SHA_WITH_AES_256_CBC_SHA |
| 4998 | |
| 4999 | o TLS_SRP_SHA_RSA_WITH_AES_256_CBC_SHA |
| 5000 | |
| 5001 | o TLS_SRP_SHA_DSS_WITH_AES_256_CBC_SHA |
| 5002 | |
| 5003 | o TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 |
| 5004 | |
| 5005 | o TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 |
| 5006 | |
| 5007 | o TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 |
| 5008 | |
| 5009 | o TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 |
| 5010 | |
| 5011 | o TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 |
| 5012 | |
| 5013 | o TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 |
| 5014 | |
| 5015 | o TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 |
| 5016 | |
| 5017 | o TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 |
| 5018 | |
| 5019 | o TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 |
| 5020 | |
| 5021 | o TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 |
| 5022 | |
| 5023 | o TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 |
| 5024 | |
| 5025 | o TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 |
| 5026 | |
| 5027 | o TLS_ECDHE_PSK_WITH_RC4_128_SHA |
| 5028 | |
| 5029 | o TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA |
| 5030 | |
| 5031 | o TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA |
| 5032 | |
| 5033 | o TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA |
| 5034 | |
| 5035 | o TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 |
| 5036 | |
| 5037 | o TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 |
| 5038 | |
| 5039 | |
| 5040 | |
| 5041 | |
| 5042 | Belshe, et al. Standards Track [Page 90] |
| 5043 | \f |
| 5044 | RFC 7540 HTTP/2 May 2015 |
| 5045 | |
| 5046 | |
| 5047 | o TLS_ECDHE_PSK_WITH_NULL_SHA |
| 5048 | |
| 5049 | o TLS_ECDHE_PSK_WITH_NULL_SHA256 |
| 5050 | |
| 5051 | o TLS_ECDHE_PSK_WITH_NULL_SHA384 |
| 5052 | |
| 5053 | o TLS_RSA_WITH_ARIA_128_CBC_SHA256 |
| 5054 | |
| 5055 | o TLS_RSA_WITH_ARIA_256_CBC_SHA384 |
| 5056 | |
| 5057 | o TLS_DH_DSS_WITH_ARIA_128_CBC_SHA256 |
| 5058 | |
| 5059 | o TLS_DH_DSS_WITH_ARIA_256_CBC_SHA384 |
| 5060 | |
| 5061 | o TLS_DH_RSA_WITH_ARIA_128_CBC_SHA256 |
| 5062 | |
| 5063 | o TLS_DH_RSA_WITH_ARIA_256_CBC_SHA384 |
| 5064 | |
| 5065 | o TLS_DHE_DSS_WITH_ARIA_128_CBC_SHA256 |
| 5066 | |
| 5067 | o TLS_DHE_DSS_WITH_ARIA_256_CBC_SHA384 |
| 5068 | |
| 5069 | o TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256 |
| 5070 | |
| 5071 | o TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384 |
| 5072 | |
| 5073 | o TLS_DH_anon_WITH_ARIA_128_CBC_SHA256 |
| 5074 | |
| 5075 | o TLS_DH_anon_WITH_ARIA_256_CBC_SHA384 |
| 5076 | |
| 5077 | o TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256 |
| 5078 | |
| 5079 | o TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384 |
| 5080 | |
| 5081 | o TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256 |
| 5082 | |
| 5083 | o TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384 |
| 5084 | |
| 5085 | o TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256 |
| 5086 | |
| 5087 | o TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384 |
| 5088 | |
| 5089 | o TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256 |
| 5090 | |
| 5091 | o TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384 |
| 5092 | |
| 5093 | o TLS_RSA_WITH_ARIA_128_GCM_SHA256 |
| 5094 | |
| 5095 | |
| 5096 | |
| 5097 | |
| 5098 | Belshe, et al. Standards Track [Page 91] |
| 5099 | \f |
| 5100 | RFC 7540 HTTP/2 May 2015 |
| 5101 | |
| 5102 | |
| 5103 | o TLS_RSA_WITH_ARIA_256_GCM_SHA384 |
| 5104 | |
| 5105 | o TLS_DH_RSA_WITH_ARIA_128_GCM_SHA256 |
| 5106 | |
| 5107 | o TLS_DH_RSA_WITH_ARIA_256_GCM_SHA384 |
| 5108 | |
| 5109 | o TLS_DH_DSS_WITH_ARIA_128_GCM_SHA256 |
| 5110 | |
| 5111 | o TLS_DH_DSS_WITH_ARIA_256_GCM_SHA384 |
| 5112 | |
| 5113 | o TLS_DH_anon_WITH_ARIA_128_GCM_SHA256 |
| 5114 | |
| 5115 | o TLS_DH_anon_WITH_ARIA_256_GCM_SHA384 |
| 5116 | |
| 5117 | o TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256 |
| 5118 | |
| 5119 | o TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384 |
| 5120 | |
| 5121 | o TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256 |
| 5122 | |
| 5123 | o TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384 |
| 5124 | |
| 5125 | o TLS_PSK_WITH_ARIA_128_CBC_SHA256 |
| 5126 | |
| 5127 | o TLS_PSK_WITH_ARIA_256_CBC_SHA384 |
| 5128 | |
| 5129 | o TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256 |
| 5130 | |
| 5131 | o TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384 |
| 5132 | |
| 5133 | o TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256 |
| 5134 | |
| 5135 | o TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384 |
| 5136 | |
| 5137 | o TLS_PSK_WITH_ARIA_128_GCM_SHA256 |
| 5138 | |
| 5139 | o TLS_PSK_WITH_ARIA_256_GCM_SHA384 |
| 5140 | |
| 5141 | o TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256 |
| 5142 | |
| 5143 | o TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384 |
| 5144 | |
| 5145 | o TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256 |
| 5146 | |
| 5147 | o TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384 |
| 5148 | |
| 5149 | o TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 |
| 5150 | |
| 5151 | |
| 5152 | |
| 5153 | |
| 5154 | Belshe, et al. Standards Track [Page 92] |
| 5155 | \f |
| 5156 | RFC 7540 HTTP/2 May 2015 |
| 5157 | |
| 5158 | |
| 5159 | o TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 |
| 5160 | |
| 5161 | o TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 |
| 5162 | |
| 5163 | o TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 |
| 5164 | |
| 5165 | o TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 |
| 5166 | |
| 5167 | o TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 |
| 5168 | |
| 5169 | o TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 |
| 5170 | |
| 5171 | o TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 |
| 5172 | |
| 5173 | o TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 |
| 5174 | |
| 5175 | o TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 |
| 5176 | |
| 5177 | o TLS_DH_RSA_WITH_CAMELLIA_128_GCM_SHA256 |
| 5178 | |
| 5179 | o TLS_DH_RSA_WITH_CAMELLIA_256_GCM_SHA384 |
| 5180 | |
| 5181 | o TLS_DH_DSS_WITH_CAMELLIA_128_GCM_SHA256 |
| 5182 | |
| 5183 | o TLS_DH_DSS_WITH_CAMELLIA_256_GCM_SHA384 |
| 5184 | |
| 5185 | o TLS_DH_anon_WITH_CAMELLIA_128_GCM_SHA256 |
| 5186 | |
| 5187 | o TLS_DH_anon_WITH_CAMELLIA_256_GCM_SHA384 |
| 5188 | |
| 5189 | o TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 |
| 5190 | |
| 5191 | o TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 |
| 5192 | |
| 5193 | o TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 |
| 5194 | |
| 5195 | o TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384 |
| 5196 | |
| 5197 | o TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 |
| 5198 | |
| 5199 | o TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 |
| 5200 | |
| 5201 | o TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 |
| 5202 | |
| 5203 | o TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 |
| 5204 | |
| 5205 | o TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256 |
| 5206 | |
| 5207 | |
| 5208 | |
| 5209 | |
| 5210 | Belshe, et al. Standards Track [Page 93] |
| 5211 | \f |
| 5212 | RFC 7540 HTTP/2 May 2015 |
| 5213 | |
| 5214 | |
| 5215 | o TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 |
| 5216 | |
| 5217 | o TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 |
| 5218 | |
| 5219 | o TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 |
| 5220 | |
| 5221 | o TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 |
| 5222 | |
| 5223 | o TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 |
| 5224 | |
| 5225 | o TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 |
| 5226 | |
| 5227 | o TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 |
| 5228 | |
| 5229 | o TLS_RSA_WITH_AES_128_CCM |
| 5230 | |
| 5231 | o TLS_RSA_WITH_AES_256_CCM |
| 5232 | |
| 5233 | o TLS_RSA_WITH_AES_128_CCM_8 |
| 5234 | |
| 5235 | o TLS_RSA_WITH_AES_256_CCM_8 |
| 5236 | |
| 5237 | o TLS_PSK_WITH_AES_128_CCM |
| 5238 | |
| 5239 | o TLS_PSK_WITH_AES_256_CCM |
| 5240 | |
| 5241 | o TLS_PSK_WITH_AES_128_CCM_8 |
| 5242 | |
| 5243 | o TLS_PSK_WITH_AES_256_CCM_8 |
| 5244 | |
| 5245 | Note: This list was assembled from the set of registered TLS |
| 5246 | cipher suites at the time of writing. This list includes those |
| 5247 | cipher suites that do not offer an ephemeral key exchange and |
| 5248 | those that are based on the TLS null, stream, or block cipher type |
| 5249 | (as defined in Section 6.2.3 of [TLS12]). Additional cipher |
| 5250 | suites with these properties could be defined; these would not be |
| 5251 | explicitly prohibited. |
| 5252 | |
| 5253 | |
| 5254 | |
| 5255 | |
| 5256 | |
| 5257 | |
| 5258 | |
| 5259 | |
| 5260 | |
| 5261 | |
| 5262 | |
| 5263 | |
| 5264 | |
| 5265 | |
| 5266 | Belshe, et al. Standards Track [Page 94] |
| 5267 | \f |
| 5268 | RFC 7540 HTTP/2 May 2015 |
| 5269 | |
| 5270 | |
| 5271 | Acknowledgements |
| 5272 | |
| 5273 | This document includes substantial input from the following |
| 5274 | individuals: |
| 5275 | |
| 5276 | o Adam Langley, Wan-Teh Chang, Jim Morrison, Mark Nottingham, Alyssa |
| 5277 | Wilk, Costin Manolache, William Chan, Vitaliy Lvin, Joe Chan, Adam |
| 5278 | Barth, Ryan Hamilton, Gavin Peters, Kent Alstad, Kevin Lindsay, |
| 5279 | Paul Amer, Fan Yang, and Jonathan Leighton (SPDY contributors). |
| 5280 | |
| 5281 | o Gabriel Montenegro and Willy Tarreau (Upgrade mechanism). |
| 5282 | |
| 5283 | o William Chan, Salvatore Loreto, Osama Mazahir, Gabriel Montenegro, |
| 5284 | Jitu Padhye, Roberto Peon, and Rob Trace (Flow control). |
| 5285 | |
| 5286 | o Mike Bishop (Extensibility). |
| 5287 | |
| 5288 | o Mark Nottingham, Julian Reschke, James Snell, Jeff Pinner, Mike |
| 5289 | Bishop, and Herve Ruellan (Substantial editorial contributions). |
| 5290 | |
| 5291 | o Kari Hurtta, Tatsuhiro Tsujikawa, Greg Wilkins, Poul-Henning Kamp, |
| 5292 | and Jonathan Thackray. |
| 5293 | |
| 5294 | o Alexey Melnikov, who was an editor of this document in 2013. |
| 5295 | |
| 5296 | A substantial proportion of Martin's contribution was supported by |
| 5297 | Microsoft during his employment there. |
| 5298 | |
| 5299 | The Japanese HTTP/2 community provided invaluable contributions, |
| 5300 | including a number of implementations as well as numerous technical |
| 5301 | and editorial contributions. |
| 5302 | |
| 5303 | |
| 5304 | |
| 5305 | |
| 5306 | |
| 5307 | |
| 5308 | |
| 5309 | |
| 5310 | |
| 5311 | |
| 5312 | |
| 5313 | |
| 5314 | |
| 5315 | |
| 5316 | |
| 5317 | |
| 5318 | |
| 5319 | |
| 5320 | |
| 5321 | |
| 5322 | Belshe, et al. Standards Track [Page 95] |
| 5323 | \f |
| 5324 | RFC 7540 HTTP/2 May 2015 |
| 5325 | |
| 5326 | |
| 5327 | Authors' Addresses |
| 5328 | |
| 5329 | Mike Belshe |
| 5330 | BitGo |
| 5331 | |
| 5332 | EMail: mike@belshe.com |
| 5333 | |
| 5334 | |
| 5335 | Roberto Peon |
| 5336 | Google, Inc |
| 5337 | |
| 5338 | EMail: fenix@google.com |
| 5339 | |
| 5340 | |
| 5341 | Martin Thomson (editor) |
| 5342 | Mozilla |
| 5343 | 331 E Evelyn Street |
| 5344 | Mountain View, CA 94041 |
| 5345 | United States |
| 5346 | |
| 5347 | EMail: martin.thomson@gmail.com |
| 5348 | |
| 5349 | |
| 5350 | |
| 5351 | |
| 5352 | |
| 5353 | |
| 5354 | |
| 5355 | |
| 5356 | |
| 5357 | |
| 5358 | |
| 5359 | |
| 5360 | |
| 5361 | |
| 5362 | |
| 5363 | |
| 5364 | |
| 5365 | |
| 5366 | |
| 5367 | |
| 5368 | |
| 5369 | |
| 5370 | |
| 5371 | |
| 5372 | |
| 5373 | |
| 5374 | |
| 5375 | |
| 5376 | |
| 5377 | |
| 5378 | Belshe, et al. Standards Track [Page 96] |
| 5379 | \f |