The qpack_static_table_version TLS extension

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 12 May 2024.¶

Copyright Notice

Copyright (c) 2023 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

HTTP/3 uses QPACK [RFC9204] 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.¶

2. QPACK Static Table Background

The original QPACK static table [RFC9204] contains 99 entries (starting at entry 0, ending at entry 98), as follows:¶

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):¶

0
[offset-to-:authority-value]
17
1
5
[offset-to-cookie-value]
[offset-to-myheader-name]
[offset-to-myheader-value]
29
www.example.com
cookie1=abc;cookie2=def
myheader
xxx

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.¶

3. 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.¶

4. QPACK Static Table Additions

5. 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.¶

6. 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 [RFC8446]:¶

struct {
    uint8 StaticTableSupportedVariant;
    uint8 StaticTableSupportedLength;
} StaticTableSupportedArray;

struct {
    uint8  StaticTableSupportedCount;
    struct StaticTableSupportedArray[1...99];
} qpack_static_table_version;

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 Section 7 for an example of this.¶

Sample pseudocode processing for client and server:¶

set variable CV to 1
set variable CL to max supported length for Variant 1

for (CC = 0 to number-of-supported-variants) {
    set StaticTableSupportedVariant[CC] to supported Variant
    set StaticTableSupportedLength[CC] to supported length of Variant
}
set StaticTableSupportedCount to CC

Include qpack_static_table_version in ClientHello

if (ServerHello does not contain qpack_static_table_version) {
    goto error
} else {
    save qpack_static_table_version from ServerHello as SC,SV,SL
    if (SC != 1) {
        goto exit
    } else {
        if (SV is not a supported Variant) {
            goto exit
        }
        if (SL > supported length for Variant SV) {
            goto exit
        }
        set CV to SV
        set CL to SL
    }
}
exit:
    use CV,CL for static table index processing

set variable SC to 1
set variable SV to supported Variant value
set variable SL to supported Length value for Variant SV

if (ClientHello does not contain qpack_static_table_version or if qpack_static_table_version contains invalid values) {
    set SV to 1
    set SL to 99
} else {
    save qpack_static_table_version from ClientHello as CC,[CV,CL]
    for (SC = 0 to CC) {
        if (CV[SC] == SV) {               # matching Variant
            if (CL[SC] <= SL) {           # shorter/same Length
                set SL to CL[SC]
                goto exit
            }
        }
    }
    # non-matching Variant/Length - fall back to Variant 1;99
    set SV to 1
    set SL to 99
    Include qpack_static_table_version with values 1,[SV,SL] in ServerHello
}
exit:
    Use SV,SL for static table index processing

7. Processing Examples

Example published registries (after some time has passed and multiple registries have been created):¶

Example values passed for the qpack_static_table_version:¶

8. 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:¶

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 [RFC9204].¶

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.¶

9. Security Considerations

This document should not affect the security of the Internet.¶

Acknowledgements

Many thanks to Rich Salz and Mike Bishop at Akamai for their invaluable help.¶

Author's Address