idnits 2.17.1 draft-ietf-httpbis-header-compression-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 198: '... implementations MUST be prepared to a...' RFC 2119 keyword, line 294: '... set, a decoder MUST obey the followi...' RFC 2119 keyword, line 473: '... ASCII characters that MUST conform to...' RFC 2119 keyword, line 502: '...d Unicode Codepoints MUST NOT be used....' RFC 2119 keyword, line 651: '...substituted pair MUST correspond to a ...' (3 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 21, 2013) is 3902 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPbis Working Group R. Peon 3 Internet-Draft Google, Inc 4 Intended status: Informational H. Ruellan 5 Expires: February 22, 2014 Canon CRF 6 August 21, 2013 8 HPACK 9 draft-ietf-httpbis-header-compression-02 11 Abstract 13 This document describes HPACK, a format adapted to efficiently 14 represent HTTP headers in the context of HTTP/2.0. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on February 22, 2014. 33 Copyright Notice 35 Copyright (c) 2013 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2.1. Outline . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3. Header Encoding . . . . . . . . . . . . . . . . . . . . . . . 4 54 3.1. Encoding Concepts . . . . . . . . . . . . . . . . . . . . 4 55 3.1.1. Encoding Context . . . . . . . . . . . . . . . . . . . 4 56 3.1.2. Header Table . . . . . . . . . . . . . . . . . . . . . 4 57 3.1.3. Reference Set . . . . . . . . . . . . . . . . . . . . 5 58 3.1.4. Header set . . . . . . . . . . . . . . . . . . . . . . 6 59 3.1.5. Header Representation . . . . . . . . . . . . . . . . 6 60 3.1.6. Header Emission . . . . . . . . . . . . . . . . . . . 6 61 3.2. Header Set Processing . . . . . . . . . . . . . . . . . . 7 62 3.2.1. Header Representation Processing . . . . . . . . . . . 7 63 3.2.2. Reference Set Emission . . . . . . . . . . . . . . . . 8 64 3.2.3. Header Set Completion . . . . . . . . . . . . . . . . 8 65 3.2.4. Header Table Management . . . . . . . . . . . . . . . 8 66 3.2.5. Specific Use Cases . . . . . . . . . . . . . . . . . . 8 67 4. Detailed Format . . . . . . . . . . . . . . . . . . . . . . . 9 68 4.1. Low-level representations . . . . . . . . . . . . . . . . 9 69 4.1.1. Integer representation . . . . . . . . . . . . . . . . 9 70 4.1.2. Header Name Representation . . . . . . . . . . . . . . 11 71 4.1.3. Header Value Representation . . . . . . . . . . . . . 11 72 4.2. Indexed Header Representation . . . . . . . . . . . . . . 11 73 4.3. Literal Header Representation . . . . . . . . . . . . . . 12 74 4.3.1. Literal Header without Indexing . . . . . . . . . . . 12 75 4.3.2. Literal Header with Incremental Indexing . . . . . . . 13 76 4.3.3. Literal Header with Substitution Indexing . . . . . . 14 77 5. Parameter Negotiation . . . . . . . . . . . . . . . . . . . . 15 78 6. Security Considerations . . . . . . . . . . . . . . . . . . . 15 79 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 80 8. Informative References . . . . . . . . . . . . . . . . . . . . 16 81 Appendix A. Change Log (to be removed by RFC Editor before 82 publication . . . . . . . . . . . . . . . . . . . . . 16 83 A.1. Since draft-ietf-httpbis-header-compression-01 . . . . . . 16 84 Appendix B. Initial Header Tables . . . . . . . . . . . . . . . . 17 85 B.1. Requests . . . . . . . . . . . . . . . . . . . . . . . . . 17 86 B.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 18 87 Appendix C. Example . . . . . . . . . . . . . . . . . . . . . . . 19 88 C.1. First header set . . . . . . . . . . . . . . . . . . . . . 19 89 C.2. Second header set . . . . . . . . . . . . . . . . . . . . 21 91 1. Introduction 93 This document describes HPACK, a format adapted to efficiently 94 represent HTTP headers in the context of HTTP/2.0. 96 2. Overview 98 In HTTP/1.X, HTTP headers, which are necessary for the functioning of 99 the protocol, are transmitted with no transformations. 100 Unfortunately, the amount of redundancy in both the keys and the 101 values of these headers is high, and is the cause of increased 102 latency on lower bandwidth links. This indicates that an alternate 103 more compact encoding for headers would be beneficial to latency, and 104 that is what is proposed here. 106 As shown by SPDY [SPDY], Deflate compresses HTTP very effectively. 107 However, the use of a compression scheme which allows for arbitrary 108 matches against the previously encoded data (such as Deflate) exposes 109 users to security issues. In particular, the compression of 110 sensitive data, together with other data controlled by an attacker, 111 may lead to leakage of that sensitive data, even when the resultant 112 bytes are transmitted over an encrypted channel. 114 Another consideration is that processing and memory costs of a 115 compressor such as Deflate may also be too high for some classes of 116 devices, for example when doing forward or reverse proxying. 118 2.1. Outline 120 The HTTP header encoding described in this document is based on a 121 header table that map (name, value) pairs to index values. This 122 scheme is believed to be safe for all known attacks against the 123 compression context today. Header tables are incrementally updated 124 during the HTTP/2.0 session. 126 The encoder is responsible for deciding which headers to insert as 127 new entries in the header table. The decoder then does exactly what 128 the encoder prescribes, ending in a state that exactly matches the 129 encoder's state. This enables decoders to remain simple and 130 understand a wide variety of encoders. 132 As two consecutive sets of headers often have headers in common, each 133 set of headers is coded as a difference from the previous set of 134 headers. The goal is to only encode the changes (headers present in 135 one of the set and not in the other) between the two sets of headers. 137 An example illustrating the use of these different mechanisms to 138 represent headers is available in Appendix C. 140 3. Header Encoding 142 3.1. Encoding Concepts 144 The encoding and decoding of headers relies on some components and 145 concepts. The set of components used form an encoding context. 147 Header Table: The header table (see Section 3.1.2) is a component 148 used to associate headers to index values. 150 Reference Set: The reference set (see Section 3.1.3) is a component 151 containing a group of headers used as a reference for the 152 differential encoding of a new set of headers. 154 Header Set: A header set (see Section 3.1.4) is a group of headers 155 that are encoded jointly. A complete set of key-value pairs as 156 encoded in an HTTP request or response is a header set. 158 Header Representation: A header can be represented in encoded form 159 either as a literal or as an index (see Section 3.1.5). The 160 indexed representation is based on the header table. 162 Header Emission: When decoding a set of headers, some operations 163 emit a header (see Section 3.1.6). An emitted header is added to 164 the set of headers. Once emitted, a header can't be removed from 165 the set of headers. 167 3.1.1. Encoding Context 169 The set of components used to encode or decode a header set form an 170 encoding context: an encoding context contains a header table and a 171 reference set. 173 Using HTTP, messages are exchanged between a client and a server in 174 both direction. To keep the encoding of headers in each direction 175 independent from the other direction, there is one encoding context 176 for each direction. 178 The headers contained in a PUSH_PROMISE frame sent by a server to a 179 client are encoded within the same context as the headers contained 180 in the HEADERS frame corresponding to a response sent from the server 181 to the client. 183 3.1.2. Header Table 185 A header table consists of an ordered list of (name, value) pairs. 186 The first entry of a header table is assigned the index 0. 188 A header can be represented by an entry of the header table if they 189 match. A header and an entry match if both their name and their 190 value match. A header name and an entry name match if they are equal 191 using a character-based, _case insensitive_ comparison (the case 192 insensitive comparison is used because HTTP header names are defined 193 in a case insensitive way). A header value and an entry value match 194 if they are equal using a character-based, _case sensitive_ 195 comparison. 197 Generally, the header table will not contain duplicate entries. 198 However, implementations MUST be prepared to accept duplicates 199 without signalling an error. 201 Initially, a header table contains a list of common headers. Two 202 initial lists of header are provided in Appendix B. One list is for 203 headers transmitted from a client to a server, the other for the 204 reverse direction. 206 A header table is modified by either adding a new entry at the end of 207 the table, or by replacing an existing entry. 209 The encoder decides how to update the header table and as such can 210 control how much memory is used by the header table. To limit the 211 memory requirements on the decoder side, the header table size is 212 bounded (see the SETTINGS_MAX_BUFFER_SIZE in Section 5). 214 The size of an entry is the sum of its name's length in bytes (as 215 defined in Section 4.1.2), of its value's length in bytes 216 (Section 4.1.3) and of 32 bytes. The 32 bytes are an accounting for 217 the entry structure overhead. For example, an entry structure using 218 two 64-bits pointers to reference the name and the value and the 219 entry, and two 64-bits integer for counting the number of references 220 to these name and value would use 32 bytes. 222 The size of a header table is the sum of the size of its entries. 224 3.1.3. Reference Set 226 A reference set is defined as an unordered set of references to 227 entries of the header table. 229 The initial reference set is the empty set. 231 The reference set is updated during the processing of a set of 232 headers. 234 Using the differential encoding, a header that is not present in the 235 reference set can be encoded either with an indexed representation 236 (if the header is present in the header table), or with a literal 237 representation (if the header is not present in the header table). 239 A header that is to be removed from the reference set is encoded with 240 an indexed representation. 242 3.1.4. Header set 244 A header set is a group of header fields that are encoded as a whole. 245 Each header field is a (name, value) pair. 247 A header set is encoded using an ordered list of zero or more header 248 representations. All the header representations describing a header 249 set a grouped into a header block. 251 3.1.5. Header Representation 253 A header can be represented either as a literal or as an index. 255 Literal Representation: A literal representation defines a new 256 header. The header name is represented either literally or as a 257 reference to an entry of the header table. The header value is 258 represented literally. 260 Three different literal representations are provided: 262 * A literal representation that does not add the header to the 263 header table (see Section 4.3.1). 265 * A literal representation that adds the header at the end of the 266 header table (see Section 4.3.2). 268 * A literal representation that uses the header to replace an 269 existing entry of the header table (see Section 4.3.3). 271 Indexed Representation: The indexed representation defines a header 272 as a reference in the header table (see Section 4.2). 274 3.1.6. Header Emission 276 The emission of header is the process of adding a header to the 277 current set of headers. Once an header is emitted, it can't be 278 removed from the current set of headers. 280 The concept of header emission allows a decoder to know when it can 281 pass a header safely to a higher level on the receiver side. This 282 allows a decoder to be implemented in a streaming way, and as such to 283 only keep in memory the header table and the reference set. With 284 such an implementation, the amount of memory used by the decoder is 285 bounded, even in presence of a very large set of headers. The 286 management of memory for handling very large sets of headers can 287 therefore be deferred to the application, which may be able to emit 288 the header to the wire and thus free up memory quickly. 290 3.2. Header Set Processing 292 The processing of an encoded header set to obtain a list of headers 293 is defined in this section. To ensure a correct decoding of a header 294 set, a decoder MUST obey the following rules. 296 3.2.1. Header Representation Processing 298 All the header representations contained in a header block are 299 processed in the order in which they are presented, as specified 300 below. 302 An _indexed representation_ corresponding to an entry _not present_ 303 in the reference set entails the following actions: 305 o The header corresponding to the entry is emitted. 307 o The entry is added to the reference set. 309 An _indexed representation_ corresponding to an entry _present_ in 310 the reference set entails the following actions: 312 o The entry is removed from the reference set. 314 A _literal representation_ that is _not added_ to the header table 315 entails the following action: 317 o The header is emitted. 319 A _literal representation_ that is _added_ to the header table 320 entails the following actions: 322 o The header is emitted. 324 o The header is added to the header table, at the location defined 325 by the representation. 327 o The new entry is added to the reference set. 329 3.2.2. Reference Set Emission 331 Once all the representations contained in a header block have been 332 processed, the headers that are in common with the previous header 333 set are emitted, during the reference set emission. 335 For the reference set emission, each header contained in the 336 reference set that has not been emitted during the processing of the 337 header block is emitted. 339 3.2.3. Header Set Completion 341 Once all of the header representations have been processed, and the 342 remaining items in the reference set have been emitted, the header 343 set is complete. 345 3.2.4. Header Table Management 347 The header table can be modified by either adding a new entry to it 348 or by replacing an existing one. Before doing such a modification, 349 it has to be ensured that the header table size will stay lower than 350 or equal to the SETTINGS_MAX_BUFFER_SIZE limit (see Section 5). To 351 achieve this, repeatedly, the first entry of the header table is 352 removed, until enough space is available for the modification. 354 A consequence of removing one or more entries at the beginning of the 355 header table is that the remaining entries are renumbered. The first 356 entry of the header table is always associated to the index 0. 358 When the modification of the header table is the replacement of an 359 existing entry, the replaced entry is the one indicated in the 360 literal representation before any entry is removed from the header 361 table. If the entry to be replaced is removed from the header table 362 when performing the size adjustment, the replacement entry is 363 inserted at the beginning of the header table. 365 The addition of a new entry with a size greater than the 366 SETTINGS_MAX_BUFFER_SIZE limit causes all the entries from the header 367 table to be dropped and the new entry not to be added to the header 368 table. The replacement of an existing entry with a new entry with a 369 size greater than the SETTINGS_MAX_BUFFER_SIZE has the same 370 consequences. 372 3.2.5. Specific Use Cases 374 Three occurrences of the same indexed representation, corresponding 375 to an entry not present in the reference set, emit the associated 376 header twice: 378 o The first occurrence emits the header a first time and adds the 379 corresponding entry to the reference set. 381 o The second occurrence removes the header's entry from the 382 reference set. 384 o The third occurrence emits the header a second time and adds again 385 its entry to the reference set. 387 This allows for headers sets which include duplicate header entries 388 to be encoded efficiently and faithfully. 390 The first occurrence of the indexed representation can be replaced by 391 a literal representation creating an entry for the header. 393 4. Detailed Format 395 4.1. Low-level representations 397 4.1.1. Integer representation 399 Integers are used to represent name indexes, pair indexes or string 400 lengths. To allow for optimized processing, an integer 401 representation always finishes at the end of a byte. 403 An integer is represented in two parts: a prefix that fills the 404 current byte and an optional list of bytes that are used if the 405 integer value does not fit in the prefix. The number of bits of the 406 prefix (called N) is a parameter of the integer representation. 408 The N-bit prefix allows filling the current byte. If the value is 409 small enough (strictly less than 2^N-1), it is encoded within the 410 N-bit prefix. Otherwise all the bits of the prefix are set to 1 and 411 the value is encoded using an unsigned variable length integer [1] 412 representation. 414 The algorithm to represent an integer I is as follows: 416 If I < 2^N - 1, encode I on N bits 417 Else 418 encode 2^N - 1 on N bits 419 While I >= 128 420 Encode (I % 128 + 128) on 8 bits 421 I = I / 128 422 encode (I) on 8 bits 424 4.1.1.1. Example 1: Encoding 10 using a 5-bit prefix 426 The value 10 is to be encoded with a 5-bit prefix. 428 o 10 is less than 31 (= 2^5 - 1) and is represented using the 5-bit 429 prefix. 431 0 1 2 3 4 5 6 7 432 +---+---+---+---+---+---+---+---+ 433 | X | X | X | 0 | 1 | 0 | 1 | 0 | 10 stored on 5 bits 434 +---+---+---+---+---+---+---+---+ 436 4.1.1.2. Example 2: Encoding 1337 using a 5-bit prefix 438 The value I=1337 is to be encoded with a 5-bit prefix. 440 1337 is greater than 31 (= 2^5 - 1). 442 The 5-bit prefix is filled with its max value (31). 444 I = 1337 - (2^5 - 1) = 1306. 446 I (1306) is greater than or equal to 128, the while loop body 447 executes: 449 I % 128 == 26 451 26 + 128 == 154 453 154 is encoded in 8 bits as: 10011010 455 I is set to 10 (1306 / 128 == 10) 457 I is no longer greater than or equal to 128, the while loop 458 terminates. 460 I, now 10, is encoded on 8 bits as: 00001010 462 The process ends. 464 0 1 2 3 4 5 6 7 465 +---+---+---+---+---+---+---+---+ 466 | X | X | X | 1 | 1 | 1 | 1 | 1 | Prefix = 31, I = 1306 467 | 1 | 0 | 0 | 1 | 1 | 0 | 1 | 0 | 1306>=128, encode(154), I = 1306/128 468 | 0 | 0 | 0 | 0 | 1 | 0 | 1 | 0 | 10<128, encode(10), done 469 +---+---+---+---+---+---+---+---+ 471 4.1.2. Header Name Representation 473 Header names are sequences of ASCII characters that MUST conform to 474 the following header-name ABNF construction: 476 LOWERALPHA = %x61-7A 477 header-char = "!" / "#" / "$" / "%" / "&" / "'" / 478 "*" / "+" / "-" / "." / "^" / "_" / 479 "`" / "|" / "~" / DIGIT / LOWERALPHA 480 header-name = [":"] 1*header-char 482 They are encoded in two parts: 484 1. The length of the text, defined as the number of octets of 485 storage required to store the text, represented as a variable- 486 length-quantity (Section 4.1.1). 488 2. The specific sequence of ASCII octets 490 4.1.3. Header Value Representation 492 Header values are encoded as sequences of UTF-8 encoded text. They 493 are encoded in two parts: 495 1. The length of the text, defined as the number of octets of 496 storage required to store the text, represented as a variable- 497 length-quantity (Section 4.1.1). 499 2. The specific sequence of octets representing the UTF-8 text. 501 Invalid UTF-8 octet sequences, "over-long" UTF-8 encodings, and UTF-8 502 octets that represent invalid Unicode Codepoints MUST NOT be used. 504 4.2. Indexed Header Representation 506 0 1 2 3 4 5 6 7 507 +---+---+---+---+---+---+---+---+ 508 | 1 | Index (7+) | 509 +---+---------------------------+ 511 Indexed Header 513 This representation starts with the '1' 1-bit pattern, followed by 514 the index of the matching pair, represented as an integer with a 515 7-bit prefix. 517 4.3. Literal Header Representation 519 4.3.1. Literal Header without Indexing 521 0 1 2 3 4 5 6 7 522 +---+---+---+---+---+---+---+---+ 523 | 0 | 1 | 1 | Index (5+) | 524 +---+---+---+-------------------+ 525 | Value Length (8+) | 526 +-------------------------------+ 527 | Value String (Length octets) | 528 +-------------------------------+ 530 Literal Header without Indexing - Indexed Name 532 0 1 2 3 4 5 6 7 533 +---+---+---+---+---+---+---+---+ 534 | 0 | 1 | 1 | 0 | 535 +---+---+---+-------------------+ 536 | Name Length (8+) | 537 +-------------------------------+ 538 | Name String (Length octets) | 539 +-------------------------------+ 540 | Value Length (8+) | 541 +-------------------------------+ 542 | Value String (Length octets) | 543 +-------------------------------+ 545 Literal Header without Indexing - New Name 547 This representation, which does not involve updating the header 548 table, starts with the '011' 3-bit pattern. 550 If the header name matches the header name of a (name, value) pair 551 stored in the Header Table, the index of the pair increased by one 552 (index + 1) is represented as an integer with a 5-bit prefix. Note 553 that if the index is strictly below 31, one byte is used. 555 If the header name does not match a header name entry, the value 0 is 556 represented on 5 bits followed by the header name (Section 4.1.2). 558 Header name representation is followed by the header value 559 represented as a literal string as described in Section 4.1.3. 561 4.3.2. Literal Header with Incremental Indexing 563 0 1 2 3 4 5 6 7 564 +---+---+---+---+---+---+---+---+ 565 | 0 | 1 | 0 | Index (5+) | 566 +---+---+---+-------------------+ 567 | Value Length (8+) | 568 +-------------------------------+ 569 | Value String (Length octets) | 570 +-------------------------------+ 572 Literal Header with Incremental Indexing - 573 Indexed Name 575 0 1 2 3 4 5 6 7 576 +---+---+---+---+---+---+---+---+ 577 | 0 | 1 | 0 | 0 | 578 +---+---+---+-------------------+ 579 | Name Length (8+) | 580 +-------------------------------+ 581 | Name String (Length octets) | 582 +-------------------------------+ 583 | Value Length (8+) | 584 +-------------------------------+ 585 | Value String (Length octets) | 586 +-------------------------------+ 588 Literal Header with Incremental Indexing - 589 New Name 591 This representation starts with the '010' 3-bit pattern. 593 If the header name matches the header name of a (name, value) pair 594 stored in the Header Table, the index of the pair increased by one 595 (index + 1) is represented as an integer with a 5-bit prefix. Note 596 that if the index is strictly below 31, one byte is used. 598 If the header name does not match a header name entry, the value 0 is 599 represented on 5 bits followed by the header name (Section 4.1.2). 601 Header name representation is followed by the header value 602 represented as a literal string as described in Section 4.1.3. 604 4.3.3. Literal Header with Substitution Indexing 606 0 1 2 3 4 5 6 7 607 +---+---+---+---+---+---+---+---+ 608 | 0 | 0 | Index (6+) | 609 +---+---+-----------------------+ 610 | Substituted Index (8+) | 611 +-------------------------------+ 612 | Value Length (8+) | 613 +-------------------------------+ 614 | Value String (Length octets) | 615 +-------------------------------+ 617 Literal Header with Substitution Indexing - 618 Indexed Name 620 0 1 2 3 4 5 6 7 621 +---+---+---+---+---+---+---+---+ 622 | 0 | 0 | 0 | 623 +---+---+-----------------------+ 624 | Name Length (8+) | 625 +-------------------------------+ 626 | Name String (Length octets) | 627 +-------------------------------+ 628 | Substituted Index (8+) | 629 +-------------------------------+ 630 | Value Length (8+) | 631 +-------------------------------+ 632 | Value String (Length octets) | 633 +-------------------------------+ 635 Literal Header with Substitution Indexing - 636 New Name 638 This representation starts with the '00' 2-bit pattern. 640 If the header name matches the header name of a (name, value) pair 641 stored in the Header Table, the index of the pair increased by one 642 (index + 1) is represented as an integer with a 6-bit prefix. Note 643 that if the index is strictly below 62, one byte is used. 645 If the header name does not match a header name entry, the value 0 is 646 represented on 6 bits followed by the header name (Section 4.1.2). 648 The index of the substituted (name, value) pair is inserted after the 649 header name representation as a 0-bit prefix integer. 651 The index of the substituted pair MUST correspond to a position in 652 the header table containing a non-void entry. An index for the 653 substituted pair that corresponds to empty position in the header 654 table MUST be treated as an error. 656 This index is followed by the header value represented as a literal 657 string as described in Section 4.1.3. 659 5. Parameter Negotiation 661 A few parameters can be used to accommodate client and server 662 processing and memory requirements. [[anchor3: These settings are 663 currently not supported as they have not been integrated in the main 664 specification. Therefore, the maximum buffer size for the header 665 table is fixed at 4096 bytes.]] 667 SETTINGS_MAX_BUFFER_SIZE: Allows the sender to inform the remote 668 endpoint of the maximum size it accepts for the header table. 669 The default value is 4096 bytes. 670 [[anchor4: Is this default value OK? Do we need a maximum size? 671 Do we want to allow infinite buffer?]] 672 When the remote endpoint receives a SETTINGS frame containing a 673 SETTINGS_MAX_BUFFER_SIZE setting with a value smaller than the one 674 currently in use, it MUST send as soon as possible a HEADER frame 675 with a stream identifier of 0x0 containing a value smaller than or 676 equal to the received setting value. 677 [[anchor5: This changes slightly the behaviour of the HEADERS 678 frame, which should be updated as follows:]] 679 A HEADER frame with a stream identifier of 0x0 indicates that the 680 sender has reduced the maximum size of the header table. The new 681 maximum size of the header table is encoded on 32-bit. The 682 decoder MUST reduce its own header table by dropping entries from 683 it until the size of the header table is lower than or equal to 684 the transmitted maximum size. 686 6. Security Considerations 688 This compressor exists to solve security issues present in stream 689 compressors such as DEFLATE whereby the compression context can be 690 efficiently probed to reveal secrets. A conformant implementation of 691 this specification should be fairly safe against that kind of attack, 692 as the reaping of any information from the compression context 693 requires more work than guessing and verifying the plaintext data 694 directly with the server. As with any secret, however, the longer 695 the length of the secret, the more difficult the secret is to guess. 696 It is inadvisable to have short cookies that are relied upon to 697 remain secret for any duration of time. 699 A proper security-conscious implementation will also need to prevent 700 timing attacks by ensuring that the amount of time it takes to do 701 string comparisons is always a function of the total length of the 702 strings, and not a function of the number of matched characters. 704 Another common security problem is when the remote endpoint 705 successfully causes the local endpoint to exhaust its memory. This 706 compressor attempts to deal with the most obvious ways that this 707 could occur by limiting both the peak and the steady-state amount of 708 memory consumed in the compressor state, by providing ways for the 709 application to consume/flush the emitted headers in small chunks, and 710 by considering overhead in the state size calculation. Implementors 711 must still be careful in the creation of APIs to an implementation of 712 this compressor by ensuring that header keys and values are either 713 emitted as a stream, or that the compression implementation have a 714 limit on the maximum size of a key or value. Failure to implement 715 these kinds of safeguards may still result in a scenario where the 716 local endpoint exhausts its memory. 718 7. IANA Considerations 720 This memo includes no request to IANA. 722 8. Informative References 724 [SPDY] Belshe, M. and R. Peon, "SPDY Protocol", February 2012, 725 . 727 [1] 729 Appendix A. Change Log (to be removed by RFC Editor before publication 731 A.1. Since draft-ietf-httpbis-header-compression-01 733 o Refactored of Header Encoding Section: split definitions and 734 processing rule. 736 o Backward incompatible change: Updated reference set management as 737 per issue #214. This changes how the interaction between the 738 reference set and eviction works. This also changes the working 739 of the reference set in some specific cases. 741 o Backward incompatible change: modified initial header list, as per 742 issue #188. 744 o Added example of 32 bytes entry structure (issue #191). 746 o Added Header Set Completion section. Reflowed some text. 747 Clarified some writing which was akward. Added text about 748 duplicate header entry encoding. Clarified some language w.r.t 749 Header Set. Changed x-my-header to mynewheader. Added text in the 750 HeaderEmission section indicating that the application may also be 751 able to free up memory more quickly. Added information in 752 Security Considerations section. 754 Appendix B. Initial Header Tables 756 [[anchor9: The tables in this section should be updated based on 757 statistical analysis of header names frequency and specific HTTP 2.0 758 header rules (like removal of some headers).]] 759 [[anchor10: These tables are not adapted for headers contained in 760 PUSH_PROMISE frames. Either the tables can be merged, or the table 761 for responses can be updated.]] 763 B.1. Requests 765 The following table lists the pre-defined headers that make-up the 766 initial header table user to represent requests sent from a client to 767 a server. 769 +-------+---------------------+--------------+ 770 | Index | Header Name | Header Value | 771 +-------+---------------------+--------------+ 772 | 0 | :scheme | http | 773 | 1 | :scheme | https | 774 | 2 | :host | | 775 | 3 | :path | / | 776 | 4 | :method | GET | 777 | 5 | accept | | 778 | 6 | accept-charset | | 779 | 7 | accept-encoding | | 780 | 8 | accept-language | | 781 | 9 | cookie | | 782 | 10 | if-modified-since | | 783 | 11 | user-agent | | 784 | 12 | referer | | 785 | 13 | authorization | | 786 | 14 | allow | | 787 | 15 | cache-control | | 788 | 16 | connection | | 789 | 17 | content-length | | 790 | 18 | content-type | | 791 | 19 | date | | 792 | 20 | expect | | 793 | 21 | from | | 794 | 22 | if-match | | 795 | 23 | if-none-match | | 796 | 24 | if-range | | 797 | 25 | if-unmodified-since | | 798 | 26 | max-forwards | | 799 | 27 | proxy-authorization | | 800 | 28 | range | | 801 | 29 | via | | 802 +-------+---------------------+--------------+ 804 Table 1: Initial Header Table for Requests 806 B.2. Responses 808 The following table lists the pre-defined headers that make-up the 809 initial header table used to represent responses sent from a server 810 to a client. The same header table is also used to represent request 811 headers sent from a server to a client in a PUSH_PROMISE frame. 813 +-------+-----------------------------+--------------+ 814 | Index | Header Name | Header Value | 815 +-------+-----------------------------+--------------+ 816 | 0 | :status | 200 | 817 | 1 | age | | 818 | 2 | cache-control | | 819 | 3 | content-length | | 820 | 4 | content-type | | 821 | 5 | date | | 822 | 6 | etag | | 823 | 7 | expires | | 824 | 8 | last-modified | | 825 | 9 | server | | 826 | 10 | set-cookie | | 827 | 11 | vary | | 828 | 12 | via | | 829 | 13 | access-control-allow-origin | | 830 | 14 | accept-ranges | | 831 | 15 | allow | | 832 | 16 | connection | | 833 | 17 | content-disposition | | 834 | 18 | content-encoding | | 835 | 19 | content-language | | 836 | 20 | content-location | | 837 | 21 | content-range | | 838 | 22 | link | | 839 | 23 | location | | 840 | 24 | proxy-authenticate | | 841 | 25 | refresh | | 842 | 26 | retry-after | | 843 | 27 | strict-transport-security | | 844 | 28 | transfer-encoding | | 845 | 29 | www-authenticate | | 846 +-------+-----------------------------+--------------+ 848 Table 2: Initial Header Table for Responses 850 Appendix C. Example 852 Here is an example that illustrates different representations and how 853 tables are updated. [[anchor13: This section needs to be updated to 854 better reflect the new processing of header fields, and include more 855 examples.]] 857 C.1. First header set 859 The first header set to represent is the following: 861 :path: /my-example/index.html 862 user-agent: my-user-agent 863 mynewheader: first 865 The header table is empty, all headers are represented as literal 866 headers with indexing. The 'mynewheader' header name is not in the 867 header name table and is encoded literally. This gives the following 868 representation: 870 0x44 (literal header with incremental indexing, name index = 3) 871 0x16 (header value string length = 22) 872 /my-example/index.html 873 0x4D (literal header with incremental indexing, name index = 12) 874 0x0D (header value string length = 13) 875 my-user-agent 876 0x40 (literal header with incremental indexing, new name) 877 0x0B (header name string length = 11) 878 mynewheader 879 0x05 (header value string length = 5) 880 first 882 The header table is as follows after the processing of these headers: 884 Header table 885 +---------+----------------+---------------------------+ 886 | Index | Header Name | Header Value | 887 +---------+----------------+---------------------------+ 888 | 0 | :scheme | http | 889 +---------+----------------+---------------------------+ 890 | 1 | :scheme | https | 891 +---------+----------------+---------------------------+ 892 | ... | ... | ... | 893 +---------+----------------+---------------------------+ 894 | 37 | warning | | 895 +---------+----------------+---------------------------+ 896 | 38 | :path | /my-example/index.html | added header 897 +---------+----------------+---------------------------+ 898 | 39 | user-agent | my-user-agent | added header 899 +---------+----------------+---------------------------+ 900 | 40 | mynewheader | first | added header 901 +---------+----------------+---------------------------+ 903 As all the headers in the first header set are indexed in the header 904 table, all are kept in the reference set of headers, which is: 906 Reference Set: 907 :path, /my-example/index.html 908 user-agent, my-user-agent 909 mynewheader, first 911 C.2. Second header set 913 The second header set to represent is the following: 915 :path: /my-example/resources/script.js 916 user-agent: my-user-agent 917 mynewheader: second 919 Comparing this second header set to the reference set, the first and 920 third headers are from the reference set are not present in this 921 second header set and must be removed. In addition, in this new set, 922 the first and third headers have to be encoded. The path header is 923 represented as a literal header with substitution indexing. The 924 mynewheader will be represented as a literal header with incremental 925 indexing. 927 0xa6 (indexed header, index = 38: removal from reference set) 928 0xa8 (indexed header, index = 40: removal from reference set) 929 0x04 (literal header, substitution indexing, name index = 3) 930 0x26 (replaced entry index = 38) 931 0x1f (header value string length = 31) 932 /my-example/resources/script.js 933 0x5f 0x0a (literal header, incremental indexing, name index = 40) 934 0x06 (header value string length = 6) 935 second 937 The header table is updated as follow: 939 Header table 940 +---------+----------------+---------------------------+ 941 | Index | Header Name | Header Value | 942 +---------+----------------+---------------------------+ 943 | 0 | :scheme | http | 944 +---------+----------------+---------------------------+ 945 | 1 | :scheme | https | 946 +---------+----------------+---------------------------+ 947 | ... | ... | ... | 948 +---------+----------------+---------------------------+ 949 | 37 | warning | | 950 +---------+----------------+---------------------------+ 951 | 38 | :path | /my-example/resources/ | replaced 952 | | | script.js | header 953 +---------+----------------+---------------------------+ 954 | 39 | user-agent | my-user-agent | 955 +---------+----------------+---------------------------+ 956 | 40 | mynewheader | first | 957 +---------+----------------+---------------------------+ 958 | 41 | mynewheader | second | added header 959 +---------+----------------+---------------------------+ 961 All the headers in this second header set are indexed in the header 962 table, therefore, all are kept in the reference set of headers, which 963 becomes: 965 Reference Set: 966 :path, /my-example/resources/script.js 967 user-agent, my-user-agent 968 mynewheader, second 970 Authors' Addresses 972 Roberto Peon 973 Google, Inc 975 EMail: fenix@google.com 977 Herve Ruellan 978 Canon CRF 980 EMail: herve.ruellan@crf.canon.fr