From 1aee4fab837362c92efd37eea5c3d38175719c1c Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Fri, 12 Mar 2021 16:59:50 -0600 Subject: [PATCH 1/3] Issue #201 - Add a list of headers to the top of the explainer --- README.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 81aadd2..002ffc6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,18 @@ # User Agent Client Hints -This repository hosts the User Agent Client Hints specification. +This repository hosts the User Agent Client Hints (UA-CH) specification. + +UA-CH introduces the following [Client Hints](https://tools.ietf.org/html/rfc8942) HTTP headers and +a corresponding JavaScript API: + +* `Sec-CH-UA-Arch` +* `Sec-CH-UA-Mobile` +* `Sec-CH-UA-Model` +* `Sec-CH-UA-Platform` +* `Sec-CH-UA-Platform-Version` +* `Sec-CH-UA` +* `Sec-CH-UA-Full-Version` + ## Contributing From 5b7f97fe3ce7c150c5f3eb83d95bc6ec5a112068 Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Fri, 12 Mar 2021 18:08:58 -0600 Subject: [PATCH 2/3] Issue #105 - Add a UA hint for CPU bitness --- README.md | 28 ++++++++++++++------- index.bs | 74 +++++++++++++++++++++++++++++++++++++------------------ 2 files changed, 69 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 002ffc6..9f083c5 100644 --- a/README.md +++ b/README.md @@ -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` @@ -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" @@ -169,10 +178,11 @@ 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" }; @@ -180,7 +190,7 @@ accomplish this as follows: interface NavigatorUAData { readonly attribute FrozenArray brands; // [ {brand: "Google Chrome", version: "84"}, {brand: "Chromium", version: "84"} ] readonly attribute boolean mobile; // false - Promise getHighEntropyValues(sequence hints); // { "PhoneOS", "10A", "arm", "X644GTM", "73.32.AGX.5" } + Promise getHighEntropyValues(sequence hints); // { "arm", "64", "X644GTM", "PhoneOS", "10A", "73.32.AGX.5" } }; interface mixin NavigatorUA { diff --git a/index.bs b/index.bs index 4a27852..cc5a883 100644 --- a/index.bs +++ b/index.bs @@ -196,6 +196,8 @@ has defined a number of properties for itself: version. (for example: "NT 6.0", "15", or "17G") * platform architecture - The [=user agent=]'s underlying CPU architecture (for example: "ARM", or "x86") +* platform bitness - The [=user agent=]'s underlying CPU + architecture bitness (for example: "32", or "64") * model - The [=user agent=]'s device model (for example: "", or "Pixel 2 XL") * mobileness - A boolean indicating if the [=user agent=]'s @@ -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. @@ -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} ------------------------------ @@ -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 `Sec-CH-UA-Bitness` 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} ------------------------------- @@ -380,10 +390,11 @@ dictionary NavigatorUABrandVersion { }; dictionary UADataValues { - DOMString platform; - DOMString platformVersion; DOMString architecture; + DOMString bitness; DOMString model; + DOMString platform; + DOMString platformVersion; DOMString uaFullVersion; }; @@ -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|. @@ -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} ============================= @@ -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} --------------------------- From 198df579e4d2d4aa22f08292ffbffe9069dbc12d Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Mon, 15 Mar 2021 16:28:12 -0500 Subject: [PATCH 3/3] Issue #105 - Add some use-case info to explainer (And some small language tweaks and a typos fix in the spec) --- README.md | 4 +++- index.bs | 24 ++++++++++++------------ 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 9f083c5..f374cb8 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,9 @@ accomplish this as follows: ``` 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). + (i.e., the size in bits of an integer or memory address). This could be used to determine + which binary to serve for downloads. + For example: ```http diff --git a/index.bs b/index.bs index cc5a883..7efdddb 100644 --- a/index.bs +++ b/index.bs @@ -184,24 +184,24 @@ given [=user agent=], which servers can opt-into receiving via the Client Hints defined in [[!RFC8942]]. The definitions below assume that each [=user agent=] has defined a number of properties for itself: -* brand - The [=user agent=]'s commercial name (for example: +* brand - The [=user agent=]'s commercial name (e.g., "cURL", "Edge", "The World's Best Web Browser") * significant version - The [=user agent=]'s marketing version, - which includes distinguishable web-exposed features (for example: "72", "3", or "12.1") -* full version - The [=user agent=]'s build version (for - example: "72.0.3245.12", "3.14159", or "297.70E04154A") + which includes distinguishable web-exposed features (e.g., "72", "3", or "12.1") +* full version - The [=user agent=]'s build version (e.g., + "72.0.3245.12", "3.14159", or "297.70E04154A") * platform brand - The [=user agent=]'s operating system's - commercial name. (for example: "Windows", "iOS", or "AmazingOS") + commercial name. (e.g., "Windows", "iOS", or "AmazingOS") * platform version - The [=user agent=]'s operating system's - version. (for example: "NT 6.0", "15", or "17G") + version. (e.g., "NT 6.0", "15", or "17G") * platform architecture - The [=user agent=]'s underlying CPU - architecture (for example: "ARM", or "x86") + architecture (e.g., "ARM", or "x86") * platform bitness - The [=user agent=]'s underlying CPU - architecture bitness (for example: "32", or "64") -* model - The [=user agent=]'s device model (for example: "", - or "Pixel 2 XL") + architecture bitness (e.g., "32" or "64") +* model - The [=user agent=]'s device model (e.g., "", or + "Pixel 2 XL") * mobileness - A boolean indicating if the [=user agent=]'s - device is a mobile device. (for example: ?0 or ?1) + device is a mobile device. (e.g., ?0 or ?1) [=User agents=] SHOULD keep these strings short and to the point, but servers MUST accept arbitrary @@ -219,7 +219,7 @@ mapped to the empty string. 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. + different binary executable resources are likely to be available. [=User Agents=] MUST return the empty string for [=model=] if [=mobileness=] is false. [=User Agents=] MUST return the empty string for [=model=] even if [=mobileness=] is true, except on