]> The qpack_static_table_version TLS extension Akamai Technologies Inc.
rhewitt@akamai.com
General Internet Engineering Task Force qpack static table version http/3 h3 tls extension This document specifies a new "qpack_static_table_version" TLS extension to enable clients and servers to agree upon the version of the HTTP/3 QPACK Static Table to use for communications between them. It also defines a new IANA registry to be used for documenting and publishing the entries in the QPACK static table. About This Document Status information for this document may be found at . Discussion of this document takes place on the HTTP Working Group mailing list (), which is archived at . Working Group information can be found at . Source for this draft and an issue tracker can be found at .
Introduction HTTP/3 uses QPACK for compression of the header and trailer sections. QPACK reuses core concepts from the HPACK algorithm used for HTTP/2, but as noted in its design "[...]is redesigned to allow correctness in the presence of out-of-order delivery, with flexibility for implementations to balance between resilience against head-of-line blocking and optimal compression ratio." A central feature of QPACK is the use of a 'static table' which contains a predefined list of frequently-used field names or field name/value combinations (generically "field strings"), each of which is identified by a unique, unchanging index in the table. To minimize over-the-wire bytes, clients and servers can pass this index rather than the field string itself in the header section of the request or reponse. Less frequently-used field strings are defined as ASCII text in the QPACK 'dynamic table'. Because of the optimal compression, defining field strings in the static table is significantly desirable over passing them in the dynamic table. When the static table was originally defined, the entries it contained were calculated by determining the relative frequency with which each field string was found in a representative sampling of web traffic. However, as new HTTP fields become more frequently-used over time, it makes sense that they be added as additional entries to the static table to retain the high level of compression. This specification defines a new TLS extension which can be passed by both client and server to identify and agree on the version (size) of the static table that they will both use. Because the size of the static table must be known prior to any HTTP requests passing between the client and server, this information must be passed during the TLS handshake. This specification also defines a new IANA registry where the entries in the QPACK static table will be published and updated. Additional related registries will be created over time.
Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The following terms are used in this document:
  • HTTP fields: Metadata sent as part of an HTTP message. The term encompasses both header and trailer fields. Colloquially, the term "headers" has often been used to refer to HTTP header fields and trailer fields; this document uses "fields" for generality.
  • HTTP field line: A name-value pair sent as part of an HTTP field section. See Sections 6.3 and 6.5 of .
  • HTTP field value: Data associated with a field name, composed from all field line values with that field name in that section, concatenated together with comma separators.
  • HTTP field string: A field name or field name/value combination, as stored in the QPACK static table.
Note that QPACK is a name, not an abbreviation.
QPACK Static Table Background The original QPACK static table contains 99 entries (starting at entry 0, ending at entry 98), as follows:
Entry Value Notes
0 (first entry) :authority Field name only
1 :path   / Field name/value combination
2 Age   0 Field name/value combination
...2 - 97...
98 (last entry) x-frame-options   sameorigin Field name/value combination
The table was generated by analyzing actual Internet traffic in 2018 and including the most common header fields, after filtering out some unsupported and non-standard values. Due to this methodology, some of the entries may be inconsistent or appear multiple times with similar but not identical values. The order of the entries is optimized to encode the most common header fields with the smallest number of bytes. For example, an HTTP/3 request which nominally passes the following six headers:
  • :authority: www.example.com (entry 0 in static table as field name only)
  • :method: GET (entry 17 in static table as field name/value)
  • path: / (entry 1 in static table as field name/value)
  • cookie: cookie1=abc;cookie2=def (entry 5 in static table as field name only)
  • myheader: xxx (not specified in static table)
  • accept: */* (entry 29 in static table as field name/value)
would actually pass the following in a header 'blob' (low-level technical formatting elided and new lines added for comprehension):
Header blob consisting of references to static and dynamic table entries
Thus many headers (e.g. "accept: */*") can be passed as simple static table indexes, each of which is only 2 or 3 bytes. Where the static table entry doesn't include a field value (e.g. :authority), there will also be an offset to the related value in the header blob.
QPACK Static Table Problems The QPACK static table functionality, whilst elegant and highly efficient, has a number of problems:
  1. The headers included in the static table may have been the most frequently used in 2018, but that was (as of the writing of this RFC) five years ago, and things change - new headers are brought into use and become very common - more common than some of the entries in the static table. An example is the various Client Hints headers (Accept-CH and the various Sec-CH-* headers). Because these headers are not included in the static table, they must always be encoded in the dynamic table, thus not taking advantage of the data reduction benefits of using static table indexes.
  2. Some of the values in the static table are actually incorrect - for example, entries 73 and 74 are both for the access-control-allow-credentials field name, but the two values specified (TRUE and FALSE) are both invalid for that field name. Whilst there may be some benefit to passing invalid values (if they are truly frequently passed, even if they are invalid, there is benefit in passing them in as minimal a value as possible), it doesn't sit well that these values are being passed at all.
  3. It doesn't allow for the fact that some 'micro' clients may not wish to include the entire static table, especially if they either use vendor-specific headers that are not included in the current table or if they only use a small subset of the headers in the table.
Therefore, it makes sense to devise a system to both define variants of the static table (containing more, fewer or different entries), which clients and servers can choose to use and also to define a means for those clients and servers to negotiate the static table they will use - this must clearly occur before any HTTP requests which use the table.
QPACK Static Table Additions
Standard registries Initially, a registry called QPACK Static Table Variant 1 will be created and maintained by IANA in which the initial QPACK static table will be published. See for more details. Over time, subsequent related registries using a naming convention of QPACK Static Table Variant N (where N is an integer incremented by 1 from the prior registry) will be created to contain a re-ordered copy of the table that is defined in the prior registry. Each registry will have two 'attributes' that are used by clients and servers during TLS negotiation - a Variant (part of the registry name) and a Length (the number of entries in the registry). In this document, a registry may be referred to using the shorthand of "Variant;Length" - for example "1;99". The initial registry (Variant 1) will have 99 entries (Length 99), shorthandedly known as 1;99. These values match the initial value of the QPACK static table as defined in the QPACK RFC . Every subsequent registry will have a Length value greater than or equal to 99. Periodically (see for proposed periods), IESG designated experts will re-sample actual internet traffic and as new field strings are found to have become more prevalent than the current last entry in the registry with the highest Variant, the new field strings will be ordered by prevalence with one another (if more than one field string) and appended as new entries to that registry. Periodically (see for proposed periods), a new QPACK Static Table Variant N registry will be created (where N is incremented by 1 from the prior registry Variant). This registry will contain all the entries in the prior registry Variant, but they will all be re-ordered, to ensure that the most commonly-found header lines are near the start of the table. When a new QPACK Static Table Variant N registry is published, all prior registries are 'locked' and will not be changed; new entries will not be appended to them. Thus at any time, there may be multiple concurrently-published QPACK Static Table registries, each with a different Variant.
Example Note that with the exception of the initial length of the QPACK Static Table Variant 1 registry, this section is hypothetical Initially the QPACK Static Table Variant 1 registry is published and contains 99 entries. This is the table that is defined in the QPACK RFC. After a certain period of time, web traffic is re-sampled and it is found that 12 new field strings exist which are more common than "x-frame-options: sameorigin" (entry 99 in the Variant 1 registry). These 12 field strings are ordered by prevalence relative to each other and appended as entries 100-111 to the QPACK Static Table Variant 1 registry. After another period of time, internet traffic is re-sampled again and it is found that 5 new field strings exist which are more common than entry 111 in the Variant 1 registry. Again, these 5 field strings are ordered by prevalence relative to each other and appended to the QPACK Static Table Variant 1 registry. At the same time, a new registry, QPACK Static Table Variant 2, is published. This registry contains all 116 entries from the QPACK Static Table Variant 1 registry, re-ordered in order of total prevalence. The QPACK Static Table Variant 1 registry is locked. There are now two registries:
  • QPACK Static Table Variant 1 containing 116 entries: [LOCKED] Entries 0-98 are in the same order as the initial QPACK table. Entries 99-111 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-98. Entries 112-116 are ordered by prevalence with one another but not with any prevalence relative to entries 0-111.
  • QPACK Static Table Variant 2 containing 116 entries: All entries are ordered by prevalence compared to one another.
After a period of time, 3 new field strings exist which are more common than entry 116 in QPACK Static Table Variant 2. These 3 field strings are ordered by prevalence relative to each other and appended to the QPACK Static Table Variant 2 registry. At this point there are still two registries: - the Variant 1 registry is locked and the Variant 2 registry has changed:
  • QPACK Static Table Variant 1 containing 116 entries: [LOCKED] Entries 0-98 are in the same order as the initial QPACK table. Entries 99-111 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-98. Entries 112-116 are ordered by prevalence with one another but not with any prevalence relative to entries 0-111.
  • QPACK Static Table Variant 2 containing 119 entries: Entries 0-116 are ordered by prevalence compared to one another. Entries 117-119 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-116.
After a period of time, 4 new field strings exist which are more common than entry 119 in QPACK Static Table Variant 2. These 4 field strings are ordered by prevalence relative to each other and appended to the QPACK Static Table Variant 2 registry. At the same time, a new registry, QPACK Static Table Variant 3, is published. This contains all the entries from the Variant 2 registry, re-ordered in order of total prevalence. The QPACK Static Table Variant 2 registry is locked. There are now three registries:
  • QPACK Static Table Variant 1 containing 116 entries: [LOCKED] Entries 0-98 are in the same order as the initial QPACK table. Entries 99-111 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-98. Entries 112-116 are ordered by prevalence with one another but not with any prevalence relative to entries 0-111.
  • QPACK Static Table Variant 2 containing 123 entries [LOCKED]: Entries 0-116 are ordered by prevalence compared to one another. Entries 117-119 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-116. Entries 120-123 are ordered by prevalence with one another, but not with any prevalence relative to entries 0-119.
  • QPACK Static Table Variant 3 containing 123 entries: All entries are ordered by prevalence compared to one another.
This process continues, with new header lines periodically being appended to the latest registry Variant and a new registry Variant of the table periodically being created.
Vendor registries Additionally, registries can be proposed by any third-party vendor or similar interested party, which can contain any of the following:
  • Any subset of the entries from any other existing registry, in any order
  • Versions of the entries in any other registry with the same field name but a different field value
  • Vendor specific entries which are inappropriate for general use
Thus different vendors can propose their own registries which include only field strings that they use - this allows those vendors to minimize the size of the static table to only the minimal set of field names and values that are appropriate to their business, and which are possibly recognized only by their own client and server software. These vendor-defined registries MUST have a naming format of QPACK Static Table Variant nnn where 'nnn' represents any three digit number from 200 to 999. The publication of vendor-defined registries is at the discretion of IANA. See for more details.
QPACK Static Table support HTTP/3-supporting clients and servers MUST always support QPACK Static Table Variant 1 with a Length of 99. They MAY also support other registry Variant/Length combinations.
The qpack_static_table_version TLS extension The qpack_static_table_version TLS extension is a structure which represents the following
  • When sent in a request from the client to the server, it represents one or more registry Variant/Length combinations supported by the client.
  • When sent in a response from the server to the client, it represents the single negotiated Variant/Length combination from the list sent by the client that will be used by both client and server.
The qpack_static_table_version TLS extension is OPTIONAL and MAY be sent by either client or server or both or neither. Rules for how its existence or absence should be handled are described below. The extension_data for the qpack_static_table_version extension is described below using the syntax defined in :
The StaticTableSupportedCount field specifies the number of entries in StaticTableSupportedArray. When passed in a request from a client to a server, it MUST have a value from 1 to 99 inclusive; any other value is invalid and the server MUST treat this as if a single entry in the StaticTableSupportedArray array was passed by the sender with StaticTableSupportedVariant having a value of 1 and StaticTableSupportedLength having a value of 99. When passed in a response from a server to a client, it MUST have a value of 1. The following specifications apply to each entry in StaticTableSupportedArray when passed in a request from a client to a server:
  • The StaticTableSupportedVariant field must be a positive integer and indicates client support for that Variant registry. A negative value or a value of 0 is invalid and the server MUST ignore that StaticTableSupportedArray array entry.
  • The StaticTableSupportedLength field must be a positive integer. A negative value or a value of 0 is invalid and the server MUST ignore that StaticTableSupportedArray array entry. A value that is lower than the current length of the registry Variant identified by the StaticTableSupportedVariant field (as known by the server) is valid; this allows a client which may have very limited memory and/or which expects to send/receive only a few known headers to specify a low Length. For example, a client could pass 1;30, indicating that they support only the first 30 entries in the QPACK Static Table Variant 1 registry and any other header lines must be specified in the dynamic table.
The qpack_static_table_version extension MAY be passed by a client to a server in the ClientHello, to indicate one or more registry Variants and the associated Length of each Variant that that the client supports. If the qpack_static_table_version extension is not present in the ClientHello, the server MUST assume that the client supports QPACK Static Table Variant 1 up to 99 entries. If the qpack_static_table_version extension is not passed by a client in the ClientHello, the server MUST NOT pass the qpack_static_table_version extension in the ServerHello, and MUST use QPACK Static Table Variant 1 up to 99 entries. If the ClientHello includes the qpack_static_table_version extension, the server MAY respond in the ServerHello with its own copy of the qpack_static_table_version extension, which MUST specify a StaticTableSupportedCount value of 1 and MUST contain only a single entry in the StaticTableSupportedArray array. This returned entry MUST match one of the entries passed in the client's qpack_static_table_version extension, indicating the server's preferred choice of registry. If either the ClientHello or the ServerHello do not include the qpack_static_table_version extension, or if an invalid value is specified for any of its component fields, then both client and server MUST fall back to use QPACK Static Table Variant 1 up to 99 entries. If the client passes the qpack_static_table_version extension with one or more valid values and the server responds with a single valid value as noted above, the client MUST use that value. Note that the chosen Variant and Length may be separately derived from either client or server. See example 5 in for an example of this. Sample pseudocode processing for client and server:
Client processing supported length for Variant SV) { goto exit } set CV to SV set CL to SL } } exit: use CV,CL for static table index processing]]>
Server processing
Processing Examples Example published registries (after some time has passed and multiple registries have been created):
Variant Length
1 116
2 123
3 123
Example values passed for the qpack_static_table_version:
Example Client qpack_static_table_version passed Server supported Variant/Length Variant/Length used Notes
1 not passed not passed 1;99 Neither client nor server passed the extension, so both use the default 1;99 Variant.
2 not passed 2;116 1;99 The client did not pass the extension, so both use the default 1;99 Variant.
3 1;114 not passed 1;99 The server did not pass the extension, so both use the default 1;99 Variant.
4 1;99, 2;123 1;116 1;99 The client indicates support for two Variants. The server only supports Variant 1. Because the client passed a lower Length for Variant 1, the client Length (99) is used.
5 1;116, 2;123, 301,15 1;101 1;101 The client indicates support for two standard Variants and one vendor Variant. The server only supports standard Variant 1. Because the server passed a lower Length for Variant 1, the server Length (101) is used.
6 215;30, 216;30 1;99 1;99 The client indicates support for two vendor Variants. The server does not support any Vendor variants, so it passes 1;99. Note that the client MUST support 1;99 even if it does not advertise support for it.
IANA Considerations This memo requests that IANA creates a registry for the QPACK static table, to be periodically updated and supserseded by IESG-appointed Designated Expert(s). The registry name is QPACK Static Table Variant 1 and is part of the Transport Layer Security (TLS) registry grouping. The registration policy is Expert Review. The registry will contain a copy of the QPACK static table ("table"). Each entry in the table consists of the following three fields:
Field Type Notes
Index Unsigned Integer First entry has Index 0, then 1, 2 etc.
Name String Field name - follows field name validation specified in Section 5.1 of . Case-insensitive, but per convention, specify in lower-case
Value String Field value - follows field value validation specified in Section 5.5 of . Case-sensitive. MAY BE BLANK
The initial set of entries in the registry will be copied directly from the entries in the QPACK static table defined in Appendix A in . As per the technical information in this document, on a periodic basis, the Designated Expert(s) will sample HTTP/3 web traffic and may, as a result, append new entries to the registry. It is suggested that the sampling process occurs approximately once every year, but the decision of whether to append new entries to the registry may occur at a slower rate, since it depends entirely on the rate at which new fields become sufficiently prevalent in HTTP/3 web traffic. On a separate periodic basis, a new registry will be created using the same format as the above registry, but will be named QPACK Static Table Variant N (where N is an integer incremented by 1 from the prior registry). This new registry will be a re-ordered copy of the prior registry. When a new QPACK Static Table registry is created, all prior registry versions must be locked and no new entries can be appended to them. It is suggested that this process happens approximately once every three years, but again, it depends on the results of the HTTP/3 web traffic sampling. The intention is that any appending of new entries to the registry and/or the creation of a new QPACK Static Table registry will be accompanied by a published RFC. But in order to allow for the allocation of values prior to the RFC being approved for publication, the Designated Expert can undertake either action once it seems clear that an RFC will be published. The Designated expert will post a request to the HTTP WG mailing list (or a successor designated by the Area Director) for comment and review, including an Internet-Draft.
Security Considerations This document should not affect the security of the Internet.
References Normative References
Acknowledgements Many thanks to Rich Salz and Mike Bishop at Akamai for their invaluable help.