Design-Documents/Tor-Browser-Design-Doc.md

@@ -87,7 +87,7 @@ For more practical information regarding Tor Browser development, please consult
 
 ### 1.1. Browser Component Overview
 
-The Tor Browser is based on [Mozilla's Extended Support Release (ESR) Firefox branch](https://www.mozilla.org/en-US/firefox/organizations/). We have a [series of patches](https://gitlab.torproject.org/tpo/applications/tor-browser) against this browser to enhance privacy and security. Browser behavior is additionally augmented through the [Torbutton extension](https://gitlab.torproject.org/tpo/applications/torbutton), though we are in the process of moving this functionality into direct Firefox patches. We also [change a number of Firefox preferences](https://gitlab.torproject.org/tpo/applications/tor-browser/-/blob/main/browser/app/profile/000-tor-browser.js) from their defaults.
+The Tor Browser is based on [Mozilla's Extended Support Release (ESR) Firefox branch](https://www.mozilla.org/en-US/firefox/organizations/). We have a [series of patches](https://gitlab.torproject.org/tpo/applications/tor-browser) against this browser to enhance privacy and security. We also [change a number of Firefox preferences](https://gitlab.torproject.org/tpo/applications/tor-browser/-/blob/main/browser/app/profile/000-tor-browser.js) from their defaults.
 
 Tor process management and configuration is accomplished through the [Tor Launcher](https://gitlab.torproject.org/tpo/applications/tor-launcher) addon, which provides the initial Tor configuration splash screen and bootstrap progress bar. Tor Launcher is also compatible with Thunderbird, Instantbird, and XULRunner.
 
@@ -325,23 +325,23 @@ Proxy obedience is assured through the following:
 
 2. **Disabling plugins**
 
-    Plugins, like Flash, have the ability to make arbitrary OS system calls and [bypass proxy settings](https://ip-check.info/). This includes the ability to make UDP sockets and send arbitrary data independent of the browser proxy settings.
+    ~Plugins, like Flash, have the ability to make arbitrary OS system calls and [bypass proxy settings](https://ip-check.info/). This includes the ability to make UDP sockets and send arbitrary data independent of the browser proxy settings.~
 
-    Torbutton disables plugins by using the `@mozilla.org/plugin/host;1` service to mark the plugin tags as disabled. This block can be undone through both the Torbutton Security UI, and the Firefox Plugin Preferences.
+    ~Torbutton disables plugins by using the `@mozilla.org/plugin/host;1` service to mark the plugin tags as disabled. This block can be undone through both the Torbutton Security UI, and the Firefox Plugin Preferences.~
 
-    If the user does enable plugins in this way, plugin-handled objects are still restricted from automatic load through Firefox's click-to-play preference `plugins.click_to_play`.
+    ~If the user does enable plugins in this way, plugin-handled objects are still restricted from automatic load through Firefox's click-to-play preference `plugins.click_to_play`.~
 
-    In addition, to reduce any unproxied activity by arbitrary plugins at load time, and to reduce the fingerprintability of the installed plugin list, we also patch the Firefox source code to prevent the load of any plugins except for Flash and Gnash. Even for Flash and Gnash, we also patch Firefox to prevent loading them into the address space until they are explicitly enabled.
+    ~In addition, to reduce any unproxied activity by arbitrary plugins at load time, and to reduce the fingerprintability of the installed plugin list, we also patch the Firefox source code to prevent the load of any plugins except for Flash and Gnash. Even for Flash and Gnash, we also patch Firefox to prevent loading them into the address space until they are explicitly enabled.~
 
     With [Gecko Media Plugins](https://wiki.mozilla.org/GeckoMediaPlugins) (GMPs) a second type of plugins is available. They are mainly third party codecs and [EME](https://www.w3.org/TR/encrypted-media/) content decryption modules. We currently disable these plugins as they either can't be built reproducibly or are binary blobs which we are not allowed to audit (or both). For the EME case we use the `--disable-eme` configure switch and set `browser.eme.ui.enabled`, `media.gmp-eme-adobe.visible`, `media.gmp-eme-adobe.enabled`, `media.gmp-widevinecdm.visible`, `media.gmp-widevinecdm.enabled`, `media.eme.enabled`, and `media.eme.apiVisible` to **false** to indicate to the user that this feature is disabled. For GMPs in general we make sure that the external server is not even pinged for updates/downloads in the first place by setting `media.gmp-manager.url.override` to `data:text/plain`, and avoid any UI with `media.gmp-provider.enabled` set to **false**. Moreover, we disable GMP downloads via local fallback by setting `media.gmp-manager.updateEnabled` to **false**. To reduce our attack surface we exclude the ClearKey EME system, too.
 
 3. **External App Blocking and Drag Event Filtering**
 
-    External apps can be induced to load files that perform network activity. Unfortunately, there are cases where such apps can be launched automatically with little to no user input. In order to prevent this, we ship [Firefox](https://gitlab.torproject.org/legacy/trac/-/issues/8324) [patches](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/41613) and Torbutton installs a component to provide the user with a popup whenever the browser attempts to launch a helper application.
+    External apps can be induced to load files that perform network activity. Unfortunately, there are cases where such apps can be launched automatically with little to no user input. In order to prevent this, we ship [Firefox](https://gitlab.torproject.org/legacy/trac/-/issues/8324) [patches](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/41613) to provide the user with a popup whenever the browser attempts to launch a helper application.
 
     Furthermore, we ship a [patch for Linux users](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/23044) that makes sure `sftp://` and `smb://` URLs are not passed along to the operating system as this can lead to proxy bypasses on systems that have GIO/GnomeVFS support.
 
-    Additionally, modern desktops now preemptively fetch any URLs in Drag and Drop events as soon as the drag is initiated. This download happens independent of the browser's Tor settings, and can be triggered by something as simple as holding the mouse button down for slightly too long while clicking on an image link. We filter drag and drop events events [from Torbutton](https://gitlab.torproject.org/tpo/applications/torbutton/-/blob/main/components/external-app-blocker.js) before the OS downloads the URLs the events contained.
+    Additionally, modern desktops now preemptively fetch any URLs in Drag and Drop events as soon as the drag is initiated. This download happens independent of the browser's Tor settings, and can be triggered by something as simple as holding the mouse button down for slightly too long while clicking on an image link. We filter [drag and drop events](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/41613) before the OS downloads the URLs the events contained.
 
 4. **Disabling system extensions and clearing the addon allow-list**
 
@@ -426,7 +426,7 @@ Unfortunately, many aspects of browser state can serve as identifier storage, an
 
     **Design Goal**: Tor circuits and HTTP connections from a third party in one URL bar origin MUST NOT be reused for that same third party in another URL bar origin.
 
-    **Implementation Status**: The isolation functionality is provided by a Torbutton component that [sets the SOCKS username and password for each request](https://gitlab.torproject.org/tpo/applications/torbutton/-/blob/main/components/domain-isolator.js). The Tor client has logic to prevent connections with different SOCKS usernames and passwords from using the same Tor circuit. Firefox has existing logic to ensure that connections with SOCKS proxies do not re-use existing HTTP Keep-Alive connections unless the proxy settings match. [We extended this logic](https://bugzilla.mozilla.org/show_bug.cgi?id=1200802) to cover SOCKS username and password authentication, providing us with HTTP Keep-Alive unlinkability.
+    **Implementation Status**: The isolation functionality is provided by a component that [sets the SOCKS username and password for each request](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/3455). The Tor client has logic to prevent connections with different SOCKS usernames and passwords from using the same Tor circuit. Firefox has existing logic to ensure that connections with SOCKS proxies do not re-use existing HTTP Keep-Alive connections unless the proxy settings match. [We extended this logic](https://bugzilla.mozilla.org/show_bug.cgi?id=1200802) to cover SOCKS username and password authentication, providing us with HTTP Keep-Alive unlinkability.
 
 9. **SharedWorkers**
 
@@ -454,9 +454,9 @@ Unfortunately, many aspects of browser state can serve as identifier storage, an
 
 13. **window.name**
 
-    [window.name](https://developer.mozilla.org/En/DOM/Window.name) is a magical DOM property that for some reason is allowed to retain a persistent value for the lifespan of a browser tab. It is possible to utilize this property for [identifier storage](https://www.thomasfrank.se/sessionvars.html).
+    ~[window.name](https://developer.mozilla.org/En/DOM/Window.name) is a magical DOM property that for some reason is allowed to retain a persistent value for the lifespan of a browser tab. It is possible to utilize this property for [identifier storage](https://www.thomasfrank.se/sessionvars.html).
 
-    In order to eliminate non-consensual linkability but still allow for sites that utilize this property to function, we reset the `window.name` property of tabs in Torbutton every time we encounter a blank Referer. This behavior allows `window.name` to persist for the duration of a click-driven navigation session, but as soon as the user enters a new URL or navigates between HTTPS/HTTP schemes, the property is cleared.
+    In order to eliminate non-consensual linkability but still allow for sites that utilize this property to function, we reset the `window.name` property of tabs in Torbutton every time we encounter a blank Referer. This behavior allows `window.name` to persist for the duration of a click-driven navigation session, but as soon as the user enters a new URL or navigates between HTTPS/HTTP schemes, the property is cleared.~
 
 14. **Auto form-fill**
 
@@ -808,11 +808,11 @@ For more details on fingerprinting bugs and enhancements, see the [Fingerprintin
 
 ### 4.7. Long-Term Unlinkability via "New Identity" button
 
-In order to avoid long-term linkability, we provide a "New Identity" context menu option in Torbutton. This context menu option is active if Torbutton can read the environment variables $TOR_CONTROL_PASSWD and $TOR_CONTROL_PORT.
+In order to avoid long-term linkability, we provide a "New Identity" context menu option in Tor Browser.
 
 **Design Goal**: All linkable identifiers and browser state MUST be cleared by this feature.
 
-**Implementation Status**: First, Torbutton disables JavaScript in all open tabs and windows by using both the [browser.docShell.allowJavaScript](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIDocShell#Attributes) attribute as well as [nsIDOMWindowUtil.suppressEventHandling()](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIDOMWindowUtils#suppressEventHandling%28%29). We then stop all page activity for each tab using [browser.webNavigation.stop(nsIWebNavigation.STOP_ALL)](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIWebNavigation#stop%28%29). We then clear the site-specific Zoom by temporarily disabling the preference `browser.zoom.siteSpecific`, and clear the GeoIP wifi token URL `geo.wifi.access_token` and the last opened URL preference (if it exists). Each tab is then closed.
+**Implementation Status**: First, Tor Browser disables JavaScript in all open tabs and windows by using both the [browser.docShell.allowJavaScript](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIDocShell#Attributes) attribute as well as [nsIDOMWindowUtil.suppressEventHandling()](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIDOMWindowUtils#suppressEventHandling%28%29). We then stop all page activity for each tab using [browser.webNavigation.stop(nsIWebNavigation.STOP_ALL)](https://developer.mozilla.org/en-US/docs/XPCOM_Interface_Reference/nsIWebNavigation#stop%28%29). We then clear the site-specific Zoom by temporarily disabling the preference `browser.zoom.siteSpecific`, and clear the GeoIP wifi token URL `geo.wifi.access_token` and the last opened URL preference (if it exists). Each tab is then closed.
 
 After closing all tabs, we then clear the searchbox and findbox text and emit ["browser:purge-session-history"](https://developer.mozilla.org/en-US/docs/Supporting_private_browsing_mode#Private_browsing_notifications) (which instructs addons and various Firefox components to clear their session state). Then we manually clear the following state: HTTP auth, SSL state, crypto tokens, OCSP state, site-specific content preferences (including HSTS state), the undo tab history, content and image cache, offline and memory cache, offline storage, Cache storage, IndexedDB storage, asm.js cache, cookies, DOM storage, the safe browsing key, the Google wifi geolocation token (if it exists), and the domain isolator state. We also clear NoScript's site and temporary permissions, and all other browser site permissions.
 
@@ -854,9 +854,9 @@ In addition to the above mechanisms that are devoted to preserving privacy while
 
 3. **Privacy-preserving update notification**
 
-    In order to inform the user when their Tor Browser is out of date, we perform a privacy-preserving update check asynchronously in the background. The check uses Tor to download the file https://www.torproject.org/projects/torbrowser/RecommendedTBBVersions and searches that version list for the current value for the local preference `torbrowser.version`. If the value from our preference is present in the recommended version list, the check is considered to have succeeded and the user is up to date. If not, it is considered to have failed and an update is needed. The check is triggered upon browser launch, new window, and new tab, but is rate limited so as to happen no more frequently than once every 1.5 hours.
+    ~In order to inform the user when their Tor Browser is out of date, we perform a privacy-preserving update check asynchronously in the background. The check uses Tor to download the file https://www.torproject.org/projects/torbrowser/RecommendedTBBVersions and searches that version list for the current value for the local preference `torbrowser.version`. If the value from our preference is present in the recommended version list, the check is considered to have succeeded and the user is up to date. If not, it is considered to have failed and an update is needed. The check is triggered upon browser launch, new window, and new tab, but is rate limited so as to happen no more frequently than once every 1.5 hours.~
 
-    If the check fails, we cache this fact, and update the Torbutton graphic to display a flashing warning icon and insert a menu option that provides a link to our download page. Additionally, we reset the value for the browser homepage to point to a [page that informs the user](https://check.torproject.org/?lang=en-US&small=1&uptodate=0) that their browser is out of date.
+    ~If the check fails, we cache this fact, and update the Torbutton graphic to display a flashing warning icon and insert a menu option that provides a link to our download page. Additionally, we reset the value for the browser homepage to point to a [page that informs the user](https://check.torproject.org/?lang=en-US&small=1&uptodate=0) that their browser is out of date.~
 
     We also make use of the in-browser Mozilla updater, and have [patched the updater](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/4234) to avoid sending OS and Kernel version information as part of its update pings.