Technical review: Document ch-ua-high-entropy-values permissions-policy (#42880)

Author: chrisdavidmills

files/en-us/web/api/navigatoruadata/gethighentropyvalues/index.md

@@ -10,13 +10,16 @@ browser-compat: api.NavigatorUAData.getHighEntropyValues
 
 {{APIRef("User-Agent Client Hints API")}}{{SeeCompatTable}}{{AvailableInWorkers}}
 
-The **`getHighEntropyValues()`** method of the {{domxref("NavigatorUAData")}} interface is a {{jsxref("Promise")}} that resolves with a dictionary object containing the _high entropy_ values the user-agent returns.
+The **`getHighEntropyValues()`** method of the {{domxref("NavigatorUAData")}} interface returns a {{jsxref("Promise")}} that resolves with a dictionary object containing low entropy information and requested high entropy information about the browser.
+
+The resolved object has the ["low entropy" properties](/en-US/docs/Web/API/NavigatorUAData#instance_properties) available on the `NavigatorUAData` object included by default — these are the values that are unlikely to enable fingerprinting of the user.
+It also contains the subset of "high entropy" values requested in the parameter object, and for which permission has been granted.
+These are the values that are more likely to enable fingerprinting.
+Note that meaning of the terms [low entropy](/en-US/docs/Web/HTTP/Guides/Client_hints#low_entropy_hints) and [high entropy](/en-US/docs/Web/HTTP/Guides/Client_hints#high_entropy_hints) is the same as defined in the HTTP [User Agent Client Hints](/en-US/docs/Web/HTTP/Guides/Client_hints) mechanism.
 
 > [!NOTE]
-> The terms _high entropy_ and _low entropy_ refer to the amount of information these values reveal about the browser.
-> The values returned as properties are deemed low entropy, and unlikely to identify a user.
-> The values returned by `getHighEntropyValues()` could potentially reveal more information.
-> These values are therefore retrieved via a {{jsxref("Promise")}}, allowing time for the browser to request user permission, or make other checks.
+> Usage of the `getHighEntropyValues()` method to retrieve high-entropy user-agent data can be controlled via the {{HTTPHeader('Permissions-Policy/ch-ua-high-entropy-values', 'ch-ua-high-entropy-values')}} {{HTTPHeader('Permissions-Policy')}}.
+> If the permission is not allowed, the method will only return the `brands`, `mobile`, and `platform` low-entropy data.
 
 ## Syntax
 
@@ -27,7 +30,8 @@ getHighEntropyValues(hints)
 ### Parameters
 
 - `hints`
-  - : An array containing the hints to be returned, one or more of:
+  - : An array containing the high-entropy hints to be returned.
+    This may include one or more of:
     - `"architecture"`
     - `"bitness"`
     - `"formFactors"`
@@ -39,7 +43,7 @@ getHighEntropyValues(hints)
 
 ### Return value
 
-A {{jsxref("Promise")}} that resolves to an object containing some or all of the following values (based on the hints requested):
+A {{jsxref("Promise")}} that resolves to an object containing some or all of the following values (based on the hints requested and granted):
 
 - `brands`
   - : Returns an array of objects containing `brand` and `version` specifying the browser brand and its version (the same information as provided by {{domxref("NavigatorUAData.brands")}}).

files/en-us/web/api/navigatoruadata/index.md

@@ -14,7 +14,7 @@ The **`NavigatorUAData`** interface of the {{domxref("User-Agent Client Hints AP
 An instance of this object is returned by calling {{domxref("Navigator.userAgentData")}} or {{domxref("WorkerNavigator.userAgentData")}}. Therefore, this interface has no constructor.
 
 > [!NOTE]
-> The terms _high entropy_ and _low entropy_ refer to the amount of information these values reveal about the browser. The values returned as properties are deemed low entropy, and unlikely to identify a user. The values returned by {{domxref("NavigatorUAData.getHighEntropyValues()")}} could potentially reveal more information. These values are therefore retrieved via a {{jsxref("Promise")}}, allowing time for the browser to request user permission, or make other checks.
+> The terms _high entropy_ and _low entropy_ refer to the amount of information these values reveal about the browser. The values returned as properties are deemed [low entropy](/en-US/docs/Web/HTTP/Guides/Client_hints#low_entropy_hints), which are unlikely to identify a user. The {{domxref("NavigatorUAData.getHighEntropyValues()")}} can be used to request additional [high entropy](/en-US/docs/Web/HTTP/Guides/Client_hints#high_entropy_hints) values, which could potentially reveal more identifying information. These values are therefore retrieved via a {{jsxref("Promise")}}, allowing time for the browser to request user permission, or make other checks.
 
 ## Instance properties
 
@@ -28,7 +28,7 @@ An instance of this object is returned by calling {{domxref("Navigator.userAgent
 ## Instance methods
 
 - {{domxref("NavigatorUAData.getHighEntropyValues()")}} {{Experimental_Inline}}
-  - : Returns a {{jsxref("Promise")}} that resolves with a dictionary object containing the _high entropy_ values the user-agent returns.
+  - : Returns a {{jsxref("Promise")}} that resolves with a dictionary object containing low entropy information and requested high entropy information about the browser.
 - {{domxref("NavigatorUAData.toJSON()")}} {{Experimental_Inline}}
   - : A _serializer_ that returns a JSON representation of the _low entropy_ properties of the `NavigatorUAData` object.
 

files/en-us/web/api/user-agent_client_hints_api/index.md

@@ -82,6 +82,29 @@ navigator.userAgentData
   });
 ```
 
+## Security considerations
+
+Websites that support setting a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy) (via the HTTP {{HTTPHeader("Permissions-Policy")}} header or the {{HTMLElement("iframe")}} attribute [`allow`](/en-US/docs/Web/HTML/Reference/Elements/iframe#allow)) can restrict the ability to use the User-Agent Client Hints API using the directive {{HTTPHeader("Permissions-Policy/ch-ua-high-entropy-values", "ch-ua-high-entropy-values")}}.
+
+Specifically, when the permission is not granted, the {{domxref("NavigatorUAData.getHighEntropyValues()")}} will only return low-entropy data such as `brands`, `mobile`, and `platform`.
+
+For example, the following policy would only allow the current origin and two other specific origins to retrieve high-entropy data.
+
+```http
+Permissions-Policy: ch-ua-high-entropy-values=("self https://a.example.com" "https://b.example.com")
+```
+
+You could then embed one of the two other origins:
+
+```html
+<iframe src="https://a.example.com" allow="ch-ua-high-entropy-values"></iframe>
+```
+
+The default allowlist for `ch-ua-high-entropy-values` is `*`, which permits any content within the current document and all nested browsing contexts to use `getHighEntropyValues()`.
+
+> [!NOTE]
+> Access to individual high-entropy features can be controlled with their own [individual permissions policies](https://wicg.github.io/client-hints-infrastructure/#policy-controlled-features).
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/http/reference/headers/permissions-policy/ch-ua-high-entropy-values/index.md

@@ -0,0 +1,59 @@
+---
+title: "Permissions-Policy: ch-ua-high-entropy-values directive"
+short-title: ch-ua-high-entropy-values
+slug: Web/HTTP/Reference/Headers/Permissions-Policy/ch-ua-high-entropy-values
+page-type: http-permissions-policy-directive
+status:
+  - experimental
+browser-compat: http.headers.Permissions-Policy.ch-ua-high-entropy-values
+sidebar: http
+---
+
+{{SeeCompatTable}}
+
+The HTTP {{HTTPHeader("Permissions-Policy")}} header `ch-ua-high-entropy-values` directive controls whether or not the document is permitted to use the {{domxref("NavigatorUAData.getHighEntropyValues()")}} method to retrieve high-entropy user-agent data.
+
+If the permission is not allowed, the method will only return the `brands`, `mobile`, and `platform` low-entropy data.
+
+## Syntax
+
+```http
+Permissions-Policy: ch-ua-high-entropy-values=<allowlist>;
+```
+
+- `<allowlist>`
+  - : A list of origins for which permission is granted to use the feature. See [`Permissions-Policy` > Syntax](/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#syntax) for more details.
+
+## Default policy
+
+The default allowlist for `ch-ua-high-entropy-values` is `*`.
+
+## Examples
+
+### Restricting high-entropy data to specific origins
+
+The following policy would only allow the current origin and two other specific origins to retrieve high-entropy data.
+
+```http
+Permissions-Policy: ch-ua-high-entropy-values=("self https://a.example.com" "https://b.example.com")
+```
+
+You could then embed one of the two other origins:
+
+```html
+<iframe src="https://a.example.com" allow="ch-ua-high-entropy-values"></iframe>
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{HTTPHeader("Permissions-Policy")}} header
+- [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy)
+- [User-Agent Client Hints API](/en-US/docs/Web/API/User-Agent_Client_Hints_API)

files/en-us/web/http/reference/headers/permissions-policy/index.md

@@ -99,6 +99,10 @@ You can specify
   - : Controls whether or not the document is permitted to use the [Captured Surface Control API](/en-US/docs/Web/API/Screen_Capture_API/Captured_Surface_Control).
     The promise returned by the API's main methods will reject with a `NotAllowedError` {{DOMxRef("DOMException")}} if the permission is not allowed.
 
+- {{HTTPHeader('Permissions-Policy/ch-ua-high-entropy-values', 'ch-ua-high-entropy-values')}} {{experimental_inline}}
+  - : Controls whether or not the document is permitted to use the {{domxref("NavigatorUAData.getHighEntropyValues()")}} method to retrieve high-entropy user-agent data.
+    If the permission is not allowed, the method will only return the `brands`, `mobile`, and `platform` low-entropy data.
+
 - {{httpheader('Permissions-Policy/compute-pressure','compute-pressure')}} {{Experimental_Inline}}
   - : Controls access to the [Compute Pressure API](/en-US/docs/Web/API/Compute_Pressure_API).