Compression Dictionary Transport

Using a previous version of a resource as a dictionary for a newer version enables delivery of a delta-compressed version of the changes, usually resulting in significantly smaller responses than can be achieved by compression alone.¶

If several resources share common patterns in their responses then it can be useful to reference an external dictionary that contains those common patterns, effectively compressing them out of the responses. Some examples of this are common template HTML for similar pages across a site and common keys and values in API calls.¶

The "match" value of the Use-As-Dictionary header is a String value that provides the URL Pattern to use for request matching (see [URLPATTERN]).¶

The URL Pattern used for matching does not support using regular expressions.¶

1. Let MATCH be the value of "match" for the given dictionary.
2. Let URL be the URL of the dictionary request.
3. Let PATTERN be an instance of the URLPattern class constructed by setting input=MATCH, and baseURL=URL (see [URLPATTERN-CLASS]).
4. If the hasRegExpGroups attribute of PATTERN is TRUE then return FALSE (see [URLPATTERN-REGEXP]).
5. Return TRUE.

The "match" value is required and MUST be included in the Use-As-Dictionary response header for the dictionary to be considered valid.¶

Operating at the HTTP-level, the specified match patterns will operate on the percent-encoded version of the URL path (see Section 2 of [URL]).¶

The "match-dest" value of the Use-As-Dictionary header is an Inner List of String values that provides a list of Fetch request destinations for the dictionary to match (see [REQUEST-DESTINATION]).¶

An empty list for "match-dest" MUST match all destinations.¶

For clients that do not support request destinations, the client MUST treat it as an empty list and match all destinations.¶

The "match-dest" value is optional and defaults to an empty list.¶

The "id" value of the Use-As-Dictionary header is a String value that specifies a server identifier for the dictionary. If an "id" value is present and has a string length longer than zero then it MUST be sent to the server in a "Dictionary-ID" request header when the client sends an "Available-Dictionary" request header for the same dictionary (see Section 2.2).¶

The server identifier MUST be treated as an opaque string by the client.¶

The server identifier MUST NOT be relied upon by the server to guarantee the contents of the dictionary. The dictionary hash MUST be validated before use.¶

The "id" value string length (after any decoding) supports up to 1024 characters.¶

The "id" value is optional and defaults to the empty string.¶

The "type" value of the Use-As-Dictionary header is a Token value that describes the file format of the supplied dictionary.¶

"raw" is defined as a dictionary format which represents an unformatted blob of bytes suitable for any compression scheme to use.¶

If a client receives a dictionary with a type that it does not understand, it MUST NOT use the dictionary.¶

The "type" value is optional and defaults to "raw".¶

To be considered as a match, the dictionary resource MUST be either fresh [HTTP-CACHING] or allowed to be served stale (see eg [RFC5861]).¶

When a dictionary is stored as a result of a "Use-As-Dictionary" directive, it includes a "match" string and optional "match-dest" string that are used to match an outgoing request from a client to the available dictionaries.¶

1. If the current client supports request destinations and a "match-dest" string was provided with the dictionary:
   • Let DEST be the value of "match-dest" for the given dictionary.
   • Let REQUEST_DEST be the value of the destination for the current request.
   • If DEST is not an empty list and if REQUEST_DEST is not in the DEST list of destinations, return FALSE
2. Let BASEURL be the URL of the dictionary request.
3. Let URL represent the URL of the outbound request being checked.
4. If the Origin of BASEURL and the Origin of URL are not the same, return FALSE (see Section 4.3.1 of [HTTP]).
5. Let MATCH be the value of "match" for the given dictionary.
6. Let PATTERN be an instance of the URLPattern class constructed by setting input=MATCH, and baseURL=BASEURL (see [URLPATTERN-CLASS]).
7. Return the result of running the "test" method of PATTERN with input=URL which will check for a match between the request URL and the supplied "match" URL Pattern (see [URLPATTERN-TEST]).

1. For clients that support request destinations, a dictionary that specifies and matches a "match-dest" takes precedence over a match that does not use a destination.
2. Given equivalent destination precedence, the dictionary with the longest "match" takes precedence.
3. Given equivalent destination and match length precedence, the most recently fetched dictionary takes precedence.

To make sure that a dictionary can only impact content from the same origin where the dictionary was served, the URL Pattern used for matching a dictionary to requests (Section 2.1.1) is guaranteed to be for the same origin that the dictionary is served from.¶

For clients, like web browsers, that provide additional protection against the readability of the payload of a response and against user tracking, additional protections MUST be taken to make sure that the use of dictionary-based compression does not reveal information that would not otherwise be available.¶

In these cases, dictionary compression MUST only be used when both the dictionary and the compressed response are fully readable by the client.¶

In browser terms, that means that both are either same-origin to the context they are being fetched from or that the response is cross-origin and passes the CORS check (see [CORS-CHECK]).¶

As with any usage of compressed content in a secure context, a potential timing attack exists if the attacker can control any part of the dictionary, or if it can read the dictionary and control any part of the content being compressed, while performing multiple requests that vary the dictionary or injected content. Under such an attack, the changing size or processing time of the response reveals information about the content, which might be sufficient to read the supposedly secure response.¶

In general, a server can mitigate such attacks by preventing variations per request, as in preventing active use of multiple dictionaries for the same content, disabling compression when any portion of the content comes from uncontrolled sources, and securing access and control over the dictionary content in the same way as the response content. In addition, the following requirements on a server are intended to disable dictionary-aware compression when the client provides CORS request header fields that indicate a cross-origin request context.¶

1. If there is no "Sec-Fetch-Site" request header then return TRUE.
2. if the value of the "Sec-Fetch-Site" request header is "same-origin" then return TRUE.
3. If there is no "Sec-Fetch-Mode" request header then return TRUE.
4. If the value of the "Sec-Fetch-Mode" request header is "navigate" or "same-origin" then return TRUE.
5. If the value of the "Sec-Fetch-Mode" request header is "cors":
   • If the response does not include an "Access-Control-Allow-Origin" response header then return FALSE.
   • If the request does not include an "Origin" request header then return FALSE.
   • If the value of the "Access-Control-Allow-Origin" response header is "*" then return TRUE.
   • If the value of the "Access-Control-Allow-Origin" response header matches the value of the "Origin" request header then return TRUE.
6. return FALSE.