diff options
Diffstat (limited to 'toolkit/components/antitracking/docs')
13 files changed, 825 insertions, 0 deletions
diff --git a/toolkit/components/antitracking/docs/cookie-purging/index.md b/toolkit/components/antitracking/docs/cookie-purging/index.md new file mode 100644 index 0000000000..7b8c76cd39 --- /dev/null +++ b/toolkit/components/antitracking/docs/cookie-purging/index.md @@ -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.rst#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. +--> diff --git a/toolkit/components/antitracking/docs/data-sanitization/index.md b/toolkit/components/antitracking/docs/data-sanitization/index.md new file mode 100644 index 0000000000..412896c200 --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/index.md @@ -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) + + + + + +#### 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) + + + +#### 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.sys.mjs](https://searchfox.org/mozilla-central/source/toolkit/components/forgetaboutsite/ForgetAboutSite.sys.mjs) + + - [nsIClearDataService flags + used](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/cleardata/nsIClearDataService.idl#302-307) + + + + + +#### 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) + + + + + +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. + + + +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) +--> diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image1.png b/toolkit/components/antitracking/docs/data-sanitization/media/image1.png Binary files differnew file mode 100644 index 0000000000..c9029753a3 --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/media/image1.png diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image2.png b/toolkit/components/antitracking/docs/data-sanitization/media/image2.png Binary files differnew file mode 100644 index 0000000000..451b297b7e --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/media/image2.png diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image3.png b/toolkit/components/antitracking/docs/data-sanitization/media/image3.png Binary files differnew file mode 100644 index 0000000000..8b37d5f160 --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/media/image3.png diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image4.png b/toolkit/components/antitracking/docs/data-sanitization/media/image4.png Binary files differnew file mode 100644 index 0000000000..566b0d3b36 --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/media/image4.png diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image5.png b/toolkit/components/antitracking/docs/data-sanitization/media/image5.png Binary files differnew file mode 100644 index 0000000000..21f34894fa --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/media/image5.png diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image6.png b/toolkit/components/antitracking/docs/data-sanitization/media/image6.png Binary files differnew file mode 100644 index 0000000000..719227d2ca --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/media/image6.png diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image7.png b/toolkit/components/antitracking/docs/data-sanitization/media/image7.png Binary files differnew file mode 100644 index 0000000000..9259380188 --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/media/image7.png diff --git a/toolkit/components/antitracking/docs/data-sanitization/media/image8.png b/toolkit/components/antitracking/docs/data-sanitization/media/image8.png Binary files differnew file mode 100644 index 0000000000..469aa398cd --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/media/image8.png diff --git a/toolkit/components/antitracking/docs/index.rst b/toolkit/components/antitracking/docs/index.rst new file mode 100644 index 0000000000..45d888b989 --- /dev/null +++ b/toolkit/components/antitracking/docs/index.rst @@ -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> diff --git a/toolkit/components/antitracking/docs/query-stripping/index.md b/toolkit/components/antitracking/docs/query-stripping/index.md new file mode 100644 index 0000000000..e49d8513ba --- /dev/null +++ b/toolkit/components/antitracking/docs/query-stripping/index.md @@ -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? + + + +[**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). diff --git a/toolkit/components/antitracking/docs/query-stripping/overview.png b/toolkit/components/antitracking/docs/query-stripping/overview.png Binary files differnew file mode 100644 index 0000000000..63cf495202 --- /dev/null +++ b/toolkit/components/antitracking/docs/query-stripping/overview.png |
