Client Hints is collection of HTTP and user-agent features that enables privacy-preserving proactive content negotiation with explicit third party delegation mechanism:
- Proactive content negotiation at the HTTP layer (defined in the IETF I-D) enables servers to request delivery of specific hints to enable optimized and automated selection of resources based on the user's device conditions and preferences, and enables client to decide which hints requests they respect with a per-origin granularity.
- Origin scoped, opt-in nature of negotiation (to be defined as part of the HTML and Fetch specifications) enables the client to only advertise requested hint data (e.g. user agent and device characteristics) to select 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 Feature Policy, enabling tight control over which third party origins can access requested hint data.
The goal of Client Hints is to reduce active 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.
This document outlines the Client Hints infrastructure, explains it at a higher level and points to the various specification and draft proposals in which it is officially defined. It does not describe the various features and hints which rely on the infrastructure. They will be defined in their respective specifications.
How can servers opt into receiving hints from the client? How should client send those hints? And how should that be handled across origins?
Servers can opt-in to Client Hints by using the HTTP response headers described
in the sections below. For security and privacy reasons, the opt-in must be
received on the response of the top-level navigation, over a secure connection.
They can similarly opt-in by using the headers' HTML equivalents, the <meta>
HTML tag and its http-equiv
attribute.
The Accept-CH
header enables servers to request specific hints from the
browser. The header's value is a comma separated list, where each value in that
list represents a request header hint that the server is interested in
receiving.
When an Accept-CH
opt-in is received on the top-level navigation, same-origin
subresource requests on that page will receive the requested hints.
If the server's response to the navigation request includes the Accept-CH: foo, bar
header, same-origin subresource requests on the page will include the
Sec-Foo: foo-value
and Sec-Bar: bar-value
request headers.
In order to enable delivery of hints for future navigation requests to the
origin, on top on subresource requests, the server can use Accept-CH-Lifetime
header to communicate an integer value, which represents the number of seconds,
indicating a preference for how long this policy should be kept by the
browser.
If the server's response to the navigation request includes the Accept-CH: foo, bar
and Accept-CH-Lifetime: 3600
, same-origin requests on that origin
will include the Sec-Foo: foo-value
and Sec-Bar: bar-value
request headers
for the next hour, including the navigation requests of future navigations.
The opt-in mechanism description above includes the fact that the opt-in is only applied to same-origin requests, and only when it is received on a navigation resource. Why is that important?
As mentioned before, we don't want the mechanism to be used to increase fingerprinting on the web. The hints that Client Hints provides should generally be available through Javascript APIs (see the Privacy Considerations section for more details).
That means that for active resources (e.g. HTML), Client Hints does not
increase the active fingerprinting surface. Those resources can already
exfiltrate that data, via scripts, styles or certain elements (e.g. <img srcset>
). Client Hints only provides them with a more convenient and
performant way to do that, when that data is needed for content negotiation
purposes.
But, that also means that we don't want passive cross-origin subresources (e.g. images) to be able to exfiltrate the same data without explicit permission, and we certainly don't want them to be able to exfiltrate it for the entire origin, beyond the lifetime of the current navigation.
Therefore, by default, Client Hints opt-in is only valid when delivered on top-level navigation requests, and applies only to same-origin resources by default. Hint access to cross-origin requests requires explicit delegation by the first-party origin.
If Client Hints are only being sent on same-origin requests, how can we handle cross-origin requests?
As the use-case for client hints is to enable content negotiation at scale, and as many optimization services are offered over different origins than the main page's origin, cross-origin support is a vital part of client hints.
In order to support that use-case, we have defined delegation of client hints to specific cross-origin hosts, using Feature Policy.
Servers can opt-in to such delegation by applying ch-
prefixed policies for
the desired hints.
A server sending the following header Feature-Policy: ch-example foo.com bar.com; ch-example-2 foobar.org
will delegate the example
hint to the
"foo.com" and "bar.com" origins and example-2
to the foobar.org origin. That
would enable those origins to receive those hints and perform content
adaptation based on them.
Why is it privacy safe for pages to delegate hints to certain third party origins?
Since we're treating Client Hints as an active fingerprinting equivalent, we are comfortable with the information it exposes to servers, as the same information is already freely available in the equivalent Javascript APIs. Similarly, third party delegation is safe because pages are already able to use other means, such as link decoration, to achieve the same information sharing with third parties, only in less performant ways.
Adding new request headers increases the risk that legacy server systems already use those values for a different purpose. Changing the request header values such legacy systems receive may result in server bugs.
While that risk is significantly mitigated by the opt-in mechanisms of Client
Hints (as those same servers would be opting in to get those headers), we feel
it is required to mitigate it even further. So, Client Hints request headers
should be preceded by Sec-
prefix.
The Sec-
prefix also ensures that these headers are only generated by the
browser and not added by potentially-malicious developers. That gives servers
further guarantees when processing those headers. It may also enable us to
simplify the related Fetch processing model, as it clearly indicates that these
are headers that were added by the user agent.
When adapting content to specific client hints request headers, servers should
add the Vary
header to their responses to indicate such adaptation to caches,
and make sure that such resources are not cached using only their URL as the
cache key.
This is also the reason that each Client Hint is represented using a separate header, in order to reduce cache variance in responses that may rely on some hints, but not others.
There are a few key mechanisms we already discussed that are part of the Client Hints infrastructure, and which enable secure and privacy preserving deployment of Client Hints:
- Server opt-ins must be delivered on a top-level navigation request, over a secure connection.
- Hints are delivered only to same-origin requests, over a secure connection.
- If hints are required for certain third party hosts, the first-party content can explicitly delegate specific hints to specific servers.
- Hints are
Sec-
prefixed, to provide servers with more confidence regarding the values they deliver, as well as to avoid legacy server bugs.
Beyond that, when implementing Client Hints, browsers should make sure that certain privacy related precautions are being taken:
- Client Hint features should not be shipped unless there is a Javascript-based
equivalent API, which enables developers access to the same data and is
deemed privacy-safe to ship
- One reason for that is Extensible Web principles — we want the
shipped features to be somewhat polyfillable (Even if
Sec-
headers cannot be added by developers) - As discussed above, from a privacy perspective, we consider Client-Hints to be a potential active fingerprinting vector equivalent. Therefore, it is only safe to ship with it hints which provide information that is already available through other active fingerprinting means, such as a Javascript API.
- One reason for that is Extensible Web principles — we want the
shipped features to be somewhat polyfillable (Even if
- Browsers should turn off hints when users choose to turn off Javascript
- If the user has turned off Javascript, that means that the Javascript-based equivalent active fingerprinting vectors have been disabled. Since that could have been the user's intention when turning off scripting, browsers should respect that and similarly turn off Client Hints.
- Browsers can choose to omit or to lie about certain Client Hints to increase
their users' privacy
- Browsers are free to take privacy-enhancing heuristics into account when deciding to respect the server's opt-in to receive them. Similar heuristics can also be used when deciding what values they should be sending.
- Accept-CH-Lifetime persistence should not outlast other types of origin state
- Browsers typically provide their users with means to clear state regarding
certain origins: for example, delete the cache for an origin or its
cookies. When users take such an action, it is likely that they want to get
rid of all implicit state the browser may hold regarding that origin. Since
the
Accept-CH-Lifetime
opt-in hold origin state in the browser for a period of predetermined time, its associated state needs to be similarly evicted when such user actions are taken.
- Browsers typically provide their users with means to clear state regarding
certain origins: for example, delete the cache for an origin or its
cookies. When users take such an action, it is likely that they want to get
rid of all implicit state the browser may hold regarding that origin. Since
the
When we need to choose a solution that will provide alternative resources to the user's browser based on various factors, we are faced with a design dillema: We can provide the browser with a list of all potential URLs and let the browser choose the best one, or we can use content negotiation and pick the best fit resource variant on the server.
The former option certainly has its place, and it is used successfully across
the web in examples like <picture>
, srcset
, <video>
, etc.
At the same time, there are some use-cases where it is not sufficient. Transformation and adaptation of the page's subresources in a manner that is independent from the page's markup can result in more scalable and dedicated solutions, that don't have to be assimilated to markup related workflows.
By decoupling the resource selection from markup, we can enable external services to perform those transformations automatically. We can also provide a wider range of resources, as offering more resources may result in some server-side costs, but those costs are not directly exposed to the user in the form of markup bloat.
There are many potential dimensions by which we'd want the content adapted to the user:
- Device characteristics
- Screen dimensions
- Screen density
- Memory and CPU capabilities
- Range of colors the screen can display
- Browser characteristics
- User Agent major or full version
- Device model, OS version and platform
- Supported formats and codecs
- User preferences
- Data saving preferences
- Preferred language
- Network conditions
- RTT
- Effective bandwidth
The list above is not necessarily exhaustive, but it can give us an idea as to why simply providing the browser with URLs for all the above dimensions and their permutations may not be practical, at least in some cases.
Client Hints requires that the server explicitly advertise and request a set of hints it would like to receive. This makes such requests explicit and does not enable passive fingerprinting using those hints, which is one of the key and guiding requirements for Client Hints.
Beyond that, exposing all details and adaptation dimensions to all servers runs a risk of bloating request headers. There are many potential details that can be useful for content negotiation, and we expect that list to grow over time. Sending all the hints all the time can quickly result in bloat, and make requests significantly larger than they should be. To avoid that, it is more efficient for servers to specifically request the headers they would take into account, and send only these hints with upgoing requests.
Unfortunately, that decision doesn't come without tradeoffs. Client Hints as an opt-in mechanism currently means that content adaptation of the initial navigation request on the very first view is not possible, at least not without hacks.
At the same time, for features which are critical for content negotiation of navigation requests, browsers may choose to send them regardless of a server opt-in, in case it deems exposing that information as something that doesn't increase the passive fingerprinting surface.
Note: there may be other, out of band, opt-in mechanisms in the future that could enable delivery of hints on first navigation to new origins, such as Origin Policy.
Content negotiation is typically viewed as a mechanism that enables passive fingerprinting, by adding different bits of data to different user's requests by default, and enabling servers to use that to tell users apart without leaving any trace of that activity.
The Client Hints infrastructure and its opt-in enables us to avoid that, as servers need to tell the browsers which information they need, making any such fingerprinting use detectable.
But, Client Hints can also enable us to do more than that for user privacy, and
turn passive-fingerprinting-enabling content-negotiation mechanisms (e.g. The
User-Agent
or Accept-Language
request headers) into opt-in-only mechanisms.
That would effectively reduce the passive fingerprinting surface on the web,
and enable browser to keep closer tabs on entities that use that information
for seemingly nefarious reasons.
Client hints is a powerful content negotiation mechanism that enables us to adapt the content to the user's needs without compromising their privacy. It does that through the use of server opt-in, to guaranty that access to the information requires active and tracable action on the server's side. As such, the mechanism does not increase the web's current active fingerprinting surface.
The Client Hints infrastructure can be further used to reduce the web's passive
fingerprinting surface, by converting common use-cases for today's passive
fingerprinting vectors (e.g. the User-Agent
string) into Client Hints which
require a specific opt-in.