idnits 2.17.1 draft-ietf-quic-qpack-18.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 1866 has weird spacing: '...thority www.e...' == Line 1881 has weird spacing: '...thority www.e...' == Line 1889 has weird spacing: '...thority www.e...' == Line 1906 has weird spacing: '...thority www.e...' == Line 1909 has weird spacing: '...tom-key custo...' == (14 more instances...) -- The document date (25 September 2020) is 1302 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: A later version (-34) exists of draft-ietf-quic-http-31 == Outdated reference: A later version (-34) exists of draft-ietf-quic-transport-31 == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-11 -- Possible downref: Normative reference to a draft: ref. 'SEMANTICS' -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 0 errors (**), 0 flaws (~~), 11 warnings (==), 4 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: 29 March 2021 Akamai Technologies 6 A. Frindell, Ed. 7 Facebook 8 25 September 2020 10 QPACK: Header Compression for HTTP/3 11 draft-ietf-quic-qpack-18 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 29 March 2021. 48 Copyright Notice 50 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . . . . 13 84 3.2.5. Relative Indexing . . . . . . . . . . . . . . . . . . 14 85 3.2.6. Post-Base Indexing . . . . . . . . . . . . . . . . . 15 86 4. Wire Format . . . . . . . . . . . . . . . . . . . . . . . . . 15 87 4.1. Primitives . . . . . . . . . . . . . . . . . . . . . . . 15 88 4.1.1. Prefixed Integers . . . . . . . . . . . . . . . . . . 15 89 4.1.2. String Literals . . . . . . . . . . . . . . . . . . . 15 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 Acknowledgement . . . . . . . . . . . . . . . 19 99 4.4.2. Stream Cancellation . . . . . . . . . . . . . . . . . 20 100 4.4.3. Insert Count Increment . . . . . . . . . . . . . . . 20 101 4.5. Field Line Representations . . . . . . . . . . . . . . . 20 102 4.5.1. Encoded Field Section Prefix . . . . . . . . . . . . 21 103 4.5.2. Indexed Field Line . . . . . . . . . . . . . . . . . 23 104 4.5.3. Indexed Field Line With Post-Base Index . . . . . . . 24 105 4.5.4. Literal Field Line With Name Reference . . . . . . . 24 106 4.5.5. Literal Field Line With Post-Base Name Reference . . 25 107 4.5.6. Literal Field Line With Literal Name . . . . . . . . 25 108 5. Configuration . . . . . . . . . . . . . . . . . . . . . . . . 26 109 6. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 26 110 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 111 7.1. Probing Dynamic Table State . . . . . . . . . . . . . . . 27 112 7.2. Applicability to QPACK and HTTP . . . . . . . . . . . . . 28 113 7.3. Mitigation . . . . . . . . . . . . . . . . . . . . . . . 28 114 7.4. Never-Indexed Literals . . . . . . . . . . . . . . . . . 29 115 7.5. Static Huffman Encoding . . . . . . . . . . . . . . . . . 30 116 7.6. Memory Consumption . . . . . . . . . . . . . . . . . . . 30 117 7.7. Implementation Limits . . . . . . . . . . . . . . . . . . 31 118 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 119 8.1. Settings Registration . . . . . . . . . . . . . . . . . . 32 120 8.2. Stream Type Registration . . . . . . . . . . . . . . . . 32 121 8.3. Error Code Registration . . . . . . . . . . . . . . . . . 32 122 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 123 9.1. Normative References . . . . . . . . . . . . . . . . . . 33 124 9.2. Informative References . . . . . . . . . . . . . . . . . 34 125 Appendix A. Static Table . . . . . . . . . . . . . . . . . . . . 34 126 Appendix B. Encoding and Decoding Examples . . . . . . . . . . . 39 127 B.1. Literal Field Line With Name Reference . . . . . . . . . 39 128 B.2. Dynamic Table . . . . . . . . . . . . . . . . . . . . . . 40 129 B.3. Speculative Insert . . . . . . . . . . . . . . . . . . . 41 130 B.4. Duplicate Instruction, Stream Cancellation . . . . . . . 42 131 B.5. Dynamic Table Insert, Eviction . . . . . . . . . . . . . 43 132 Appendix C. Sample One Pass Encoding Algorithm . . . . . . . . . 44 133 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 45 134 D.1. Since draft-ietf-quic-qpack-17 . . . . . . . . . . . . . 45 135 D.2. Since draft-ietf-quic-qpack-16 . . . . . . . . . . . . . 45 136 D.3. Since draft-ietf-quic-qpack-15 . . . . . . . . . . . . . 45 137 D.4. Since draft-ietf-quic-qpack-14 . . . . . . . . . . . . . 45 138 D.5. Since draft-ietf-quic-qpack-13 . . . . . . . . . . . . . 46 139 D.6. Since draft-ietf-quic-qpack-12 . . . . . . . . . . . . . 46 140 D.7. Since draft-ietf-quic-qpack-11 . . . . . . . . . . . . . 46 141 D.8. Since draft-ietf-quic-qpack-10 . . . . . . . . . . . . . 46 142 D.9. Since draft-ietf-quic-qpack-09 . . . . . . . . . . . . . 46 143 D.10. Since draft-ietf-quic-qpack-08 . . . . . . . . . . . . . 46 144 D.11. Since draft-ietf-quic-qpack-06 . . . . . . . . . . . . . 46 145 D.12. Since draft-ietf-quic-qpack-05 . . . . . . . . . . . . . 46 146 D.13. Since draft-ietf-quic-qpack-04 . . . . . . . . . . . . . 46 147 D.14. Since draft-ietf-quic-qpack-03 . . . . . . . . . . . . . 47 148 D.15. Since draft-ietf-quic-qpack-02 . . . . . . . . . . . . . 47 149 D.16. Since draft-ietf-quic-qpack-01 . . . . . . . . . . . . . 47 150 D.17. Since draft-ietf-quic-qpack-00 . . . . . . . . . . . . . 47 151 D.18. Since draft-ietf-quic-qcram-00 . . . . . . . . . . . . . 48 152 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 48 153 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49 155 1. Introduction 157 The QUIC transport protocol ([QUIC-TRANSPORT]) is designed to support 158 HTTP semantics, and its design subsumes many of the features of 159 HTTP/2 ([RFC7540]). HTTP/2 uses HPACK ([RFC7541]) for compression of 160 the header and trailer sections. If HPACK were used for HTTP/3 161 ([HTTP3]), it would induce head-of-line blocking for field sections 162 due to built-in assumptions of a total ordering across frames on all 163 streams. 165 QPACK reuses core concepts from HPACK, but is redesigned to allow 166 correctness in the presence of out-of-order delivery, with 167 flexibility for implementations to balance between resilience against 168 head-of-line blocking and optimal compression ratio. The design 169 goals are to closely approach the compression ratio of HPACK with 170 substantially less head-of-line blocking under the same loss 171 conditions. 173 1.1. Conventions and Definitions 175 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 176 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 177 "OPTIONAL" in this document are to be interpreted as described in 178 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 179 capitals, as shown here. 181 Definitions of terms that are used in this document: 183 HTTP fields: Metadata sent as part of an HTTP message. The term 184 encompasses both header and trailer fields. Colloquially, the 185 term "headers" has often been used to refer to HTTP header fields 186 and trailer fields; this document uses "fields" for generality. 188 HTTP field line: A name-value pair sent as part of an HTTP field 189 section. See Section 5 of [SEMANTICS]. 191 HTTP field value: Data associated with a field name, composed from 192 all field line values with that field name in that section, 193 concatenated together and separated with commas. 195 Field section: An ordered collection of HTTP field lines associated 196 with an HTTP message. A field section can contain multiple field 197 lines with the same name. It can also contain duplicate field 198 lines. An HTTP message can include both header field and trailer 199 field sections. 201 Representation: An instruction that represents a field line, 202 possibly by reference to the dynamic and static tables. 204 Encoder: An implementation that encodes field sections. 206 Decoder: An implementation that decodes encoded field sections. 208 Absolute Index: A unique index for each entry in the dynamic table. 210 Base: A reference point for relative and post-base indices. 211 Representations that reference dynamic table entries are relative 212 to a Base. 214 Insert Count: The total number of entries inserted in the dynamic 215 table. 217 QPACK is a name, not an acronym. 219 1.2. Notational Conventions 221 Diagrams use the format described in Section 3.1 of [RFC2360], with 222 the following additional conventions: 224 x (A) Indicates that x is A bits long 226 x (A+) Indicates that x uses the prefixed integer encoding defined 227 in Section 4.1.1, beginning with an A-bit prefix. 229 x ... Indicates that x is variable-length and extends to the end of 230 the region. 232 2. Compression Process Overview 234 Like HPACK, QPACK uses two tables for associating field lines 235 ("headers") to indices. The static table (Section 3.1) is predefined 236 and contains common header field lines (some of them with an empty 237 value). The dynamic table (Section 3.2) is built up over the course 238 of the connection and can be used by the encoder to index both header 239 and trailer field lines in the encoded field sections. 241 QPACK defines unidirectional streams for sending instructions from 242 encoder to decoder and vice versa. 244 2.1. Encoder 246 An encoder converts a header or trailer field section into a series 247 of representations by emitting either an indexed or a literal 248 representation for each field line in the list; see Section 4.5. 249 Indexed representations achieve high compression by replacing the 250 literal name and possibly the value with an index to either the 251 static or dynamic table. References to the static table and literal 252 representations do not require any dynamic state and never risk head- 253 of-line blocking. References to the dynamic table risk head-of-line 254 blocking if the encoder has not received an acknowledgement 255 indicating the entry is available at the decoder. 257 An encoder MAY insert any entry in the dynamic table it chooses; it 258 is not limited to field lines it is compressing. 260 QPACK preserves the ordering of field lines within each field 261 section. An encoder MUST emit field representations in the order 262 they appear in the input field section. 264 QPACK is designed to contain the more complex state tracking to the 265 encoder, while the decoder is relatively simple. 267 2.1.1. Limits on Dynamic Table Insertions 269 Inserting entries into the dynamic table might not be possible if the 270 table contains entries that cannot be evicted. 272 A dynamic table entry cannot be evicted immediately after insertion, 273 even if it has never been referenced. Once the insertion of a 274 dynamic table entry has been acknowledged and there are no 275 outstanding references to the entry in unacknowledged 276 representations, the entry becomes evictable. Note that references 277 on the encoder stream never preclude the eviction of an entry, 278 because those references are guaranteed to be processed before the 279 instruction evicting the entry. 281 If the dynamic table does not contain enough room for a new entry 282 without evicting other entries, and the entries that would be evicted 283 are not evictable, the encoder MUST NOT insert that entry into the 284 dynamic table (including duplicates of existing entries). In order 285 to avoid this, an encoder that uses the dynamic table has to keep 286 track of each dynamic table entry referenced by each field section 287 until those representations are acknowledged by the decoder; see 288 Section 4.4.1. 290 2.1.1.1. Avoiding Prohibited Insertions 292 To ensure that the encoder is not prevented from adding new entries, 293 the encoder can avoid referencing entries that are close to eviction. 294 Rather than reference such an entry, the encoder can emit a Duplicate 295 instruction (Section 4.3.4), and reference the duplicate instead. 297 Determining which entries are too close to eviction to reference is 298 an encoder preference. One heuristic is to target a fixed amount of 299 available space in the dynamic table: either unused space or space 300 that can be reclaimed by evicting non-blocking entries. To achieve 301 this, the encoder can maintain a draining index, which is the 302 smallest absolute index (Section 3.2.4) in the dynamic table that it 303 will emit a reference for. As new entries are inserted, the encoder 304 increases the draining index to maintain the section of the table 305 that it will not reference. If the encoder does not create new 306 references to entries with an absolute index lower than the draining 307 index, the number of unacknowledged references to those entries will 308 eventually become zero, allowing them to be evicted. 310 +--------+---------------------------------+----------+ 311 | Unused | Referenceable | Draining | 312 | Space | Entries | Entries | 313 +--------+---------------------------------+----------+ 314 ^ ^ ^ 315 | | | 316 Insertion Point Draining Index Dropping 317 Point 319 Figure 1: Draining Dynamic Table Entries 321 2.1.2. Blocked Streams 323 Because QUIC does not guarantee order between data on different 324 streams, a decoder might encounter a representation that references a 325 dynamic table entry that it has not yet received. 327 Each encoded field section contains a Required Insert Count 328 (Section 4.5.1), the lowest possible value for the Insert Count with 329 which the field section can be decoded. For a field section encoded 330 using references to the dynamic table, the Required Insert Count is 331 one larger than the largest absolute index of all referenced dynamic 332 table entries. For a field section encoded with no references to the 333 dynamic table, the Required Insert Count is zero. 335 When the decoder receives an encoded field section with a Required 336 Insert Count greater than its own Insert Count, the stream cannot be 337 processed immediately, and is considered "blocked"; see 338 Section 2.2.1. 340 The decoder specifies an upper bound on the number of streams that 341 can be blocked using the SETTINGS_QPACK_BLOCKED_STREAMS setting; see 342 Section 5. An encoder MUST limit the number of streams that could 343 become blocked to the value of SETTINGS_QPACK_BLOCKED_STREAMS at all 344 times. If a decoder encounters more blocked streams than it promised 345 to support, it MUST treat this as a connection error of type 346 QPACK_DECOMPRESSION_FAILED. 348 Note that the decoder might not become blocked on every stream that 349 risks becoming blocked. 351 An encoder can decide whether to risk having a stream become blocked. 352 If permitted by the value of SETTINGS_QPACK_BLOCKED_STREAMS, 353 compression efficiency can often be improved by referencing dynamic 354 table entries that are still in transit, but if there is loss or 355 reordering the stream can become blocked at the decoder. An encoder 356 can avoid the risk of blocking by only referencing dynamic table 357 entries that have been acknowledged, but this could mean using 358 literals. Since literals make the encoded field section larger, this 359 can result in the encoder becoming blocked on congestion or flow 360 control limits. 362 2.1.3. Avoiding Flow Control Deadlocks 364 Writing instructions on streams that are limited by flow control can 365 produce deadlocks. 367 A decoder might stop issuing flow control credit on the stream that 368 carries an encoded field section until the necessary updates are 369 received on the encoder stream. If the granting of flow control 370 credit on the encoder stream (or the connection as a whole) depends 371 on the consumption and release of data on the stream carrying the 372 encoded field section, a deadlock might result. 374 More generally, a stream containing a large instruction can become 375 deadlocked if the decoder withholds flow control credit until the 376 instruction is completely received. 378 To avoid these deadlocks, an encoder SHOULD avoid writing an 379 instruction unless sufficient stream and connection flow control 380 credit is available for the entire instruction. 382 2.1.4. Known Received Count 384 The Known Received Count is the total number of dynamic table 385 insertions and duplications acknowledged by the decoder. The encoder 386 tracks the Known Received Count in order to identify which dynamic 387 table entries can be referenced without potentially blocking a 388 stream. The decoder tracks the Known Received Count in order to be 389 able to send Insert Count Increment instructions. 391 A Section Acknowledgement instruction (Section 4.4.1) implies that 392 the decoder has received all dynamic table state necessary to decode 393 the field section. If the Required Insert Count of the acknowledged 394 field section is greater than the current Known Received Count, Known 395 Received Count is updated to the value of the Required Insert Count. 397 An Insert Count Increment instruction (Section 4.4.3) increases the 398 Known Received Count by its Increment parameter. See Section 2.2.2.3 399 for guidance. 401 2.2. Decoder 403 As in HPACK, the decoder processes a series of representations and 404 emits the corresponding field sections. It also processes 405 instructions received on the encoder stream that modify the dynamic 406 table. Note that encoded field sections and encoder stream 407 instructions arrive on separate streams. This is unlike HPACK, where 408 encoded field sections (header blocks) can contain instructions that 409 modify the dynamic table, and there is no dedicated stream of HPACK 410 instructions. 412 The decoder MUST emit field lines in the order their representations 413 appear in the encoded field section. 415 2.2.1. Blocked Decoding 417 Upon receipt of an encoded field section, the decoder examines the 418 Required Insert Count. When the Required Insert Count is less than 419 or equal to the decoder's Insert Count, the field section can be 420 processed immediately. Otherwise, the stream on which the field 421 section was received becomes blocked. 423 While blocked, encoded field section data SHOULD remain in the 424 blocked stream's flow control window. A stream becomes unblocked 425 when the Insert Count becomes greater than or equal to the Required 426 Insert Count for all encoded field sections the decoder has started 427 reading from the stream. 429 When processing encoded field sections, the decoder expects the 430 Required Insert Count to equal the lowest possible value for the 431 Insert Count with which the field section can be decoded, as 432 prescribed in Section 2.1.2. If it encounters a Required Insert 433 Count smaller than expected, it MUST treat this as a connection error 434 of type QPACK_DECOMPRESSION_FAILED; see Section 2.2.3. If it 435 encounters a Required Insert Count larger than expected, it MAY treat 436 this as a connection error of type QPACK_DECOMPRESSION_FAILED. 438 2.2.2. State Synchronization 440 The decoder signals the following events by emitting decoder 441 instructions (Section 4.4) on the decoder stream. 443 2.2.2.1. Completed Processing of a Field Section 445 After the decoder finishes decoding a field section encoded using 446 representations containing dynamic table references, it MUST emit a 447 Section Acknowledgement instruction (Section 4.4.1). A stream may 448 carry multiple field sections in the case of intermediate responses, 449 trailers, and pushed requests. The encoder interprets each 450 Section Acknowledgement instruction as acknowledging the earliest 451 unacknowledged field section containing dynamic table references sent 452 on the given stream. 454 2.2.2.2. Abandonment of a Stream 456 When an endpoint receives a stream reset before the end of a stream 457 or before all encoded field sections are processed on that stream, or 458 when it abandons reading of a stream, it generates a Stream 459 Cancellation instruction; see Section 4.4.2. This signals to the 460 encoder that all references to the dynamic table on that stream are 461 no longer outstanding. A decoder with a maximum dynamic table 462 capacity (Section 3.2.3) equal to zero MAY omit sending Stream 463 Cancellations, because the encoder cannot have any dynamic table 464 references. An encoder cannot infer from this instruction that any 465 updates to the dynamic table have been received. 467 The Section Acknowledgement and Stream Cancellation instructions 468 permit the encoder to remove references to entries in the dynamic 469 table. When an entry with absolute index lower than the Known 470 Received Count has zero references, then it is considered evictable; 471 see Section 2.1.1. 473 2.2.2.3. New Table Entries 475 After receiving new table entries on the encoder stream, the decoder 476 chooses when to emit Insert Count Increment instructions; see 477 Section 4.4.3. Emitting this instruction after adding each new 478 dynamic table entry will provide the timeliest feedback to the 479 encoder, but could be redundant with other decoder feedback. By 480 delaying an Insert Count Increment instruction, the decoder might be 481 able to coalesce multiple Insert Count Increment instructions, or 482 replace them entirely with Section Acknowledgements; see 483 Section 4.4.1. However, delaying too long may lead to compression 484 inefficiencies if the encoder waits for an entry to be acknowledged 485 before using it. 487 2.2.3. Invalid References 489 If the decoder encounters a reference in a field line representation 490 to a dynamic table entry that has already been evicted or that has an 491 absolute index greater than or equal to the declared Required Insert 492 Count (Section 4.5.1), it MUST treat this as a connection error of 493 type QPACK_DECOMPRESSION_FAILED. 495 If the decoder encounters a reference in an encoder instruction to a 496 dynamic table entry that has already been evicted, it MUST treat this 497 as a connection error of type QPACK_ENCODER_STREAM_ERROR. 499 3. Reference Tables 501 Unlike in HPACK, entries in the QPACK static and dynamic tables are 502 addressed separately. The following sections describe how entries in 503 each table are addressed. 505 3.1. Static Table 507 The static table consists of a predefined list of field lines, each 508 of which has a fixed index over time. Its entries are defined in 509 Appendix A. 511 All entries in the static table have a name and a value. However, 512 values can be empty (that is, have a length of 0). Each entry is 513 identified by a unique index. 515 Note that the QPACK static table is indexed from 0, whereas the HPACK 516 static table is indexed from 1. 518 When the decoder encounters an invalid static table index in a field 519 line representation it MUST treat this as a connection error of type 520 QPACK_DECOMPRESSION_FAILED. If this index is received on the encoder 521 stream, this MUST be treated as a connection error of type 522 QPACK_ENCODER_STREAM_ERROR. 524 3.2. Dynamic Table 526 The dynamic table consists of a list of field lines maintained in 527 first-in, first-out order. Each HTTP/3 endpoint holds a dynamic 528 table that is initially empty. Entries are added by encoder 529 instructions received on the encoder stream; see Section 4.3. 531 The dynamic table can contain duplicate entries (i.e., entries with 532 the same name and same value). Therefore, duplicate entries MUST NOT 533 be treated as an error by the decoder. 535 Dynamic table entries can have empty values. 537 3.2.1. Dynamic Table Size 539 The size of the dynamic table is the sum of the size of its entries. 541 The size of an entry is the sum of its name's length in bytes, its 542 value's length in bytes, and 32. The size of an entry is calculated 543 using the length of its name and value without Huffman encoding 544 applied. 546 3.2.2. Dynamic Table Capacity and Eviction 548 The encoder sets the capacity of the dynamic table, which serves as 549 the upper limit on its size. The initial capacity of the dynamic 550 table is zero. The encoder sends a Set Dynamic Table Capacity 551 instruction (Section 4.3.1) with a non-zero capacity to begin using 552 the dynamic table. 554 Before a new entry is added to the dynamic table, entries are evicted 555 from the end of the dynamic table until the size of the dynamic table 556 is less than or equal to (table capacity - size of new entry). The 557 encoder MUST NOT cause a dynamic table entry to be evicted unless 558 that entry is evictable; see Section 2.1.1. The new entry is then 559 added to the table. It is an error if the encoder attempts to add an 560 entry that is larger than the dynamic table capacity; the decoder 561 MUST treat this as a connection error of type 562 QPACK_ENCODER_STREAM_ERROR. 564 A new entry can reference an entry in the dynamic table that will be 565 evicted when adding this new entry into the dynamic table. 566 Implementations are cautioned to avoid deleting the referenced name 567 or value if the referenced entry is evicted from the dynamic table 568 prior to inserting the new entry. 570 Whenever the dynamic table capacity is reduced by the encoder 571 (Section 4.3.1), entries are evicted from the end of the dynamic 572 table until the size of the dynamic table is less than or equal to 573 the new table capacity. This mechanism can be used to completely 574 clear entries from the dynamic table by setting a capacity of 0, 575 which can subsequently be restored. 577 3.2.3. Maximum Dynamic Table Capacity 579 To bound the memory requirements of the decoder, the decoder limits 580 the maximum value the encoder is permitted to set for the dynamic 581 table capacity. In HTTP/3, this limit is determined by the value of 582 SETTINGS_QPACK_MAX_TABLE_CAPACITY sent by the decoder; see Section 5. 583 The encoder MUST NOT set a dynamic table capacity that exceeds this 584 maximum, but it can choose to use a lower dynamic table capacity; see 585 Section 4.3.1. 587 For clients using 0-RTT data in HTTP/3, the server's maximum table 588 capacity is the remembered value of the setting, or zero if the value 589 was not previously sent. When the client's 0-RTT value of the 590 SETTING is zero, the server MAY set it to a non-zero value in its 591 SETTINGS frame. If the remembered value is non-zero, the server MUST 592 send the same non-zero value in its SETTINGS frame. If it specifies 593 any other value, or omits SETTINGS_QPACK_MAX_TABLE_CAPACITY from 594 SETTINGS, the encoder must treat this as a connection error of type 595 QPACK_DECODER_STREAM_ERROR. 597 For HTTP/3 servers and HTTP/3 clients when 0-RTT is not attempted or 598 is rejected, the maximum table capacity is 0 until the encoder 599 processes a SETTINGS frame with a non-zero value of 600 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 602 When the maximum table capacity is zero, the encoder MUST NOT insert 603 entries into the dynamic table, and MUST NOT send any encoder 604 instructions on the encoder stream. 606 3.2.4. Absolute Indexing 608 Each entry possesses an absolute index that is fixed for the lifetime 609 of that entry. The first entry inserted has an absolute index of 610 "0"; indices increase by one with each insertion. 612 3.2.5. Relative Indexing 614 Relative indices begin at zero and increase in the opposite direction 615 from the absolute index. Determining which entry has a relative 616 index of "0" depends on the context of the reference. 618 In encoder instructions (Section 4.3), a relative index of "0" refers 619 to the most recently inserted value in the dynamic table. Note that 620 this means the entry referenced by a given relative index will change 621 while interpreting instructions on the encoder stream. 623 +-----+---------------+-------+ 624 | n-1 | ... | d | Absolute Index 625 + - - +---------------+ - - - + 626 | 0 | ... | n-d-1 | Relative Index 627 +-----+---------------+-------+ 628 ^ | 629 | V 630 Insertion Point Dropping Point 632 n = count of entries inserted 633 d = count of entries dropped 635 Figure 2: Example Dynamic Table Indexing - Encoder Stream 637 Unlike in encoder instructions, relative indices in field line 638 representations are relative to the Base at the beginning of the 639 encoded field section; see Section 4.5.1. This ensures that 640 references are stable even if encoded field sections and dynamic 641 table updates are processed out of order. 643 In a field line representation, a relative index of "0" refers to the 644 entry with absolute index equal to Base - 1. 646 Base 647 | 648 V 649 +-----+-----+-----+-----+-------+ 650 | n-1 | n-2 | n-3 | ... | d | Absolute Index 651 +-----+-----+ - +-----+ - + 652 | 0 | ... | n-d-3 | Relative Index 653 +-----+-----+-------+ 655 n = count of entries inserted 656 d = count of entries dropped 657 In this example, Base = n - 2 658 Figure 3: Example Dynamic Table Indexing - Relative Index in 659 Representation 661 3.2.6. Post-Base Indexing 663 Post-Base indices are used in field line representations for entries 664 with absolute indices greater than or equal to Base, starting at 0 665 for the entry with absolute index equal to Base, and increasing in 666 the same direction as the absolute index. 668 Post-Base indices allow an encoder to process a field section in a 669 single pass and include references to entries added while processing 670 this (or other) field sections. 672 Base 673 | 674 V 675 +-----+-----+-----+-----+-----+ 676 | n-1 | n-2 | n-3 | ... | d | Absolute Index 677 +-----+-----+-----+-----+-----+ 678 | 1 | 0 | Post-Base Index 679 +-----+-----+ 681 n = count of entries inserted 682 d = count of entries dropped 683 In this example, Base = n - 2 685 Figure 4: Example Dynamic Table Indexing - Post-Base Index in 686 Representation 688 4. Wire Format 690 4.1. Primitives 692 4.1.1. Prefixed Integers 694 The prefixed integer from Section 5.1 of [RFC7541] is used heavily 695 throughout this document. The format from [RFC7541] is used 696 unmodified. Note, however, that QPACK uses some prefix sizes not 697 actually used in HPACK. 699 QPACK implementations MUST be able to decode integers up to and 700 including 62 bits long. 702 4.1.2. String Literals 704 The string literal defined by Section 5.2 of [RFC7541] is also used 705 throughout. This string format includes optional Huffman encoding. 707 HPACK defines string literals to begin on a byte boundary. They 708 begin with a single bit flag, denoted as 'H' in this document 709 (indicating whether the string is Huffman-coded), followed by the 710 Length encoded as a 7-bit prefix integer, and finally Length bytes of 711 data. When Huffman encoding is enabled, the Huffman table from 712 Appendix B of [RFC7541] is used without modification. 714 This document expands the definition of string literals by permitting 715 them to begin other than on a byte boundary. An "N-bit prefix string 716 literal" begins with the same Huffman flag, followed by the length 717 encoded as an (N-1)-bit prefix integer. The prefix size, N, can have 718 a value between 2 and 8 inclusive. The remainder of the string 719 literal is unmodified. 721 A string literal without a prefix length noted is an 8-bit prefix 722 string literal and follows the definitions in [RFC7541] without 723 modification. 725 4.2. Encoder and Decoder Streams 727 QPACK defines two unidirectional stream types: 729 * An encoder stream is a unidirectional stream of type 0x02. It 730 carries an unframed sequence of encoder instructions from encoder 731 to decoder. 733 * A decoder stream is a unidirectional stream of type 0x03. It 734 carries an unframed sequence of decoder instructions from decoder 735 to encoder. 737 HTTP/3 endpoints contain a QPACK encoder and decoder. Each endpoint 738 MUST initiate at most one encoder stream and at most one decoder 739 stream. Receipt of a second instance of either stream type MUST be 740 treated as a connection error of type H3_STREAM_CREATION_ERROR. 741 These streams MUST NOT be closed. Closure of either unidirectional 742 stream type MUST be treated as a connection error of type 743 H3_CLOSED_CRITICAL_STREAM. 745 An endpoint MAY avoid creating an encoder stream if it will not be 746 used (for example if its encoder does not wish to use the dynamic 747 table, or if the maximum size of the dynamic table permitted by the 748 peer is zero). 750 An endpoint MAY avoid creating a decoder stream if its decoder sets 751 the maximum capacity of the dynamic table to zero. 753 An endpoint MUST allow its peer to create an encoder stream and a 754 decoder stream even if the connection's settings prevent their use. 756 4.3. Encoder Instructions 758 An encoder sends encoder instructions on the encoder stream to set 759 the capacity of the dynamic table and add dynamic table entries. 760 Instructions adding table entries can use existing entries to avoid 761 transmitting redundant information. The name can be transmitted as a 762 reference to an existing entry in the static or the dynamic table or 763 as a string literal. For entries that already exist in the dynamic 764 table, the full entry can also be used by reference, creating a 765 duplicate entry. 767 4.3.1. Set Dynamic Table Capacity 769 An encoder informs the decoder of a change to the dynamic table 770 capacity using an instruction that begins with the '001' three-bit 771 pattern. This is followed by the new dynamic table capacity 772 represented as an integer with a 5-bit prefix; see Section 4.1.1. 774 0 1 2 3 4 5 6 7 775 +---+---+---+---+---+---+---+---+ 776 | 0 | 0 | 1 | Capacity (5+) | 777 +---+---+---+-------------------+ 779 Figure 5: Set Dynamic Table Capacity 781 The new capacity MUST be lower than or equal to the limit described 782 in Section 3.2.3. In HTTP/3, this limit is the value of the 783 SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter (Section 5) received from 784 the decoder. The decoder MUST treat a new dynamic table capacity 785 value that exceeds this limit as a connection error of type 786 QPACK_ENCODER_STREAM_ERROR. 788 Reducing the dynamic table capacity can cause entries to be evicted; 789 see Section 3.2.2. This MUST NOT cause the eviction of entries that 790 are not evictable; see Section 2.1.1. Changing the capacity of the 791 dynamic table is not acknowledged as this instruction does not insert 792 an entry. 794 4.3.2. Insert With Name Reference 796 An encoder adds an entry to the dynamic table where the field name 797 matches the field name of an entry stored in the static or the 798 dynamic table using an instruction that starts with the '1' one-bit 799 pattern. The second ('T') bit indicates whether the reference is to 800 the static or dynamic table. The 6-bit prefix integer 801 (Section 4.1.1) that follows is used to locate the table entry for 802 the field name. When T=1, the number represents the static table 803 index; when T=0, the number is the relative index of the entry in the 804 dynamic table. 806 The field name reference is followed by the field value represented 807 as a string literal; see Section 4.1.2. 809 0 1 2 3 4 5 6 7 810 +---+---+---+---+---+---+---+---+ 811 | 1 | T | Name Index (6+) | 812 +---+---+-----------------------+ 813 | H | Value Length (7+) | 814 +---+---------------------------+ 815 | Value String (Length bytes) | 816 +-------------------------------+ 818 Figure 6: Insert Field Line -- Indexed Name 820 4.3.3. Insert With Literal Name 822 An encoder adds an entry to the dynamic table where both the field 823 name and the field value are represented as string literals using an 824 instruction that starts with the '01' two-bit pattern. 826 This is followed by the name represented as a 6-bit prefix string 827 literal, and the value represented as an 8-bit prefix string literal; 828 see Section 4.1.2. 830 0 1 2 3 4 5 6 7 831 +---+---+---+---+---+---+---+---+ 832 | 0 | 1 | H | Name Length (5+) | 833 +---+---+---+-------------------+ 834 | Name String (Length bytes) | 835 +---+---------------------------+ 836 | H | Value Length (7+) | 837 +---+---------------------------+ 838 | Value String (Length bytes) | 839 +-------------------------------+ 841 Figure 7: Insert Field Line -- New Name 843 4.3.4. Duplicate 845 An encoder duplicates an existing entry in the dynamic table using an 846 instruction that begins with the '000' three-bit pattern. This is 847 followed by the relative index of the existing entry represented as 848 an integer with a 5-bit prefix; see Section 4.1.1. 850 0 1 2 3 4 5 6 7 851 +---+---+---+---+---+---+---+---+ 852 | 0 | 0 | 0 | Index (5+) | 853 +---+---+---+-------------------+ 855 Figure 8: Duplicate 857 The existing entry is re-inserted into the dynamic table without 858 resending either the name or the value. This is useful to avoid 859 adding a reference to an older entry, which might block inserting new 860 entries. 862 4.4. Decoder Instructions 864 A decoder sends decoder instructions on the decoder stream to inform 865 the encoder about the processing of field sections and table updates 866 to ensure consistency of the dynamic table. 868 4.4.1. Section Acknowledgement 870 After processing an encoded field section whose declared Required 871 Insert Count is not zero, the decoder emits a Section Acknowledgement 872 instruction. The instruction begins with the '1' one-bit pattern, 873 followed by the field section's associated stream ID encoded as a 874 7-bit prefix integer; see Section 4.1.1. 876 This instruction is used as described in Section 2.1.4 and in 877 Section 2.2.2. 879 0 1 2 3 4 5 6 7 880 +---+---+---+---+---+---+---+---+ 881 | 1 | Stream ID (7+) | 882 +---+---------------------------+ 884 Figure 9: Section Acknowledgement 886 If an encoder receives a Section Acknowledgement instruction 887 referring to a stream on which every encoded field section with a 888 non-zero Required Insert Count has already been acknowledged, this 889 MUST be treated as a connection error of type 890 QPACK_DECODER_STREAM_ERROR. 892 The Section Acknowledgement instruction might increase the Known 893 Received Count; see Section 2.1.4. 895 4.4.2. Stream Cancellation 897 When a stream is reset or reading is abandoned, the decoder emits a 898 Stream Cancellation instruction. The instruction begins with the 899 '01' two-bit pattern, followed by the stream ID of the affected 900 stream encoded as a 6-bit prefix integer. 902 This instruction is used as described in Section 2.2.2. 904 0 1 2 3 4 5 6 7 905 +---+---+---+---+---+---+---+---+ 906 | 0 | 1 | Stream ID (6+) | 907 +---+---+-----------------------+ 909 Figure 10: Stream Cancellation 911 4.4.3. Insert Count Increment 913 The Insert Count Increment instruction begins with the '00' two-bit 914 pattern, followed by the Increment encoded as a 6-bit prefix integer. 915 This instruction increases the Known Received Count (Section 2.1.4) 916 by the value of the Increment parameter. The decoder should send an 917 Increment value that increases the Known Received Count to the total 918 number of dynamic table insertions and duplications processed so far. 920 0 1 2 3 4 5 6 7 921 +---+---+---+---+---+---+---+---+ 922 | 0 | 0 | Increment (6+) | 923 +---+---+-----------------------+ 925 Figure 11: Insert Count Increment 927 An encoder that receives an Increment field equal to zero, or one 928 that increases the Known Received Count beyond what the encoder has 929 sent MUST treat this as a connection error of type 930 QPACK_DECODER_STREAM_ERROR. 932 4.5. Field Line Representations 934 An encoded field section consists of a prefix and a possibly empty 935 sequence of representations defined in this section. Each 936 representation corresponds to a single field line. These 937 representations reference the static table or the dynamic table in a 938 particular state, but do not modify that state. 940 Encoded field sections are carried in frames on streams defined by 941 the enclosing protocol. 943 4.5.1. Encoded Field Section Prefix 945 Each encoded field section is prefixed with two integers. The 946 Required Insert Count is encoded as an integer with an 8-bit prefix 947 using the encoding described in Section 4.5.1.1. The Base is encoded 948 as a sign bit ('S') and a Delta Base value with a 7-bit prefix; see 949 Section 4.5.1.2. 951 0 1 2 3 4 5 6 7 952 +---+---+---+---+---+---+---+---+ 953 | Required Insert Count (8+) | 954 +---+---------------------------+ 955 | S | Delta Base (7+) | 956 +---+---------------------------+ 957 | Encoded Field Lines ... 958 +-------------------------------+ 960 Figure 12: Encoded Field Section 962 4.5.1.1. Required Insert Count 964 Required Insert Count identifies the state of the dynamic table 965 needed to process the encoded field section. Blocking decoders use 966 the Required Insert Count to determine when it is safe to process the 967 rest of the field section. 969 The encoder transforms the Required Insert Count as follows before 970 encoding: 972 if ReqInsertCount == 0: 973 EncInsertCount = 0 974 else: 975 EncInsertCount = (ReqInsertCount mod (2 * MaxEntries)) + 1 977 Here "MaxEntries" is the maximum number of entries that the dynamic 978 table can have. The smallest entry has empty name and value strings 979 and has the size of 32. Hence "MaxEntries" is calculated as 981 MaxEntries = floor( MaxTableCapacity / 32 ) 983 "MaxTableCapacity" is the maximum capacity of the dynamic table as 984 specified by the decoder; see Section 3.2.3. 986 This encoding limits the length of the prefix on long-lived 987 connections. 989 The decoder can reconstruct the Required Insert Count using an 990 algorithm such as the following. If the decoder encounters a value 991 of EncodedInsertCount that could not have been produced by a 992 conformant encoder, it MUST treat this as a connection error of type 993 QPACK_DECOMPRESSION_FAILED. 995 TotalNumberOfInserts is the total number of inserts into the 996 decoder's dynamic table. 998 FullRange = 2 * MaxEntries 999 if EncodedInsertCount == 0: 1000 ReqInsertCount = 0 1001 else: 1002 if EncodedInsertCount > FullRange: 1003 Error 1004 MaxValue = TotalNumberOfInserts + MaxEntries 1006 # MaxWrapped is the largest possible value of 1007 # ReqInsertCount that is 0 mod 2*MaxEntries 1008 MaxWrapped = floor(MaxValue / FullRange) * FullRange 1009 ReqInsertCount = MaxWrapped + EncodedInsertCount - 1 1011 # If ReqInsertCount exceeds MaxValue, the Encoder's value 1012 # must have wrapped one fewer time 1013 if ReqInsertCount > MaxValue: 1014 if ReqInsertCount <= FullRange: 1015 Error 1016 ReqInsertCount -= FullRange 1018 # Value of 0 must be encoded as 0. 1019 if ReqInsertCount == 0: 1020 Error 1022 For example, if the dynamic table is 100 bytes, then the Required 1023 Insert Count will be encoded modulo 6. If a decoder has received 10 1024 inserts, then an encoded value of 4 indicates that the Required 1025 Insert Count is 9 for the field section. 1027 4.5.1.2. Base 1029 The Base is used to resolve references in the dynamic table as 1030 described in Section 3.2.5. 1032 To save space, the Base is encoded relative to the Required Insert 1033 Count using a one-bit sign ('S') and the Delta Base value. A sign 1034 bit of 0 indicates that the Base is greater than or equal to the 1035 value of the Required Insert Count; the decoder adds the value of 1036 Delta Base to the Required Insert Count to determine the value of the 1037 Base. A sign bit of 1 indicates that the Base is less than the 1038 Required Insert Count; the decoder subtracts the value of Delta Base 1039 from the Required Insert Count and also subtracts one to determine 1040 the value of the Base. That is: 1042 if S == 0: 1043 Base = ReqInsertCount + DeltaBase 1044 else: 1045 Base = ReqInsertCount - DeltaBase - 1 1047 A single-pass encoder determines the Base before encoding a field 1048 section. If the encoder inserted entries in the dynamic table while 1049 encoding the field section and is referencing them, Required Insert 1050 Count will be greater than the Base, so the encoded difference is 1051 negative and the sign bit is set to 1. If the field section was not 1052 encoded using representations that reference the most recent entry in 1053 the table and did not insert any new entries, the Base will be 1054 greater than the Required Insert Count, so the delta will be positive 1055 and the sign bit is set to 0. 1057 An encoder that produces table updates before encoding a field 1058 section might set Base to the value of Required Insert Count. In 1059 such case, both the sign bit and the Delta Base will be set to zero. 1061 A field section that was encoded without references to the dynamic 1062 table can use any value for the Base; setting Delta Base to zero is 1063 one of the most efficient encodings. 1065 For example, with a Required Insert Count of 9, a decoder receives an 1066 S bit of 1 and a Delta Base of 2. This sets the Base to 6 and 1067 enables post-base indexing for three entries. In this example, a 1068 relative index of 1 refers to the 5th entry that was added to the 1069 table; a post-base index of 1 refers to the 8th entry. 1071 4.5.2. Indexed Field Line 1073 An indexed field line representation identifies an entry in the 1074 static table, or an entry in the dynamic table with an absolute index 1075 less than the value of the Base. 1077 0 1 2 3 4 5 6 7 1078 +---+---+---+---+---+---+---+---+ 1079 | 1 | T | Index (6+) | 1080 +---+---+-----------------------+ 1082 Figure 13: Indexed Field Line 1084 This representation starts with the '1' 1-bit pattern, followed by 1085 the 'T' bit indicating whether the reference is into the static or 1086 dynamic table. The 6-bit prefix integer (Section 4.1.1) that follows 1087 is used to locate the table entry for the field line. When T=1, the 1088 number represents the static table index; when T=0, the number is the 1089 relative index of the entry in the dynamic table. 1091 4.5.3. Indexed Field Line With Post-Base Index 1093 An indexed field line with post-base index representation identifies 1094 an entry in the dynamic table with an absolute index greater than or 1095 equal to the value of the Base. 1097 0 1 2 3 4 5 6 7 1098 +---+---+---+---+---+---+---+---+ 1099 | 0 | 0 | 0 | 1 | Index (4+) | 1100 +---+---+---+---+---------------+ 1102 Figure 14: Indexed Field Line with Post-Base Index 1104 This representation starts with the '0001' 4-bit pattern. This is 1105 followed by the post-base index (Section 3.2.6) of the matching field 1106 line, represented as an integer with a 4-bit prefix; see 1107 Section 4.1.1. 1109 4.5.4. Literal Field Line With Name Reference 1111 A literal field line with name reference representation encodes a 1112 field line where the field name matches the field name of an entry in 1113 the static table, or the field name of an entry in the dynamic table 1114 with an absolute index less than the value of the Base. 1116 0 1 2 3 4 5 6 7 1117 +---+---+---+---+---+---+---+---+ 1118 | 0 | 1 | N | T |Name Index (4+)| 1119 +---+---+---+---+---------------+ 1120 | H | Value Length (7+) | 1121 +---+---------------------------+ 1122 | Value String (Length bytes) | 1123 +-------------------------------+ 1125 Figure 15: Literal Field Line With Name Reference 1127 This representation starts with the '01' two-bit pattern. The 1128 following bit, 'N', indicates whether an intermediary is permitted to 1129 add this field line to the dynamic table on subsequent hops. When 1130 the 'N' bit is set, the encoded field line MUST always be encoded 1131 with a literal representation. In particular, when a peer sends a 1132 field line that it received represented as a literal field line with 1133 the 'N' bit set, it MUST use a literal representation to forward this 1134 field line. This bit is intended for protecting field values that 1135 are not to be put at risk by compressing them; see Section 7 for more 1136 details. 1138 The fourth ('T') bit indicates whether the reference is to the static 1139 or dynamic table. The 4-bit prefix integer (Section 4.1.1) that 1140 follows is used to locate the table entry for the field name. When 1141 T=1, the number represents the static table index; when T=0, the 1142 number is the relative index of the entry in the dynamic table. 1144 Only the field name is taken from the dynamic table entry; the field 1145 value is encoded as an 8-bit prefix string literal; see 1146 Section 4.1.2. 1148 4.5.5. Literal Field Line With Post-Base Name Reference 1150 A literal field line with post-base name reference representation 1151 encodes a field line where the field name matches the field name of a 1152 dynamic table entry with an absolute index greater than or equal to 1153 the value of the Base. 1155 0 1 2 3 4 5 6 7 1156 +---+---+---+---+---+---+---+---+ 1157 | 0 | 0 | 0 | 0 | N |NameIdx(3+)| 1158 +---+---+---+---+---+-----------+ 1159 | H | Value Length (7+) | 1160 +---+---------------------------+ 1161 | Value String (Length bytes) | 1162 +-------------------------------+ 1164 Figure 16: Literal Field Line With Post-Base Name Reference 1166 This representation starts with the '0000' four-bit pattern. The 1167 fifth bit is the 'N' bit as described in Section 4.5.4. This is 1168 followed by a post-base index of the dynamic table entry 1169 (Section 3.2.6) encoded as an integer with a 3-bit prefix; see 1170 Section 4.1.1. 1172 Only the field name is taken from the dynamic table entry; the field 1173 value is encoded as an 8-bit prefix string literal; see 1174 Section 4.1.2. 1176 4.5.6. Literal Field Line With Literal Name 1178 The literal field line with literal name representation encodes a 1179 field name and a field value as string literals. 1181 0 1 2 3 4 5 6 7 1182 +---+---+---+---+---+---+---+---+ 1183 | 0 | 0 | 1 | N | H |NameLen(3+)| 1184 +---+---+---+---+---+-----------+ 1185 | Name String (Length bytes) | 1186 +---+---------------------------+ 1187 | H | Value Length (7+) | 1188 +---+---------------------------+ 1189 | Value String (Length bytes) | 1190 +-------------------------------+ 1192 Figure 17: Literal Field Line With Literal Name 1194 This representation begins with the '001' three-bit pattern. The 1195 fourth bit is the 'N' bit as described in Section 4.5.4. The name 1196 follows, represented as a 4-bit prefix string literal, then the 1197 value, represented as an 8-bit prefix string literal; see 1198 Section 4.1.2. 1200 5. Configuration 1202 QPACK defines two settings for the HTTP/3 SETTINGS frame: 1204 SETTINGS_QPACK_MAX_TABLE_CAPACITY (0x1): The default value is zero. 1205 See Section 3.2 for usage. This is the equivalent of the 1206 SETTINGS_HEADER_TABLE_SIZE from HTTP/2. 1208 SETTINGS_QPACK_BLOCKED_STREAMS (0x7): The default value is zero. 1209 See Section 2.1.2. 1211 6. Error Handling 1213 The following error codes are defined for HTTP/3 to indicate failures 1214 of QPACK that prevent the stream or connection from continuing: 1216 QPACK_DECOMPRESSION_FAILED (0x200): The decoder failed to interpret 1217 an encoded field section and is not able to continue decoding that 1218 field section. 1220 QPACK_ENCODER_STREAM_ERROR (0x201): The decoder failed to interpret 1221 an encoder instruction received on the encoder stream. 1223 QPACK_DECODER_STREAM_ERROR (0x202): The encoder failed to interpret 1224 a decoder instruction received on the decoder stream. 1226 7. Security Considerations 1228 This section describes potential areas of security concern with 1229 QPACK: 1231 * Use of compression as a length-based oracle for verifying guesses 1232 about secrets that are compressed into a shared compression 1233 context. 1235 * Denial of service resulting from exhausting processing or memory 1236 capacity at a decoder. 1238 7.1. Probing Dynamic Table State 1240 QPACK reduces the encoded size of field sections by exploiting the 1241 redundancy inherent in protocols like HTTP. The ultimate goal of 1242 this is to reduce the amount of data that is required to send HTTP 1243 requests or responses. 1245 The compression context used to encode header and trailer fields can 1246 be probed by an attacker who can both define fields to be encoded and 1247 transmitted and observe the length of those fields once they are 1248 encoded. When an attacker can do both, they can adaptively modify 1249 requests in order to confirm guesses about the dynamic table state. 1250 If a guess is compressed into a shorter length, the attacker can 1251 observe the encoded length and infer that the guess was correct. 1253 This is possible even over the Transport Layer Security Protocol 1254 (TLS, see [TLS]), because while TLS provides confidentiality 1255 protection for content, it only provides a limited amount of 1256 protection for the length of that content. 1258 Note: Padding schemes only provide limited protection against an 1259 attacker with these capabilities, potentially only forcing an 1260 increased number of guesses to learn the length associated with a 1261 given guess. Padding schemes also work directly against 1262 compression by increasing the number of bits that are transmitted. 1264 Attacks like CRIME ([CRIME]) demonstrated the existence of these 1265 general attacker capabilities. The specific attack exploited the 1266 fact that DEFLATE ([RFC1951]) removes redundancy based on prefix 1267 matching. This permitted the attacker to confirm guesses a character 1268 at a time, reducing an exponential-time attack into a linear-time 1269 attack. 1271 7.2. Applicability to QPACK and HTTP 1273 QPACK mitigates but does not completely prevent attacks modeled on 1274 CRIME ([CRIME]) by forcing a guess to match an entire field line, 1275 rather than individual characters. An attacker can only learn 1276 whether a guess is correct or not, so is reduced to a brute force 1277 guess for the field values associated with a given field name. 1279 The viability of recovering specific field values therefore depends 1280 on the entropy of values. As a result, values with high entropy are 1281 unlikely to be recovered successfully. However, values with low 1282 entropy remain vulnerable. 1284 Attacks of this nature are possible any time that two mutually 1285 distrustful entities control requests or responses that are placed 1286 onto a single HTTP/3 connection. If the shared QPACK compressor 1287 permits one entity to add entries to the dynamic table, and the other 1288 to access those entries, then the state of the table can be learned. 1290 Having requests or responses from mutually distrustful entities 1291 occurs when an intermediary either: 1293 * sends requests from multiple clients on a single connection toward 1294 an origin server, or 1296 * takes responses from multiple origin servers and places them on a 1297 shared connection toward a client. 1299 Web browsers also need to assume that requests made on the same 1300 connection by different web origins ([RFC6454]) are made by mutually 1301 distrustful entities. 1303 7.3. Mitigation 1305 Users of HTTP that require confidentiality for header or trailer 1306 fields can use values with entropy sufficient to make guessing 1307 infeasible. However, this is impractical as a general solution 1308 because it forces all users of HTTP to take steps to mitigate 1309 attacks. It would impose new constraints on how HTTP is used. 1311 Rather than impose constraints on users of HTTP, an implementation of 1312 QPACK can instead constrain how compression is applied in order to 1313 limit the potential for dynamic table probing. 1315 An ideal solution segregates access to the dynamic table based on the 1316 entity that is constructing the message. Field values that are added 1317 to the table are attributed to an entity, and only the entity that 1318 created a particular value can extract that value. 1320 To improve compression performance of this option, certain entries 1321 might be tagged as being public. For example, a web browser might 1322 make the values of the Accept-Encoding header field available in all 1323 requests. 1325 An encoder without good knowledge of the provenance of field values 1326 might instead introduce a penalty for many field lines with the same 1327 field name and different values. This penalty could cause a large 1328 number of attempts to guess a field value to result in the field not 1329 being compared to the dynamic table entries in future messages, 1330 effectively preventing further guesses. 1332 Note: Simply removing entries corresponding to the field from the 1333 dynamic table can be ineffectual if the attacker has a reliable 1334 way of causing values to be reinstalled. For example, a request 1335 to load an image in a web browser typically includes the Cookie 1336 header field (a potentially highly valued target for this sort of 1337 attack), and web sites can easily force an image to be loaded, 1338 thereby refreshing the entry in the dynamic table. 1340 This response might be made inversely proportional to the length of 1341 the field value. Disabling access to the dynamic table for a given 1342 field name might occur for shorter values more quickly or with higher 1343 probability than for longer values. 1345 7.4. Never-Indexed Literals 1347 Implementations can also choose to protect sensitive fields by not 1348 compressing them and instead encoding their value as literals. 1350 Refusing to insert a field line into the dynamic table is only 1351 effective if doing so is avoided on all hops. The never-indexed 1352 literal bit (see Section 4.5.4) can be used to signal to 1353 intermediaries that a particular value was intentionally sent as a 1354 literal. 1356 An intermediary MUST NOT re-encode a value that uses a literal 1357 representation with the 'N' bit set with another representation that 1358 would index it. If QPACK is used for re-encoding, a literal 1359 representation with the 'N' bit set MUST be used. If HPACK is used 1360 for re-encoding, the never-indexed literal representation (see 1361 Section 6.2.3 of [RFC7541]) MUST be used. 1363 The choice to mark that a field value should never be indexed depends 1364 on several factors. Since QPACK does not protect against guessing an 1365 entire field value, short or low-entropy values are more readily 1366 recovered by an adversary. Therefore, an encoder might choose not to 1367 index values with low entropy. 1369 An encoder might also choose not to index values for fields that are 1370 considered to be highly valuable or sensitive to recovery, such as 1371 the Cookie or Authorization header fields. 1373 On the contrary, an encoder might prefer indexing values for fields 1374 that have little or no value if they were exposed. For instance, a 1375 User-Agent header field does not commonly vary between requests and 1376 is sent to any server. In that case, confirmation that a particular 1377 User-Agent value has been used provides little value. 1379 Note that these criteria for deciding to use a never-indexed literal 1380 representation will evolve over time as new attacks are discovered. 1382 7.5. Static Huffman Encoding 1384 There is no currently known attack against a static Huffman encoding. 1385 A study has shown that using a static Huffman encoding table created 1386 an information leakage, however this same study concluded that an 1387 attacker could not take advantage of this information leakage to 1388 recover any meaningful amount of information (see [PETAL]). 1390 7.6. Memory Consumption 1392 An attacker can try to cause an endpoint to exhaust its memory. 1393 QPACK is designed to limit both the peak and stable amounts of memory 1394 allocated by an endpoint. 1396 The amount of memory used by the encoder is limited by the protocol 1397 using QPACK through the definition of the maximum size of the dynamic 1398 table, and the maximum number of blocking streams. In HTTP/3, these 1399 values are controlled by the decoder through the settings parameters 1400 SETTINGS_QPACK_MAX_TABLE_CAPACITY and SETTINGS_QPACK_BLOCKED_STREAMS, 1401 respectively (see Section 3.2.3 and Section 2.1.2). The limit on the 1402 size of the dynamic table takes into account the size of the data 1403 stored in the dynamic table, plus a small allowance for overhead. 1404 The limit on the number of blocked streams is only a proxy for the 1405 maximum amount of memory required by the decoder. The actual maximum 1406 amount of memory will depend on how much memory the decoder uses to 1407 track each blocked stream. 1409 A decoder can limit the amount of state memory used for the dynamic 1410 table by setting an appropriate value for the maximum size of the 1411 dynamic table. In HTTP/3, this is realized by setting an appropriate 1412 value for the SETTINGS_QPACK_MAX_TABLE_CAPACITY parameter. An 1413 encoder can limit the amount of state memory it uses by signaling a 1414 lower dynamic table size than the decoder allows (see Section 3.2.2). 1416 A decoder can limit the amount of state memory used for blocked 1417 streams by setting an appropriate value for the maximum number of 1418 blocked streams. In HTTP/3, this is realized by setting an 1419 appropriate value for the QPACK_BLOCKED_STREAMS parameter. Streams 1420 which risk becoming blocked consume no additional state memory on the 1421 encoder. 1423 An encoder allocates memory to track all dynamic table references in 1424 unacknowledged field sections. An implementation can directly limit 1425 the amount of state memory by only using as many references to the 1426 dynamic table as it wishes to track; no signaling to the decoder is 1427 required. However, limiting references to the dynamic table will 1428 reduce compression effectiveness. 1430 The amount of temporary memory consumed by an encoder or decoder can 1431 be limited by processing field lines sequentially. A decoder 1432 implementation does not need to retain a complete list of field lines 1433 while decoding a field section. An encoder implementation does not 1434 need to retain a complete list of field lines while encoding a field 1435 section if it is using a single-pass algorithm. Note that it might 1436 be necessary for an application to retain a complete list of field 1437 lines for other reasons; even if QPACK does not force this to occur, 1438 application constraints might make this necessary. 1440 While the negotiated limit on the dynamic table size accounts for 1441 much of the memory that can be consumed by a QPACK implementation, 1442 data that cannot be immediately sent due to flow control is not 1443 affected by this limit. Implementations should limit the size of 1444 unsent data, especially on the decoder stream where flexibility to 1445 choose what to send is limited. Possible responses to an excess of 1446 unsent data might include limiting the ability of the peer to open 1447 new streams, reading only from the encoder stream, or closing the 1448 connection. 1450 7.7. Implementation Limits 1452 An implementation of QPACK needs to ensure that large values for 1453 integers, long encoding for integers, or long string literals do not 1454 create security weaknesses. 1456 An implementation has to set a limit for the values it accepts for 1457 integers, as well as for the encoded length; see Section 4.1.1. In 1458 the same way, it has to set a limit to the length it accepts for 1459 string literals; see Section 4.1.2. 1461 8. IANA Considerations 1463 8.1. Settings Registration 1465 This document specifies two settings. The entries in the following 1466 table are registered in the "HTTP/3 Settings" registry established in 1467 [HTTP3]. 1469 +==========================+======+===============+=========+ 1470 | Setting Name | Code | Specification | Default | 1471 +==========================+======+===============+=========+ 1472 | QPACK_MAX_TABLE_CAPACITY | 0x1 | Section 5 | 0 | 1473 +--------------------------+------+---------------+---------+ 1474 | QPACK_BLOCKED_STREAMS | 0x7 | Section 5 | 0 | 1475 +--------------------------+------+---------------+---------+ 1477 Table 1 1479 8.2. Stream Type Registration 1481 This document specifies two stream types. The entries in the 1482 following table are registered in the "HTTP/3 Stream Type" registry 1483 established in [HTTP3]. 1485 +======================+======+===============+========+ 1486 | Stream Type | Code | Specification | Sender | 1487 +======================+======+===============+========+ 1488 | QPACK Encoder Stream | 0x02 | Section 4.2 | Both | 1489 +----------------------+------+---------------+--------+ 1490 | QPACK Decoder Stream | 0x03 | Section 4.2 | Both | 1491 +----------------------+------+---------------+--------+ 1493 Table 2 1495 8.3. Error Code Registration 1497 This document specifies three error codes. The entries in the 1498 following table are registered in the "HTTP/3 Error Code" registry 1499 established in [HTTP3]. 1501 +============================+=======+=============+===============+ 1502 | Name | Code | Description | Specification | 1503 +============================+=======+=============+===============+ 1504 | QPACK_DECOMPRESSION_FAILED | 0x200 | Decoding of | Section 6 | 1505 | | | a field | | 1506 | | | section | | 1507 | | | failed | | 1508 +----------------------------+-------+-------------+---------------+ 1509 | QPACK_ENCODER_STREAM_ERROR | 0x201 | Error on | Section 6 | 1510 | | | the encoder | | 1511 | | | stream | | 1512 +----------------------------+-------+-------------+---------------+ 1513 | QPACK_DECODER_STREAM_ERROR | 0x202 | Error on | Section 6 | 1514 | | | the decoder | | 1515 | | | stream | | 1516 +----------------------------+-------+-------------+---------------+ 1518 Table 3 1520 9. References 1522 9.1. Normative References 1524 [HTTP3] Bishop, M., Ed., "Hypertext Transfer Protocol Version 3 1525 (HTTP/3)", Work in Progress, Internet-Draft, draft-ietf- 1526 quic-http-31, 25 September 2020, 1527 . 1529 [QUIC-TRANSPORT] 1530 Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based 1531 Multiplexed and Secure Transport", Work in Progress, 1532 Internet-Draft, draft-ietf-quic-transport-31, 25 September 1533 2020, . 1536 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1537 Requirement Levels", BCP 14, RFC 2119, 1538 DOI 10.17487/RFC2119, March 1997, 1539 . 1541 [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for 1542 HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, 1543 . 1545 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1546 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1547 May 2017, . 1549 [SEMANTICS] 1550 Fielding, R., Nottingham, M., and J. Reschke, "HTTP 1551 Semantics", Work in Progress, Internet-Draft, draft-ietf- 1552 httpbis-semantics-11, 27 August 2020, 1553 . 1556 9.2. Informative References 1558 [CRIME] Wikipedia, "CRIME", May 2015, . 1561 [PETAL] Tan, J. and J. Nahata, "PETAL: Preset Encoding 1562 Table Information Leakage", April 2013, 1563 . 1566 [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification 1567 version 1.3", RFC 1951, DOI 10.17487/RFC1951, May 1996, 1568 . 1570 [RFC2360] Scott, G., "Guide for Internet Standards Writers", BCP 22, 1571 RFC 2360, DOI 10.17487/RFC2360, June 1998, 1572 . 1574 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 1575 DOI 10.17487/RFC6454, December 2011, 1576 . 1578 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 1579 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 1580 DOI 10.17487/RFC7540, May 2015, 1581 . 1583 [TLS] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1584 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1585 . 1587 Appendix A. Static Table 1589 This table was generated by analyzing actual Internet traffic in 2018 1590 and including the most common header fields, after filtering out some 1591 unsupported and non-standard values. Due to this methodology, some 1592 of the entries may be inconsistent or appear multiple times with 1593 similar but not identical values. The order of the entries is 1594 optimized to encode the most common header fields with the smallest 1595 number of bytes. 1597 +=======+==================================+=======================+ 1598 | Index | Name | Value | 1599 +=======+==================================+=======================+ 1600 | 0 | :authority | | 1601 +-------+----------------------------------+-----------------------+ 1602 | 1 | :path | / | 1603 +-------+----------------------------------+-----------------------+ 1604 | 2 | age | 0 | 1605 +-------+----------------------------------+-----------------------+ 1606 | 3 | content-disposition | | 1607 +-------+----------------------------------+-----------------------+ 1608 | 4 | content-length | 0 | 1609 +-------+----------------------------------+-----------------------+ 1610 | 5 | cookie | | 1611 +-------+----------------------------------+-----------------------+ 1612 | 6 | date | | 1613 +-------+----------------------------------+-----------------------+ 1614 | 7 | etag | | 1615 +-------+----------------------------------+-----------------------+ 1616 | 8 | if-modified-since | | 1617 +-------+----------------------------------+-----------------------+ 1618 | 9 | if-none-match | | 1619 +-------+----------------------------------+-----------------------+ 1620 | 10 | last-modified | | 1621 +-------+----------------------------------+-----------------------+ 1622 | 11 | link | | 1623 +-------+----------------------------------+-----------------------+ 1624 | 12 | location | | 1625 +-------+----------------------------------+-----------------------+ 1626 | 13 | referer | | 1627 +-------+----------------------------------+-----------------------+ 1628 | 14 | set-cookie | | 1629 +-------+----------------------------------+-----------------------+ 1630 | 15 | :method | CONNECT | 1631 +-------+----------------------------------+-----------------------+ 1632 | 16 | :method | DELETE | 1633 +-------+----------------------------------+-----------------------+ 1634 | 17 | :method | GET | 1635 +-------+----------------------------------+-----------------------+ 1636 | 18 | :method | HEAD | 1637 +-------+----------------------------------+-----------------------+ 1638 | 19 | :method | OPTIONS | 1639 +-------+----------------------------------+-----------------------+ 1640 | 20 | :method | POST | 1641 +-------+----------------------------------+-----------------------+ 1642 | 21 | :method | PUT | 1643 +-------+----------------------------------+-----------------------+ 1644 | 22 | :scheme | http | 1645 +-------+----------------------------------+-----------------------+ 1646 | 23 | :scheme | https | 1647 +-------+----------------------------------+-----------------------+ 1648 | 24 | :status | 103 | 1649 +-------+----------------------------------+-----------------------+ 1650 | 25 | :status | 200 | 1651 +-------+----------------------------------+-----------------------+ 1652 | 26 | :status | 304 | 1653 +-------+----------------------------------+-----------------------+ 1654 | 27 | :status | 404 | 1655 +-------+----------------------------------+-----------------------+ 1656 | 28 | :status | 503 | 1657 +-------+----------------------------------+-----------------------+ 1658 | 29 | accept | */* | 1659 +-------+----------------------------------+-----------------------+ 1660 | 30 | accept | application/dns- | 1661 | | | message | 1662 +-------+----------------------------------+-----------------------+ 1663 | 31 | accept-encoding | gzip, deflate, br | 1664 +-------+----------------------------------+-----------------------+ 1665 | 32 | accept-ranges | bytes | 1666 +-------+----------------------------------+-----------------------+ 1667 | 33 | access-control-allow-headers | cache-control | 1668 +-------+----------------------------------+-----------------------+ 1669 | 34 | access-control-allow-headers | content-type | 1670 +-------+----------------------------------+-----------------------+ 1671 | 35 | access-control-allow-origin | * | 1672 +-------+----------------------------------+-----------------------+ 1673 | 36 | cache-control | max-age=0 | 1674 +-------+----------------------------------+-----------------------+ 1675 | 37 | cache-control | max-age=2592000 | 1676 +-------+----------------------------------+-----------------------+ 1677 | 38 | cache-control | max-age=604800 | 1678 +-------+----------------------------------+-----------------------+ 1679 | 39 | cache-control | no-cache | 1680 +-------+----------------------------------+-----------------------+ 1681 | 40 | cache-control | no-store | 1682 +-------+----------------------------------+-----------------------+ 1683 | 41 | cache-control | public, max- | 1684 | | | age=31536000 | 1685 +-------+----------------------------------+-----------------------+ 1686 | 42 | content-encoding | br | 1687 +-------+----------------------------------+-----------------------+ 1688 | 43 | content-encoding | gzip | 1689 +-------+----------------------------------+-----------------------+ 1690 | 44 | content-type | application/dns- | 1691 | | | message | 1692 +-------+----------------------------------+-----------------------+ 1693 | 45 | content-type | application/ | 1694 | | | javascript | 1695 +-------+----------------------------------+-----------------------+ 1696 | 46 | content-type | application/json | 1697 +-------+----------------------------------+-----------------------+ 1698 | 47 | content-type | application/x-www- | 1699 | | | form-urlencoded | 1700 +-------+----------------------------------+-----------------------+ 1701 | 48 | content-type | image/gif | 1702 +-------+----------------------------------+-----------------------+ 1703 | 49 | content-type | image/jpeg | 1704 +-------+----------------------------------+-----------------------+ 1705 | 50 | content-type | image/png | 1706 +-------+----------------------------------+-----------------------+ 1707 | 51 | content-type | text/css | 1708 +-------+----------------------------------+-----------------------+ 1709 | 52 | content-type | text/html; | 1710 | | | charset=utf-8 | 1711 +-------+----------------------------------+-----------------------+ 1712 | 53 | content-type | text/plain | 1713 +-------+----------------------------------+-----------------------+ 1714 | 54 | content-type | text/ | 1715 | | | plain;charset=utf-8 | 1716 +-------+----------------------------------+-----------------------+ 1717 | 55 | range | bytes=0- | 1718 +-------+----------------------------------+-----------------------+ 1719 | 56 | strict-transport-security | max-age=31536000 | 1720 +-------+----------------------------------+-----------------------+ 1721 | 57 | strict-transport-security | max-age=31536000; | 1722 | | | includesubdomains | 1723 +-------+----------------------------------+-----------------------+ 1724 | 58 | strict-transport-security | max-age=31536000; | 1725 | | | includesubdomains; | 1726 | | | preload | 1727 +-------+----------------------------------+-----------------------+ 1728 | 59 | vary | accept-encoding | 1729 +-------+----------------------------------+-----------------------+ 1730 | 60 | vary | origin | 1731 +-------+----------------------------------+-----------------------+ 1732 | 61 | x-content-type-options | nosniff | 1733 +-------+----------------------------------+-----------------------+ 1734 | 62 | x-xss-protection | 1; mode=block | 1735 +-------+----------------------------------+-----------------------+ 1736 | 63 | :status | 100 | 1737 +-------+----------------------------------+-----------------------+ 1738 | 64 | :status | 204 | 1739 +-------+----------------------------------+-----------------------+ 1740 | 65 | :status | 206 | 1741 +-------+----------------------------------+-----------------------+ 1742 | 66 | :status | 302 | 1743 +-------+----------------------------------+-----------------------+ 1744 | 67 | :status | 400 | 1745 +-------+----------------------------------+-----------------------+ 1746 | 68 | :status | 403 | 1747 +-------+----------------------------------+-----------------------+ 1748 | 69 | :status | 421 | 1749 +-------+----------------------------------+-----------------------+ 1750 | 70 | :status | 425 | 1751 +-------+----------------------------------+-----------------------+ 1752 | 71 | :status | 500 | 1753 +-------+----------------------------------+-----------------------+ 1754 | 72 | accept-language | | 1755 +-------+----------------------------------+-----------------------+ 1756 | 73 | access-control-allow-credentials | FALSE | 1757 +-------+----------------------------------+-----------------------+ 1758 | 74 | access-control-allow-credentials | TRUE | 1759 +-------+----------------------------------+-----------------------+ 1760 | 75 | access-control-allow-headers | * | 1761 +-------+----------------------------------+-----------------------+ 1762 | 76 | access-control-allow-methods | get | 1763 +-------+----------------------------------+-----------------------+ 1764 | 77 | access-control-allow-methods | get, post, options | 1765 +-------+----------------------------------+-----------------------+ 1766 | 78 | access-control-allow-methods | options | 1767 +-------+----------------------------------+-----------------------+ 1768 | 79 | access-control-expose-headers | content-length | 1769 +-------+----------------------------------+-----------------------+ 1770 | 80 | access-control-request-headers | content-type | 1771 +-------+----------------------------------+-----------------------+ 1772 | 81 | access-control-request-method | get | 1773 +-------+----------------------------------+-----------------------+ 1774 | 82 | access-control-request-method | post | 1775 +-------+----------------------------------+-----------------------+ 1776 | 83 | alt-svc | clear | 1777 +-------+----------------------------------+-----------------------+ 1778 | 84 | authorization | | 1779 +-------+----------------------------------+-----------------------+ 1780 | 85 | content-security-policy | script-src 'none'; | 1781 | | | object-src 'none'; | 1782 | | | base-uri 'none' | 1783 +-------+----------------------------------+-----------------------+ 1784 | 86 | early-data | 1 | 1785 +-------+----------------------------------+-----------------------+ 1786 | 87 | expect-ct | | 1787 +-------+----------------------------------+-----------------------+ 1788 | 88 | forwarded | | 1789 +-------+----------------------------------+-----------------------+ 1790 | 89 | if-range | | 1791 +-------+----------------------------------+-----------------------+ 1792 | 90 | origin | | 1793 +-------+----------------------------------+-----------------------+ 1794 | 91 | purpose | prefetch | 1795 +-------+----------------------------------+-----------------------+ 1796 | 92 | server | | 1797 +-------+----------------------------------+-----------------------+ 1798 | 93 | timing-allow-origin | * | 1799 +-------+----------------------------------+-----------------------+ 1800 | 94 | upgrade-insecure-requests | 1 | 1801 +-------+----------------------------------+-----------------------+ 1802 | 95 | user-agent | | 1803 +-------+----------------------------------+-----------------------+ 1804 | 96 | x-forwarded-for | | 1805 +-------+----------------------------------+-----------------------+ 1806 | 97 | x-frame-options | deny | 1807 +-------+----------------------------------+-----------------------+ 1808 | 98 | x-frame-options | sameorigin | 1809 +-------+----------------------------------+-----------------------+ 1811 Table 4 1813 Appendix B. Encoding and Decoding Examples 1815 The following examples represent a series of exchanges between an 1816 encoder and a decoder. The exchanges are designed to exercise most 1817 QPACK instructions, and highlight potentially common patterns and 1818 their impact on dynamic table state. The encoder sends three encoded 1819 field sections containing one field line each, as wells as two 1820 speculative inserts that are not referenced. 1822 The state of the encoder's dynamic table is shown, along with its 1823 current size. Each entry is shown with the Absolute Index of the 1824 entry (Abs), the current number of outstanding encoded field sections 1825 with references to that entry (Ref), along with the name and value. 1826 Entries above the 'acknowledged' line have been acknowledged by the 1827 decoder. 1829 B.1. Literal Field Line With Name Reference 1831 The encoder sends an encoded field section containing a literal 1832 representation of a field with a static name reference. 1834 Data | Interpretation 1835 | Encoder's Dynamic Table 1837 Stream: 0 1838 0000 | Required Insert Count = 0, Base = 0 1839 510b 2f69 6e64 6578 | Literal Field Line with Name Reference 1840 2e68 746d 6c | Static Table, Index=1 1841 | (:path=/index.html) 1843 Abs Ref Name Value 1844 ^-- acknowledged --^ 1845 Size=0 1847 B.2. Dynamic Table 1849 The encoder sets the dynamic table capacity, inserts a header with a 1850 dynamic name reference, then sends a potentially blocking, encoded 1851 field section referencing this new entry. The decoder acknowledges 1852 processing the encoded field section, which implicitly acknowledges 1853 all dynamic table insertions up to the Required Insert Count. 1855 Stream: Encoder 1856 3fbd01 | Set Dynamic Table Capacity=220 1857 c00f 7777 772e 6578 | Insert With Name Reference 1858 616d 706c 652e 636f | Static Table, Index=0 1859 6d | (:authority=www.example.com) 1860 c10c 2f73 616d 706c | Insert With Name Reference 1861 652f 7061 7468 | Static Table, Index=1 1862 | (:path=/sample/path) 1864 Abs Ref Name Value 1865 ^-- acknowledged --^ 1866 1 0 :authority www.example.com 1867 2 0 :path /sample/path 1868 Size=106 1870 Stream: 4 1871 0381 | Required Insert Count = 2, Base = 0 1872 10 | Indexed Field Line With Post-Base Index 1873 | Absolute Index = Base(0) + Index(0) + 1 = 1 1874 | (:authority=www.example.com) 1875 11 | Indexed Field Line With Post-Base Index 1876 | Absolute Index = Base(0) + Index(1) + 1 = 2 1877 | (:path=/sample/path) 1879 Abs Ref Name Value 1880 ^-- acknowledged --^ 1881 1 1 :authority www.example.com 1882 2 1 :path /sample/path 1883 Size=106 1885 Stream: Decoder 1886 84 | Section Acknowledgement (stream=4) 1888 Abs Ref Name Value 1889 1 0 :authority www.example.com 1890 2 0 :path /sample/path 1891 ^-- acknowledged --^ 1892 Size=106 1894 B.3. Speculative Insert 1896 The encoder inserts a header into the dynamic table with a literal 1897 name. The decoder acknowledges receipt of the entry. The encoder 1898 does not send any encoded field sections. 1900 Stream: Encoder 1901 4a63 7573 746f 6d2d | Insert With Literal Name 1902 6b65 790c 6375 7374 | (custom-key=custom-value) 1903 6f6d 2d76 616c 7565 | 1905 Abs Ref Name Value 1906 1 0 :authority www.example.com 1907 2 0 :path /sample/path 1908 ^-- acknowledged --^ 1909 3 0 custom-key custom-value 1910 Size=160 1912 Stream: Decoder 1913 01 | Insert Count Increment (1) 1915 Abs Ref Name Value 1916 1 0 :authority www.example.com 1917 2 0 :path /sample/path 1918 3 0 custom-key custom-value 1919 ^-- acknowledged --^ 1920 Size=160 1922 B.4. Duplicate Instruction, Stream Cancellation 1924 The encoder duplicates an existing entry in the dynamic table, then 1925 sends an encoded field section referencing the dynamic table entries 1926 including the duplicated entry. The decoder notifies the encoder 1927 that the encoded field section was not processed by sending a stream 1928 cancellation. 1930 Stream: Encoder 1931 02 | Duplicate (Relative Index=2) 1933 Abs Ref Name Value 1934 1 0 :authority www.example.com 1935 2 0 :path /sample/path 1936 3 0 custom-key custom-value 1937 ^-- acknowledged --^ 1938 4 0 :authority www.example.com 1939 Size=217 1941 Stream: 8 1942 0500 | Required Insert Count = 4, Base = 4 1943 80 | Indexed Field Line, Dynamic Table 1944 | Absolute Index = Base(4) - Index(0) = 4 1945 | (:authority=www.example.com) 1946 c1 | Indexed Field Line, Static Table Index = 1 1947 | (:path=/) 1948 81 | Indexed Field Line, Dynamic Table 1949 | Absolute Index = Base(4) - Index(1) = 3 1950 | (custom-key=custom-value) 1952 Abs Ref Name Value 1953 1 0 :authority www.example.com 1954 2 0 :path /sample/path 1955 3 1 custom-key custom-value 1956 ^-- acknowledged --^ 1957 4 1 :authority www.example.com 1958 Size=217 1960 Stream: Decoder 1961 48 | Stream Cancellation (Stream=8) 1963 Abs Ref Name Value 1964 1 0 :authority www.example.com 1965 2 0 :path /sample/path 1966 3 0 custom-key custom-value 1967 ^-- acknowledged --^ 1968 4 0 :authority www.example.com 1969 Size=215 1971 B.5. Dynamic Table Insert, Eviction 1973 The encoder inserts another header into the dynamic table, which 1974 evicts the oldest entry. The encoder does not send any encoded field 1975 sections. 1977 Stream: Encoder 1978 810d 6375 7374 6f6d | Insert With Name Reference 1979 2d76 616c 7565 32 | Dynamic Table, Absolute Index=2 1980 | (custom-key=custom-value2) 1982 Abs Ref Name Value 1983 2 0 :path /sample/path 1984 3 0 custom-key custom-value 1985 ^-- acknowledged --^ 1986 4 0 :authority www.example.com 1987 5 0 custom-key custom-value2 1988 Size=215 1990 Appendix C. Sample One Pass Encoding Algorithm 1992 Pseudo-code for single pass encoding, excluding handling of 1993 duplicates, non-blocking mode, available encoder stream flow control 1994 and reference tracking. 1996 base = dynamicTable.getInsertCount() 1997 requiredInsertCount = 0 1998 for line in field_lines: 1999 staticIndex = staticTable.findIndex(line) 2000 if staticIndex is not None: 2001 encodeIndexReference(streamBuffer, staticIndex) 2002 continue 2004 dynamicIndex = dynamicTable.findIndex(line) 2005 if dynamicIndex is None: 2006 # No matching entry. Either insert+index or encode literal 2007 staticNameIndex = staticTable.findName(line.name) 2008 if staticNameIndex is None: 2009 dynamicNameIndex = dynamicTable.findName(line.name) 2011 if shouldIndex(line) and dynamicTable.canIndex(line): 2012 encodeInsert(encoderBuffer, staticNameIndex, 2013 dynamicNameIndex, line) 2014 dynamicIndex = dynamicTable.add(line) 2016 if dynamicIndex is None: 2017 # Could not index it, literal 2018 if dynamicNameIndex is not None: 2019 # Encode literal with dynamic name, possibly above base 2020 encodeDynamicLiteral(streamBuffer, dynamicNameIndex, 2021 base, line) 2022 requiredInsertCount = max(requiredInsertCount, 2023 dynamicNameIndex) 2024 else: 2026 # Encodes a literal with a static name or literal name 2027 encodeLiteral(streamBuffer, staticNameIndex, line) 2028 else: 2029 # Dynamic index reference 2030 assert(dynamicIndex is not None) 2031 requiredInsertCount = max(requiredInsertCount, dynamicIndex) 2032 # Encode dynamicIndex, possibly above base 2033 encodeDynamicIndexReference(streamBuffer, dynamicIndex, base) 2035 # encode the prefix 2036 if requiredInsertCount == 0: 2037 encodeIndexReference(prefixBuffer, 0, 0, 8) 2038 encodeIndexReference(prefixBuffer, 0, 0, 7) 2039 else: 2040 wireRIC = ( 2041 requiredInsertCount 2042 % (2 * getMaxEntries(maxTableCapacity)) 2043 ) + 1; 2044 encodeInteger(prefixBuffer, 0x00, wireRIC, 8) 2045 if base >= requiredInsertCount: 2046 encodeInteger(prefixBuffer, 0, base - requiredInsertCount, 7) 2047 else: 2048 encodeInteger(prefixBuffer, 0x80, 2049 requiredInsertCount - base - 1, 7) 2051 return encoderBuffer, prefixBuffer + streamBuffer 2053 Appendix D. Change Log 2055 *RFC Editor's Note:* Please remove this section prior to 2056 publication of a final version of this document. 2058 D.1. Since draft-ietf-quic-qpack-17 2060 Editorial changes only 2062 D.2. Since draft-ietf-quic-qpack-16 2064 Editorial changes only 2066 D.3. Since draft-ietf-quic-qpack-15 2068 No changes 2070 D.4. Since draft-ietf-quic-qpack-14 2072 Added security considerations 2074 D.5. Since draft-ietf-quic-qpack-13 2076 No changes 2078 D.6. Since draft-ietf-quic-qpack-12 2080 Editorial changes only 2082 D.7. Since draft-ietf-quic-qpack-11 2084 Editorial changes only 2086 D.8. Since draft-ietf-quic-qpack-10 2088 Editorial changes only 2090 D.9. Since draft-ietf-quic-qpack-09 2092 * Decoders MUST emit Header Acknowledgements (#2939) 2094 * Updated error code for multiple encoder or decoder streams (#2970) 2096 * Added explicit defaults for new SETTINGS (#2974) 2098 D.10. Since draft-ietf-quic-qpack-08 2100 * Endpoints are permitted to create encoder and decoder streams even 2101 if they can't use them (#2100, #2529) 2103 * Maximum values for settings removed (#2766, #2767) 2105 D.11. Since draft-ietf-quic-qpack-06 2107 * Clarify initial dynamic table capacity maximums (#2276, #2330, 2108 #2330) 2110 D.12. Since draft-ietf-quic-qpack-05 2112 * Introduced the terms dynamic table capacity and maximum dynamic 2113 table capacity. 2115 * Renamed SETTINGS_HEADER_TABLE_SIZE to 2116 SETTINGS_QPACK_MAX_TABLE_CAPACITY. 2118 D.13. Since draft-ietf-quic-qpack-04 2120 * Changed calculation of Delta Base Index to avoid an illegal value 2121 (#2002, #2005) 2123 D.14. Since draft-ietf-quic-qpack-03 2125 * Change HTTP settings defaults (#2038) 2127 * Substantial editorial reorganization 2129 D.15. Since draft-ietf-quic-qpack-02 2131 * Largest Reference encoded modulo MaxEntries (#1763) 2133 * New Static Table (#1355) 2135 * Table Size Update with Insert Count=0 is a connection error 2136 (#1762) 2138 * Stream Cancellations are optional when 2139 SETTINGS_HEADER_TABLE_SIZE=0 (#1761) 2141 * Implementations must handle 62 bit integers (#1760) 2143 * Different error types for each QPACK stream, other changes to 2144 error handling (#1726) 2146 * Preserve header field order (#1725) 2148 * Initial table size is the maximum permitted when table is first 2149 usable (#1642) 2151 D.16. Since draft-ietf-quic-qpack-01 2153 * Only header blocks that reference the dynamic table are 2154 acknowledged (#1603, #1605) 2156 D.17. Since draft-ietf-quic-qpack-00 2158 * Renumbered instructions for consistency (#1471, #1472) 2160 * Decoder is allowed to validate largest reference (#1404, #1469) 2162 * Header block acknowledgments also acknowledge the associated 2163 largest reference (#1370, #1400) 2165 * Added an acknowledgment for unread streams (#1371, #1400) 2167 * Removed framing from encoder stream (#1361,#1467) 2169 * Control streams use typed unidirectional streams rather than fixed 2170 stream IDs (#910,#1359) 2172 D.18. Since draft-ietf-quic-qcram-00 2174 * Separate instruction sets for table updates and header blocks 2175 (#1235, #1142, #1141) 2177 * Reworked indexing scheme (#1176, #1145, #1136, #1130, #1125, 2178 #1314) 2180 * Added mechanisms that support one-pass encoding (#1138, #1320) 2182 * Added a setting to control the number of blocked decoders (#238, 2183 #1140, #1143) 2185 * Moved table updates and acknowledgments to dedicated streams 2186 (#1121, #1122, #1238) 2188 Acknowledgments 2190 The IETF QUIC Working Group received an enormous amount of support 2191 from many people. 2193 The compression design team did substantial work exploring the 2194 problem space and influencing the initial draft. The contributions 2195 of design team members Roberto Peon, Martin Thomson, and Dmitri 2196 Tikhonov are gratefully acknowledged. 2198 The following people also provided substantial contributions to this 2199 document: 2201 * Bence Beky 2203 * Alessandro Ghedini 2205 * Ryan Hamilton 2207 * Robin Marx 2209 * Patrick McManus 2211 * 奥 一穂 (Kazuho Oku) 2213 * Lucas Pardue 2215 * Biren Roy 2217 * Ian Swett 2218 This draft draws heavily on the text of [RFC7541]. The indirect 2219 input of those authors is also gratefully acknowledged. 2221 Buck's contribution was supported by Google during his employment 2222 there. 2224 A portion of Mike's contribution was supported by Microsoft during 2225 his employment there. 2227 Authors' Addresses 2229 Charles 'Buck' Krasic 2230 Netflix 2232 Email: ckrasic@netflix.com 2234 Mike Bishop 2235 Akamai Technologies 2237 Email: mbishop@evequefou.be 2239 Alan Frindell (editor) 2240 Facebook 2242 Email: afrind@fb.com