Archived: Client Hints Infrastructure

This is a simplified archive of the page at https://wicg.github.io/client-hints-infrastructure/

Use this page embed on your own site:

Client Hints is collection of HTTP and user-agent features that enablesprivacy-preserving, proactive content negotiation with an explicit third-partydelegation mechanism:

ReadArchived

1. Introduction

Client Hints is collection of HTTP and user-agent features that enables privacy-preserving, proactive content negotiation with an explicit third-party delegation mechanism:

  • Proactive content negotiation at the HTTP layer enables servers to request delivery of specific hints, in order to enable optimized and automated selection of resources based on a user’s device, conditions and preferences, and lets clients decide which hint requests they want to grant, with per-hint and per-origin granularity.

  • Integration of said mechanism with web concepts, defined in this document, enables browsers to benefit from content adaptation, and have it play nicely with current web restrictions (e.g. same-origin policy).

  • The opt-in nature of the mechanism enables browsers to advertise requested hint data (e.g. user agent and device characteristics) selectively to secure-transport origins, instead of appending such data on every outgoing request.

  • Origin opt-in applies to same-origin assets only and delivery to third-party origins is subject to explicit first party delegation via Permissions Policy, enabling tight control over which third party origins can access requested hint data.

The goal of Client Hints is to reduce passive fingerprinting on the web while enabling scalable and privacy preserving content adaptation between client and server, via a standardized set of content negotiation primitives at the HTTP and user agent levels.

2. Infrastructure definition

The specification of the Client Hints infrastructure is divided between the following specifications and proposals:

  • IETF [RFC8942]

    • Provides the motivation for Client Hints.

    • Defines the fundamental Client Hints infrastructure:

      • The Accept-CH response header, which servers may use to advertise support for certain Client Hints.

    • Provides both general guidelines, and formal requirements, about Client Hints’ impact on caching, security, and privacy.

    • Does not define any actual, particular hints – or say anything about how Client Hints works in web contexts.

  • Client Hints infrastructure - this document

    • Defines how web clients should process the Accept-CH headers sent by servers.

    • Defines the environment settings object state related to Accept-CH, which stores information about which servers should get which hints.

    • Defines how, and when, web clients should actually go about sending hints, based on the state of their environment settings object.

      • More specifically, it integrates the HTML web concepts with Fetch’s algorithms to make sure that opted-in hints are added to requests for same-origin or delegated-to cross-origin requests. It also makes sure hints are removed from not delegated-to cross-origin requests after redirections.

    • Integrates those concepts with the [HTML] and [FETCH] specifications, by patching various concepts there.

  • W3C Permissions Policy specification (relevant section)

    • In order to perform third party Client Hint delegation, Permissions Policy has been extended to control features within fetch requests (rather than just Documents).

3. Environment settings object processing

3.1. Client hints set

A client hints set is a set of client hints tokens.

3.2. Accept-CH cache

An Accept-CH cache is owned by the user agent and is an ordered map, keyed on origin (an origin), with a value of client hints set (a client hints set).

The Accept-CH cache can effectively act as an alternative cookie store, since sites can use each of the hints as a bit set on the client, and that information will be communicated to them on every request. As such, a user agent MUST evict that cache whenever the user clears their cookies or when session cookies expire.

Note: A site can clear the browser’s Accept-CH cache for its origin by sending an empty Accept-CH header in a response. This sets the origin’s client hints set to an empty set.

Note: As the cache can only be modified by the top-level frame, it is considered to be partitioned.

To add a new Accept-CH cache entry to the Accept-CH cache, given an origin origin and a client hints set hintSet, set Accept-CH cache[origin] to hintSet.

When asked to retrieve the client hints set given a settingsObject:

  1. Let hintSet be an empty ordered set.
  2. Let originMatchingEntries be the entries in the Accept-CH cache whose origin is same origin with settingsObject’s origin.
  3. For each entry in originMatchingEntries, for each token in its client hints set, append the token to hintSet.
  4. For each hint in hintSet, append hint to settingsObject’s client hints set.

When asked to update the Client Hints set given a settingsObject and response:

  1. Run retrieve the client hints set with settingsObject.
  2. If the result of executing Is an environment settings object contextually secure? on settingsObject is "Not Secure", abort these steps.
  3. Let browsingContext be settingsObject’s global object's browsing context.
  4. If the top-level browsing context does not equal browsingContext, abort these steps.
  5. If response’s Accept-CH header is present, parse the header field value according to the Accept-CH header parsing rules, as a field-name. Add each parsed client hints token to settingsObject’s client hints set.
  6. Add a new Accept-CH cache entry with response’s origin and settingsObject’s client hints set.

3.3. Accept-CH state (name="accept-ch")

Note: This metadata appends client hints tokens to the environment settings object's client hints set. It does not add those hints to the Accept-CH cache. After this algorithm runs once, no further modification to the client hints set can occur without reloading the page.

  1. Let metaElement be the meta element.
  2. If metaElement is not a child of a head element, then return.
  3. If metaElement has no content attribute, or if that attribute’s value is the empty string, then return.
  4. If metaElement has any preceding sibling link or script elements (or if any link or script elements have begun to execute), then return.
  5. Let acceptCHValue be the value of metaElement’s content attribute.
  6. Let settingsObject be metaElement’s relevant settings object.
  7. Let permissionsPolicy be metaElement’s node document’s permissions policy
  8. If the result of executing Is an environment settings object contextually secure? on settingsObject is "Not Secure", then return.
  9. Let browsingContext be settingsObject’s global object's browsing context.
  10. If the top-level browsing context does not equal browsingContext, abort these steps.
  11. Let policyDirective be the result of running [$ parse-policy-directive $] on acceptCHValue and the origin of the metaElement’s node document.
    1. For each feature->allowList of policyDirective:
    2. If feature is not a client hints token, then continue.
    3. If allowList is the special value *, then continue.
    4. Append feature to settingsObject’s client hints set and Append allowList to permissionsPolicy[feature]'s permissions policy.

Note: * can still be inherited from the default policy or HTTP header permissions policy.

4. Integration with HTML

This specification integrates with the [HTML] specification by patching the algorithms below:

At process a navigate response, after step 7 call update the Client Hints set with the relevant settings object and response as inputs.

4.2. Worker initialization

At set up a worker environment settings object, after step 6, add the following step:

  1. Set settingsObject’s client hints set to be a clone of outside settings’ client hints set.

4.3. Standard metadata names

For the section standard metadata names, add a subsection named accept-ch with the outlined explanation.

4.4. Extending environment settings object

An environment settings object has a client hints set: a client hints set, initially the empty set, used for fetches performed using the environment settings object as a request client.

5. Request processing

When asked to append client hints to request with settingsObject and request as input, run the following steps:

  1. Let hintSet be an empty client hints set.
  2. Run retrieve the client hints set with settingsObject.
  3. For each client hints token lowEntropyHint in the registry’s low entropy hint table, append lowEntropyHint to hintSet.
  4. If request’s client is not null, then for each client hints token requestHint in request’s client hints set, append requestHint to hintSet.
  5. For each possibleHint in hintSet, if request is a subresource request and the result of running Permissions Policy § 9.11 Should request be allowed to use feature? given request and possibleHint’s associated feature in § 7.2 Policy-controlled features returns false, remove possibleHint from hintSet.
  6. For each hintName in hintSet, if the request’s header list does not contain hintName:
    1. Let value be the result of running find client hint value with hintName.
    2. append hintName/value to the header list

When asked to update client hints from redirect if needed with request as input, run the following steps:

  1. If request’s client is null, then abort these steps.
  2. Let clientHintsSet be request’s client’s client hints set.

  3. For each hintName of clientHintsSet:

    1. Set hintName to "Sec-" concatenated with hintName.

    2. If request’s header list contains hintName and if the result of running Should request be allowed to use feature?, given request and hintName’s associated policy-controlled feature, returns false, then remove hintName from request’s header list.

    3. Else if request’s header list doesn’t contain hintName and if the result of running Should request be allowed to use feature?, given request and hintName’s associated policy-controlled feature, returns true, then add hintName to request’s header list.

6. Integration with Fetch

This specification integrates with the [FETCH] specification by patching the algorithms below:

In Fetching, after step 1.6, run append client hints to request with the relevant settings object and request as input.

In HTTP-redirect fetch, after step 7, run update client hints from redirect if needed with request as input.

7. Feature Registry

Note: This section contains feature-specific definitions. New features that rely on the Client Hints infrastructure need to add their respective definitions to this registry. User Agents can implement some of those features without implementing others.

7.1. Client hints token

A client hints token is a byte-lowercase representation of one of Sec-CH-Save-Data, Sec-CH-DPR, Sec-CH-Width, Sec-CH-Viewport-Width, Sec-CH-Viewport-Height, Sec-CH-Device-Memory, Sec-CH-RTT, Sec-CH-Downlink, Sec-CH-ECT, Sec-CH-Prefers-Color-Scheme, Sec-CH-UA, Sec-CH-UA-Arch, Sec-CH-UA-Bitness, Sec-CH-UA-Full-Version, Sec-CH-UA-Full-Version-List, Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, or Sec-CH-UA-Platform-Version,

Note: A client hints token will also match the request header sent by the user agent when appropriate (as determined by the request processing algorithm).

7.2. Policy-controlled features

This document defines policy-controlled client hints features, the following policy-controlled features:

Should we tie low-entropy-ness to allowlists, generally?

7.3. Low entropy hint table

The low entropy hint table below defines hints that are only exposing low amounts of entropy.
Name Value
Sec-CH-Save-Data a suitable Save-Data value
Sec-CH-UA a suitable UA value
Sec-CH-UA-Mobile a suitable Mobile value
Sec-CH-UA-Platform a suitable Platform value

7.4. Find client hint value

When asked to find client hint value, given hint as input, switch on hint and return the result:

Save-Data
a suitable Save-Data value
DPR
a suitable DPR value
Viewport-Width
a suitable Viewport-Width value
Viewport-Height
a suitable Viewport-Height value
Width
a suitable Width value
Device-Memory
a suitable Device-Memory value
RTT
a suitable RTT value
Downlink
a suitable Downlink value
ECT
a suitable ECT value
Prefers-Color-Scheme
a suitable color theme value
UA
a suitable UA value
UA-Arch
a suitable Arch value
UA-Bitness
a suitable Bitness value
UA-Full-Version
a suitable Full-Version value
UA-Full-Version-List
a suitable Full-Version-List value
UA-Mobile
a suitable Mobile value
UA-Model
a suitable Model value
UA-Platform
a suitable Platform value
UA-Platform-Version
a suitable Platform-Version value

Links for image features are broken, need to actually define that and link to them.

8. Security and Privacy considerations

See [RFC8942].

9. Terms

The following terms are defined in the HTTP specifications: field-name

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.