Skip to content

Commit

Permalink
Update README to reflect HTML tag (#112)
Browse files Browse the repository at this point in the history
* Update README to reflect HTML tag

closes #111

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md
  • Loading branch information
arichiv authored Jun 29, 2022

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent 9a21e36 commit 5251c9b
Showing 1 changed file with 56 additions and 38 deletions.
94 changes: 56 additions & 38 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Explainer

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

* Proactive content negotiation at the HTTP layer (defined in the
@@ -18,9 +18,9 @@ delegation mechanism:
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 Feature Policy,
enabling tight control over which third party origins can access requested
* Origin opt-in applies to same-origin assets only and delivery to cross-origin
origins is subject to explicit cross-origin delegation via Feature Policy,
enabling tight control over which cross-origin origins can access requested
hint data.

The goal of Client Hints is to **reduce passive fingerprinting** on the web
@@ -55,23 +55,32 @@ 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, unless the
If a server's response to a 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 unless the
client has reasons to avoid sending that information to the server.

#### Example
### `Delegate-CH`

If a server's response to a 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.
The `Delegate-CH` `<meta>` HTML tag enables top level frames to request specific hints
from the browser. The header's value is a semi-colon separated list (akin to the
[Permissions Policy syntax](https://www.w3.org/TR/permissions-policy/#algo-parse-policy-directive)),
where each value in that list represents a request header hint that the server is interested in
receiving.

If the HTML response to a navigation request includes the `<meta http-equiv="Delegate-CH"
value="Sec-Foo; Sec-Bar">` tag, same-origin subresource requests on the page will include
the `Sec-Foo: foo-value` and `Sec-Bar: bar-value` request headers, unless the
client has reasons to avoid sending that information to the server.

## Same-Origin Policy

There are two important restrictions on the opt-in mechanism description above:
There are three important restrictions on the opt-in mechanism description above:

- opt-ins will only be granted when the opt-in headers are received with a
top-level navigation resource
- after the opt-in, hints will only be sent with same-origin requests
- any `Delegate-CH` `<meta>` HTML tags injected by javascript will be ignored

Why are these limitations important?

@@ -89,57 +98,66 @@ content-negotiation purposes and ensures that authors and user agents have
ultimate control over which servers get what information.

Client Hints also allow this information to be collected on *passive*
sub-resources (e.g. images). We don't want third parties to be able to
sub-resources (e.g. images). We don't want cross-origin origins to be able to
exfiltrate data about the client/user without explicit permission from the
first party. And we certainly don't want them to be able to exfiltrate it for
the entire third-party origin, beyond the lifetime of the current navigation.
top-level origin. And we certainly don't want them to be able to exfiltrate it
cross-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, by default, applies only to same-origin
resources. Cross-origin requests must only receive hints when explicit
permission is given by the first-party origin.
top-level navigation requests before any scripts execute, and, by default,
applies only to same-origin resources. Cross-origin requests must only receive
hints when explicit permission is given by the top-level document's origin.

## Cross-origin hint delegation

Why do we need cross-origin Client Hints?

As the purpose of 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(e.g., CDNs, resource-specific hosting services, or dedicated,
page's origin (e.g., CDNs, resource-specific hosting services, or dedicated,
resource-specific, first-party sub-domains), cross-origin support is a vital
part of Client Hints.

In order to support these use-cases, 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 feature policies for
the desired hints.
cross-origin, using a HTTP Permissions Policy or HTML Feature Policy.

### Example
### HTTP Example

A first-party server sending the following header `Feature-Policy: ch-example
foo.com bar.com; ch-example-2 foobar.org` as part of a top-level navigation
A server sending the following header `Permissions-Policy: ch-example=(
"foo.com" "bar.com"), ch-example-2="foobar.org"` as part of a top-level navigation
response will delegate the `example` hint to the "foo.com" and "bar.com"
origins and `example-2` to the "foobar.org" origin. So, the client would know
that it had explicit permission from the first party to send these hints to
these third parties, so that these third parties could perform content
origins and `example-2` to the "foobar.org" origin. So, the client would know
that it had explicit permission from the top-level origin to send these hints
cross-origin, so that these cross-origin origins could perform content
adaptation based on them.

### HTML Example

A top level frame containing the following `<meta>` HTML tag: `<meta accept-ch="Delegate-CH"
value="sec-ch-example foo.com bar.com; sec-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. So, the client would know that it had explicit permission from the top-level origin to
send these hints cross-origin, so that these cross-origin origins could perform content
adaptation based on them.

### Privacy implications

Why is it privacy-safe for pages to delegate hints to certain third party
origins?
Why is it privacy-safe for pages to delegate hints to certain cross-origin origins?

Since we're treating Client Hints as an active fingerprinting equivalent, we
are comfortable with the information it exposes to first-party servers, as the same
are comfortable with the information it exposes to the top-level origin, as the same
information is already freely available in the equivalent Javascript APIs.
Similarly, third party delegation is safe because first parties are already able to use
Similarly, cross-origin delegation is safe because top-level origin are already able to use
other means (such as link decoration), to achieve the same information sharing
with third parties, in less convenient and performant ways.
cross-origin, in less convenient and performant ways.

Further, the HTML delegation can only occur when the `<meta>` HTML tag is not injected
via javascript, ensuring scripts cannot delegate hints in ways that relax the restrictions
the top-level content author did not permit.

In short, first parties already have the power to share information about the
client with third parties. Third party delegation of Client Hints provides a
cleaner pathway for that sharing, and ensures that first parties, and
In short, top-level origins already have the power to share information about the
client cross-origin. Cross-origin delegation of Client Hints provides a
cleaner pathway for that sharing, and ensures that top-level origin, and
ultimately clients, are aware and in control of what is being shared with who.

## `Sec-` prefix
@@ -180,8 +198,8 @@ of Client Hints:
* Server opt-ins must be delivered on a top-level navigation request, over a
secure connection.
* Hints are only delivered with same-origin requests, over a secure connection.
* If the first party wants hints to be delivered to certain third-party hosts,
the first-party can explicitly delegate specific hints to specific hostnames.
* If the top-level origin wants hints to be delivered to certain cross-origin origins,
the top-level origin can explicitly delegate specific hints to specific origins.
* Hints are `Sec-` prefixed, to provide servers with more confidence regarding
the values they deliver, as well as to avoid legacy server bugs.

0 comments on commit 5251c9b

Please sign in to comment.