Bug 1811349 - Add documentation for cookie purging, data sanitization and query stripping. r=anti-tracking-reviewers,bvandersloot DONTBUILD
Differential Revision: https://phabricator.services.mozilla.com/D167301
217
toolkit/components/antitracking/docs/cookie-purging/index.md
Normal file
@ -0,0 +1,217 @@
|
||||
# Cookie Purging
|
||||
|
||||
“Cookie Purging” describes a technique that will periodically clear
|
||||
cookies and site data of known tracking domains without user interaction
|
||||
to protect against [bounce
|
||||
tracking](https://privacycg.github.io/nav-tracking-mitigations/#bounce-tracking).
|
||||
|
||||
## Protection Background
|
||||
|
||||
### What similar protections do other browsers have?
|
||||
|
||||
**Safari** classifies sites as redirect trackers which directly or
|
||||
shortly after navigation redirect the user to other sites. Sites which
|
||||
receive user interaction are exempt from this. To detect bigger redirect
|
||||
networks, sites may also inherit redirect tracker
|
||||
[classification](https://privacycg.github.io/nav-tracking-mitigations/#mitigations-safari).
|
||||
If a site is classified as a redirect tracker, any site pointing to it
|
||||
will inherit this classification. Safari does not use tracker lists.
|
||||
|
||||
When the source site is classified as a tracker, Safari will purge all
|
||||
storage, excluding cookies. Sites which receive user interaction within
|
||||
seven days of browser use are exempt. If the destination site's URL
|
||||
includes query parameters or URL fragments, Safari caps the lifetime of
|
||||
client-side set cookies of the destination site to 24 hours.
|
||||
|
||||
**Brave** uses lists to classify redirect trackers. Recently, they have
|
||||
rolled out a new protection, [Unlinkable Bouncing](https://brave.com/privacy-updates/16-unlinkable-bouncing/),
|
||||
which limits first party storage lifetime. The underlying mechanism is
|
||||
called “first-party ephemeral storage”. If a user visits a known
|
||||
bounce-tracker which doesn’t have any pre-existing storage, the browser
|
||||
will create a temporary first-party storage bucket for the destination
|
||||
site. This temporary storage is cleared 30 seconds after the user closes
|
||||
the last tab of the site.
|
||||
|
||||
**Chrome** and **Edge** currently do not implement any navigational
|
||||
tracking protections.
|
||||
|
||||
### Is it standardized?
|
||||
|
||||
At this time there are no standardized navigational tracking
|
||||
protections. The PrivacyCG has a [work item for Navigation-based Tracking Mitigations](https://privacycg.github.io/nav-tracking-mitigations/).
|
||||
Also see Apple’s proposal
|
||||
[here](https://github.com/privacycg/proposals/issues/6).
|
||||
|
||||
### How does it fit into our vision of “Zero Privacy Leaks?”
|
||||
|
||||
Existing tracking protections mechanisms focus mostly on third-party
|
||||
trackers. Redirect tracking can circumvent these mechanisms and utilize
|
||||
first-party storage for tracking. Cookie purging contributes to the
|
||||
“Zero Privacy Leaks” vision by mitigating this cross-site tracking
|
||||
vector.
|
||||
|
||||
## Firefox Status
|
||||
|
||||
Metabug: [Bug 1594226 - \[Meta\] Purging Tracking Cookies](https://bugzilla.mozilla.org/show_bug.cgi?id=1594226)
|
||||
|
||||
### What is the ship state of this protection in Firefox?
|
||||
|
||||
Shipped to Release in standard ETP mode
|
||||
|
||||
### Is there outstanding work?
|
||||
|
||||
The mechanism of storing user interaction as a permission via
|
||||
nsIPermissionManager has shown to be brittle and has led to users
|
||||
getting logged out of sites in the past. The concept of a permission
|
||||
doesn’t fully match that of a user interaction flag. Permissions may be
|
||||
separated between normal browsing and PBM (Bug
|
||||
[1692567](https://bugzilla.mozilla.org/show_bug.cgi?id=1692567)).
|
||||
They may also get purged when clearing site data (Bug
|
||||
[1675018](https://bugzilla.mozilla.org/show_bug.cgi?id=1675018)).
|
||||
|
||||
A proposed solution to this is to create a dedicated data store for
|
||||
keeping track of user interaction. This could also enable tracking user
|
||||
interaction relative to browser usage time, rather than absolute time
|
||||
([Bug 1637146](https://bugzilla.mozilla.org/show_bug.cgi?id=1637146)).
|
||||
|
||||
Important outstanding bugs:
|
||||
- [Bug 1637146 - Use use-time rather than absolute time when computing whether to purge cookies](https://bugzilla.mozilla.org/show_bug.cgi?id=1637146)
|
||||
|
||||
### Existing Documentation
|
||||
|
||||
- [https://developer.mozilla.org/en-US/docs/Web/Privacy/Redirect\_tracking\_protection](https://developer.mozilla.org/en-US/docs/Web/Privacy/Redirect_tracking_protection)
|
||||
|
||||
- [PrivacyCG: Navigational-Tracking Mitigations](https://privacycg.github.io/nav-tracking-mitigations/)
|
||||
|
||||
|
||||
## Technical Information
|
||||
|
||||
### Feature Prefs
|
||||
|
||||
Cookie purging can be enabled or disabled by flipping the
|
||||
`privacy.purge_trackers.enabled` preference. Further, it will only run if
|
||||
the `network.cookie.cookieBehavior` pref is set to `4` or `5` ([bug 1643045](https://bugzilla.mozilla.org/show_bug.cgi?id=1643045) adds
|
||||
support for behaviors `1` and `3`).
|
||||
|
||||
Different log levels can be set via the pref
|
||||
`privacy.purge_trackers.logging.level`.
|
||||
|
||||
The time until user interaction permissions expire can be set to a lower
|
||||
amount of time using the `privacy.userInteraction.expiration` pref. Note
|
||||
that you will have to set this pref before visiting the sites you want
|
||||
to test on, it will not apply retroactively.
|
||||
|
||||
### How does it work?
|
||||
|
||||
Cookie purging periodically clears first-party storage of known
|
||||
trackers, which the user has not interacted with recently. It is
|
||||
implemented in the
|
||||
[PurgeTrackerService](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/antitracking/PurgeTrackerService.jsm),
|
||||
which implements the
|
||||
[nsIPurgeTrackerService](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/antitracking/nsIPurgeTrackerService.idl)
|
||||
IDL interface.
|
||||
|
||||
#### What origins are cleared?
|
||||
|
||||
An origin will be cleared if it fulfills the following conditions:
|
||||
|
||||
1. It has stored cookies or accessed other site storage (e.g.
|
||||
[localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API),
|
||||
[IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API),
|
||||
or the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage))
|
||||
within the last 72 hours. Since cookies are per-host, we will
|
||||
clear both the http and https origin variants of a cookie host.
|
||||
|
||||
2. The origin is [classified as a tracker](https://developer.mozilla.org/en-US/docs/Web/Privacy/Storage_Access_Policy#tracking_protection_explained)
|
||||
in our Tracking Protection list.
|
||||
|
||||
3. No origin with the same base domain (eTLD+1) has a user-interaction
|
||||
permission.
|
||||
|
||||
- This permission is granted to an origin for 45 days once a user
|
||||
interacts with a top-level document from that origin.
|
||||
"Interacting" includes scrolling.
|
||||
|
||||
- Although this permission is stored on a per-origin level, we
|
||||
will check whether any origin with the same base domain has
|
||||
it, to avoid breaking sites with subdomains and a
|
||||
corresponding cookie setup.
|
||||
|
||||
#### What data is cleared?
|
||||
|
||||
Firefox will clear the [following data](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/antitracking/PurgeTrackerService.jsm#205-213):
|
||||
|
||||
- Network cache and image cache
|
||||
|
||||
- Cookies
|
||||
|
||||
- DOM Quota Storage (localStorage, IndexedDB, ServiceWorkers, DOM
|
||||
Cache, etc.)
|
||||
|
||||
- DOM Push notifications
|
||||
|
||||
- Reporting API Reports
|
||||
|
||||
- Security Settings (i.e. HSTS)
|
||||
|
||||
- EME Media Plugin Data
|
||||
|
||||
- Plugin Data (e.g. Flash)
|
||||
|
||||
- Media Devices
|
||||
|
||||
- Storage Access permissions granted to the origin
|
||||
|
||||
- HTTP Authentication Tokens
|
||||
|
||||
- HTTP Authentication Cache
|
||||
|
||||
**Note:** Even though we're clearing all of this data, we currently only
|
||||
flag origins for clearing when they use cookies or other site storage.
|
||||
|
||||
Storage clearing ignores origin attributes. This means that storage will
|
||||
be cleared across
|
||||
[containers](https://wiki.mozilla.org/Security/Contextual_Identity_Project/Containers)
|
||||
and isolated storage (i.e. from [First-Party Isolation](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/cookies#first-party_isolation)).
|
||||
|
||||
#### How frequently is data cleared?
|
||||
|
||||
Firefox clears storage based on the firing of an internal event called
|
||||
[idle-daily](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/antitracking/PurgeTrackerService.jsm#60,62,65),
|
||||
which is defined by the following conditions:
|
||||
|
||||
- It will, at the earliest, fire 24h after the last idle-daily event
|
||||
fired.
|
||||
|
||||
- It will only fire if the user has been idle for at least 3min (for
|
||||
24-48h after the last idle-daily) or 1 min (for >48h after the
|
||||
last idle-daily).
|
||||
|
||||
This means that there are at least 24 hours between each storage
|
||||
clearance, and storage will only be cleared when the browser is idle.
|
||||
When clearing cookies, we sort cookies by creation date and batch them
|
||||
into sets of 100 (controlled by the pref
|
||||
`privacy.purge_trackers.max_purge_count`) for performance reasons.
|
||||
|
||||
#### Debugging
|
||||
|
||||
For debugging purposes, it's easiest to trigger storage clearing by
|
||||
triggering the service directly via the [Browser Console command line](/devtools-user/browser_console/index.html#browser_console_command_line).
|
||||
Note that this is different from the normal [Web Console](/devtools-user/web_console/index.rst)
|
||||
you might use to debug a website, and requires the
|
||||
`devtools.chrome.enabled` pref to be set to true to use it interactively.
|
||||
Once you've enabled the Browser Console you can trigger storage clearing
|
||||
by running the following command:
|
||||
|
||||
``` javascript
|
||||
await Components.classes["@mozilla.org/purge-tracker-service;1"]
|
||||
.getService(Components.interfaces.nsIPurgeTrackerService)
|
||||
.purgeTrackingCookieJars()
|
||||
```
|
||||
|
||||
<!---
|
||||
TODO: consider integrating
|
||||
[https://developer.mozilla.org/en-US/docs/Web/Privacy/Redirect\_tracking\_protection](https://developer.mozilla.org/en-US/docs/Web/Privacy/Redirect_tracking_protection)
|
||||
into firefox source docs. The article doesn’t really belong into MDN,
|
||||
because it’s very specific to Firefox.
|
||||
-->
|
443
toolkit/components/antitracking/docs/data-sanitization/index.md
Normal file
@ -0,0 +1,443 @@
|
||||
# Data Sanitization
|
||||
|
||||
<!-- TODO: This doesn't strictly talk only about toolkit code. Consider splitting the article up and moving to relevant components -->
|
||||
|
||||
Firefox has several Data Sanitization features. They allow users to
|
||||
clear preferences and website data. Clearing data is an essential
|
||||
feature for user privacy. There are two major privacy issues data
|
||||
clearing helps mitigate:
|
||||
|
||||
1. Websites tracking the user via web-exposed APIs and storages. This
|
||||
can be traditional storages, e.g. localStorage, or cookies.
|
||||
However, sites can also use Supercookies, e.g. caches, to persist
|
||||
storage in the browser.
|
||||
|
||||
2. Attackers who have control over a computer can exfiltrate data from
|
||||
Firefox, such as history, passwords, etc.
|
||||
|
||||
## Protection Background
|
||||
|
||||
### What similar protections do other browsers have?
|
||||
|
||||
All major browsers implement data clearing features
|
||||
([Chrome](https://support.google.com/chrome/answer/2392709?hl=en&co=GENIE.Platform%3DDesktop&oco=0#zippy=),
|
||||
[Edge](https://support.microsoft.com/en-us/microsoft-edge/view-and-delete-browser-history-in-microsoft-edge-00cf7943-a9e1-975a-a33d-ac10ce454ca4),
|
||||
[Safari](https://support.apple.com/guide/safari/clear-your-browsing-history-sfri47acf5d6/mac),
|
||||
[Brave](https://support.brave.com/hc/en-us/articles/360054509991-How-do-I-clear-Cookies-and-Site-data-in-Brave-on-Android-)).
|
||||
They usually include a way for users to clear site data within a
|
||||
configurable time-span along with a list of data categories to be
|
||||
cleared.
|
||||
|
||||
Chrome, Edge and Brave all share Chromium’s data clearing dialog with
|
||||
smaller adjustments. Notably, Brave extends it with a clear-on-shutdown
|
||||
mechanism similar to Firefox, while Chrome only supports clearing
|
||||
specifically site data on shutdown.
|
||||
|
||||
Safari’s history clearing feature only allows users to specify a time
|
||||
span. It does not allow filtering by categories, but clears all website
|
||||
related data.
|
||||
|
||||
All browsers allow fine grained control over website cookies and
|
||||
storages via the developer tools.
|
||||
|
||||
### Is it standardized?
|
||||
|
||||
This is a browser UX feature and is therefore not standardized. It is
|
||||
not part of the web platform.
|
||||
|
||||
There is a standardized HTTP header sites can send to clear associated
|
||||
browser cache, cookies and storage:
|
||||
[Clear-Site-Data](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Clear-Site-Data).
|
||||
However, Firefox no longer allows sites to clear caches via the header
|
||||
since [Bug
|
||||
1671182](https://bugzilla.mozilla.org/show_bug.cgi?id=1671182).
|
||||
|
||||
### How does it fit into our vision of “Zero Privacy Leaks?”
|
||||
|
||||
Clearing site data protects users against various tracking techniques
|
||||
that rely on browser state to (re-)identify users. While Total Cookie
|
||||
Protection covers many cross-site tracking scenarios, clearing site data
|
||||
can additionally protect against first-party tracking and other tracking
|
||||
methods that bypass TCP such as [navigational
|
||||
tracking](https://privacycg.github.io/nav-tracking-mitigations/#intro).
|
||||
|
||||
## Firefox Status
|
||||
|
||||
### What is the ship state of this protection in Firefox?
|
||||
|
||||
This long standing set of features is shipped in Release in default ETP
|
||||
mode. In Firefox 91 we introduced [Enhanced Cookie
|
||||
Clearing](https://blog.mozilla.org/security/2021/08/10/firefox-91-introduces-enhanced-cookie-clearing/)
|
||||
which makes use of TCP’s cookie jars. This feature only benefits users
|
||||
who have TCP enabled - in ETP strict mode or Private Browsing Mode.
|
||||
|
||||
### Is there outstanding work?
|
||||
|
||||
Since [Bug
|
||||
1422365](https://bugzilla.mozilla.org/show_bug.cgi?id=1422365) the
|
||||
ClearDataService provides a common interface to clear data of various
|
||||
storage implementations. However, we don’t have full coverage of all
|
||||
browser state yet. There are several smaller blind spots, most of which
|
||||
are listed in this [meta
|
||||
bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1102808). There is
|
||||
also a long backlog of data sanitization bugs
|
||||
[here](https://bugzilla.mozilla.org/show_bug.cgi?id=1550317).
|
||||
|
||||
From a user perspective it’s difficult to understand what kind of data
|
||||
is cleared from which UI. The category selection in the “Clear recent
|
||||
history” dialog is especially confusing.
|
||||
|
||||
Data clearing can take a long time on bigger Firefox profiles. Since
|
||||
these operations mostly run on the main thread, this can lock up the UI
|
||||
making the browser unresponsive until the operation has completed.
|
||||
|
||||
Generally it would be worth revisiting cleaner implementations in the
|
||||
ClearDataService and beyond to see where we can improve clearing
|
||||
performance.
|
||||
|
||||
Slow data clearing is especially problematic on shutdown. If the
|
||||
sanitize-on-shutdown feature takes too long to clear storage, the parent
|
||||
process will be terminated, resulting in a shutdown crash. [Bug
|
||||
1756724](https://bugzilla.mozilla.org/show_bug.cgi?id=1756724)
|
||||
proposes a solution to this: We could show a progress dialog when
|
||||
clearing data. This way we can allow a longer shutdown phase, since the
|
||||
user is aware that we’re clearing data.
|
||||
|
||||
Important outstanding bugs:
|
||||
|
||||
- [Bug 1550317 - \[meta\] Broken data
|
||||
sanitization](https://bugzilla.mozilla.org/show_bug.cgi?id=1550317)
|
||||
|
||||
- [Bug 1102808 - \[meta\] Clear Recent History / Forget button
|
||||
blind
|
||||
spots](https://bugzilla.mozilla.org/show_bug.cgi?id=1102808)
|
||||
|
||||
- [Bug 1756724 - Show a data clearing progress dialog when
|
||||
sanitizing data at shutdown due to "delete cookies and site data
|
||||
when Firefox is
|
||||
closed"](https://bugzilla.mozilla.org/show_bug.cgi?id=1756724)
|
||||
|
||||
### Existing Documentation
|
||||
<!-- TODO: link existing documentation, if any -->
|
||||
|
||||
\-
|
||||
|
||||
## Technical Information
|
||||
|
||||
### Feature Prefs
|
||||
|
||||
| Pref | Description |
|
||||
| ---- | ----------- |
|
||||
| places.forgetThisSite.clearByBaseDomain | Switches “Forget about this site” to clear for the whole base domain rather than just the host. |
|
||||
| privacy.sanitize.sanitizeOnShutdown | Whether to clear data on Firefox shutdown. |
|
||||
| privacy.clearOnShutdown.* | Categories of data to be cleared on shutdown. True = clear category. Data is only cleared if privacy.sanitize.sanitizeOnShutdown is enabled.|
|
||||
|
||||
### How does it work?
|
||||
|
||||
The following section lists user facing data sanitization features in
|
||||
Firefox, along with a brief description and a diagram how they tie into
|
||||
the main clearing logic in `nsIClearDataService`.
|
||||
|
||||
#### Clear Data
|
||||
|
||||
- Accessible via `about:preferences#privacy`
|
||||
|
||||
- Clears site data and caches depending on user selection
|
||||
|
||||
- Clears
|
||||
|
||||
- Cookies
|
||||
|
||||
- DOM storages
|
||||
|
||||
- HSTS
|
||||
|
||||
- EME
|
||||
|
||||
- Caches: CSS, Preflight, HSTS
|
||||
|
||||
- Source
|
||||
|
||||
- [clearSiteData.xhtml](https://searchfox.org/mozilla-central/source/browser/components/preferences/dialogs/clearSiteData.xhtml)
|
||||
|
||||
- [clearSiteData.js](https://searchfox.org/mozilla-central/source/browser/components/preferences/dialogs/clearSiteData.js)
|
||||
|
||||
- [clearSiteData.css](https://searchfox.org/mozilla-central/source/browser/components/preferences/dialogs/clearSiteData.css)
|
||||
|
||||
![image3](media/image3.png)
|
||||
|
||||
![image1](media/image1.png)
|
||||
|
||||
#### Clear Recent History
|
||||
|
||||
- Accessible via hamburger menu => History => Clear Recent
|
||||
history or `about:preferences#privacy` => History => Clear
|
||||
History
|
||||
|
||||
- Clears a configurable list of categories as [defined in
|
||||
Sanitizer.jsm](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#356)
|
||||
|
||||
- Can clear everything or a specific time range
|
||||
|
||||
- Source
|
||||
|
||||
- [sanitize.xhtml](https://searchfox.org/mozilla-central/source/browser/base/content/sanitize.xhtml)
|
||||
|
||||
- [sanitizeDialog.js](https://searchfox.org/mozilla-central/source/browser/base/content/sanitizeDialog.js)
|
||||
|
||||
![image4](media/image4.png)
|
||||
|
||||
#### Forget About this Site
|
||||
|
||||
- Accessible via hamburger menu => History => Contextmenu of an
|
||||
item => Forget About This Site
|
||||
|
||||
- Clears all data associated with the base domain of the selected site
|
||||
|
||||
- \[With TCP\] Also clears data of any third-party sites embedded
|
||||
under the top level base domain
|
||||
|
||||
- The goal is to remove all traces of the associated site from Firefox
|
||||
|
||||
- Clears
|
||||
\[[flags](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/cleardata/nsIClearDataService.idl#302-307)\]
|
||||
|
||||
- History, session history, download history
|
||||
|
||||
- All caches
|
||||
|
||||
- Site data (cookies, dom storages)
|
||||
|
||||
- Encrypted Media Extensions (EME)
|
||||
|
||||
- Passwords (See [Bug
|
||||
702925](https://bugzilla.mozilla.org/show_bug.cgi?id=702925))
|
||||
|
||||
- Permissions
|
||||
|
||||
- Content preferences (e.g. page zoom level)
|
||||
|
||||
- Predictor network data
|
||||
|
||||
- Reports (Reporting API)
|
||||
|
||||
- Client-Auth-Remember flag, Certificate exceptions
|
||||
|
||||
- Does **not** clear bookmarks
|
||||
|
||||
- Source
|
||||
|
||||
- [ForgetAboutSite.jsm](https://searchfox.org/mozilla-central/source/toolkit/components/forgetaboutsite/ForgetAboutSite.jsm)
|
||||
|
||||
- [nsIClearDataService flags
|
||||
used](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/cleardata/nsIClearDataService.idl#302-307)
|
||||
|
||||
![image6](media/image6.png)
|
||||
|
||||
![image2](media/image2.png)
|
||||
|
||||
#### Sanitize on Shutdown
|
||||
|
||||
- Can be enabled via `about:preferences#privacy` => History: Firefox
|
||||
will: Use custom settings for history => Check “Clear history
|
||||
when Firefox closes”
|
||||
|
||||
- After [Bug
|
||||
1681493](https://bugzilla.mozilla.org/show_bug.cgi?id=1681493)
|
||||
it can also be controlled via the checkbox “Delete cookies and
|
||||
site data when Firefox is closed”
|
||||
|
||||
- On shutdown of Firefox, will clear all data for the selected
|
||||
categories. The list of categories is defined in
|
||||
[Sanitizer.jsm](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#356)
|
||||
|
||||
- Categories are the same as for the “Clear recent history” dialog
|
||||
|
||||
- Exceptions
|
||||
|
||||
- Sites which have a “cookie” permission, set to
|
||||
[ACCESS\_SESSION](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/netwerk/cookie/nsICookiePermission.idl#28)
|
||||
always get cleared, even if sanitize-on-shutdown is disabled
|
||||
|
||||
- Sites which have a “cookie” permission set to
|
||||
[ACCESS\_ALLOW](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/netwerk/cookie/nsICookiePermission.idl#19)
|
||||
are exempt from data clearing
|
||||
|
||||
- Caveat: When “site settings” is selected in the categories to be
|
||||
cleared, the Sanitizer will remove exception permissions too.
|
||||
This results in the above exceptions being cleared.
|
||||
|
||||
- Uses PrincipalsCollector to obtain a list of principals which have
|
||||
site data associated with them
|
||||
|
||||
- [getAllPrincipals](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/cleardata/PrincipalsCollector.jsm#72)
|
||||
queries the QuotaManager, the cookie service and the service
|
||||
worker manager for principals
|
||||
|
||||
- The list of principals obtained is checked for permission
|
||||
exceptions. Principals which set a cookie
|
||||
[ACCESS\_ALLOW](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/netwerk/cookie/nsICookiePermission.idl#19)
|
||||
permission are removed from the list.
|
||||
|
||||
- Sanitizer.jsm [calls the
|
||||
ClearDataService](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#1022,1027-1032)
|
||||
to clear data for every principal from the filtered list
|
||||
|
||||
- Source
|
||||
|
||||
- Most of the sanitize-on-shutdown logic is implemented in
|
||||
[Sanitizer.jsm](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm)
|
||||
|
||||
- The main entry point is
|
||||
[sanitizeOnShutdown](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#790)
|
||||
|
||||
- [Parts of
|
||||
sanitize-on-shutdown](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/Sanitizer.jsm#904-911)
|
||||
always have to run, even if the rest of the feature is
|
||||
disabled, to support clearing storage of sites which have
|
||||
“cookie” set to
|
||||
[ACCESS\_SESSION](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/netwerk/cookie/nsICookiePermission.idl#28)
|
||||
(see exceptions above)
|
||||
|
||||
#### Manage Cookies and Site Data
|
||||
|
||||
- Accessible via `about:preferences#privacy` => Cookies and Site Data
|
||||
=> Manage Data
|
||||
|
||||
- Clears
|
||||
\[[flags](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/SiteDataManager.jsm#499,510-514)\]
|
||||
|
||||
- Cookies
|
||||
|
||||
- DOM storages
|
||||
|
||||
- EME
|
||||
|
||||
- Caches: CSS, Preflight, HSTS
|
||||
|
||||
- Lists site cookies and storage grouped by base domain.
|
||||
|
||||
- Clearing data on a more granular (host or origin) level is not
|
||||
possible. This is a deliberate decision to make this UI more
|
||||
thorough in cleaning and easier to understand. If users need very
|
||||
granular data management capabilities, they can install an addon
|
||||
or use the devtools.
|
||||
|
||||
- Allows users to clear storage for specific sites, or all sites
|
||||
|
||||
- \[With TCP\] Also clears data of any third-party sites embedded
|
||||
under the top level base domain
|
||||
|
||||
- Collects list of sites via
|
||||
[SiteDataManager.getSites](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/SiteDataManager.jsm#366)
|
||||
|
||||
- Before removal, prompts via SiteDataManger.promptSiteDataRemoval
|
||||
|
||||
- On removal calls SiteDataManager.removeAll() if all sites have been
|
||||
selected or SiteDataManager.remove() passing a list of sites to be
|
||||
removed.
|
||||
|
||||
- Source
|
||||
|
||||
- [siteDataSettings.xhtml](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/components/preferences/dialogs/siteDataSettings.xhtml)
|
||||
|
||||
- [siteDataSettings.js](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/components/preferences/dialogs/siteDataSettings.js)
|
||||
|
||||
#### Clear Cookies and Site Data
|
||||
|
||||
- Accessible via the identity panel (click on lock icon in the URL
|
||||
bar)
|
||||
|
||||
- Clears
|
||||
\[[flags](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/modules/SiteDataManager.jsm#499,510-514)\]
|
||||
|
||||
- Cookies
|
||||
|
||||
- DOM storages
|
||||
|
||||
- EME
|
||||
|
||||
- Caches: CSS, Preflight, HSTS
|
||||
|
||||
- Button handler method:
|
||||
[clearSiteData](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/browser/base/content/browser-siteIdentity.js#364-385)
|
||||
|
||||
- Calls SiteDataManager.remove() with the base domain of the currently
|
||||
selected tab
|
||||
|
||||
- The button is only shown if a site has any cookies or quota storage.
|
||||
This is checked
|
||||
[here](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/browser/base/content/browser-siteIdentity.js#923).
|
||||
|
||||
- Source
|
||||
|
||||
- [identityPanel.inc.xhtml](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/browser/components/controlcenter/content/identityPanel.inc.xhtml#97)
|
||||
|
||||
- [browser-siteIdentity.js](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/browser/base/content/browser-siteIdentity.js#364)
|
||||
|
||||
![image7](media/image7.png)
|
||||
|
||||
![image5](media/image5.png)
|
||||
|
||||
A broad overview of the different data clearing features accessible via
|
||||
about:preferences#privacy.
|
||||
|
||||
The user can clear data on demand or choose to clear data on shutdown.
|
||||
For the latter the user may make exceptions for specific origins not to
|
||||
be cleared or to be always cleared on shutdown.
|
||||
|
||||
#### ClearDataService
|
||||
|
||||
This service serves as a unified module to hold all data clearing logic
|
||||
in Firefox / Gecko. Callers can use the
|
||||
[nsIClearDataService](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/cleardata/nsIClearDataService.idl)
|
||||
interface to clear data. From JS the service is accessible via
|
||||
Services.clearData.
|
||||
|
||||
To specify which state to clear pass a combination of
|
||||
[flags](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/cleardata/nsIClearDataService.idl#161-308)
|
||||
into aFlags.
|
||||
|
||||
Every category of browser state should have its own cleaner
|
||||
implementation which exposes the following methods to the
|
||||
ClearDataService:
|
||||
|
||||
- **deleteAll**: Deletes all data owned by the cleaner
|
||||
|
||||
- **deleteByPrincipal**: Deletes data associated with a specific
|
||||
principal.
|
||||
|
||||
- **deleteByBaseDomain**: Deletes all entries which are associated
|
||||
with the given base domain. This includes data partitioned by
|
||||
Total Cookie Protection.
|
||||
|
||||
- **deleteByHost**: Clears data associated with a host. Does not clear
|
||||
partitioned data.
|
||||
|
||||
- **deleteByRange**: Clear data which matches a given time-range.
|
||||
|
||||
- **deleteByLocalFiles**: Delete data held for local files and other
|
||||
hostless origins.
|
||||
|
||||
- **deleteByOriginAttributes**: Clear entries which match an
|
||||
[OriginAttributesPattern](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/caps/OriginAttributes.h#153).
|
||||
|
||||
Some of these methods are optional. See [comment
|
||||
here](https://searchfox.org/mozilla-central/rev/cf77e656ef36453e154bd45a38eea08b13d6a53e/toolkit/components/cleardata/ClearDataService.jsm#85-105).
|
||||
If a cleaner does not support a specific method, we will usually try to
|
||||
fall back to deleteAll. For privacy reasons we try to over-clear storage
|
||||
rather than under-clear it or not clear it at all because we can’t
|
||||
target individual entries.
|
||||
|
||||
![image8](media/image8.png)
|
||||
|
||||
Overview of the most important cleaning methods of the ClearDataService
|
||||
called by other Firefox / Gecko components. deleteDataFromPrincipal is
|
||||
called programmatically, while user exposed data clearing features clear
|
||||
by base domain, host or all data.
|
||||
|
||||
<!--
|
||||
TODO: For firefox-source-docs, import JSdoc for relevant modules
|
||||
[like
|
||||
so](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/prompts/docs/nsIPromptService-reference.rst#9)
|
||||
-->
|
After Width: | Height: | Size: 17 KiB |
After Width: | Height: | Size: 52 KiB |
After Width: | Height: | Size: 38 KiB |
After Width: | Height: | Size: 25 KiB |
After Width: | Height: | Size: 120 KiB |
After Width: | Height: | Size: 12 KiB |
After Width: | Height: | Size: 13 KiB |
After Width: | Height: | Size: 58 KiB |
12
toolkit/components/antitracking/docs/index.rst
Normal file
@ -0,0 +1,12 @@
|
||||
=================================
|
||||
Anti-Tracking
|
||||
=================================
|
||||
|
||||
This page is an overview of various anti-tracking components.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Cookie Purging <cookie-purging/index.md>
|
||||
Data Sanitization <data-sanitization/index.md>
|
||||
Query Stripping <query-stripping/index.md>
|
153
toolkit/components/antitracking/docs/query-stripping/index.md
Normal file
@ -0,0 +1,153 @@
|
||||
# Query Parameter Stripping
|
||||
|
||||
To combat [Navigational
|
||||
Tracking](https://privacycg.github.io/nav-tracking-mitigations/#navigational-tracking)
|
||||
through [link
|
||||
decoration](https://privacycg.github.io/nav-tracking-mitigations/#link-decoration),
|
||||
Firefox can strip known tracking query parameters from URLs before the
|
||||
user navigates to them.
|
||||
|
||||
## Protection Background
|
||||
|
||||
### What similar protections do other browsers have?
|
||||
|
||||
Brave also has a list-based query parameter stripping mechanism. A list
|
||||
of query parameters stripped can be found
|
||||
[here](https://github.com/brave/brave-core/blob/5fcad3e35bac6fea795941fd8189a59d79d488bc/browser/net/brave_site_hacks_network_delegate_helper.cc#L29-L67).
|
||||
Brave also has a strip-on-copy feature which allows users to copy a
|
||||
stripped version of the current URL.
|
||||
|
||||
### Is it standardized?
|
||||
|
||||
At this time there are no standardized navigational tracking
|
||||
protections. The PrivacyCG has a [work item for Navigation-based
|
||||
Tracking
|
||||
Mitigations](https://privacycg.github.io/nav-tracking-mitigations/).
|
||||
Also see Apple’s proposal
|
||||
[here](https://github.com/privacycg/proposals/issues/6).
|
||||
|
||||
### How does it fit into our vision of “Zero Privacy Leaks?”
|
||||
|
||||
Existing tracking protections mechanisms in Firefox, such as ETP and TCP
|
||||
focus mostly on third-party trackers. Redirect tracking can circumvent
|
||||
these mechanisms by passing identifiers through link decoration and
|
||||
first-party storage. Query parameter stripping contributes to the “Zero
|
||||
Privacy Leaks” vision by mitigating this cross-site tracking vector.
|
||||
|
||||
## Firefox Status
|
||||
|
||||
Metabug: [Bug 1706602 - \[meta\] Implement URL query string stripping
|
||||
prototype](https://bugzilla.mozilla.org/show_bug.cgi?id=1706602)
|
||||
|
||||
### What is the ship state of this protection in Firefox?
|
||||
|
||||
Query stripping is enabled in release in ETP strict with an initial list
|
||||
of query params:
|
||||
|
||||
- mc\_eid
|
||||
|
||||
- oly\_anon\_id
|
||||
|
||||
- oly\_enc\_id
|
||||
|
||||
- \_\_s
|
||||
|
||||
- vero\_id
|
||||
|
||||
- \_hsenc
|
||||
|
||||
- mkt\_tok
|
||||
|
||||
- fbclid
|
||||
|
||||
It is enabled in Nightly by default in all modes with an extended
|
||||
strip-list. You can find the current list of parameters that are
|
||||
stripped
|
||||
[here](https://firefox.settings.services.mozilla.com/v1/buckets/main/collections/query-stripping/records).
|
||||
Note that some records have a *filter\_expression* that limits where
|
||||
they apply.
|
||||
|
||||
### Is there outstanding work?
|
||||
|
||||
After our initial release on ETP strict, we are considering to ship the
|
||||
feature to Private Browsing Mode and possibly also to enable it by default
|
||||
in release in the future.
|
||||
|
||||
Other possible improvements:
|
||||
|
||||
- Extend the list of query parameters stripped, in accordance with our policy.
|
||||
|
||||
- Extend the protection to cover different kinds of link decoration, beyond just query parameters.
|
||||
|
||||
- Ability to identify and strip hashed link decoration fields
|
||||
|
||||
- Strip query params for urls shared / copied out from the browser
|
||||
|
||||
Outstanding bugs:
|
||||
|
||||
- See dependencies of [Bug 1706602 - \[meta\] Implement URL query
|
||||
string stripping
|
||||
prototype](https://bugzilla.mozilla.org/show_bug.cgi?id=1706602)
|
||||
|
||||
### Existing Documentation
|
||||
|
||||
- [Anti-Tracking Policy: Navigational cross-site
|
||||
tracking](https://wiki.mozilla.org/Security/Anti_tracking_policy#2._Navigational_cross-site_tracking)
|
||||
|
||||
## Technical Information
|
||||
|
||||
### Feature Prefs
|
||||
|
||||
| Pref | Description |
|
||||
| ---- | ----------- |
|
||||
| privacy.query_stripping.enabled | Enable / disable the feature in normal browsing. |
|
||||
| privacy.query_stripping.enabled.pbmode | Enable / disable the feature in private browsing. |
|
||||
| privacy.query_stripping.allow_list | Comma separated list of sites (without scheme) which should not have their query parameters stripped. |
|
||||
| privacy.query_stripping.redirect | Whether to perform stripping for redirects. |
|
||||
| privacy.query_stripping.strip_list | List of space delimited query parameters to be stripped. |
|
||||
|
||||
### How does it work?
|
||||
|
||||
![Architecture](overview.png "Overview")
|
||||
|
||||
[**UrlQueryStrippingListService**](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStrippingListService.jsm)
|
||||
|
||||
- Collects list of query parameters to be stripped and allow-list from
|
||||
the *privacy.query\_stripping.strip\_list/allow\_list* preference
|
||||
and the *query-stripping* Remote Settings collection
|
||||
|
||||
- Lists from the two sources are
|
||||
[concatenated](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStrippingListService.jsm#150-151)
|
||||
|
||||
- Lists are distributed via [observer
|
||||
notification](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStrippingListService.jsm#158-161)
|
||||
via the
|
||||
[nsIUrlQueryStrippingListService](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/nsIURLQueryStrippingListService.idl#25).
|
||||
[onQueryStrippingListUpdate](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/nsIURLQueryStrippingListService.idl#25)
|
||||
is called initially on registration and whenever the preferences
|
||||
or the Remote Settings collection updates.
|
||||
|
||||
[**URLQueryStringStripper**](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStringStripper.h)
|
||||
|
||||
- Only subscriber of the
|
||||
[UrlQueryStrippingListService](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStrippingListService.jsm)
|
||||
|
||||
- Holds [hash set
|
||||
representations](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStringStripper.h#56-57)
|
||||
of the strip- and allow-list.
|
||||
|
||||
- [URLQueryStringStripper::Strip](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/toolkit/components/antitracking/URLQueryStringStripper.cpp#45):
|
||||
takes a nsIURI as input and strips any query parameters that are
|
||||
on the strip-list. If the given URI matches a site on the
|
||||
allow-list no query parameters are stripped.
|
||||
|
||||
**Consumers**
|
||||
|
||||
- [nsDocShell::DoURILoad](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/docshell/base/nsDocShell.cpp#10569):
|
||||
Strips in the content, before creating the channel.
|
||||
|
||||
- [BrowsingContext::LoadURI](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/docshell/base/BrowsingContext.cpp#2019):
|
||||
Strips before loading the URI in the parent.
|
||||
|
||||
- [nsHttpChannel::AsyncProcessRedirection](https://searchfox.org/mozilla-central/rev/3269d4c928ef0d8310c2f57634e9b6057aa636e9/netwerk/protocol/http/nsHttpChannel.cpp#5154):
|
||||
Strips query parameters for HTTP redirects (e.g. 301).
|
After Width: | Height: | Size: 44 KiB |
@ -94,3 +94,5 @@ XPCSHELL_TESTS_MANIFESTS += ["test/xpcshell/xpcshell.ini"]
|
||||
TEST_DIRS += ["test/gtest"]
|
||||
|
||||
REQUIRES_UNIFIED_BUILD = True
|
||||
|
||||
SPHINX_TREES["anti-tracking"] = "docs"
|
||||
|
@ -28,3 +28,4 @@ This is the nascent documentation of the Toolkit code that is shared across Fire
|
||||
components/extensions/webextensions/index
|
||||
/extensions/spellcheck/index
|
||||
mozapps/update/docs/index
|
||||
components/antitracking/anti-tracking/index
|
||||
|