Private Aggregation API

1. Introduction

This section is non-normative.

1.1. Motivation

Browsers are now working to prevent cross-site user tracking, including by partitioning storage and removing third-party cookies. There are a range of API proposals to continue supporting legitimate use cases in a way that respects user privacy. Many of these APIs, including the Shared Storage API and the Protected Audience API, isolate potentially identifying cross-site data in special contexts, which ensures that the data cannot escape the user agent.

Relative to cross-site data from an individual user, aggregate data about groups of users can be less sensitive and yet would be sufficient for a wide range of use cases. An aggregation service has been built to allow reporting noisy, aggregated cross-site data. This service was originally created for use by the Attribution Reporting API, but allowing more general aggregation supports additional use cases. In particular, the Protected Audience and Shared Storage APIs expect this functionality to be available.

1.2. Overview

This document outlines a general-purpose API that can be called from isolated contexts that have access to cross-site data (such as a Shared Storage worklet). Within these contexts, potentially identifying data can be encapsulated into "aggregatable reports". To prevent leakage, the cross-site data in these reports is encrypted to ensure it can only be processed by the aggregation service. During processing, this service adds noise and imposes limits on how many queries can be performed.

This API provides functions that allow the origin to construct an aggregatable report and specify the values to be embedded into its encrypted payload (for later computation via the aggregation service). These calls result in the aggregatable report being queued to be sent to the reporting endpoint of the script’s origin after a delay. After the endpoint receives the reports, it will batch the reports and send them to the aggregation service for processing. The output of that process is a summary report containing the (approximate) result, which is dispatched back to the script’s origin.

1.3. Alternative considered

Instead of the chosen API shape, we considered aligning with a design that is much closer to fetch(). However, there are a few key differences which make this unfavorable:

• This API is designed to be used in isolated contexts where fetch() is not available.

• It’s an anti-goal to give the developer control over when aggregatable reports are being sent or knowledge that they were sent (outside of the isolated context). Note, however, the exception when providing a context ID from outside the isolated context, see Protecting against leaks via the number of reports below.

• The reports cannot be sent to arbitrary reporting endpoints, only a particular .well-known path on the script origin.

• The report’s input is very specific (an array of PAHistogramContributions) and is not amenable to fetch()'s general purpose contents.

• There is no concept of a response.

So, we chose the more tailored API shape detailed below.

2. Exposed interface

[Exposed=(InterestGroupScriptRunnerGlobalScope,SharedStorageWorklet),
 SecureContext]
interface PrivateAggregation {
  undefined contributeToHistogram(PAHistogramContribution contribution);
  undefined enableDebugMode(optional PADebugModeOptions options = {});
};

dictionary PAHistogramContribution {
  required bigint bucket;
  required long value;
  bigint filteringId = 0;
};

dictionary PADebugModeOptions {
  required bigint debugKey;
};

Per the Web Platform Design Principles, we should consider switching long to [EnforceRange] long long.

enableDebugMode(options)'s argument should not have a default value of {}. Alternatively, debugKey should not be required in PADebugModeOptions.

Each PrivateAggregation object has the following fields:

scoping details (default null)

A scoping details or null

allowed to use (default false)

A boolean

Note: See Exposing to global scopes below.

3. Exposing to global scopes

To expose this API to a global scope, a read only attribute privateAggregation of type PrivateAggregation should be exposed on the global scope. Its getter steps should be set to the get the privateAggregation steps given this.

Each global scope should set the allowed to use for the PrivateAggregation object it exposes based on whether a relevant document is allowed to use the "private-aggregation" policy-controlled feature.

Additionally, each global scope should set the scoping details for the PrivateAggregation object it exposes to a non-null value. The global scope should wait to set the field until the API is intended to be available.

class ExampleOperation {
  async run(data) {
    privateAggregation.contributeToHistogram(...)  // This is allowed.
  }
}
register('example-operation', ExampleOperation);

privateAggregation.contributeToHistogram(...)  // This would cause an error.

For any batching scope returned by the get batching scope steps, the process contributions for a batching scope steps should later be performed given that same batching scope, the global scope’s relevant settings object's origin, some context type and a timeout (or null).

Note: This last requirement means that global scopes with different origins cannot share the same batching scope, see Same-origin policy discussion.

For any debug scope returned by the get debug scope steps, the mark a debug scope complete steps should later be performed given that same debug scope.

Note: A later algorithm asserts that, for any contribution cache entry in the contribution cache, the mark a debug scope complete steps were performed given the entry’s debug scope before the process contributions for a batching scope steps are performed given the entry’s batching scope.

3.1. APIs exposing Private Aggregation

This section is non-normative.

This API is currently exposed in global scopes defined in the specifications of two APIs:

1. Shared Storage and

2. Protected Audience.

4. Structures

4.1. Batching scope

Unique internal value is not an exported definition. See infra/583.

4.2. Debug scope

4.3. Scoping details

get batching scope steps

An algorithm returning a batching scope

get debug scope steps

An algorithm returning a debug scope

4.4. Debug details

enabled (default false)

A boolean

key (default null)

An unsigned 64-bit integer or null. The key must be null if enabled is false.

4.5. Contribution cache entry

contribution

A PAHistogramContribution

batching scope

A batching scope

debug scope

A debug scope

debug details (default null)

A debug details or null

4.6. Aggregatable report

An aggregatable report is a struct with the following items:

reporting origin

An origin

original report time

A moment

report time

A moment

contributions

A list of PAHistogramContributions

api

A context type

report ID

A string

debug details

A debug details

aggregation coordinator

An aggregation coordinator

context ID

A string or null

filtering ID max bytes

A positive integer

queued

A boolean

4.7. Aggregation coordinator

An aggregation coordinator is an origin that the allowed aggregation coordinator set contains.

Consider switching to the suitable origin concept used by the Attribution Reporting API here and elsewhere.

Move other structures to be defined inline instead of via a header. Consider also removing all the subheadings.

4.8. Context type

4.9. Pre-specified report parameters

A pre-specified report parameters is a struct with the following items:

context ID (default: null)

A string or null

filtering ID max bytes (default: default filtering ID max bytes)

A positive integer

5. Storage

A user agent holds an aggregatable report cache, which is a list of aggregatable reports.

A user agent holds an aggregation coordinator map, which is a map from batching scopes to aggregation coordinators.

A user agent holds a pre-specified report parameters map, which is a map from batching scopes to pre-specified report parameters.

A user agent holds a contribution cache, which is a list of contribution cache entries.

A user agent holds a debug scope map, which is a map from debug scopes to debug details.

Elsewhere, link to definition when using user agent.

5.1. Clearing storage

The user agent must expose controls that allow the user to delete data from the aggregatable report cache as well as any contribution history data stored for the consume budget if permitted algorithm.

The user agent may expose controls that allow the user to delete data from the contribution cache, the debug scope map and the pre-specified report parameters map.

6. Constants

Default filtering ID max bytes is a positive integer controlling the max bytes used if none is explicitly chosen. Its value is 1.

Valid filtering ID max bytes range is a set of positive integers controlling the allowable values of max bytes. Its value is the range 1 to 8, inclusive.

Consider adding more constants.

7. Implementation-defined values

Allowed aggregation coordinator set is a set of origins that controls which origins are valid aggregation coordinators. Every item in this set must be a potentially trustworthy origin.

Default aggregation coordinator is an aggregation coordinator that controls which is used for a report if none is explicitly selected.

Maximum report contributions is a map from context type to positive integers. Semantically, it defines the maximum number of contributions that can be present in a single report for every kind of calling context, e.g. Shared Storage.

Minimum report delay is a non-negative duration that controls the minimum delay to deliver an aggregatable report.

Randomized report delay is a positive duration that controls the random delay to deliver an aggregatable report. This delay is additional to the minimum report delay.

8. Permissions Policy integration

This specification defines a policy-controlled feature identified by the string "private-aggregation". Its default allowlist is "*".

Note: The allowed to use field is set by other specifications that integrate with this API according to this policy-controlled feature.

9. Algorithms

To serialize an integer, represent it as a string of the shortest possible decimal number.

This would ideally be replaced by a more descriptive algorithm in Infra. See infra/201.

9.1. Exported algorithms

Note: These algorithms allow other specifications to integrate with this API.

Elsewhere, surround algorithms in a <div algorithm> block to match, and add styling for all algorithms per bikeshed/1472.

9.2. Scheduling reports

9.3. Sending reports

Note: This section is largely copied from the Attribution Reporting API spec, adapting as necessary.

Do we have to use the queue a task algorithm here?

The user agent must periodically attempt to queue reports for sending given its aggregatable report cache.

9.4. Serializing reports

Note: This section is largely copied from the Attribution Reporting API spec, adapting as necessary.

10. User-agent automation

A user agent holds a boolean automation local testing mode enabled (default false).

For the purposes of user-agent automation and website testing, this document defines the below [WebDriver] extension commands to control the API configuration.

10.1. Set local testing mode

11. Privacy considerations

This section is non-normative.

11.1. Cross-site information disclosure

This API lets isolated contexts with access to cross-site data (i.e. Shared Storage worklets/Protected Audience script runners) send aggregatable reports over the network.

Aggregatable reports contain encrypted high entropy cross-site information, in the form of key-value pairs (i.e. contributions to a histogram). The information embedded in the contributions is arbitrary but can include things like browsing history and other cross-site activity. The API aims to protect this information from being passed from one site to another.

11.1.1. Restricted contribution processing

The histogram contributions are not exposed directly. Instead, they are encrypted so that they can only be processed by a trusted aggregation service. This trusted aggregation service sums the values across the reports for each key and adds noise to each of these values to produce ‘summary reports’.

The output of that processing will be an aggregated, noised histogram. The service ensures that any report can not be processed multiple times. Further, information exposure is limited by contribution budgets on the user agent. In principle, this framework can support specifying a noise parameter which satisfies differential privacy.

11.1.2. Unencrypted metadata

These reports also expose a limited amount of metadata, which is not based on cross-site data. The recipient of the report may also be able to observe side-channel information such as the time when the report was sent, or IP address of the sender.

11.1.3. Protecting against leaks via the number of reports

However, the number of reports with the given metadata could expose some cross-site information. To protect against this, the API delays sending reports by a randomized amount of time to make it difficult to determine whether a report was sent or not from any particular event. In the case that a context ID is supplied or a non-default filtering ID max bytes is specified, the API makes the number of reports sent deterministic (sending 'null reports' if necessary -- each containing only a contribution with a value of 0 in the payload). Additional mitigations may also be possible in the future, e.g. adding noise to the report count.

11.1.4. Protecting against leaks via payload size

The length of the payload could additionally expose some cross-site information, namely how many contributions are included. To protect against this, the payload is padded to a fixed number of contributions.

11.1.5. Temporary debugging mechanism

The enableDebugMode() method allows for many of the protections of this API to be bypassed to ease testing and integration. Specifically, the contents of the payload, i.e. the histogram contributions, are revealed in the clear when the debug mode is enabled. Optionally, a debug key can also be set to associate the report with the calling context. In the future, this mechanism will only be available for callers that are eligible to set third-party cookies. In that case, the API caller already has the ability to communicate information cross-site.

Tie enableDebugMode() to third-party cookie eligibility. [Issue #57]

11.1.6. Privacy parameters

The amount of information exposed by this API is a product of the privacy parameters used (e.g. contribution limits and the noise distribution used in the aggregation service). While we aim to minimize the amount of information exposed, we also aim to support a wide range of use cases. The privacy parameters are left implementation-defined to allow different and evolving choices in the tradeoffs between information exposure and utility.

11.2. Clearing site data

The aggregatable report cache as well as any contribution history data stored for the consume budget if permitted algorithm contain data about a user’s web activity. As such, user controls to delete this data are required, see clearing storage.

On the other hand, the contribution cache, the debug scope map and the pre-specified report parameters map only contain short-lived data tied to particular batching scopes and debug scopes, so controls are not required.

11.3. Reporting delay concerns

Delaying sending reports after API invocation can enable side-channel leakage in some situations.

11.3.1. Cross-network reporting origin leakage

A report may be stored while the browser is connected to one network but sent while the browser is connected to a different network, potentially enabling cross-network leakage of the reporting origin.

Example: A user runs the browser with a particular browsing profile on their home network. An aggregatable report with a particular reporting origin is stored with a report time in the future. After the report time is reached, the user runs the browser with the same browsing profile on their employer’s network, at which point the browser sends the report to the reporting origin. Although the report itself may be sent over HTTPS, the reporting origin may be visible to the network administrator via DNS or the TLS client hello (which can be mitigated with ECH). Some reporting origins may be known to operate only or primarily on sensitive sites, so this could leak information about the user’s browsing activity to the user’s employer without their knowledge or consent.

Possible mitigations include:

1. Only sending reports with a given reporting origin when the browser has already made a request to that origin on the same network: This prevents the network administrator from gaining additional information from the Private Aggregation API. However, it increases report loss and report delays, which reduces the utility of the API for the reporting origin. It might also increase the effectiveness of timing attacks, as the origin may be able to better link the report with the user’s request that allowed the report to be released.

2. Send reports immediately: This reduces the likelihood of a report being stored and sent on different networks. However, it increases the likelihood that the reporting origin can correlate the original API invocation to the report being sent, which weakens the privacy controls of the API, see Protecting against leaks via the number of reports.

3. Use a trusted proxy server to send reports: This effectively moves the reporting origin into the report body, so only the proxy server would be visible to the network administrator.

4. Require DNS over HTTPS: This effectively hides the reporting origin from the network administrator, but is likely impractical to enforce and is itself perhaps circumventable by the network administrator, e.g. by monitoring IP addresses instead.

11.3.2. User-presence tracking

The browser only tries to send reports while it is running and while it has internet connectivity (even without an explicit check for connectivity, naturally the report will fail to be sent if there is none), so receiving or not receiving a (serialized) aggregatable report at the original report time leaks information about the user’s presence. Additionally, because the report request inherently includes an IP address, this could reveal the user’s IP-derived location to the reporting origin, including at-home vs. at-work or approximate real-world geolocation, or reveal patterns in the user’s browsing activity.

Possible mitigations include:

1. Send reports immediately: This effectively eliminates the presence tracking, as the original request made to the reporting origin is in close temporal proximity to the report request. However, it increases the likelihood that the reporting origin can correlate the original API invocation to the report being sent, which weakens the privacy controls of the API, see Protecting against leaks via the number of reports.

2. Send reports immediately to a trusted proxy server, which would itself apply additional delay: This would effectively hide both the user’s IP address and their online-offline presence from the reporting origin.

12. Security considerations

This section is non-normative.

12.1. Same-origin policy

Writes to the aggregatable report cache, contribution cache, debug scope map and pre-specified report parameters map are attributed to the reporting origin and the data included in any report with a given reporting origin are generated with only data from that origin.

One notable exception is the consume budget if permitted algorithm which is implementation-defined and can consider contribution history from other origins. For example, the algorithm could consider all history from a particular site. This would be an explicit relaxation of the same-origin policy as multiple origins would be able to influence the API’s behavior. One particular risk of these kinds of shared limits is the introduction of denial of service attacks, where a group of origins could collude to intentionally consume all available budget, causing subsequent origins to be unable to access the API. This trades off security for privacy, in that the limits are there to reduce the efficacy of many origins colluding together to violate privacy. However, this security risk is lessened if the set of origins limited are all same site. User agents should consider these tradeoffs when choosing the consume budget if permitted algorithm.

12.2. Protecting the histogram contributions

As discussed above, the processing of histogram contributions is limited to protect privacy. This limitation relies on only the trusted aggregation service being able to access the unencrypted histogram contributions.

To ensure this, this API uses HPKE, a modern encryption specification. Additionally, each user agent is encouraged to require regular key rotation by the aggregation service. This limits the amount of data encrypted with the same key and thus the amount of vulnerable data in the case of a key being compromised.

While not specified here, each user agent is strongly encouraged to consider the security of any aggregation service design before allowing its public keys to be returned by obtain the public key for encryption.