diff options
Diffstat (limited to 'toolkit/components/antitracking/docs')
14 files changed, 612 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..b04222d190 --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/index.md @@ -0,0 +1,230 @@ +# 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 that 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 - which is not enabled default for users. + +### 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). + +The clear history UI has a intuitive and modern UI, which offers users an easy way to clear their data, while feeling that their privacy is secured in Firefox. The UI changes were undertaken in this [meta bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1853996). + +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.| +| privacy.clearHistory.* | Categories of data to be cleared in the clear history or browser context. True = clear category.| +| privacy.clearSiteData.* | Categories of data to be cleared in the clear site data context. True = clear category.| + +### 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`. + +The recent revamp of them clear history dialog led to a combination of the various entry points, to use the same dialog +#### Clear browsing data and cookies +- Accessible via + - `about:preferences#privacy` => Clear Site Data + - `about:preferences#privacy` => Clear History + - Hamburger menu => History => Clear Recent History + - Clears a configurable list of categories as defined in [Sanitizer.sys.mjs](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/Sanitizer.sys.mjs#455) +- Can clear everything or a specific time range +- Shows data sizes based on time range for cookies and site data using the method [getQuotaUsageForTimeRanges](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/SiteDataManager.sys.mjs#392) +- Currently, the cache and some site settings are over cleared (clears everything, regardless of time range selection). Outstanding bugs: + - [Bug 1860069 - Clearing cache by range clears the full cache](https://bugzilla.mozilla.org/show_bug.cgi?id=1860069) + - [Bug 1878902 - Investigate clearing site preferences by range](https://bugzilla.mozilla.org/show_bug.cgi?id=1878902) +- Source + - [sanitize_v2.xhtml](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/base/content/sanitize_v2.xhtml) + - [sanitizeDialog.js](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/base/content/sanitizeDialog.js) + + + +#### 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.sys.mjs](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/Sanitizer.sys.mjs#455) +- 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/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/toolkit/components/cleardata/PrincipalsCollector.sys.mjs#83) 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.sys.mjs [calls the ClearDataService](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/Sanitizer.sys.mjs#1299,1304-1309) to clear data for every principal from the filtered list +- Source + - Most of the sanitize-on-shutdown logic is implemented in [Sanitizer.sys.mjs](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/Sanitizer.sys.mjs) + - The main entry point is [sanitizeOnShutdown](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/Sanitizer.sys.mjs#1050) + + - [Parts of sanitize-on-shutdown](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/Sanitizer.sys.mjs#1145-1152) 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) + +```{mermaid} +flowchart TD + A[Clear History] & B[Clear Site Data] & C[Clear On Shutdown]-->|init| D[sanitizeDialog.js] + D --> |Clear|E[Sanitizer.sys.mjs] + E --> F[ClearDataService.sys.mjs] +``` + +#### 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/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/toolkit/components/forgetaboutsite/ForgetAboutSite.sys.mjs) + - [nsIClearDataService flags used](https://searchfox.org/mozilla-central/rev/fbb1e8462ad82b0e76b5c13dd0d6280cfb69e68d/toolkit/components/cleardata/nsIClearDataService.idl#302-307) + +```{mermaid} +flowchart TD + A[Places controller.js] --> B[removeDataFromBaseDomain] + B --> C[ForgetAboutSite.sys.mjs] + C --> D[ClearDataService.sys.mjs] +``` + + + + +#### Manage Cookies and Site Data + +- Accessible via `about:preferences#privacy` => Cookies and Site Data => Manage Data +- Clears \[[flags](https://searchfox.org/mozilla-central/rev/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/SiteDataManager.sys.mjs#537,549-554)\] + - 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/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/SiteDataManager.sys.mjs#437) +- 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/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/browser/modules/SiteDataManager.sys.mjs#537,549-554)\] + - 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/6b8a3f804789fb865f42af54e9d2fef9dd3ec74d/toolkit/components/cleardata/ClearDataService.sys.mjs#85-110). + +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..25b0811441 --- /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/data-sanitization/media/newClearHistoryDialog.png b/toolkit/components/antitracking/docs/data-sanitization/media/newClearHistoryDialog.png Binary files differnew file mode 100644 index 0000000000..49f99cc6a5 --- /dev/null +++ b/toolkit/components/antitracking/docs/data-sanitization/media/newClearHistoryDialog.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 |
