@@ -83,7 +83,7 @@ This document describes the [design requirements](#2-design-requirements-and-phi
For more practical information regarding Tor Browser development, please consult the [Application's Team Wiki](https://gitlab.torproject.org/tpo/applications/team/-/wikis/Development-Information).
### 1.1. Tor Browser Component Overview
### 1.1 Tor Browser Component Overview
The browser is based on [Mozilla's Extended Support Release (ESR) Firefox branch](https://www.mozilla.org/en-US/firefox/organizations/). We maintain a [series of patches](https://gitlab.torproject.org/tpo/applications/tor-browser) atop ESR Firefox which:
- Backport surgical privacy features, security fixes and bug fixes from Mozilla's Rapid Release (RR) Firefox branch
...
...
@@ -97,7 +97,7 @@ To provide censorship circumvention in areas where the public Tor network is blo
## 2. Design Requirements and Philosophy
The browser design requirements are meant to describe the properties of a Private Browsing Mode that defends against both network and local forensic adversaries.
These browser design requirements are meant to describe the properties of a Private Browsing Mode that defends against both network and local forensic adversaries.
There are two main categories of requirements: [Security Requirements](#21-security-requirements), and [Privacy Requirements](#22-privacy-requirements). Security Requirements are the minimum properties in order for a browser to be able to support Tor and similar privacy proxies safely. Privacy requirements are the set of properties that cause us to prefer one browser over another.
...
...
@@ -105,7 +105,7 @@ While we will endorse the use of browsers that meet the security requirements, i
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
### 2.1. Security Requirements
### 2.1 Security Requirements
The security requirements are primarily concerned with ensuring the safe use of Tor. Violations in these properties typically result in serious risk for the user in terms of immediate deanonymization and/or observability. With respect to browser support, security requirements are the minimum properties in order for Tor to support the use of a particular browser.
...
...
@@ -128,7 +128,7 @@ The security requirements are primarily concerned with ensuring the safe use of
`this section should be removed and we need to redirect users who need such protections to Tails`
### 2.2. Privacy Requirements
### 2.2 Privacy Requirements
The privacy requirements are primarily concerned with reducing linkability: the ability for a user's activity on one site to be linked with their activity on another site without their knowledge or explicit consent. With respect to browser support, privacy requirements are the set of properties that cause us to prefer one browser over another.
...
...
@@ -146,7 +146,7 @@ n
The browser MUST provide an obvious, easy way for the user to remove all of its authentication tokens and browser state and obtain a fresh identity. Additionally, the browser SHOULD clear linkable state by default automatically upon browser restart, except at user option.
### 2.3. Philosophy
### 2.3 Philosophy
In addition to the above design requirements, the technology decisions about the browser are also guided by some philosophical positions about technology.
...
...
@@ -202,7 +202,7 @@ In addition to the above design requirements, the technology decisions about the
A Tor web browser adversary has a number of goals, capabilities, and attack types that can be used to illustrate the design requirements for the browser. Let's start with the goals.
### 3.1. Adversary Goals
### 3.1 Adversary Goals
1.**Bypassing proxy settings**
...
...
@@ -232,7 +232,7 @@ A Tor web browser adversary has a number of goals, capabilities, and attack type
`section about censorship goals`
### 3.2. Adversary Capabilities - Positioning
### 3.2 Adversary Capabilities - Positioning
The adversary can position themselves at a number of different locations in order to execute their attacks.
...
...
@@ -256,7 +256,7 @@ The adversary can position themselves at a number of different locations in orde
`also mention adversaries in the home`
### 3.3. Adversary Capabilities - Attacks
### 3.3 Adversary Capabilities - Attacks
The adversary can perform the following attacks from a number of different positions to accomplish various aspects of their goals. It should be noted that many of these attacks (especially those involving IP address leakage) are often performed by accident by websites that simply have JavaScript, dynamic CSS elements, and plugins. Others are performed by ad servers seeking to correlate users' activity across different IP addresses, and still others are performed by malicious agents on the Tor network and at national firewalls.
...
...
@@ -330,7 +330,7 @@ The Implementation section is divided into subsections, each of which correspond
In some cases, the implementation meets the design requirements in a non-ideal way (for example, by disabling features). In rare cases, there may be no implementation at all. Both of these cases are denoted by differentiating between the **Design Goal** and the **Implementation Status** for each property. Corresponding bugs in the [Tor Browser issue tracker](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues) are typically linked for these cases.
### 4.1. Proxy Obedience
### 4.1 Proxy Obedience
Proxy obedience is assured through the following:
...
...
@@ -374,11 +374,11 @@ Proxy obedience is assured through the following:
`not quiet true, pdfjs is system extension we include`
### 4.2. State Separation
### 4.2 State Separation
The browser state is separated from existing browser state through use of a custom Firefox profile, and by setting the `$HOME` environment variable to the root of the bundle's directory. The browser also does not load any system-wide extensions (through the use of `extensions.enabledScopes` and `extensions.autoDisableScopes`). Furthermore, plugins are disabled, which prevents Flash cookies from leaking from a pre-existing Flash directory.
### 4.3. Disk Avoidance
### 4.3 Disk Avoidance
**Design Goal**: The User Agent MUST (at user option) prevent all disk records of browser activity. The user SHOULD be able to optionally enable URL history and other history features if they so desire.
...
...
@@ -388,7 +388,7 @@ As an additional defense-in-depth measure, we set `browser.cache.disk.enable`, `
For more details on disk leak bugs and enhancements, see the [Disk Leak](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/?sort=updated_desc&state=opened&label_name%5B%5D=Disk%20Leak&first_page_size=20) tag in our issue tracker.
### ~4.4. Application Data Isolation~
### ~4.4 Application Data Isolation~
~The browser MUST NOT cause any information to be written outside of the bundle directory. This is to ensure that the user is able to completely and safely remove it without leaving other traces of Tor usage on their computer.~
...
...
@@ -396,7 +396,7 @@ For more details on disk leak bugs and enhancements, see the [Disk Leak](https:/
`purge purge`
### 4.5. Cross-Origin Identifier Unlinkability
### 4.5 Cross-Origin Identifier Unlinkability
The Cross-Origin Identifier Unlinkability design requirement is satisfied through first party isolation of all browser identifier sources. First party isolation means that all identifier sources and browser state are scoped (isolated) using the URL bar domain. This scoping is performed in combination with any additional third party scope. When first party isolation is used with explicit identifier storage that already has a constrained third party scope (such as cookies and DOM storage), this approach is referred to as "double-keying". `3rd party cookies are disabled, not double-keyed`
...
...
@@ -545,7 +545,7 @@ The Cross-Origin Identifier Unlinkability design requirement is satisfied throug
For more details on identifier linkability bugs and enhancements, see the [Linkability](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/?sort=updated_desc&state=opened&label_name%5B%5D=Linkability&first_page_size=20) label in our issue tracker.
Browser fingerprinting is the act of inspecting browser behaviors and features in an attempt to differentiate and track individual users.
...
...
@@ -659,9 +659,9 @@ Where our actual implementation differs from an ideal solution, we separately de
3.**Open TCP Port and Local Network Fingerprinting**
In Firefox, by using either WebSockets or XHR, it is possible for remote content to [enumerate the list of TCP ports open on 127.0.0.1](http://www.andlabs.org/tools/jsrecon.html), as well as on any other machines on the local network. In other browsers, this can be accomplished by DOM events on image or script tags. This open vs filtered vs closed port list can provide a very unique fingerprint of a machine, because it essentially enables the detection of many different popular third party applications and optional system services (Skype, Bitcoin, Bittorrent and other P2P software, SSH ports, SMB and related LAN services, CUPS and printer daemon config ports, mail servers, and so on). It is also possible to determine when ports are closed versus filtered/blocked (and thus probe custom firewall configuration).
In Firefox, by using either WebSockets or XHR, it is possible for remote content to [enumerate the list of TCP ports open on 127.00.1](http://www.andlabs.org/tools/jsrecon.html), as well as on any other machines on the local network. In other browsers, this can be accomplished by DOM events on image or script tags. This open vs filtered vs closed port list can provide a very unique fingerprint of a machine, because it essentially enables the detection of many different popular third party applications and optional system services (Skype, Bitcoin, Bittorrent and other P2P software, SSH ports, SMB and related LAN services, CUPS and printer daemon config ports, mail servers, and so on). It is also possible to determine when ports are closed versus filtered/blocked (and thus probe custom firewall configuration).
We prevent access to 127.0.0.1/localhost by ensuring that even these requests are still sent by Firefox to our SOCKS proxy (ie we set `network.proxy.no_proxies_on` to the empty string). The local Tor client then rejects them, since it is configured to proxy for internal IP addresses by default. Access to the local network is forbidden via the same mechanism. We also disable the WebRTC API as mentioned previously, since even if it were usable over Tor, it still currently provides the local IP address and associated network information to websites.
We prevent access to 127.00.1/localhost by ensuring that even these requests are still sent by Firefox to our SOCKS proxy (ie we set `network.proxy.no_proxies_on` to the empty string). The local Tor client then rejects them, since it is configured to proxy for internal IP addresses by default. Access to the local network is forbidden via the same mechanism. We also disable the WebRTC API as mentioned previously, since even if it were usable over Tor, it still currently provides the local IP address and associated network information to websites.
4.**Invasive Authentication Mechanisms (NTLM and SPNEGO)**
...
...
@@ -691,7 +691,7 @@ Where our actual implementation differs from an ideal solution, we separately de
**Design Goal**: Our design goal here is to reduce the resolution information down to the bare minimum required for properly rendering inside a content window. We intend to report all rendering information correctly with respect to the size and properties of the content window, but report an effective size of 0 for all border material, and also report that the desktop is only as big as the inner content window. Additionally, new browser windows are sized such that their content windows are one of a few fixed sizes based on the user's desktop resolution. In addition, to further reduce resolution-based fingerprinting, we are [investigating zoom/viewport-based mechanisms](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/7256) that might allow us to always report the same desktop resolution regardless of the actual size of the content window, and simply scale to make up the difference. As an alternative to zoom-based solutions we are testing a [different approach](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/14429) in our alpha series that tries to round the browser window at all times to a multiple 200x100 pixels. Regardless which solution we finally pick, until it will be available the user should also be informed that maximizing their windows can lead to fingerprintability under the current scheme.
**Implementation Status**: We automatically resize new browser windows to a 200x100 pixel multiple based on desktop resolution by backporting patches from [bug 1330882](https://2019.www.torproject.org/projects/torbrowser/design/) and setting `privacy.resistfingerprinting` to **true**. To minimize the effect of the long tail of large monitor sizes, we also cap the window size at 1000 pixels in each direction. In addition to that we set `privacy.resistFingerprinting` to **true** to use the client content window size for window.screen, and to report a `window.devicePixelRatio` of 1.0. Similarly, we use that preference to return content window relative points for DOM events. We also force popups to open in new tabs (via `browser.link.open_newwindow.restriction`), to avoid full-screen popups inferring information about the browser resolution. In addition, we prevent auto-maximizing on browser start, and inform users that maximized windows are detrimental to privacy in this mode.
**Implementation Status**: We automatically resize new browser windows to a 200x100 pixel multiple based on desktop resolution by backporting patches from [bug 1330882](https://2019.www.torproject.org/projects/torbrowser/design/) and setting `privacy.resistfingerprinting` to **true**. To minimize the effect of the long tail of large monitor sizes, we also cap the window size at 1000 pixels in each direction. In addition to that we set `privacy.resistFingerprinting` to **true** to use the client content window size for window.screen, and to report a `window.devicePixelRatio` of 1.0 Similarly, we use that preference to return content window relative points for DOM events. We also force popups to open in new tabs (via `browser.link.open_newwindow.restriction`), to avoid full-screen popups inferring information about the browser resolution. In addition, we prevent auto-maximizing on browser start, and inform users that maximized windows are detrimental to privacy in this mode.
8.**Display Media information**
...
...
@@ -839,7 +839,7 @@ Where our actual implementation differs from an ideal solution, we separately de
For more details on fingerprinting bugs and enhancements, see the [Fingerprinting](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/?sort=updated_desc&state=opened&label_name%5B%5D=Fingerprinting&first_page_size=20) label in issue bug tracker.
### 4.7. Long-Term Unlinkability via "New Identity" button
### 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 the browser.
...
...
@@ -853,7 +853,7 @@ After the state is cleared, we then close all remaining HTTP Keep-Alive connecti
Finally, a fresh browser window is opened, and the current browser window is closed (this does not spawn a new Firefox process, only a new window). Upon the close of the final window, an unload handler is fired to invoke the [garbage collector](https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIDOMWindowUtils#garbageCollect%28%29), which has the effect of immediately purging any blob:UUID URLs that were created by website content via [URL.createObjectURL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL).
### 4.8. Other Security Measures
### 4.8 Other Security Measures
In addition to the above mechanisms that are devoted to preserving privacy while browsing, we also have a number of technical mechanisms to address other privacy and security issues.
...
...
@@ -897,7 +897,7 @@ In addition to the above mechanisms that are devoted to preserving privacy while
In the age of state-sponsored malware, [we believe](https://blog.torproject.org/blog/deterministic-builds-part-one-cyberwar-and-global-compromise) it is impossible to expect to keep a single build machine or software signing key secure, given the class of adversaries that Tor has to contend with. For this reason, we have deployed a build system that allows anyone to use our source code to reproduce byte-for-byte identical binary packages to the ones that we distribute.
### 5.1. Achieving Binary Reproducibility
### 5.1 Achieving Binary Reproducibility
The GNU toolchain has been working on providing reproducible builds for some time, however a large software project such as Firefox typically ends up embedding a large number of details about the machine it was built on, both intentionally and inadvertently. Additionally, manual changes to the build machine configuration can accumulate over time and are difficult for others to replicate externally, which leads to difficulties with binary reproducibility.
...
...
@@ -931,7 +931,7 @@ The use of the Gitian system eliminates build non-determinism by normalizing the
Gitian provides an option to use LXC containers instead of full qemu-kvm virtualization. Unfortunately, these containers can allow additional details about the host OS to leak. In particular, umask settings as well as the hostname and Linux kernel version can leak from the host OS into the LXC container. We addressed umask by setting it explicitly in our Gitian descriptor scriptlet, and addressed the hostname and kernel version leaks by directly patching the aspects of the Firefox build process that included this information into the build. It also turns out that some libraries (in particular: libgmp) attempt to detect the current CPU to determine which optimizations to compile in. This CPU type is uniform on our KVM instances, but differs under LXC.
### 5.2. Package Signatures and Verification
### 5.2 Package Signatures and Verification
The build process generates a single sha256sums-unsigned-build.txt file that contains a sorted list of the SHA-256 hashes of every package produced for that build version. Each official builder uploads this file and a GPG signature of it to a directory on a Tor Project's web server. The build scripts have an optional matching step that downloads these signatures, verifies them, and ensures that the local builds match this file.
...
...
@@ -941,13 +941,13 @@ The fact that the entire set of packages for a given version can be authenticate
The Windows releases are also signed by a hardware token provided by Digicert. In order to verify package integrity, the signature must be stripped off using the osslsigncode tool, as described on the [Signature Verification](https://www.torproject.org/docs/verifying-signatures.html.en#BuildVerification) page.
### 5.3. Anonymous Verification
### 5.3 Anonymous Verification
Due to the fact that bit-identical packages can be produced by anyone, the security of this build system extends beyond the security of the official build machines. In fact, it is still possible for build integrity to be achieved even if all official build machines are compromised.
By default, all tor-specific dependencies and inputs to the build process are downloaded over Tor, which allows build verifiers to remain anonymous and hidden. Because of this, any individual can use our anonymity network to privately download our source code, verify it against public, signed, audited, and mirrored git repositories, and reproduce our builds exactly, without being subject to targeted attacks. If they notice any differences, they can alert the public builders/signers, hopefully using a pseudonym or our anonymous bug tracker account, to avoid revealing the fact that they are a build verifier.
### 5.4. Update Safety
### 5.4 Update Safety
We make use of the Firefox updater in order to provide automatic updates to users. We make use of certificate pinning to ensure that update checks cannot be tampered with by setting `security.cert_pinning.enforcement_level` to **2**, and we sign the individual MAR update files with keys that get rotated every year.
...
...
@@ -961,7 +961,7 @@ In an ideal world, the mechanisms of tracking that can be employed during a link
Because the total elimination of side channels during cross-origin navigation will undoubtedly break federated login as well as destroy ad revenue, we also describe auditable alternatives and promising web draft standards that would preserve this functionality while still providing transparency when tracking is occurring.
### 6.1. Deprecation Wishlist
### 6.1 Deprecation Wishlist
1.**The Referer Header**
...
...
@@ -983,7 +983,7 @@ Because the total elimination of side channels during cross-origin navigation wi
Automated cross-origin redirects are one form of this behavior that is possible for us to [address ourselves](https://gitlab.torproject.org/tpo/applications/tor-browser/-/issues/40787), as they are comparatively rare and can be handled with site permissions.
