Skip to content

Commit

Permalink
Issue WICG#105 - Add a UA hint for CPU bitness
Browse files Browse the repository at this point in the history
  • Loading branch information
@miketaylr
miketaylr committed Mar 13, 2021
1 parent 1aee4fa commit 5b7f97f
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 33 deletions.
28 changes: 19 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ UA-CH introduces the following [Client Hints](https://tools.ietf.org/html/rfc894
a corresponding JavaScript API:

* `Sec-CH-UA-Arch`
* `Sec-CH-UA-Bitness`
* `Sec-CH-UA-Mobile`
* `Sec-CH-UA-Model`
* `Sec-CH-UA-Platform`
Expand Down Expand Up @@ -127,32 +128,40 @@ accomplish this as follows:
which user agents might want to tell in this field and to learn more about the admittedly odd looking
`"?Not:Your Browser"; v="11"`.
2. The `Sec-CH-UA-Platform` header field represents the platform's brand and major version. For example:
1. The `Sec-CH-UA-Platform` header field represents the platform's brand and major version. For example:
```http
Sec-CH-UA-Platform: "Windows"
```
3. The `Sec-CH-UA-Arch` header field represents the underlying architecture's instruction set and
width. For example:
1. The `Sec-CH-UA-Arch` header field represents the underlying architecture's instruction set.
For example:
```http
Sec-CH-UA-Arch: "arm"
```
4. The `Sec-CH-UA-Model` header field represents the user agent's underlying device model. For example:
1. The `Sec-CH-UA-Bitness` header field represents the underlying architecture's bitness
(i.e., the size in bits of an integer or memory address).
For example:
```http
Sec-CH-UA-Bitness: "64"
```
1. The `Sec-CH-UA-Model` header field represents the user agent's underlying device model. For example:
```http
Sec-CH-UA-Model: "Pixel 2 XL"
```
5. The `Sec-CH-UA-Mobile` header field represents whether the user agent should receive a specifically "mobile"
1. The `Sec-CH-UA-Mobile` header field represents whether the user agent should receive a specifically "mobile"
UX.
```http
Sec-CH-UA-Mobile: ?1
```
6. The `Sec-CH-UA-Full-Version` header field represents the user agent's full version.
1. The `Sec-CH-UA-Full-Version` header field represents the user agent's full version.
```http
Sec-CH-UA-Full-Version: "73.1.2343B.TR"
Expand All @@ -169,18 +178,19 @@ accomplish this as follows:
};
dictionary UADataValues {
DOMString platform; // "PhoneOS"
DOMString platformVersion; // "10A"
DOMString architecture; // "arm"
DOMString bitness; // "64"
DOMString model; // "X644GTM"
DOMString platform; // "PhoneOS"
DOMString platformVersion; // "10A"
DOMString uaFullVersion; // "73.32.AGX.5"
};
[Exposed=(Window,Worker)]
interface NavigatorUAData {
readonly attribute FrozenArray<NavigatorUABrandVersion> brands; // [ {brand: "Google Chrome", version: "84"}, {brand: "Chromium", version: "84"} ]
readonly attribute boolean mobile; // false
Promise<UADataValues> getHighEntropyValues(sequence<DOMString> hints); // { "PhoneOS", "10A", "arm", "X644GTM", "73.32.AGX.5" }
Promise<UADataValues> getHighEntropyValues(sequence<DOMString> hints); // { "arm", "64", "X644GTM", "PhoneOS", "10A", "73.32.AGX.5" }
};
interface mixin NavigatorUA {
Expand Down
74 changes: 50 additions & 24 deletions index.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,8 @@ has defined a number of properties for itself:
version. (for example: "NT 6.0", "15", or "17G")
* <dfn for="user agent" export>platform architecture</dfn> - The [=user agent=]'s underlying CPU
architecture (for example: "ARM", or "x86")
* <dfn for="user agent" export>platform bitness</dfn> - The [=user agent=]'s underlying CPU
architecture bitness (for example: "32", or "64")
* <dfn for="user agent" export>model</dfn> - The [=user agent=]'s device model (for example: "",
or "Pixel 2 XL")
* <dfn for="user agent" export>mobileness</dfn> - A boolean indicating if the [=user agent=]'s
Expand All @@ -213,13 +215,8 @@ values for each, as they are all values constructed at the [=user agent=]'s whim
Other CPU architectures could be mapped into one of these values in case that makes sense, or be
mapped to the empty string.

ISSUE 105: There might be use-cases for higher-entropy, more specific CPU architectures (e.g. 32
vs. 64 bit architectures, or specific instruction sets for the download of highly optimized
executable binaries). If necessary, we could support those use-cases through one or more separate
hints.

[=User agents=] SHOULD return the empty string or a fictitious value for [=platform architecture=]
unless the user's platform is one where both the following conditions apply:
or [=platform bitness=] unless the user's platform is one where both the following conditions apply:
* Binary download of executables is likely.
* Different CPU architectures are likely to require different binary executable resources, and
different binary exeutable resources are likely to be available.
Expand All @@ -229,7 +226,7 @@ Agents=] MUST return the empty string for [=model=] even if [=mobileness=] is tr
platforms where the model is typically exposed.

[=User agents=] MAY return the empty string or a fictitious value for [=full version=], [=platform
architecture=] or [=model=], for privacy, compatibility, or other reasons.
architecture=], [=platform bitness=] or [=model=], for privacy, compatibility, or other reasons.

The 'Sec-CH-UA-Arch' Header Field {#sec-ch-ua-arch}
------------------------------
Expand All @@ -245,6 +242,19 @@ The header's ABNF is:
Sec-CH-UA-Arch = sh-string
~~~

The 'Sec-CH-UA-Bitness' Header Field {#sec-ch-ua-bitness}
------------------------------

The <dfn http-header>`Sec-CH-UA-Bitness`</dfn> request header field gives a server information about
the bitness of the architecture of the platform on which a given [=user agent=] is executing. It is
a [=Structured Header=] whose value MUST be a [=structured header/string=]
[[!RFC8941]].

The header's ABNF is:

~~~ abnf
Sec-CH-UA-Bitness = sh-string
~~~

The 'Sec-CH-UA-Model' Header Field {#sec-ch-ua-model}
-------------------------------
Expand Down Expand Up @@ -380,10 +390,11 @@ dictionary NavigatorUABrandVersion {
};

dictionary UADataValues {
DOMString platform;
DOMString platformVersion;
DOMString architecture;
DOMString bitness;
DOMString model;
DOMString platform;
DOMString platformVersion;
DOMString uaFullVersion;
};

Expand Down Expand Up @@ -504,17 +515,19 @@ ISSUE(wicg/ua-client-hints): We can improve upon when and why a UA decides to re

1. Let |uaData| be a new {{UADataValues}}.

2. If |hints| [=list/contains=] "platform", set |uaData|["{{UADataValues/platform}}"] to the [=user agent=]'s [=user agent/platform brand=].

3. If |hints| [=list/contains=] "platformVersion", set |uaData|["{{UADataValues/platformVersion}}"] to the [=user agent=]'s [=user agent/platform version=].

4. If |hints| [=list/contains=] "architecture", set |uaData|["{{UADataValues/architecture}}"] to the [=user agent=]'s [=user agent/platform architecture=].

5. If |hints| [=list/contains=] "model", set |uaData|["{{UADataValues/model}}"] to the [=user agent=]'s [=user agent/model=].

6. If |hints| [=list/contains=] "uaFullVersion", let |uaData|["{{UADataValues/uaFullVersion}}"] be the the user agent's [=user agent/full version=].

7. [=Queue a task=] on the [=permission task source=] to [=resolve=] |p| with |uaData|.
1. If |hints| [=list/contains=] "architecture", set |uaData|["{{UADataValues/architecture}}"] to
the [=user agent=]'s [=user agent/platform architecture=].
1. If |hints| [=list/contains=] "bitness", set |uaData|["{{UADataValues/bitness}}"] to
the [=user agent=]'s [=user agent/platform bitness=].
1. If |hints| [=list/contains=] "model", set |uaData|["{{UADataValues/model}}"] to the
[=user agent=]'s [=user agent/model=].
1. If |hints| [=list/contains=] "platform", set |uaData|["{{UADataValues/platform}}"] to the
[=user agent=]'s [=user agent/platform brand=].
1. If |hints| [=list/contains=] "platformVersion", set |uaData|["{{UADataValues/platformVersion}}"]
to the [=user agent=]'s [=user agent/platform version=].
1. If |hints| [=list/contains=] "uaFullVersion", let |uaData|["{{UADataValues/uaFullVersion}}"]
be the the user agent's [=user agent/full version=].
1. [=Queue a task=] on the [=permission task source=] to [=resolve=] |p| with |uaData|.

4. Return |p|.

Expand Down Expand Up @@ -555,10 +568,10 @@ The information in the Client Hints defined above reveals quite a bit of informa
agent and the platform/device upon which it runs. [=User agents=] ought to exercise judgement before
granting access to this information, and MAY impose restrictions above and beyond the secure
transport and delegation requirements noted above. For instance, [=user agents=] could choose to reveal
[=user agent/platform architecture=] only on requests it intends to download, giving the server the
opportunity to serve the right binary. Likewise, they could offer users control over the values
revealed to servers, or gate access on explicit user interaction via a permission prompt or via a
settings interface.
[=user agent/platform architecture=] or [=user agent/platform bitness=] only on requests it intends
to download, giving the server the opportunity to serve the right binary. Likewise, they could offer
users control over the values revealed to servers, or gate access on explicit user interaction via a
permission prompt or via a settings interface.

Implementation Considerations {#impl-considerations}
=============================
Expand Down Expand Up @@ -659,6 +672,19 @@ Author/Change controller: IETF

Specification document: this specification ([[#sec-ch-ua-arch]])

'Sec-CH-UA-Bitness' Header Field {#iana-bitness}
--------------------------

Header field name: Sec-CH-UA-Bitness

Applicable protocol: http

Status: standard

Author/Change controller: IETF

Specification document: this specification ([[#sec-ch-ua-bitness]])

'Sec-CH-UA-Model' Header Field {#iana-model}
---------------------------

Expand Down

0 comments on commit 5b7f97f

Please sign in to comment.