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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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 |
.../http2/cache_http2_session.c 297 |
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] |
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] |
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] |
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] |
676 | RFC 7540 HTTP/2 May 2015 |
677 | |
678 | |
679 | Type: The 8-bit type of the frame. The frame type determines the |
.../http2/cache_http2_proto.c 1491 |
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 |
.../http2/cache_http2_proto.c 1510 |
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, |
.../http2/cache_http2_proto.c 1482 |
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] |
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] |
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] |
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] |
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 |
include/tbl/h2_frames.h 57 |
939 | this state MUST be treated as a connection error (Section 5.4.1) |
include/tbl/h2_frames.h 66 |
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] |
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] |
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] |
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] |
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 |
.../http2/cache_http2_proto.c 1284 |
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 |
.../http2/cache_http2_proto.c 729 |
1154 | greater than all streams that the initiating endpoint has opened or |
.../http2/cache_http2_proto.c 1285 |
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] |
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 |
.../http2/cache_http2_proto.c 739 |
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] |
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 |
include/tbl/h2_frames.h 40 |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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 |
include/tbl/h2_frames.h 51 |
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 |
include/tbl/h2_frames.h 46 |
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 |
.../http2/cache_http2_proto.c 860 |
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] |
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] |
1852 | RFC 7540 HTTP/2 May 2015 |
1853 | |
1854 | |
1855 | END_HEADERS (0x4): When set, bit 2 indicates that this frame |
include/tbl/h2_frames.h 60 |
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 |
.../http2/cache_http2_proto.c 1299 |
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 |
include/tbl/h2_frames.h 55 |
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 |
.../http2/cache_http2_proto.c 776 |
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] |
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 |
include/tbl/h2_frames.h 64 |
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] |
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 |
include/tbl/h2_frames.h 73 |
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 |
.../http2/cache_http2_proto.c 377 |
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] |
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 |
.../http2/cache_http2_proto.c 577 |
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. |
include/tbl/h2_frames.h 83 |
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 |
.../http2/cache_http2_proto.c 581 |
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] |
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 |
include/tbl/h2_settings.h 43 |
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 |
include/tbl/h2_settings.h 54 |
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 |
include/tbl/h2_settings.h 65 |
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] |
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 |
include/tbl/h2_settings.h 75 |
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 |
include/tbl/h2_settings.h 85 |
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 |
include/tbl/h2_settings.h 96 |
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 |
.../http2/cache_http2_proto.c 535 |
2182 | parameters MUST be ignored. Once all values have been processed, the |
2183 | |
2184 | |
2185 | |
2186 | Belshe, et al. Standards Track [Page 39] |
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] |
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 |
include/tbl/h2_frames.h 96 |
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 |
include/tbl/h2_frames.h 91 |
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 |
.../http2/cache_http2_proto.c 325 |
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] |
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] |
2356 | RFC 7540 HTTP/2 May 2015 |
2357 | |
2358 | |
2359 | PING frames are not associated with any individual stream. If a PING |
.../http2/cache_http2_proto.c 305 |
2360 | frame is received with a stream identifier field value other than |
include/tbl/h2_frames.h 101 |
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 |
.../http2/cache_http2_proto.c 303 |
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] |
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. |
include/tbl/h2_frames.h 110 |
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] |
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] |
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] |
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] |
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 |
.../http2/cache_http2_proto.c 504 |
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] |
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. |
.../http2/cache_http2_proto.c 508 |
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] |
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 |
include/tbl/h2_frames.h 132 |
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 |
include/tbl/h2_frames.h 127 |
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] |
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] |
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] |
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] |
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 |
.../http2/cache_http2_hpack.c 226 |
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] |
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] |
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 |
.../http2/cache_http2_proto.c 652 |
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] |
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 |
.../http2/cache_http2_hpack.c 253 |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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 | |
include/tbl/h2_settings.h 47 |
4225 | | ENABLE_PUSH | 0x2 | 1 | Section 6.5.2 | |
include/tbl/h2_settings.h 58 |
4226 | | MAX_CONCURRENT_STREAMS | 0x3 | (infinite) | Section 6.5.2 | |
include/tbl/h2_settings.h 69 |
4227 | | INITIAL_WINDOW_SIZE | 0x4 | 65535 | Section 6.5.2 | |
include/tbl/h2_settings.h 79 |
4228 | | MAX_FRAME_SIZE | 0x5 | 16384 | Section 6.5.2 | |
include/tbl/h2_settings.h 89 |
4229 | | MAX_HEADER_LIST_SIZE | 0x6 | (infinite) | Section 6.5.2 | |
include/tbl/h2_settings.h 100 |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |
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] |