idnits 2.17.00 (12 Aug 2021) /tmp/idnits17826/draft-ietf-quic-qpack-21.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: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1899 has weird spacing: '...thority www.e...' == Line 1914 has weird spacing: '...thority www.e...' == Line 1922 has weird spacing: '...thority www.e...' == Line 1939 has weird spacing: '...thority www.e...' == Line 1942 has weird spacing: '...tom-key custo...' == (14 more instances...) -- The document date (2 February 2021) is 466 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: draft-ietf-quic-transport has been published as RFC 9000 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-14 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' Summary: 0 errors (**), 0 flaws (~~), 10 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 QUIC C. Krasic 3 Internet-Draft Netflix 4 Intended status: Standards Track M. Bishop 5 Expires: 6 August 2021 Akamai Technologies 6 A. Frindell, Ed. 7 Facebook 8 2 February 2021 10 QPACK: Header Compression for HTTP/3 11 draft-ietf-quic-qpack-21 13 Abstract 15 This specification defines QPACK, a compression format for 16 efficiently representing HTTP fields, to be used in HTTP/3. This is 17 a variation of HPACK compression that seeks to reduce head-of-line 18 blocking. 20 Note to Readers 22 Discussion of this draft takes place on the QUIC working group 23 mailing list (quic@ietf.org (mailto:quic@ietf.org)), which is 24 archived at https://mailarchive.ietf.org/arch/ 25 search/?email_list=quic. 27 Working Group information can be found at https://github.com/quicwg; 28 source code and issues list for this draft can be found at 29 https://github.com/quicwg/base-drafts/labels/-qpack. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on 6 August 2021. 48 Copyright Notice 50 Copyright (c) 2021 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 55 license-info) in effect on the date of publication of this document. 56 Please review these documents carefully, as they describe your rights 57 and restrictions with respect to this document. Code Components 58 extracted from this document must include Simplified BSD License text 59 as described in Section 4.e of the Trust Legal Provisions and are 60 provided without warranty as described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 65 1.1. Conventions and Definitions . . . . . . . . . . . . . . . 4 66 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5 67 2. Compression Process Overview . . . . . . . . . . . . . . . . 6 68 2.1. Encoder . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 2.1.1. Limits on Dynamic Table Insertions . . . . . . . . . 6 70 2.1.2. Blocked Streams . . . . . . . . . . . . . . . . . . . 7 71 2.1.3. Avoiding Flow Control Deadlocks . . . . . . . . . . . 8 72 2.1.4. Known Received Count . . . . . . . . . . . . . . . . 9 73 2.2. Decoder . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 2.2.1. Blocked Decoding . . . . . . . . . . . . . . . . . . 9 75 2.2.2. State Synchronization . . . . . . . . . . . . . . . . 10 76 2.2.3. Invalid References . . . . . . . . . . . . . . . . . 11 77 3. Reference Tables . . . . . . . . . . . . . . . . . . . . . . 11 78 3.1. Static Table . . . . . . . . . . . . . . . . . . . . . . 11 79 3.2. Dynamic Table . . . . . . . . . . . . . . . . . . . . . . 12 80 3.2.1. Dynamic Table Size . . . . . . . . . . . . . . . . . 12 81 3.2.2. Dynamic Table Capacity and Eviction . . . . . . . . . 12 82 3.2.3. Maximum Dynamic Table Capacity . . . . . . . . . . . 13 83 3.2.4. Absolute Indexing . . . . . . . . . . . . . . . . . . 14 84 3.2.5. Relative Indexing . . . . . . . . . . . . . . . . . . 14 85 3.2.6. Post-Base Indexing . . . . . . . . . . . . . . . . . 15 86 4. Wire Format . . . . . . . . . . . . . . . . . . . . . . . . . 16 87 4.1. Primitives . . . . . . . . . . . . . . . . . . . . . . . 16 88 4.1.1. Prefixed Integers . . . . . . . . . . . . . . . . . . 16 89 4.1.2. String Literals . . . . . . . . . . . . . . . . . . . 16 90 4.2. Encoder and Decoder Streams . . . . . . . . . . . . . . . 16 91 4.3. Encoder Instructions . . . . . . . . . . . . . . . . . . 17 92 4.3.1. Set Dynamic Table Capacity . . . . . . . . . . . . . 17 93 4.3.2. Insert With Name Reference . . . . . . . . . . . . . 18 94 4.3.3. Insert With Literal Name . . . . . . . . . . . . . . 18 95 4.3.4. Duplicate . . . . . . . . . . . . . . . . . . . . . . 19 97 4.4. Decoder Instructions . . . . . . . . . . . . . . . . . . 19 98 4.4.1. Section Acknowledgment . . . . . . . . . . . . . . . 19 99 4.4.2. Stream Cancellation . . . . . . . . . . . . . . . . . 20 100 4.4.3. Insert Count Increment . . . . . . . . . . . . . . . 20 101 4.5. Field Line Representations . . . . . . . . . . . . . . . 21 102 4.5.1. Encoded Field Section Prefix . . . . . . . . . . . . 21 103 4.5.2. Indexed Field Line . . . . . . . . . . . . . . . . . 24 104 4.5.3. Indexed Field Line With Post-Base Index . . . . . . . 25 105 4.5.4. Literal Field Line With Name Reference . . . . . . . 25 106 4.5.5. Literal Field Line With Post-Base Name Reference . . 26 107 4.5.6. Literal Field Line With Literal Name . . . . . . . . 26 108 5. Configuration . . . . . . . . . . . . . . . . . . . . . . . . 27 109 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 27 110 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 111 7.1. Probing Dynamic Table State . . . . . . . . . . . . . . . 28 112 7.1.1. Applicability to QPACK and HTTP . . . . . . . . . . . 28 113 7.1.2. Mitigation . . . . . . . . . . . . . . . . . . . . . 29 114 7.1.3. Never-Indexed Literals . . . . . . . . . . . . . . . 30 115 7.2. Static Huffman Encoding . . . . . . . . . . . . . . . . . 31 116 7.3. Memory Consumption . . . . . . . . . . . . . . . . . . . 31 117 7.4. Implementation Limits . . . . . . . . . . . . . . . . . . 32 118 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 119 8.1. Settings Registration . . . . . . . . . . . . . . . . . . 33 120 8.2. Stream Type Registration . . . . . . . . . . . . . . . . 33 121 8.3. Error Code Registration . . . . . . . . . . . . . . . . . 34 122 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34 123 9.1. Normative References . . . . . . . . . . . . . . . . . . 34 124 9.2. Informative References . . . . . . . . . . . . . . . . . 35 125 Appendix A. Static Table . . . . . . . . . . . . . . . . . . . . 36 126 Appendix B. Encoding and Decoding Examples . . . . . . . . . . . 40 127 B.1. Literal Field Line With Name Reference . . . . . . . . . 41 128 B.2. Dynamic Table . . . . . . . . . . . . . . . . . . . . . . 41 129 B.3. Speculative Insert . . . . . . . . . . . . . . . . . . . 42 130 B.4. Duplicate Instruction, Stream Cancellation . . . . . . . 43 131 B.5. Dynamic Table Insert, Eviction . . . . . . . . . . . . . 44 132 Appendix C. Sample One Pass Encoding Algorithm . . . . . . . . . 45 133 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 47 134 D.1. Since draft-ietf-quic-qpack-19 . . . . . . . . . . . . . 47 135 D.2. Since draft-ietf-quic-qpack-18 . . . . . . . . . . . . . 47 136 D.3. Since draft-ietf-quic-qpack-17 . . . . . . . . . . . . . 47 137 D.4. Since draft-ietf-quic-qpack-16 . . . . . . . . . . . . . 47 138 D.5. Since draft-ietf-quic-qpack-15 . . . . . . . . . . . . . 47 139 D.6. Since draft-ietf-quic-qpack-14 . . . . . . . . . . . . . 47 140 D.7. Since draft-ietf-quic-qpack-13 . . . . . . . . . . . . . 47 141 D.8. Since draft-ietf-quic-qpack-12 . . . . . . . . . . . . . 47 142 D.9. Since draft-ietf-quic-qpack-11 . . . . . . . . . . . . . 47 143 D.10. Since draft-ietf-quic-qpack-10 . . . . . . . . . . . . . 48 144 D.11. Since draft-ietf-quic-qpack-09 . . . . . . . . . . . . . 48 145 D.12. Since draft-ietf-quic-qpack-08 . . . . . . . . . . . . . 48 146 D.13. Since draft-ietf-quic-qpack-06 . . . . . . . . . . . . . 48 147 D.14. Since draft-ietf-quic-qpack-05 . . . . . . . . . . . . . 48 148 D.15. Since draft-ietf-quic-qpack-04 . . . . . . . . . . . . . 48 149 D.16. Since draft-ietf-quic-qpack-03 . . . . . . . . . . . . . 48 150 D.17. Since draft-ietf-quic-qpack-02 . . . . . . . . . . . . . 48 151 D.18. Since draft-ietf-quic-qpack-01 . . . . . . . . . . . . . 49 152 D.19. Since draft-ietf-quic-qpack-00 . . . . . . . . . . . . . 49 153 D.20. Since draft-ietf-quic-qcram-00 . . . . . . . . . . . . . 49 154 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 50 155 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 157 1. Introduction 159 The QUIC transport protocol ([QUIC-TRANSPORT]) is designed to support 160 HTTP semantics, and its design subsumes many of the features of 161 HTTP/2 ([RFC7540]). HTTP/2 uses HPACK ([RFC7541]) for compression of 162 the header and trailer sections. If HPACK were used for HTTP/3 163 ([HTTP3]), it would induce head-of-line blocking for field sections 164 due to built-in assumptions of a total ordering across frames on all 165 streams. 167 QPACK reuses core concepts from HPACK, but is redesigned to allow 168 correctness in the presence of out-of-order delivery, with 169 flexibility for implementations to balance between resilience against 170 head-of-line blocking and optimal compression ratio. The design 171 goals are to closely approach the compression ratio of HPACK with 172 substantially less head-of-line blocking under the same loss 173 conditions. 175 1.1. Conventions and Definitions 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 179 "OPTIONAL" in this document are to be interpreted as described in 180 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 181 capitals, as shown here. 183 Definitions of terms that are used in this document: 185 HTTP fields: Metadata sent as part of an HTTP message. The term 186 encompasses both header and trailer fields. Colloquially, the 187 term "headers" has often been used to refer to HTTP header fields 188 and trailer fields; this document uses "fields" for generality. 190 HTTP field line: A name-value pair sent as part of an HTTP field 191 section. See Sections 6.3 and 6.5 of [SEMANTICS]. 193 HTTP field value: Data associated with a field name, composed from 194 all field line values with that field name in that section, 195 concatenated together with comma separators. 197 Field section: An ordered collection of HTTP field lines associated 198 with an HTTP message. A field section can contain multiple field 199 lines with the same name. It can also contain duplicate field 200 lines. An HTTP message can include both header and trailer 201 sections. 203 Representation: An instruction that represents a field line, 204 possibly by reference to the dynamic and static tables. 206 Encoder: An implementation that encodes field sections. 208 Decoder: An implementation that decodes encoded field sections. 210 Absolute Index: A unique index for each entry in the dynamic table. 212 Base: A reference point for relative and post-base indices. 213 Representations that reference dynamic table entries are relative 214 to a Base. 216 Insert Count: The total number of entries inserted in the dynamic 217 table. 219 QPACK is a name, not an acronym. 221 1.2. Notational Conventions 223 Diagrams use the format described in Section 3.1 of [RFC2360], with 224 the following additional conventions: 226 x (A) Indicates that x is A bits long 228 x (A+) Indicates that x uses the prefixed integer encoding defined 229 in Section 4.1.1, beginning with an A-bit prefix. 231 x ... Indicates that x is variable-length and extends to the end of 232 the region. 234 2. Compression Process Overview 236 Like HPACK, QPACK uses two tables for associating field lines 237 ("headers") to indices. The static table (Section 3.1) is predefined 238 and contains common header field lines (some of them with an empty 239 value). The dynamic table (Section 3.2) is built up over the course 240 of the connection and can be used by the encoder to index both header 241 and trailer field lines in the encoded field sections. 243 QPACK defines unidirectional streams for sending instructions from 244 encoder to decoder and vice versa. 246 2.1. Encoder 248 An encoder converts a header or trailer section into a series of 249 representations by emitting either an indexed or a literal 250 representation for each field line in the list; see Section 4.5. 251 Indexed representations achieve high compression by replacing the 252 literal name and possibly the value with an index to either the 253 static or dynamic table. References to the static table and literal 254 representations do not require any dynamic state and never risk head- 255 of-line blocking. References to the dynamic table risk head-of-line 256 blocking if the encoder has not received an acknowledgment indicating 257 the entry is available at the decoder. 259 An encoder MAY insert any entry in the dynamic table it chooses; it 260 is not limited to field lines it is compressing. 262 QPACK preserves the ordering of field lines within each field 263 section. An encoder MUST emit field representations in the order 264 they appear in the input field section. 266 QPACK is designed to contain the more complex state tracking to the 267 encoder, while the decoder is relatively simple. 269 2.1.1. Limits on Dynamic Table Insertions 271 Inserting entries into the dynamic table might not be possible if the 272 table contains entries that cannot be evicted. 274 A dynamic table entry cannot be evicted immediately after insertion, 275 even if it has never been referenced. Once the insertion of a 276 dynamic table entry has been acknowledged and there are no 277 outstanding references to the entry in unacknowledged 278 representations, the entry becomes evictable. Note that references 279 on the encoder stream never preclude the eviction of an entry, 280 because those references are guaranteed to be processed before the 281 instruction evicting the entry. 283 If the dynamic table does not contain enough room for a new entry 284 without evicting other entries, and the entries that would be evicted 285 are not evictable, the encoder MUST NOT insert that entry into the 286 dynamic table (including duplicates of existing entries). In order 287 to avoid this, an encoder that uses the dynamic table has to keep 288 track of each dynamic table entry referenced by each field section 289 until those representations are acknowledged by the decoder; see 290 Section 4.4.1. 292 2.1.1.1. Avoiding Prohibited Insertions 294 To ensure that the encoder is not prevented from adding new entries, 295 the encoder can avoid referencing entries that are close to eviction. 296 Rather than reference such an entry, the encoder can emit a Duplicate 297 instruction (Section 4.3.4), and reference the duplicate instead. 299 Determining which entries are too close to eviction to reference is 300 an encoder preference. One heuristic is to target a fixed amount of 301 available space in the dynamic table: either unused space or space 302 that can be reclaimed by evicting non-blocking entries. To achieve 303 this, the encoder can maintain a draining index, which is the 304 smallest absolute index (Section 3.2.4) in the dynamic table that it 305 will emit a reference for. As new entries are inserted, the encoder 306 increases the draining index to maintain the section of the table 307 that it will not reference. If the encoder does not create new 308 references to entries with an absolute index lower than the draining 309 index, the number of unacknowledged references to those entries will 310 eventually become zero, allowing them to be evicted. 312 <-- Newer Entries Older Entries --> 313 (Larger Indicies) (Smaller Indicies) 314 +--------+---------------------------------+----------+ 315 | Unused | Referenceable | Draining | 316 | Space | Entries | Entries | 317 +--------+---------------------------------+----------+ 318 ^ ^ ^ 319 | | | 320 Insertion Point Draining Index Dropping 321 Point 323 Figure 1: Draining Dynamic Table Entries 325 2.1.2. Blocked Streams 327 Because QUIC does not guarantee order between data on different 328 streams, a decoder might encounter a representation that references a 329 dynamic table entry that it has not yet received. 331 Each encoded field section contains a Required Insert Count 332 (Section 4.5.1), the lowest possible value for the Insert Count with 333 which the field section can be decoded. For a field section encoded 334 using references to the dynamic table, the Required Insert Count is 335 one larger than the largest absolute index of all referenced dynamic 336 table entries. For a field section encoded with no references to the 337 dynamic table, the Required Insert Count is zero. 339 When the decoder receives an encoded field section with a Required 340 Insert Count greater than its own Insert Count, the stream cannot be 341 processed immediately, and is considered "blocked"; see 342 Section 2.2.1. 344 The decoder specifies an upper bound on the number of streams that 345 can be blocked using the SETTINGS_QPACK_BLOCKED_STREAMS setting; see 346 Section 5. An encoder MUST limit the number of streams that could 347 become blocked to the value of SETTINGS_QPACK_BLOCKED_STREAMS at all 348 times. If a decoder encounters more blocked streams than it promised 349 to support, it MUST treat this as a connection error of type 350 QPACK_DECOMPRESSION_FAILED. 352 Note that the decoder might not become blocked on every stream that 353 risks becoming blocked. 355 An encoder can decide whether to risk having a stream become blocked. 356 If permitted by the value of SETTINGS_QPACK_BLOCKED_STREAMS, 357 compression efficiency can often be improved by referencing dynamic 358 table entries that are still in transit, but if there is loss or 359 reordering the stream can become blocked at the decoder. An encoder 360 can avoid the risk of blocking by only referencing dynamic table 361 entries that have been acknowledged, but this could mean using 362 literals. Since literals make the encoded field section larger, this 363 can result in the encoder becoming blocked on congestion or flow 364 control limits. 366 2.1.3. Avoiding Flow Control Deadlocks 368 Writing instructions on streams that are limited by flow control can 369 produce deadlocks. 371 A decoder might stop issuing flow control credit on the stream that 372 carries an encoded field section until the necessary updates are 373 received on the encoder stream. If the granting of flow control 374 credit on the encoder stream (or the connection as a whole) depends 375 on the consumption and release of data on the stream carrying the 376 encoded field section, a deadlock might result. 378 More generally, a stream containing a large instruction can become 379 deadlocked if the decoder withholds flow control credit until the 380 instruction is completely received. 382 To avoid these deadlocks, an encoder SHOULD NOT write an instruction 383 unless sufficient stream and connection flow control credit is 384 available for the entire instruction. 386 2.1.4. Known Received Count 388 The Known Received Count is the total number of dynamic table 389 insertions and duplications acknowledged by the decoder. The encoder 390 tracks the Known Received Count in order to identify which dynamic 391 table entries can be referenced without potentially blocking a 392 stream. The decoder tracks the Known Received Count in order to be 393 able to send Insert Count Increment instructions. 395 A Section Acknowledgment instruction (Section 4.4.1) implies that the 396 decoder has received all dynamic table state necessary to decode the 397 field section. If the Required Insert Count of the acknowledged 398 field section is greater than the current Known Received Count, Known 399 Received Count is updated to that Required Insert Count value. 401 An Insert Count Increment instruction (Section 4.4.3) increases the 402 Known Received Count by its Increment parameter. See Section 2.2.2.3 403 for guidance. 405 2.2. Decoder 407 As in HPACK, the decoder processes a series of representations and 408 emits the corresponding field sections. It also processes 409 instructions received on the encoder stream that modify the dynamic 410 table. Note that encoded field sections and encoder stream 411 instructions arrive on separate streams. This is unlike HPACK, where 412 encoded field sections (header blocks) can contain instructions that 413 modify the dynamic table, and there is no dedicated stream of HPACK 414 instructions. 416 The decoder MUST emit field lines in the order their representations 417 appear in the encoded field section. 419 2.2.1. Blocked Decoding 421 Upon receipt of an encoded field section, the decoder examines the 422 Required Insert Count. When the Required Insert Count is less than 423 or equal to the decoder's Insert Count, the field section can be 424 processed immediately. Otherwise, the stream on which the field 425 section was received becomes blocked. 427 While blocked, encoded field section data SHOULD remain in the 428 blocked stream's flow control window. This data is unusable until 429 the stream becomes unblocked, and releasing the flow control 430 prematurely makes the decoder vulnerable to memory exhaustion 431 attacks. A stream becomes unblocked when the Insert Count becomes 432 unblocked when the Insert Count becomes greater than or equal to the 433 Required Insert Count for all encoded field sections the decoder has 434 started reading from the stream. 436 When processing encoded field sections, the decoder expects the 437 Required Insert Count to equal the lowest possible value for the 438 Insert Count with which the field section can be decoded, as 439 prescribed in Section 2.1.2. If it encounters a Required Insert 440 Count smaller than expected, it MUST treat this as a connection error 441 of type QPACK_DECOMPRESSION_FAILED; see Section 2.2.3. If it 442 encounters a Required Insert Count larger than expected, it MAY treat 443 this as a connection error of type QPACK_DECOMPRESSION_FAILED. 445 2.2.2. State Synchronization 447 The decoder signals the following events by emitting decoder 448 instructions (Section 4.4) on the decoder stream. 450 2.2.2.1. Completed Processing of a Field Section 452 After the decoder finishes decoding a field section encoded using 453 representations containing dynamic table references, it MUST emit a 454 Section Acknowledgment instruction (Section 4.4.1). A stream may 455 carry multiple field sections in the case of intermediate responses, 456 trailers, and pushed requests. The encoder interprets each 457 Section Acknowledgment instruction as acknowledging the earliest 458 unacknowledged field section containing dynamic table references sent 459 on the given stream. 461 2.2.2.2. Abandonment of a Stream 463 When an endpoint receives a stream reset before the end of a stream 464 or before all encoded field sections are processed on that stream, or 465 when it abandons reading of a stream, it generates a Stream 466 Cancellation instruction; see Section 4.4.2. This signals to the 467 encoder that all references to the dynamic table on that stream are 468 no longer outstanding. A decoder with a maximum dynamic table 469 capacity (Section 3.2.3) equal to zero MAY omit sending Stream 470 Cancellations, because the encoder cannot have any dynamic table 471 references. An encoder cannot infer from this instruction that any 472 updates to the dynamic table have been received. 474 The Section Acknowledgment and Stream Cancellation instructions 475 permit the encoder to remove references to entries in the dynamic 476 table. When an entry with absolute index lower than the Known 477 Received Count has zero references, then it is considered evictable; 478 see Section 2.1.1. 480 2.2.2.3. New Table Entries 482 After receiving new table entries on the encoder stream, the decoder 483 chooses when to emit Insert Count Increment instructions; see 484 Section 4.4.3. Emitting this instruction after adding each new 485 dynamic table entry will provide the timeliest feedback to the 486 encoder, but could be redundant with other decoder feedback. By 487 delaying an Insert Count Increment instruction, the decoder might be 488 able to coalesce multiple Insert Count Increment instructions, or 489 replace them entirely with Section Acknowledgments; see 490 Section 4.4.1. However, delaying too long may lead to compression 491 inefficiencies if the encoder waits for an entry to be acknowledged 492 before using it. 494 2.2.3. Invalid References 496 If the decoder encounters a reference in a field line representation 497 to a dynamic table entry that has already been evicted or that has an 498 absolute index greater than or equal to the declared Required Insert 499 Count (Section 4.5.1), it MUST treat this as a connection error of 500 type QPACK_DECOMPRESSION_FAILED. 502 If the decoder encounters a reference in an encoder instruction to a 503 dynamic table entry that has already been evicted, it MUST treat this 504 as a connection error of type QPACK_ENCODER_STREAM_ERROR. 506 3. Reference Tables 508 Unlike in HPACK, entries in the QPACK static and dynamic tables are 509 addressed separately. The following sections describe how entries in 510 each table are addressed. 512 3.1. Static Table 514 The static table consists of a predefined list of field lines, each 515 of which has a fixed index over time. Its entries are defined in 516 Appendix A. 518 All entries in the static table have a name and a value. However, 519 values can be empty (that is, have a length of 0). Each entry is 520 identified by a unique index. 522 Note that the QPACK static table is indexed from 0, whereas the HPACK 523 static table is indexed from 1. 525 When the decoder encounters an invalid static table index in a field 526 line representation it MUST treat this as a connection error of type 527 QPACK_DECOMPRESSION_FAILED. If this index is received on the encoder 528 stream, this MUST be treated as a connection error of type 529 QPACK_ENCODER_STREAM_ERROR. 531 3.2. Dynamic Table 533 The dynamic table consists of a list of field lines maintained in 534 first-in, first-out order. A QPACK encoder and decoder share a 535 dynamic table that is initially empty. The encoder adds entries to 536 the dynamic table and sends them to the decoder via instructions on 537 the encoder stream; see Section 4.3. 539 The dynamic table can contain duplicate entries (i.e., entries with 540 the same name and same value). Therefore, duplicate entries MUST NOT 541 be treated as an error by the decoder. 543 Dynamic table entries can have empty values. 545 3.2.1. Dynamic Table Size 547 The size of the dynamic table is the sum of the size of its entries. 549 The size of an entry is the sum of its name's length in bytes, its 550 value's length in bytes, and 32 additional bytes. The size of an 551 entry is calculated using the length of its name and value without 552 Huffman encoding applied. 554 3.2.2. Dynamic Table Capacity and Eviction 556 The encoder sets the capacity of the dynamic table, which serves as 557 the upper limit on its size. The initial capacity of the dynamic 558 table is zero. The encoder sends a Set Dynamic Table Capacity 559 instruction (Section 4.3.1) with a non-zero capacity to begin using 560 the dynamic table. 562 Before a new entry is added to the dynamic table, entries are evicted 563 from the end of the dynamic table until the size of the dynamic table 564 is less than or equal to (table capacity - size of new entry). The 565 encoder MUST NOT cause a dynamic table entry to be evicted unless 566 that entry is evictable; see Section 2.1.1. The new entry is then 567 added to the table. It is an error if the encoder attempts to add an 568 entry that is larger than the dynamic table capacity; the decoder 569 MUST treat this as a connection error of type 570 QPACK_ENCODER_STREAM_ERROR. 572 A new entry can reference an entry in the dynamic table that will be 573 evicted when adding this new entry into the dynamic table. 574 Implementations are cautioned to avoid deleting the referenced name 575 or value if the referenced entry is evicted from the dynamic table 576 prior to inserting the new entry. 578 Whenever the dynamic table capacity is reduced by the encoder 579 (Section 4.3.1), entries are evicted from the end of the dynamic 580 table until the size of the dynamic table is less than or equal to 581 the new table capacity. This mechanism can be used to completely 582 clear entries from the dynamic table by setting a capacity of 0, 583 which can subsequently be restored. 585 3.2.3. Maximum Dynamic Table Capacity 587 To bound the memory requirements of the decoder, the decoder limits 588 the maximum value the encoder is permitted to set for the dynamic 589 table capacity. In HTTP/3, this limit is determined by the value of 590 SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder; see Section 5. 591 The encoder MUST NOT set a dynamic table capacity that exceeds this 592 maximum, but it can choose to use a lower dynamic table capacity; see 593 Section 4.3.1. 595 For clients using 0-RTT data in HTTP/3, the server's maximum table 596 capacity is the remembered value of the setting, or zero if the value 597 was not previously sent. When the client's 0-RTT value of the 598 SETTING is zero, the server MAY set it to a non-zero value in its 599 SETTINGS frame. If the remembered value is non-zero, the server MUST 600 send the same non-zero value in its SETTINGS frame. If it specifies 601 any other value, or omits SETTINGS_QPACK_MAX_TABLE_CAPACITY from 602 SETTINGS, the encoder must treat this as a connection error of type 603 QPACK_DECODER_STREAM_ERROR. 605 For HTTP/3 servers and HTTP/3 clients when 0-RTT is not attempted or 606 is rejected, the maximum table capacity is 0 until the encoder 607 processes a SETTINGS frame with a non-zero value of 608 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 610 When the maximum table capacity is zero, the encoder MUST NOT insert 611 entries into the dynamic table, and MUST NOT send any encoder 612 instructions on the encoder stream. 614 3.2.4. Absolute Indexing 616 Each entry possesses an absolute index that is fixed for the lifetime 617 of that entry. The first entry inserted has an absolute index of 0; 618 indices increase by one with each insertion. 620 3.2.5. Relative Indexing 622 Relative indices begin at zero and increase in the opposite direction 623 from the absolute index. Determining which entry has a relative 624 index of 0 depends on the context of the reference. 626 In encoder instructions (Section 4.3), a relative index of 0 refers 627 to the most recently inserted value in the dynamic table. Note that 628 this means the entry referenced by a given relative index will change 629 while interpreting instructions on the encoder stream. 631 +-----+---------------+-------+ 632 | n-1 | ... | d | Absolute Index 633 + - - +---------------+ - - - + 634 | 0 | ... | n-d-1 | Relative Index 635 +-----+---------------+-------+ 636 ^ | 637 | V 638 Insertion Point Dropping Point 640 n = count of entries inserted 641 d = count of entries dropped 643 Figure 2: Example Dynamic Table Indexing - Encoder Stream 645 Unlike in encoder instructions, relative indices in field line 646 representations are relative to the Base at the beginning of the 647 encoded field section; see Section 4.5.1. This ensures that 648 references are stable even if encoded field sections and dynamic 649 table updates are processed out of order. 651 In a field line representation, a relative index of 0 refers to the 652 entry with absolute index equal to Base - 1. 654 Base 655 | 656 V 657 +-----+-----+-----+-----+-------+ 658 | n-1 | n-2 | n-3 | ... | d | Absolute Index 659 +-----+-----+ - +-----+ - + 660 | 0 | ... | n-d-3 | Relative Index 661 +-----+-----+-------+ 663 n = count of entries inserted 664 d = count of entries dropped 665 In this example, Base = n - 2 667 Figure 3: Example Dynamic Table Indexing - Relative Index in 668 Representation 670 3.2.6. Post-Base Indexing 672 Post-Base indices are used in field line representations for entries 673 with absolute indices greater than or equal to Base, starting at 0 674 for the entry with absolute index equal to Base, and increasing in 675 the same direction as the absolute index. 677 Post-Base indices allow an encoder to process a field section in a 678 single pass and include references to entries added while processing 679 this (or other) field sections. 681 Base 682 | 683 V 684 +-----+-----+-----+-----+-----+ 685 | n-1 | n-2 | n-3 | ... | d | Absolute Index 686 +-----+-----+-----+-----+-----+ 687 | 1 | 0 | Post-Base Index 688 +-----+-----+ 690 n = count of entries inserted 691 d = count of entries dropped 692 In this example, Base = n - 2 694 Figure 4: Example Dynamic Table Indexing - Post-Base Index in 695 Representation 697 4. Wire Format 699 4.1. Primitives 701 4.1.1. Prefixed Integers 703 The prefixed integer from Section 5.1 of [RFC7541] is used heavily 704 throughout this document. The format from [RFC7541] is used 705 unmodified. Note, however, that QPACK uses some prefix sizes not 706 actually used in HPACK. 708 QPACK implementations MUST be able to decode integers up to and 709 including 62 bits long. 711 4.1.2. String Literals 713 The string literal defined by Section 5.2 of [RFC7541] is also used 714 throughout. This string format includes optional Huffman encoding. 716 HPACK defines string literals to begin on a byte boundary. They 717 begin with a single bit flag, denoted as 'H' in this document 718 (indicating whether the string is Huffman-coded), followed by the 719 Length encoded as a 7-bit prefix integer, and finally Length bytes of 720 data. When Huffman encoding is enabled, the Huffman table from 721 Appendix B of [RFC7541] is used without modification and Length 722 indicates the size of the string after encoding. 724 This document expands the definition of string literals by permitting 725 them to begin other than on a byte boundary. An "N-bit prefix string 726 literal" begins mid-byte, with the first (8-N) bits allocated to a 727 previous field. The string uses one bit for the Huffman flag, 728 followed by the Length encoded as an (N-1)-bit prefix integer. The 729 prefix size, N, can have a value between 2 and 8 inclusive. The 730 remainder of the string literal is unmodified. 732 A string literal without a prefix length noted is an 8-bit prefix 733 string literal and follows the definitions in [RFC7541] without 734 modification. 736 4.2. Encoder and Decoder Streams 738 QPACK defines two unidirectional stream types: 740 * An encoder stream is a unidirectional stream of type 0x02. It 741 carries an unframed sequence of encoder instructions from encoder 742 to decoder. 744 * A decoder stream is a unidirectional stream of type 0x03. It 745 carries an unframed sequence of decoder instructions from decoder 746 to encoder. 748 HTTP/3 endpoints contain a QPACK encoder and decoder. Each endpoint 749 MUST initiate at most one encoder stream and at most one decoder 750 stream. Receipt of a second instance of either stream type MUST be 751 treated as a connection error of type H3_STREAM_CREATION_ERROR. 753 These streams MUST NOT be closed. Closure of either unidirectional 754 stream type MUST be treated as a connection error of type 755 H3_CLOSED_CRITICAL_STREAM. 757 An endpoint MAY avoid creating an encoder stream if it will not be 758 used (for example if its encoder does not wish to use the dynamic 759 table, or if the maximum size of the dynamic table permitted by the 760 peer is zero). 762 An endpoint MAY avoid creating a decoder stream if its decoder sets 763 the maximum capacity of the dynamic table to zero. 765 An endpoint MUST allow its peer to create an encoder stream and a 766 decoder stream even if the connection's settings prevent their use. 768 4.3. Encoder Instructions 770 An encoder sends encoder instructions on the encoder stream to set 771 the capacity of the dynamic table and add dynamic table entries. 772 Instructions adding table entries can use existing entries to avoid 773 transmitting redundant information. The name can be transmitted as a 774 reference to an existing entry in the static or the dynamic table or 775 as a string literal. For entries that already exist in the dynamic 776 table, the full entry can also be used by reference, creating a 777 duplicate entry. 779 4.3.1. Set Dynamic Table Capacity 781 An encoder informs the decoder of a change to the dynamic table 782 capacity using an instruction that starts with the '001' 3-bit 783 pattern. This is followed by the new dynamic table capacity 784 represented as an integer with a 5-bit prefix; see Section 4.1.1. 786 0 1 2 3 4 5 6 7 787 +---+---+---+---+---+---+---+---+ 788 | 0 | 0 | 1 | Capacity (5+) | 789 +---+---+---+-------------------+ 791 Figure 5: Set Dynamic Table Capacity 793 The new capacity MUST be lower than or equal to the limit described 794 in Section 3.2.3. In HTTP/3, this limit is the value of the 795 SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter (Section 5) received from 796 the decoder. The decoder MUST treat a new dynamic table capacity 797 value that exceeds this limit as a connection error of type 798 QPACK_ENCODER_STREAM_ERROR. 800 Reducing the dynamic table capacity can cause entries to be evicted; 801 see Section 3.2.2. This MUST NOT cause the eviction of entries that 802 are not evictable; see Section 2.1.1. Changing the capacity of the 803 dynamic table is not acknowledged as this instruction does not insert 804 an entry. 806 4.3.2. Insert With Name Reference 808 An encoder adds an entry to the dynamic table where the field name 809 matches the field name of an entry stored in the static or the 810 dynamic table using an instruction that starts with the '1' 1-bit 811 pattern. The second ('T') bit indicates whether the reference is to 812 the static or dynamic table. The 6-bit prefix integer 813 (Section 4.1.1) that follows is used to locate the table entry for 814 the field name. When T=1, the number represents the static table 815 index; when T=0, the number is the relative index of the entry in the 816 dynamic table. 818 The field name reference is followed by the field value represented 819 as a string literal; see Section 4.1.2. 821 0 1 2 3 4 5 6 7 822 +---+---+---+---+---+---+---+---+ 823 | 1 | T | Name Index (6+) | 824 +---+---+-----------------------+ 825 | H | Value Length (7+) | 826 +---+---------------------------+ 827 | Value String (Length bytes) | 828 +-------------------------------+ 830 Figure 6: Insert Field Line -- Indexed Name 832 4.3.3. Insert With Literal Name 834 An encoder adds an entry to the dynamic table where both the field 835 name and the field value are represented as string literals using an 836 instruction that starts with the '01' 2-bit pattern. 838 This is followed by the name represented as a 6-bit prefix string 839 literal, and the value represented as an 8-bit prefix string literal; 840 see Section 4.1.2. 842 0 1 2 3 4 5 6 7 843 +---+---+---+---+---+---+---+---+ 844 | 0 | 1 | H | Name Length (5+) | 845 +---+---+---+-------------------+ 846 | Name String (Length bytes) | 847 +---+---------------------------+ 848 | H | Value Length (7+) | 849 +---+---------------------------+ 850 | Value String (Length bytes) | 851 +-------------------------------+ 853 Figure 7: Insert Field Line -- New Name 855 4.3.4. Duplicate 857 An encoder duplicates an existing entry in the dynamic table using an 858 instruction that starts with the '000' 3-bit pattern. This is 859 followed by the relative index of the existing entry represented as 860 an integer with a 5-bit prefix; see Section 4.1.1. 862 0 1 2 3 4 5 6 7 863 +---+---+---+---+---+---+---+---+ 864 | 0 | 0 | 0 | Index (5+) | 865 +---+---+---+-------------------+ 867 Figure 8: Duplicate 869 The existing entry is re-inserted into the dynamic table without 870 resending either the name or the value. This is useful to avoid 871 adding a reference to an older entry, which might block inserting new 872 entries. 874 4.4. Decoder Instructions 876 A decoder sends decoder instructions on the decoder stream to inform 877 the encoder about the processing of field sections and table updates 878 to ensure consistency of the dynamic table. 880 4.4.1. Section Acknowledgment 882 After processing an encoded field section whose declared Required 883 Insert Count is not zero, the decoder emits a Section Acknowledgment 884 instruction. The instruction starts with the '1' 1-bit pattern, 885 followed by the field section's associated stream ID encoded as a 886 7-bit prefix integer; see Section 4.1.1. 888 This instruction is used as described in Section 2.1.4 and in 889 Section 2.2.2. 891 0 1 2 3 4 5 6 7 892 +---+---+---+---+---+---+---+---+ 893 | 1 | Stream ID (7+) | 894 +---+---------------------------+ 896 Figure 9: Section Acknowledgment 898 If an encoder receives a Section Acknowledgment instruction referring 899 to a stream on which every encoded field section with a non-zero 900 Required Insert Count has already been acknowledged, this MUST be 901 treated as a connection error of type QPACK_DECODER_STREAM_ERROR. 903 The Section Acknowledgment instruction might increase the Known 904 Received Count; see Section 2.1.4. 906 4.4.2. Stream Cancellation 908 When a stream is reset or reading is abandoned, the decoder emits a 909 Stream Cancellation instruction. The instruction starts with the 910 '01' 2-bit pattern, followed by the stream ID of the affected stream 911 encoded as a 6-bit prefix integer. 913 This instruction is used as described in Section 2.2.2. 915 0 1 2 3 4 5 6 7 916 +---+---+---+---+---+---+---+---+ 917 | 0 | 1 | Stream ID (6+) | 918 +---+---+-----------------------+ 920 Figure 10: Stream Cancellation 922 4.4.3. Insert Count Increment 924 The Insert Count Increment instruction starts with the '00' 2-bit 925 pattern, followed by the Increment encoded as a 6-bit prefix integer. 926 This instruction increases the Known Received Count (Section 2.1.4) 927 by the value of the Increment parameter. The decoder should send an 928 Increment value that increases the Known Received Count to the total 929 number of dynamic table insertions and duplications processed so far. 931 0 1 2 3 4 5 6 7 932 +---+---+---+---+---+---+---+---+ 933 | 0 | 0 | Increment (6+) | 934 +---+---+-----------------------+ 936 Figure 11: Insert Count Increment 938 An encoder that receives an Increment field equal to zero, or one 939 that increases the Known Received Count beyond what the encoder has 940 sent MUST treat this as a connection error of type 941 QPACK_DECODER_STREAM_ERROR. 943 4.5. Field Line Representations 945 An encoded field section consists of a prefix and a possibly empty 946 sequence of representations defined in this section. Each 947 representation corresponds to a single field line. These 948 representations reference the static table or the dynamic table in a 949 particular state, but do not modify that state. 951 Encoded field sections are carried in frames on streams defined by 952 the enclosing protocol. 954 4.5.1. Encoded Field Section Prefix 956 Each encoded field section is prefixed with two integers. The 957 Required Insert Count is encoded as an integer with an 8-bit prefix 958 using the encoding described in Section 4.5.1.1. The Base is encoded 959 as a sign bit ('S') and a Delta Base value with a 7-bit prefix; see 960 Section 4.5.1.2. 962 0 1 2 3 4 5 6 7 963 +---+---+---+---+---+---+---+---+ 964 | Required Insert Count (8+) | 965 +---+---------------------------+ 966 | S | Delta Base (7+) | 967 +---+---------------------------+ 968 | Encoded Field Lines ... 969 +-------------------------------+ 971 Figure 12: Encoded Field Section 973 4.5.1.1. Required Insert Count 975 Required Insert Count identifies the state of the dynamic table 976 needed to process the encoded field section. Blocking decoders use 977 the Required Insert Count to determine when it is safe to process the 978 rest of the field section. 980 The encoder transforms the Required Insert Count as follows before 981 encoding: 983 if ReqInsertCount == 0: 984 EncInsertCount = 0 985 else: 986 EncInsertCount = (ReqInsertCount mod (2 * MaxEntries)) + 1 988 Here "MaxEntries" is the maximum number of entries that the dynamic 989 table can have. The smallest entry has empty name and value strings 990 and has the size of 32. Hence "MaxEntries" is calculated as 992 MaxEntries = floor( MaxTableCapacity / 32 ) 994 "MaxTableCapacity" is the maximum capacity of the dynamic table as 995 specified by the decoder; see Section 3.2.3. 997 This encoding limits the length of the prefix on long-lived 998 connections. 1000 The decoder can reconstruct the Required Insert Count using an 1001 algorithm such as the following. If the decoder encounters a value 1002 of EncodedInsertCount that could not have been produced by a 1003 conformant encoder, it MUST treat this as a connection error of type 1004 QPACK_DECOMPRESSION_FAILED. 1006 TotalNumberOfInserts is the total number of inserts into the 1007 decoder's dynamic table. 1009 FullRange = 2 * MaxEntries 1010 if EncodedInsertCount == 0: 1011 ReqInsertCount = 0 1012 else: 1013 if EncodedInsertCount > FullRange: 1014 Error 1015 MaxValue = TotalNumberOfInserts + MaxEntries 1017 # MaxWrapped is the largest possible value of 1018 # ReqInsertCount that is 0 mod 2 * MaxEntries 1019 MaxWrapped = floor(MaxValue / FullRange) * FullRange 1020 ReqInsertCount = MaxWrapped + EncodedInsertCount - 1 1022 # If ReqInsertCount exceeds MaxValue, the Encoder's value 1023 # must have wrapped one fewer time 1024 if ReqInsertCount > MaxValue: 1025 if ReqInsertCount <= FullRange: 1026 Error 1027 ReqInsertCount -= FullRange 1029 # Value of 0 must be encoded as 0. 1030 if ReqInsertCount == 0: 1031 Error 1033 For example, if the dynamic table is 100 bytes, then the Required 1034 Insert Count will be encoded modulo 6. If a decoder has received 10 1035 inserts, then an encoded value of 4 indicates that the Required 1036 Insert Count is 9 for the field section. 1038 4.5.1.2. Base 1040 The Base is used to resolve references in the dynamic table as 1041 described in Section 3.2.5. 1043 To save space, the Base is encoded relative to the Required Insert 1044 Count using a one-bit sign ('S') and the Delta Base value. A sign 1045 bit of 0 indicates that the Base is greater than or equal to the 1046 value of the Required Insert Count; the decoder adds the value of 1047 Delta Base to the Required Insert Count to determine the value of the 1048 Base. A sign bit of 1 indicates that the Base is less than the 1049 Required Insert Count; the decoder subtracts the value of Delta Base 1050 from the Required Insert Count and also subtracts one to determine 1051 the value of the Base. That is: 1053 if S == 0: 1054 Base = ReqInsertCount + DeltaBase 1055 else: 1056 Base = ReqInsertCount - DeltaBase - 1 1058 A single-pass encoder determines the Base before encoding a field 1059 section. If the encoder inserted entries in the dynamic table while 1060 encoding the field section and is referencing them, Required Insert 1061 Count will be greater than the Base, so the encoded difference is 1062 negative and the sign bit is set to 1. If the field section was not 1063 encoded using representations that reference the most recent entry in 1064 the table and did not insert any new entries, the Base will be 1065 greater than the Required Insert Count, so the delta will be positive 1066 and the sign bit is set to 0. 1068 An encoder that produces table updates before encoding a field 1069 section might set Base to the value of Required Insert Count. In 1070 such case, both the sign bit and the Delta Base will be set to zero. 1072 A field section that was encoded without references to the dynamic 1073 table can use any value for the Base; setting Delta Base to zero is 1074 one of the most efficient encodings. 1076 For example, with a Required Insert Count of 9, a decoder receives an 1077 S bit of 1 and a Delta Base of 2. This sets the Base to 6 and 1078 enables post-base indexing for three entries. In this example, a 1079 relative index of 1 refers to the 5th entry that was added to the 1080 table; a post-base index of 1 refers to the 8th entry. 1082 4.5.2. Indexed Field Line 1084 An indexed field line representation identifies an entry in the 1085 static table, or an entry in the dynamic table with an absolute index 1086 less than the value of the Base. 1088 0 1 2 3 4 5 6 7 1089 +---+---+---+---+---+---+---+---+ 1090 | 1 | T | Index (6+) | 1091 +---+---+-----------------------+ 1093 Figure 13: Indexed Field Line 1095 This representation starts with the '1' 1-bit pattern, followed by 1096 the 'T' bit indicating whether the reference is into the static or 1097 dynamic table. The 6-bit prefix integer (Section 4.1.1) that follows 1098 is used to locate the table entry for the field line. When T=1, the 1099 number represents the static table index; when T=0, the number is the 1100 relative index of the entry in the dynamic table. 1102 4.5.3. Indexed Field Line With Post-Base Index 1104 An indexed field line with post-base index representation identifies 1105 an entry in the dynamic table with an absolute index greater than or 1106 equal to the value of the Base. 1108 0 1 2 3 4 5 6 7 1109 +---+---+---+---+---+---+---+---+ 1110 | 0 | 0 | 0 | 1 | Index (4+) | 1111 +---+---+---+---+---------------+ 1113 Figure 14: Indexed Field Line with Post-Base Index 1115 This representation starts with the '0001' 4-bit pattern. This is 1116 followed by the post-base index (Section 3.2.6) of the matching field 1117 line, represented as an integer with a 4-bit prefix; see 1118 Section 4.1.1. 1120 4.5.4. Literal Field Line With Name Reference 1122 A literal field line with name reference representation encodes a 1123 field line where the field name matches the field name of an entry in 1124 the static table, or the field name of an entry in the dynamic table 1125 with an absolute index less than the value of the Base. 1127 0 1 2 3 4 5 6 7 1128 +---+---+---+---+---+---+---+---+ 1129 | 0 | 1 | N | T |Name Index (4+)| 1130 +---+---+---+---+---------------+ 1131 | H | Value Length (7+) | 1132 +---+---------------------------+ 1133 | Value String (Length bytes) | 1134 +-------------------------------+ 1136 Figure 15: Literal Field Line With Name Reference 1138 This representation starts with the '01' 2-bit pattern. The 1139 following bit, 'N', indicates whether an intermediary is permitted to 1140 add this field line to the dynamic table on subsequent hops. When 1141 the 'N' bit is set, the encoded field line MUST always be encoded 1142 with a literal representation. In particular, when a peer sends a 1143 field line that it received represented as a literal field line with 1144 the 'N' bit set, it MUST use a literal representation to forward this 1145 field line. This bit is intended for protecting field values that 1146 are not to be put at risk by compressing them; see Section 7.1 for 1147 more details. 1149 The fourth ('T') bit indicates whether the reference is to the static 1150 or dynamic table. The 4-bit prefix integer (Section 4.1.1) that 1151 follows is used to locate the table entry for the field name. When 1152 T=1, the number represents the static table index; when T=0, the 1153 number is the relative index of the entry in the dynamic table. 1155 Only the field name is taken from the dynamic table entry; the field 1156 value is encoded as an 8-bit prefix string literal; see 1157 Section 4.1.2. 1159 4.5.5. Literal Field Line With Post-Base Name Reference 1161 A literal field line with post-base name reference representation 1162 encodes a field line where the field name matches the field name of a 1163 dynamic table entry with an absolute index greater than or equal to 1164 the value of the Base. 1166 0 1 2 3 4 5 6 7 1167 +---+---+---+---+---+---+---+---+ 1168 | 0 | 0 | 0 | 0 | N |NameIdx(3+)| 1169 +---+---+---+---+---+-----------+ 1170 | H | Value Length (7+) | 1171 +---+---------------------------+ 1172 | Value String (Length bytes) | 1173 +-------------------------------+ 1175 Figure 16: Literal Field Line With Post-Base Name Reference 1177 This representation starts with the '0000' 4-bit pattern. The fifth 1178 bit is the 'N' bit as described in Section 4.5.4. This is followed 1179 by a post-base index of the dynamic table entry (Section 3.2.6) 1180 encoded as an integer with a 3-bit prefix; see Section 4.1.1. 1182 Only the field name is taken from the dynamic table entry; the field 1183 value is encoded as an 8-bit prefix string literal; see 1184 Section 4.1.2. 1186 4.5.6. Literal Field Line With Literal Name 1188 The literal field line with literal name representation encodes a 1189 field name and a field value as string literals. 1191 0 1 2 3 4 5 6 7 1192 +---+---+---+---+---+---+---+---+ 1193 | 0 | 0 | 1 | N | H |NameLen(3+)| 1194 +---+---+---+---+---+-----------+ 1195 | Name String (Length bytes) | 1196 +---+---------------------------+ 1197 | H | Value Length (7+) | 1198 +---+---------------------------+ 1199 | Value String (Length bytes) | 1200 +-------------------------------+ 1202 Figure 17: Literal Field Line With Literal Name 1204 This representation starts with the '001' 3-bit pattern. The fourth 1205 bit is the 'N' bit as described in Section 4.5.4. The name follows, 1206 represented as a 4-bit prefix string literal, then the value, 1207 represented as an 8-bit prefix string literal; see Section 4.1.2. 1209 5. Configuration 1211 QPACK defines two settings for the HTTP/3 SETTINGS frame: 1213 SETTINGS_QPACK_MAX_TABLE_CAPACITY (0x1): The default value is zero. 1214 See Section 3.2 for usage. This is the equivalent of the 1215 SETTINGS_HEADER_TABLE_SIZE from HTTP/2. 1217 SETTINGS_QPACK_BLOCKED_STREAMS (0x7): The default value is zero. 1218 See Section 2.1.2. 1220 6. Error Handling 1222 The following error codes are defined for HTTP/3 to indicate failures 1223 of QPACK that prevent the stream or connection from continuing: 1225 QPACK_DECOMPRESSION_FAILED (0x200): The decoder failed to interpret 1226 an encoded field section and is not able to continue decoding that 1227 field section. 1229 QPACK_ENCODER_STREAM_ERROR (0x201): The decoder failed to interpret 1230 an encoder instruction received on the encoder stream. 1232 QPACK_DECODER_STREAM_ERROR (0x202): The encoder failed to interpret 1233 a decoder instruction received on the decoder stream. 1235 7. Security Considerations 1237 This section describes potential areas of security concern with 1238 QPACK: 1240 * Use of compression as a length-based oracle for verifying guesses 1241 about secrets that are compressed into a shared compression 1242 context. 1244 * Denial of service resulting from exhausting processing or memory 1245 capacity at a decoder. 1247 7.1. Probing Dynamic Table State 1249 QPACK reduces the encoded size of field sections by exploiting the 1250 redundancy inherent in protocols like HTTP. The ultimate goal of 1251 this is to reduce the amount of data that is required to send HTTP 1252 requests or responses. 1254 The compression context used to encode header and trailer fields can 1255 be probed by an attacker who can both define fields to be encoded and 1256 transmitted and observe the length of those fields once they are 1257 encoded. When an attacker can do both, they can adaptively modify 1258 requests in order to confirm guesses about the dynamic table state. 1259 If a guess is compressed into a shorter length, the attacker can 1260 observe the encoded length and infer that the guess was correct. 1262 This is possible even over the Transport Layer Security Protocol 1263 (TLS, see [TLS]) and the QUIC Transport Protocol (see 1264 [QUIC-TRANSPORT]), because while TLS and QUIC provide confidentiality 1265 protection for content, they only provide a limited amount of 1266 protection for the length of that content. 1268 Note: Padding schemes only provide limited protection against an 1269 attacker with these capabilities, potentially only forcing an 1270 increased number of guesses to learn the length associated with a 1271 given guess. Padding schemes also work directly against 1272 compression by increasing the number of bits that are transmitted. 1274 Attacks like CRIME ([CRIME]) demonstrated the existence of these 1275 general attacker capabilities. The specific attack exploited the 1276 fact that DEFLATE ([RFC1951]) removes redundancy based on prefix 1277 matching. This permitted the attacker to confirm guesses a character 1278 at a time, reducing an exponential-time attack into a linear-time 1279 attack. 1281 7.1.1. Applicability to QPACK and HTTP 1283 QPACK mitigates but does not completely prevent attacks modeled on 1284 CRIME ([CRIME]) by forcing a guess to match an entire field line, 1285 rather than individual characters. An attacker can only learn 1286 whether a guess is correct or not, so is reduced to a brute force 1287 guess for the field values associated with a given field name. 1289 The viability of recovering specific field values therefore depends 1290 on the entropy of values. As a result, values with high entropy are 1291 unlikely to be recovered successfully. However, values with low 1292 entropy remain vulnerable. 1294 Attacks of this nature are possible any time that two mutually 1295 distrustful entities control requests or responses that are placed 1296 onto a single HTTP/3 connection. If the shared QPACK compressor 1297 permits one entity to add entries to the dynamic table, and the other 1298 to refer to those entries while encoding chosen field lines, then the 1299 attacker (the second entity) can learn the state of the table by 1300 observing the length of the encoded output. 1302 For example, requests or responses from mutually distrustful entities 1303 can occur when an intermediary either: 1305 * sends requests from multiple clients on a single connection toward 1306 an origin server, or 1308 * takes responses from multiple origin servers and places them on a 1309 shared connection toward a client. 1311 Web browsers also need to assume that requests made on the same 1312 connection by different web origins ([RFC6454]) are made by mutually 1313 distrustful entities. Other scenarios involving mutually distrustful 1314 entities are also possible. 1316 7.1.2. Mitigation 1318 Users of HTTP that require confidentiality for header or trailer 1319 fields can use values with entropy sufficient to make guessing 1320 infeasible. However, this is impractical as a general solution 1321 because it forces all users of HTTP to take steps to mitigate 1322 attacks. It would impose new constraints on how HTTP is used. 1324 Rather than impose constraints on users of HTTP, an implementation of 1325 QPACK can instead constrain how compression is applied in order to 1326 limit the potential for dynamic table probing. 1328 An ideal solution segregates access to the dynamic table based on the 1329 entity that is constructing the message. Field values that are added 1330 to the table are attributed to an entity, and only the entity that 1331 created a particular value can extract that value. 1333 To improve compression performance of this option, certain entries 1334 might be tagged as being public. For example, a web browser might 1335 make the values of the Accept-Encoding header field available in all 1336 requests. 1338 An encoder without good knowledge of the provenance of field values 1339 might instead introduce a penalty for many field lines with the same 1340 field name and different values. This penalty could cause a large 1341 number of attempts to guess a field value to result in the field not 1342 being compared to the dynamic table entries in future messages, 1343 effectively preventing further guesses. 1345 This response might be made inversely proportional to the length of 1346 the field value. Disabling access to the dynamic table for a given 1347 field name might occur for shorter values more quickly or with higher 1348 probability than for longer values. 1350 This mitigation is most effective between two endpoints. If messages 1351 are re-encoded by an intermediary without knowledge of which entity 1352 constructed a given message, the intermediary could inadvertently 1353 merge compression contexts that the original encoder had specifically 1354 kept separate. 1356 Note: Simply removing entries corresponding to the field from the 1357 dynamic table can be ineffectual if the attacker has a reliable 1358 way of causing values to be reinstalled. For example, a request 1359 to load an image in a web browser typically includes the Cookie 1360 header field (a potentially highly valued target for this sort of 1361 attack), and web sites can easily force an image to be loaded, 1362 thereby refreshing the entry in the dynamic table. 1364 7.1.3. Never-Indexed Literals 1366 Implementations can also choose to protect sensitive fields by not 1367 compressing them and instead encoding their value as literals. 1369 Refusing to insert a field line into the dynamic table is only 1370 effective if doing so is avoided on all hops. The never-indexed 1371 literal bit (see Section 4.5.4) can be used to signal to 1372 intermediaries that a particular value was intentionally sent as a 1373 literal. 1375 An intermediary MUST NOT re-encode a value that uses a literal 1376 representation with the 'N' bit set with another representation that 1377 would index it. If QPACK is used for re-encoding, a literal 1378 representation with the 'N' bit set MUST be used. If HPACK is used 1379 for re-encoding, the never-indexed literal representation (see 1380 Section 6.2.3 of [RFC7541]) MUST be used. 1382 The choice to mark that a field value should never be indexed depends 1383 on several factors. Since QPACK does not protect against guessing an 1384 entire field value, short or low-entropy values are more readily 1385 recovered by an adversary. Therefore, an encoder might choose not to 1386 index values with low entropy. 1388 An encoder might also choose not to index values for fields that are 1389 considered to be highly valuable or sensitive to recovery, such as 1390 the Cookie or Authorization header fields. 1392 On the contrary, an encoder might prefer indexing values for fields 1393 that have little or no value if they were exposed. For instance, a 1394 User-Agent header field does not commonly vary between requests and 1395 is sent to any server. In that case, confirmation that a particular 1396 User-Agent value has been used provides little value. 1398 Note that these criteria for deciding to use a never-indexed literal 1399 representation will evolve over time as new attacks are discovered. 1401 7.2. Static Huffman Encoding 1403 There is no currently known attack against a static Huffman encoding. 1404 A study has shown that using a static Huffman encoding table created 1405 an information leakage, however this same study concluded that an 1406 attacker could not take advantage of this information leakage to 1407 recover any meaningful amount of information (see [PETAL]). 1409 7.3. Memory Consumption 1411 An attacker can try to cause an endpoint to exhaust its memory. 1412 QPACK is designed to limit both the peak and stable amounts of memory 1413 allocated by an endpoint. 1415 QPACK uses the definition of the maximum size of the dynamic table 1416 and the maximum number of blocking streams to limit the amount of 1417 memory the encoder can cause the decoder to consume. In HTTP/3, 1418 these values are controlled by the decoder through the settings 1419 parameters SETTINGS_QPACK_MAX_TABLE_CAPACITY and 1420 SETTINGS_QPACK_BLOCKED_STREAMS, respectively (see Section 3.2.3 and 1421 Section 2.1.2). The limit on the size of the dynamic table takes 1422 into account the size of the data stored in the dynamic table, plus a 1423 small allowance for overhead. The limit on the number of blocked 1424 streams is only a proxy for the maximum amount of memory required by 1425 the decoder. The actual maximum amount of memory will depend on how 1426 much memory the decoder uses to track each blocked stream. 1428 A decoder can limit the amount of state memory used for the dynamic 1429 table by setting an appropriate value for the maximum size of the 1430 dynamic table. In HTTP/3, this is realized by setting an appropriate 1431 value for the SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter. An 1432 encoder can limit the amount of state memory it uses by choosing a 1433 smaller dynamic table size than the decoder allows and signaling this 1434 to the decoder (see Section 4.3.1). 1436 A decoder can limit the amount of state memory used for blocked 1437 streams by setting an appropriate value for the maximum number of 1438 blocked streams. In HTTP/3, this is realized by setting an 1439 appropriate value for the SETTINGS_QPACK_BLOCKED_STREAMS parameter. 1440 Streams which risk becoming blocked consume no additional state 1441 memory on the encoder. 1443 An encoder allocates memory to track all dynamic table references in 1444 unacknowledged field sections. An implementation can directly limit 1445 the amount of state memory by only using as many references to the 1446 dynamic table as it wishes to track; no signaling to the decoder is 1447 required. However, limiting references to the dynamic table will 1448 reduce compression effectiveness. 1450 The amount of temporary memory consumed by an encoder or decoder can 1451 be limited by processing field lines sequentially. A decoder 1452 implementation does not need to retain a complete list of field lines 1453 while decoding a field section. An encoder implementation does not 1454 need to retain a complete list of field lines while encoding a field 1455 section if it is using a single-pass algorithm. Note that it might 1456 be necessary for an application to retain a complete list of field 1457 lines for other reasons; even if QPACK does not force this to occur, 1458 application constraints might make this necessary. 1460 While the negotiated limit on the dynamic table size accounts for 1461 much of the memory that can be consumed by a QPACK implementation, 1462 data that cannot be immediately sent due to flow control is not 1463 affected by this limit. Implementations should limit the size of 1464 unsent data, especially on the decoder stream where flexibility to 1465 choose what to send is limited. Possible responses to an excess of 1466 unsent data might include limiting the ability of the peer to open 1467 new streams, reading only from the encoder stream, or closing the 1468 connection. 1470 7.4. Implementation Limits 1472 An implementation of QPACK needs to ensure that large values for 1473 integers, long encoding for integers, or long string literals do not 1474 create security weaknesses. 1476 An implementation has to set a limit for the values it accepts for 1477 integers, as well as for the encoded length; see Section 4.1.1. In 1478 the same way, it has to set a limit to the length it accepts for 1479 string literals; see Section 4.1.2. These limits SHOULD be large 1480 enough to process the largest individual field the HTTP 1481 implementation can be configured to accept. 1483 If an implementation encounters a value larger than it is able to 1484 decode, this MUST be treated as a stream error of type 1485 QPACK_DECOMPRESSION_FAILED if on a request stream, or a connection 1486 error of the appropriate type if on the encoder or decoder stream. 1488 8. IANA Considerations 1490 8.1. Settings Registration 1492 This document specifies two settings. The entries in the following 1493 table are registered in the "HTTP/3 Settings" registry established in 1494 [HTTP3]. 1496 +==========================+======+===============+=========+ 1497 | Setting Name | Code | Specification | Default | 1498 +==========================+======+===============+=========+ 1499 | QPACK_MAX_TABLE_CAPACITY | 0x1 | Section 5 | 0 | 1500 +--------------------------+------+---------------+---------+ 1501 | QPACK_BLOCKED_STREAMS | 0x7 | Section 5 | 0 | 1502 +--------------------------+------+---------------+---------+ 1504 Table 1 1506 For fomatting reasons, the setting names here are abbreviated by 1507 removing the 'SETTING_' prefix. 1509 8.2. Stream Type Registration 1511 This document specifies two stream types. The entries in the 1512 following table are registered in the "HTTP/3 Stream Type" registry 1513 established in [HTTP3]. 1515 +======================+======+===============+========+ 1516 | Stream Type | Code | Specification | Sender | 1517 +======================+======+===============+========+ 1518 | QPACK Encoder Stream | 0x02 | Section 4.2 | Both | 1519 +----------------------+------+---------------+--------+ 1520 | QPACK Decoder Stream | 0x03 | Section 4.2 | Both | 1521 +----------------------+------+---------------+--------+ 1523 Table 2 1525 8.3. Error Code Registration 1527 This document specifies three error codes. The entries in the 1528 following table are registered in the "HTTP/3 Error Code" registry 1529 established in [HTTP3]. 1531 +============================+=======+=============+===============+ 1532 | Name | Code | Description | Specification | 1533 +============================+=======+=============+===============+ 1534 | QPACK_DECOMPRESSION_FAILED | 0x200 | Decoding of | Section 6 | 1535 | | | a field | | 1536 | | | section | | 1537 | | | failed | | 1538 +----------------------------+-------+-------------+---------------+ 1539 | QPACK_ENCODER_STREAM_ERROR | 0x201 | Error on | Section 6 | 1540 | | | the encoder | | 1541 | | | stream | | 1542 +----------------------------+-------+-------------+---------------+ 1543 | QPACK_DECODER_STREAM_ERROR | 0x202 | Error on | Section 6 | 1544 | | | the decoder | | 1545 | | | stream | | 1546 +----------------------------+-------+-------------+---------------+ 1548 Table 3 1550 9. References 1552 9.1. Normative References 1554 [HTTP3] Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 1555 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 1556 quic-http-34, 2 February 2021, 1557 . 1559 [QUIC-TRANSPORT] 1560 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 1561 Multiplexed and Secure Transport", Work in Progress, 1562 Internet-Draft, draft-ietf-quic-transport-34, 2 February 1563 2021, . 1566 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1567 Requirement Levels", BCP 14, RFC 2119, 1568 DOI 10.17487/RFC2119, March 1997, 1569 . 1571 [RFC2360] Scott, G., "Guide for Internet Standards Writers", BCP 22, 1572 RFC 2360, DOI 10.17487/RFC2360, June 1998, 1573 . 1575 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 1576 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 1577 . 1579 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1580 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1581 May 2017, . 1583 [SEMANTICS] 1584 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 1585 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1586 httpbis-semantics-14, 12 January 2021, 1587 . 1590 9.2. Informative References 1592 [CRIME] Wikipedia, "CRIME", May 2015, . 1595 [PETAL] Tan, J. and J. Nahata, "PETAL: Preset Encoding 1596 Table Information Leakage", April 2013, 1597 . 1600 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1601 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 1602 . 1604 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1605 DOI 10.17487/RFC6454, December 2011, 1606 . 1608 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1609 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1610 DOI 10.17487/RFC7540, May 2015, 1611 . 1613 [TLS] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1614 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1615 . 1617 Appendix A. Static Table 1619 This table was generated by analyzing actual Internet traffic in 2018 1620 and including the most common header fields, after filtering out some 1621 unsupported and non-standard values. Due to this methodology, some 1622 of the entries may be inconsistent or appear multiple times with 1623 similar but not identical values. The order of the entries is 1624 optimized to encode the most common header fields with the smallest 1625 number of bytes. 1627 +=======+==================================+=======================+ 1628 | Index | Name | Value | 1629 +=======+==================================+=======================+ 1630 | 0 | :authority | | 1631 +-------+----------------------------------+-----------------------+ 1632 | 1 | :path | / | 1633 +-------+----------------------------------+-----------------------+ 1634 | 2 | age | 0 | 1635 +-------+----------------------------------+-----------------------+ 1636 | 3 | content-disposition | | 1637 +-------+----------------------------------+-----------------------+ 1638 | 4 | content-length | 0 | 1639 +-------+----------------------------------+-----------------------+ 1640 | 5 | cookie | | 1641 +-------+----------------------------------+-----------------------+ 1642 | 6 | date | | 1643 +-------+----------------------------------+-----------------------+ 1644 | 7 | etag | | 1645 +-------+----------------------------------+-----------------------+ 1646 | 8 | if-modified-since | | 1647 +-------+----------------------------------+-----------------------+ 1648 | 9 | if-none-match | | 1649 +-------+----------------------------------+-----------------------+ 1650 | 10 | last-modified | | 1651 +-------+----------------------------------+-----------------------+ 1652 | 11 | link | | 1653 +-------+----------------------------------+-----------------------+ 1654 | 12 | location | | 1655 +-------+----------------------------------+-----------------------+ 1656 | 13 | referer | | 1657 +-------+----------------------------------+-----------------------+ 1658 | 14 | set-cookie | | 1659 +-------+----------------------------------+-----------------------+ 1660 | 15 | :method | CONNECT | 1661 +-------+----------------------------------+-----------------------+ 1662 | 16 | :method | DELETE | 1663 +-------+----------------------------------+-----------------------+ 1664 | 17 | :method | GET | 1665 +-------+----------------------------------+-----------------------+ 1666 | 18 | :method | HEAD | 1667 +-------+----------------------------------+-----------------------+ 1668 | 19 | :method | OPTIONS | 1669 +-------+----------------------------------+-----------------------+ 1670 | 20 | :method | POST | 1671 +-------+----------------------------------+-----------------------+ 1672 | 21 | :method | PUT | 1673 +-------+----------------------------------+-----------------------+ 1674 | 22 | :scheme | http | 1675 +-------+----------------------------------+-----------------------+ 1676 | 23 | :scheme | https | 1677 +-------+----------------------------------+-----------------------+ 1678 | 24 | :status | 103 | 1679 +-------+----------------------------------+-----------------------+ 1680 | 25 | :status | 200 | 1681 +-------+----------------------------------+-----------------------+ 1682 | 26 | :status | 304 | 1683 +-------+----------------------------------+-----------------------+ 1684 | 27 | :status | 404 | 1685 +-------+----------------------------------+-----------------------+ 1686 | 28 | :status | 503 | 1687 +-------+----------------------------------+-----------------------+ 1688 | 29 | accept | */* | 1689 +-------+----------------------------------+-----------------------+ 1690 | 30 | accept | application/dns- | 1691 | | | message | 1692 +-------+----------------------------------+-----------------------+ 1693 | 31 | accept-encoding | gzip, deflate, br | 1694 +-------+----------------------------------+-----------------------+ 1695 | 32 | accept-ranges | bytes | 1696 +-------+----------------------------------+-----------------------+ 1697 | 33 | access-control-allow-headers | cache-control | 1698 +-------+----------------------------------+-----------------------+ 1699 | 34 | access-control-allow-headers | content-type | 1700 +-------+----------------------------------+-----------------------+ 1701 | 35 | access-control-allow-origin | * | 1702 +-------+----------------------------------+-----------------------+ 1703 | 36 | cache-control | max-age=0 | 1704 +-------+----------------------------------+-----------------------+ 1705 | 37 | cache-control | max-age=2592000 | 1706 +-------+----------------------------------+-----------------------+ 1707 | 38 | cache-control | max-age=604800 | 1708 +-------+----------------------------------+-----------------------+ 1709 | 39 | cache-control | no-cache | 1710 +-------+----------------------------------+-----------------------+ 1711 | 40 | cache-control | no-store | 1712 +-------+----------------------------------+-----------------------+ 1713 | 41 | cache-control | public, max- | 1714 | | | age=31536000 | 1715 +-------+----------------------------------+-----------------------+ 1716 | 42 | content-encoding | br | 1717 +-------+----------------------------------+-----------------------+ 1718 | 43 | content-encoding | gzip | 1719 +-------+----------------------------------+-----------------------+ 1720 | 44 | content-type | application/dns- | 1721 | | | message | 1722 +-------+----------------------------------+-----------------------+ 1723 | 45 | content-type | application/ | 1724 | | | javascript | 1725 +-------+----------------------------------+-----------------------+ 1726 | 46 | content-type | application/json | 1727 +-------+----------------------------------+-----------------------+ 1728 | 47 | content-type | application/x-www- | 1729 | | | form-urlencoded | 1730 +-------+----------------------------------+-----------------------+ 1731 | 48 | content-type | image/gif | 1732 +-------+----------------------------------+-----------------------+ 1733 | 49 | content-type | image/jpeg | 1734 +-------+----------------------------------+-----------------------+ 1735 | 50 | content-type | image/png | 1736 +-------+----------------------------------+-----------------------+ 1737 | 51 | content-type | text/css | 1738 +-------+----------------------------------+-----------------------+ 1739 | 52 | content-type | text/html; | 1740 | | | charset=utf-8 | 1741 +-------+----------------------------------+-----------------------+ 1742 | 53 | content-type | text/plain | 1743 +-------+----------------------------------+-----------------------+ 1744 | 54 | content-type | text/ | 1745 | | | plain;charset=utf-8 | 1746 +-------+----------------------------------+-----------------------+ 1747 | 55 | range | bytes=0- | 1748 +-------+----------------------------------+-----------------------+ 1749 | 56 | strict-transport-security | max-age=31536000 | 1750 +-------+----------------------------------+-----------------------+ 1751 | 57 | strict-transport-security | max-age=31536000; | 1752 | | | includesubdomains | 1753 +-------+----------------------------------+-----------------------+ 1754 | 58 | strict-transport-security | max-age=31536000; | 1755 | | | includesubdomains; | 1756 | | | preload | 1757 +-------+----------------------------------+-----------------------+ 1758 | 59 | vary | accept-encoding | 1759 +-------+----------------------------------+-----------------------+ 1760 | 60 | vary | origin | 1761 +-------+----------------------------------+-----------------------+ 1762 | 61 | x-content-type-options | nosniff | 1763 +-------+----------------------------------+-----------------------+ 1764 | 62 | x-xss-protection | 1; mode=block | 1765 +-------+----------------------------------+-----------------------+ 1766 | 63 | :status | 100 | 1767 +-------+----------------------------------+-----------------------+ 1768 | 64 | :status | 204 | 1769 +-------+----------------------------------+-----------------------+ 1770 | 65 | :status | 206 | 1771 +-------+----------------------------------+-----------------------+ 1772 | 66 | :status | 302 | 1773 +-------+----------------------------------+-----------------------+ 1774 | 67 | :status | 400 | 1775 +-------+----------------------------------+-----------------------+ 1776 | 68 | :status | 403 | 1777 +-------+----------------------------------+-----------------------+ 1778 | 69 | :status | 421 | 1779 +-------+----------------------------------+-----------------------+ 1780 | 70 | :status | 425 | 1781 +-------+----------------------------------+-----------------------+ 1782 | 71 | :status | 500 | 1783 +-------+----------------------------------+-----------------------+ 1784 | 72 | accept-language | | 1785 +-------+----------------------------------+-----------------------+ 1786 | 73 | access-control-allow-credentials | FALSE | 1787 +-------+----------------------------------+-----------------------+ 1788 | 74 | access-control-allow-credentials | TRUE | 1789 +-------+----------------------------------+-----------------------+ 1790 | 75 | access-control-allow-headers | * | 1791 +-------+----------------------------------+-----------------------+ 1792 | 76 | access-control-allow-methods | get | 1793 +-------+----------------------------------+-----------------------+ 1794 | 77 | access-control-allow-methods | get, post, options | 1795 +-------+----------------------------------+-----------------------+ 1796 | 78 | access-control-allow-methods | options | 1797 +-------+----------------------------------+-----------------------+ 1798 | 79 | access-control-expose-headers | content-length | 1799 +-------+----------------------------------+-----------------------+ 1800 | 80 | access-control-request-headers | content-type | 1801 +-------+----------------------------------+-----------------------+ 1802 | 81 | access-control-request-method | get | 1803 +-------+----------------------------------+-----------------------+ 1804 | 82 | access-control-request-method | post | 1805 +-------+----------------------------------+-----------------------+ 1806 | 83 | alt-svc | clear | 1807 +-------+----------------------------------+-----------------------+ 1808 | 84 | authorization | | 1809 +-------+----------------------------------+-----------------------+ 1810 | 85 | content-security-policy | script-src 'none'; | 1811 | | | object-src 'none'; | 1812 | | | base-uri 'none' | 1813 +-------+----------------------------------+-----------------------+ 1814 | 86 | early-data | 1 | 1815 +-------+----------------------------------+-----------------------+ 1816 | 87 | expect-ct | | 1817 +-------+----------------------------------+-----------------------+ 1818 | 88 | forwarded | | 1819 +-------+----------------------------------+-----------------------+ 1820 | 89 | if-range | | 1821 +-------+----------------------------------+-----------------------+ 1822 | 90 | origin | | 1823 +-------+----------------------------------+-----------------------+ 1824 | 91 | purpose | prefetch | 1825 +-------+----------------------------------+-----------------------+ 1826 | 92 | server | | 1827 +-------+----------------------------------+-----------------------+ 1828 | 93 | timing-allow-origin | * | 1829 +-------+----------------------------------+-----------------------+ 1830 | 94 | upgrade-insecure-requests | 1 | 1831 +-------+----------------------------------+-----------------------+ 1832 | 95 | user-agent | | 1833 +-------+----------------------------------+-----------------------+ 1834 | 96 | x-forwarded-for | | 1835 +-------+----------------------------------+-----------------------+ 1836 | 97 | x-frame-options | deny | 1837 +-------+----------------------------------+-----------------------+ 1838 | 98 | x-frame-options | sameorigin | 1839 +-------+----------------------------------+-----------------------+ 1841 Table 4 1843 Any line breaks that appear within field names or values are due to 1844 formatting. 1846 Appendix B. Encoding and Decoding Examples 1848 The following examples represent a series of exchanges between an 1849 encoder and a decoder. The exchanges are designed to exercise most 1850 QPACK instructions, and highlight potentially common patterns and 1851 their impact on dynamic table state. The encoder sends three encoded 1852 field sections containing one field line each, as well as two 1853 speculative inserts that are not referenced. 1855 The state of the encoder's dynamic table is shown, along with its 1856 current size. Each entry is shown with the Absolute Index of the 1857 entry (Abs), the current number of outstanding encoded field sections 1858 with references to that entry (Ref), along with the name and value. 1859 Entries above the 'acknowledged' line have been acknowledged by the 1860 decoder. 1862 B.1. Literal Field Line With Name Reference 1864 The encoder sends an encoded field section containing a literal 1865 representation of a field with a static name reference. 1867 Data | Interpretation 1868 | Encoder's Dynamic Table 1870 Stream: 0 1871 0000 | Required Insert Count = 0, Base = 0 1872 510b 2f69 6e64 6578 | Literal Field Line with Name Reference 1873 2e68 746d 6c | Static Table, Index=1 1874 | (:path=/index.html) 1876 Abs Ref Name Value 1877 ^-- acknowledged --^ 1878 Size=0 1880 B.2. Dynamic Table 1882 The encoder sets the dynamic table capacity, inserts a header with a 1883 dynamic name reference, then sends a potentially blocking, encoded 1884 field section referencing this new entry. The decoder acknowledges 1885 processing the encoded field section, which implicitly acknowledges 1886 all dynamic table insertions up to the Required Insert Count. 1888 Stream: Encoder 1889 3fbd01 | Set Dynamic Table Capacity=220 1890 c00f 7777 772e 6578 | Insert With Name Reference 1891 616d 706c 652e 636f | Static Table, Index=0 1892 6d | (:authority=www.example.com) 1893 c10c 2f73 616d 706c | Insert With Name Reference 1894 652f 7061 7468 | Static Table, Index=1 1895 | (:path=/sample/path) 1897 Abs Ref Name Value 1898 ^-- acknowledged --^ 1899 0 0 :authority www.example.com 1900 1 0 :path /sample/path 1901 Size=106 1903 Stream: 4 1904 0381 | Required Insert Count = 2, Base = 0 1905 10 | Indexed Field Line With Post-Base Index 1906 | Absolute Index = Base(0) + Index(0) = 0 1907 | (:authority=www.example.com) 1908 11 | Indexed Field Line With Post-Base Index 1909 | Absolute Index = Base(0) + Index(1) = 1 1910 | (:path=/sample/path) 1912 Abs Ref Name Value 1913 ^-- acknowledged --^ 1914 0 1 :authority www.example.com 1915 1 1 :path /sample/path 1916 Size=106 1918 Stream: Decoder 1919 84 | Section Acknowledgment (stream=4) 1921 Abs Ref Name Value 1922 0 0 :authority www.example.com 1923 1 0 :path /sample/path 1924 ^-- acknowledged --^ 1925 Size=106 1927 B.3. Speculative Insert 1929 The encoder inserts a header into the dynamic table with a literal 1930 name. The decoder acknowledges receipt of the entry. The encoder 1931 does not send any encoded field sections. 1933 Stream: Encoder 1934 4a63 7573 746f 6d2d | Insert With Literal Name 1935 6b65 790c 6375 7374 | (custom-key=custom-value) 1936 6f6d 2d76 616c 7565 | 1938 Abs Ref Name Value 1939 0 0 :authority www.example.com 1940 1 0 :path /sample/path 1941 ^-- acknowledged --^ 1942 2 0 custom-key custom-value 1943 Size=160 1945 Stream: Decoder 1946 01 | Insert Count Increment (1) 1948 Abs Ref Name Value 1949 0 0 :authority www.example.com 1950 1 0 :path /sample/path 1951 2 0 custom-key custom-value 1952 ^-- acknowledged --^ 1953 Size=160 1955 B.4. Duplicate Instruction, Stream Cancellation 1957 The encoder duplicates an existing entry in the dynamic table, then 1958 sends an encoded field section referencing the dynamic table entries 1959 including the duplicated entry. The packet containing the encoder 1960 stream data is delayed. Before the packet arrives, the decoder 1961 cancels the stream and notifies the encoder that the encoded field 1962 section was not processed. 1964 Stream: Encoder 1965 02 | Duplicate (Relative Index = 2) 1966 | Absolute Index = 1967 | Insert Count(4) - Index(2) - 1 = 1 1969 Abs Ref Name Value 1970 0 0 :authority www.example.com 1971 1 0 :path /sample/path 1972 2 0 custom-key custom-value 1973 ^-- acknowledged --^ 1974 3 0 :authority www.example.com 1975 Size=217 1977 Stream: 8 1978 0500 | Required Insert Count = 4, Base = 4 1979 80 | Indexed Field Line, Dynamic Table 1980 | Absolute Index = Base(4) - Index(0) - 1 = 3 1981 | (:authority=www.example.com) 1982 c1 | Indexed Field Line, Static Table Index = 1 1983 | (:path=/) 1984 81 | Indexed Field Line, Dynamic Table 1985 | Absolute Index = Base(4) - Index(1) - 1 = 2 1986 | (custom-key=custom-value) 1988 Abs Ref Name Value 1989 0 0 :authority www.example.com 1990 1 0 :path /sample/path 1991 2 1 custom-key custom-value 1992 ^-- acknowledged --^ 1993 3 1 :authority www.example.com 1994 Size=217 1996 Stream: Decoder 1997 48 | Stream Cancellation (Stream=8) 1999 Abs Ref Name Value 2000 0 0 :authority www.example.com 2001 1 0 :path /sample/path 2002 2 0 custom-key custom-value 2003 ^-- acknowledged --^ 2004 4 0 :authority www.example.com 2005 Size=217 2007 B.5. Dynamic Table Insert, Eviction 2009 The encoder inserts another header into the dynamic table, which 2010 evicts the oldest entry. The encoder does not send any encoded field 2011 sections. 2013 Stream: Encoder 2014 810d 6375 7374 6f6d | Insert With Name Reference 2015 2d76 616c 7565 32 | Dynamic Table, Relative Index = 1 2016 | Absolute Index = 2017 | Insert Count(4) - Index(1) - 1 = 2 2018 | (custom-key=custom-value2) 2020 Abs Ref Name Value 2021 1 0 :path /sample/path 2022 2 0 custom-key custom-value 2023 ^-- acknowledged --^ 2024 3 0 :authority www.example.com 2025 4 0 custom-key custom-value2 2026 Size=215 2028 Appendix C. Sample One Pass Encoding Algorithm 2030 Pseudo-code for single pass encoding, excluding handling of 2031 duplicates, non-blocking mode, available encoder stream flow control 2032 and reference tracking. 2034 # Helper functions: 2035 # ==== 2036 # Encode an interger with the specified prefix and length 2037 encodeInteger(buffer, prefix, value, prefixLength) 2039 # Encode a dynamic table insert instruction with optional static 2040 # or dynamic name index (but not both) 2041 encodeInsert(buffer, staticNameIndex, dynamicNameIndex, fieldLine) 2043 # Encode a static index reference 2044 encodeStaticIndexReference(buffer, staticIndex) 2046 # Encode a dynamic index reference relative to base 2047 encodeDynamicIndexReference(buffer, dynamicIndex, base) 2049 # Encode a literal with an optional static name index 2050 encodeLiteral(buffer, staticNameIndex, fieldLine) 2052 # Encode a literal with a dynamic name index relative to base 2053 encodeDynamicLiteral(buffer, dynamicNameIndex, base, fieldLine) 2055 # Encoding Algorithm 2056 # ==== 2057 base = dynamicTable.getInsertCount() 2058 requiredInsertCount = 0 2059 for line in fieldLines: 2060 staticIndex = staticTable.findIndex(line) 2061 if staticIndex is not None: 2062 encodeStaticIndexReference(streamBuffer, staticIndex) 2063 continue 2065 dynamicIndex = dynamicTable.findIndex(line) 2066 if dynamicIndex is None: 2067 # No matching entry. Either insert+index or encode literal 2068 staticNameIndex = staticTable.findName(line.name) 2069 if staticNameIndex is None: 2070 dynamicNameIndex = dynamicTable.findName(line.name) 2072 if shouldIndex(line) and dynamicTable.canIndex(line): 2073 encodeInsert(encoderBuffer, staticNameIndex, 2074 dynamicNameIndex, line) 2075 dynamicIndex = dynamicTable.add(line) 2077 if dynamicIndex is None: 2078 # Could not index it, literal 2079 if dynamicNameIndex is not None: 2080 # Encode literal with dynamic name, possibly above base 2081 encodeDynamicLiteral(streamBuffer, dynamicNameIndex, 2082 base, line) 2083 requiredInsertCount = max(requiredInsertCount, 2084 dynamicNameIndex) 2085 else: 2086 # Encodes a literal with a static name or literal name 2087 encodeLiteral(streamBuffer, staticNameIndex, line) 2088 else: 2089 # Dynamic index reference 2090 assert(dynamicIndex is not None) 2091 requiredInsertCount = max(requiredInsertCount, dynamicIndex) 2092 # Encode dynamicIndex, possibly above base 2093 encodeDynamicIndexReference(streamBuffer, dynamicIndex, base) 2095 # encode the prefix 2096 if requiredInsertCount == 0: 2097 encodeInteger(prefixBuffer, 0x00, 0, 8) 2098 encodeInteger(prefixBuffer, 0x00, 0, 7) 2099 else: 2100 wireRIC = ( 2101 requiredInsertCount 2102 % (2 * getMaxEntries(maxTableCapacity)) 2103 ) + 1; 2104 encodeInteger(prefixBuffer, 0x00, wireRIC, 8) 2105 if base >= requiredInsertCount: 2106 encodeInteger(prefixBuffer, 0x00, 2107 base - requiredInsertCount, 7) 2108 else: 2110 encodeInteger(prefixBuffer, 0x80, 2111 requiredInsertCount - base - 1, 7) 2113 return encoderBuffer, prefixBuffer + streamBuffer 2115 Appendix D. Change Log 2117 *RFC Editor's Note:* Please remove this section prior to 2118 publication of a final version of this document. 2120 D.1. Since draft-ietf-quic-qpack-19 2122 Editorial changes only 2124 D.2. Since draft-ietf-quic-qpack-18 2126 Editorial changes only 2128 D.3. Since draft-ietf-quic-qpack-17 2130 Editorial changes only 2132 D.4. Since draft-ietf-quic-qpack-16 2134 Editorial changes only 2136 D.5. Since draft-ietf-quic-qpack-15 2138 No changes 2140 D.6. Since draft-ietf-quic-qpack-14 2142 Added security considerations 2144 D.7. Since draft-ietf-quic-qpack-13 2146 No changes 2148 D.8. Since draft-ietf-quic-qpack-12 2150 Editorial changes only 2152 D.9. Since draft-ietf-quic-qpack-11 2154 Editorial changes only 2156 D.10. Since draft-ietf-quic-qpack-10 2158 Editorial changes only 2160 D.11. Since draft-ietf-quic-qpack-09 2162 * Decoders MUST emit Header Acknowledgments (#2939) 2164 * Updated error code for multiple encoder or decoder streams (#2970) 2166 * Added explicit defaults for new SETTINGS (#2974) 2168 D.12. Since draft-ietf-quic-qpack-08 2170 * Endpoints are permitted to create encoder and decoder streams even 2171 if they can't use them (#2100, #2529) 2173 * Maximum values for settings removed (#2766, #2767) 2175 D.13. Since draft-ietf-quic-qpack-06 2177 * Clarify initial dynamic table capacity maximums (#2276, #2330, 2178 #2330) 2180 D.14. Since draft-ietf-quic-qpack-05 2182 * Introduced the terms dynamic table capacity and maximum dynamic 2183 table capacity. 2185 * Renamed SETTINGS_HEADER_TABLE_SIZE to 2186 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 2188 D.15. Since draft-ietf-quic-qpack-04 2190 * Changed calculation of Delta Base Index to avoid an illegal value 2191 (#2002, #2005) 2193 D.16. Since draft-ietf-quic-qpack-03 2195 * Change HTTP settings defaults (#2038) 2197 * Substantial editorial reorganization 2199 D.17. Since draft-ietf-quic-qpack-02 2201 * Largest Reference encoded modulo MaxEntries (#1763) 2203 * New Static Table (#1355) 2204 * Table Size Update with Insert Count=0 is a connection error 2205 (#1762) 2207 * Stream Cancellations are optional when 2208 SETTINGS_HEADER_TABLE_SIZE=0 (#1761) 2210 * Implementations must handle 62 bit integers (#1760) 2212 * Different error types for each QPACK stream, other changes to 2213 error handling (#1726) 2215 * Preserve header field order (#1725) 2217 * Initial table size is the maximum permitted when table is first 2218 usable (#1642) 2220 D.18. Since draft-ietf-quic-qpack-01 2222 * Only header blocks that reference the dynamic table are 2223 acknowledged (#1603, #1605) 2225 D.19. Since draft-ietf-quic-qpack-00 2227 * Renumbered instructions for consistency (#1471, #1472) 2229 * Decoder is allowed to validate largest reference (#1404, #1469) 2231 * Header block acknowledgments also acknowledge the associated 2232 largest reference (#1370, #1400) 2234 * Added an acknowledgment for unread streams (#1371, #1400) 2236 * Removed framing from encoder stream (#1361,#1467) 2238 * Control streams use typed unidirectional streams rather than fixed 2239 stream IDs (#910,#1359) 2241 D.20. Since draft-ietf-quic-qcram-00 2243 * Separate instruction sets for table updates and header blocks 2244 (#1235, #1142, #1141) 2246 * Reworked indexing scheme (#1176, #1145, #1136, #1130, #1125, 2247 #1314) 2249 * Added mechanisms that support one-pass encoding (#1138, #1320) 2250 * Added a setting to control the number of blocked decoders (#238, 2251 #1140, #1143) 2253 * Moved table updates and acknowledgments to dedicated streams 2254 (#1121, #1122, #1238) 2256 Acknowledgments 2258 The IETF QUIC Working Group received an enormous amount of support 2259 from many people. 2261 The compression design team did substantial work exploring the 2262 problem space and influencing the initial draft. The contributions 2263 of design team members Roberto Peon, Martin Thomson, and Dmitri 2264 Tikhonov are gratefully acknowledged. 2266 The following people also provided substantial contributions to this 2267 document: 2269 * Bence Beky 2271 * Alessandro Ghedini 2273 * Ryan Hamilton 2275 * Robin Marx 2277 * Patrick McManus 2279 * 奥 一穂 (Kazuho Oku) 2281 * Lucas Pardue 2283 * Biren Roy 2285 * Ian Swett 2287 This draft draws heavily on the text of [RFC7541]. The indirect 2288 input of those authors is also gratefully acknowledged. 2290 Buck's contribution was supported by Google during his employment 2291 there. 2293 A portion of Mike's contribution was supported by Microsoft during 2294 his employment there. 2296 Authors' Addresses 2297 Charles 'Buck' Krasic 2298 Netflix 2300 Email: ckrasic@netflix.com 2302 Mike Bishop 2303 Akamai Technologies 2305 Email: mbishop@evequefou.be 2307 Alan Frindell (editor) 2308 Facebook 2310 Email: afrind@fb.com