Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Describe B&A payload size optimization options #1183

Merged
merged 5 commits into from
Aug 23, 2024
Merged

Describe B&A payload size optimization options #1183

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4435864
Describe B&A payload size optimization options
brusshamilton Feb 29, 2024
17420cd
Merge remote-tracking branch 'upstream/main' into PayloadSizeOptimiza…
brusshamilton May 16, 2024
5b49aaa
Add Request Size and Configuration section
brusshamilton May 16, 2024
a1c2c72
Address comments
brusshamilton Aug 13, 2024
d0b0f47
Merge remote-tracking branch 'upstream/main' into PayloadSizeOptimiza…
brusshamilton Aug 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 65 additions & 4 deletions FLEDGE_browser_bidding_and_auction_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,13 +17,33 @@ const auctionBlob = navigator.getInterestGroupAdAuctionData({
// ‘seller’ works the same as for runAdAuction.
'seller': 'https://www.example-ssp.com',
// 'coordinatorOrigin' of the TEE coordinator, defaults to
//'https://publickeyservice.gcp.privacysandboxservices.com' (for now). Used to
// select which key to use for the encrypted blob. Will eventually be
// required.
//'https://publickeyservice.pa.gcp.privacysandboxservices.com/' (for now). Used to
// select which coordinator to use for fetching the key used to encrypt the request
// blob. Will eventually be required.
'coordinatorOrigin':
'https://publickeyservice.gcp.privacysandboxservices.com',
'https://publickeyservice.pa.gcp.privacysandboxservices.com/',
// 'requestSize' the affects the size of the returned request (optional).
'requestSize': 51200,
// 'perBuyerConfig' specifies per-buyer options for size optimizations when
// constructing the blob (optional).
'perBuyerConfig': {
'https://buyer1.origin.example.com': {
// 'targetSize' specifies the size of the blob to devote to this buyer
// (optional).
"targetSize": 8192,
},
'https://buyer2.origin.example.com': {}
}
});
```

The `seller` field will be checked to ensure it matches the `seller` specified
in the auction configuration passed to `runAdAuction()` with the response. The
`coordinatorOrigin` selects which set of TEE keys should be used to encrypt this
request. The `coordinatorOrigin` must be a coordinator that is known to Chrome.
The `requestSize` and `perBuyerConfig` fields are described in more detail in
the [Request Size and Configuration](#request-size-and-configuration) section below.

The returned `auctionBlob` is a Promise that will resolve to an `AdAuctionData` object. This object contains `requestId` and `request` fields.
The `requestId` contains a UUID that needs to be presented to `runAdAuction()` along with the response.
The `request` field is a `Uint8Array` containing the information needed for the [ProtectedAudienceInput](https://github.com/privacysandbox/fledge-docs/blob/main/bidding_auction_services_api.md#protectedaudienceinput) in a `SelectAd` B&A call,
Expand Down Expand Up @@ -130,6 +150,47 @@ const myAuctionConfig = {
Note that since the `serverResponse` field in the config is a promise it is
possible to run the on-device auction in parallel with the B&A auction.

## Request Size and Configuration

### Request Size Controls
The `requestSize` field provided to `navigator.getInterestGroupAdAuctionData()`
can be used to specify the maximum size of the returned request. If the
`perBuyerConfig` field is not present and the blob fits into a
size bucket smaller than `requestSize` then that size will be used instead.
JensenPaul marked this conversation as resolved.
Show resolved Hide resolved

If the `perBuyerConfig` field is specified and non-empty, the returned encrypted
blob will be exactly `requestSize` bytes long unless there was an error. If an error
Copy link
Contributor

@JacobGo JacobGo Jul 8, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a seller concerned about request size, perBuyerConfig returning the exact requestSize is quite suboptimal. While it's highly desirable to fairly fit multiple buyers on the request, we would prefer to take the min(actual_size, request_size) instead.

Could we satisfy the privacy constraints in a way that better optimizes for streamlined request payload size?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that returning the exact request size is unfortunate, but returning even a bucketed size leaks significantly more data than we are comfortable with.

One alternative that we considered was allowing the config to be specified out of band per seller, and only allowed to change relatively slowly (preventing the leak from calling the API multiple times with the slightly different parameters). Unfortunately this can be worked around using multiple sellers that have configs that are slightly different. The sellers don't even have to be cooperating because the attack can be completely client-side.

occured then the returned blob will be 0 size and the function may throw an error.

### Buyer Controls
If the `perBuyerConfig` field is specified then the blob will only include the
interest groups for the buyers specifically listed. If `requestSize` is not
specified then the sum of the `targetSize` of each buyer will be used for the
`requestSize`. Interest groups for each buyer will be added to the request -- in
decreasing order by the interest group's `priority` field -- until the next
interest group does not fit.

Space can be allocated between different buyers in several different modes, depending
on what options are specified in the `perBuyerConfig`:

1. Equally - Space is divided equally between buyers when `targetSize` is not specified.

2. Proportionally - Space is assigned to buyers using `targetSize` as the
weight. So a buyer with a `targetSize` of 2 will can use twice as much space
as a buyer with a `targetSize` of 1. If all buyers have a `targetSize`
specified then proportional mode is used.

3. Fixed/Mixed - Space is first allocated to buyers with `targetSize` specified.
They get up to `targetSize` bytes. The remaining space is divided equally
between the buyers that did not have `targetSize` specified.

The browser will first process buyers with `targetSize` specified before
processing buyers without that field specified. Within either of these groups
buyers are processed in random order. Space that was allocated to a buyer but
was not used is divided up among remaining buyers based on the active allocation
mode. The browser may, as an optimization, calculate and use the maximum length
used by a buyer to better inform its allocation strategy.

## Privacy Considerations

The blobs sent to and received from the B&A servers can contain data that could be used to re-identify the user across different web sites. To prevent this data from being used to join the user’s cross-site identities, the data is encrypted with public keys whose corresponding private keys are only shared with B&A server instances running in TEEs and running public open-source binaries known to prevent cross-site identity joins (e.g. by preventing logging or other activities which might permit such joins).
Expand Down
Loading