Tor Browser Advanced Topics
- 1 Tor Browser Adversary Model
- 2 Torbutton Design
- 3 SecBrowser
- 4 Custom Homepage
- 5 Custom Configurations
- 6 Proxy Settings
- 7 Backup and Restore
- 8 Restore Backup
- 9 Local Connections Exception Threat Analysis
- 10 tor-launcher vs torbrowser-launcher
- 11 Platform-specific Issues: Qubes-Whonix ™
- 11.1 Running Tor Browser in Qubes TemplateVM or DisposableVM Template
- 11.2 tb-updater in Qubes TemplateVM
- 11.3 tb-updater in Qubes DisposableVM Template
- 11.4 DisposableVM Template Customization
- 12 Platform-specific Issues: Whonix ™ Custom Linux Workstation
- 13 Platform-specific Issues: Windows
- 14 Tor Browser Update: Technical Details
- 15 Footnotes / References
- 16 License
Tor Browser Adversary Model
The Tor Browser design has carefully considered the goals, capabilities and types of attacks undertaken by adversaries and planned accordingly. The design specifications address:
|Anonymity Set Reduction (Fingerprinting)||To identify specific individuals, system data like the browser build, timezone or display resolution is used to track down (or at least track) their activities.|
|Bypassing Proxy Settings||Directly compromising and bypassing Tor, or forcing connections to specific IP addresses.|
|Correlating Activity across Multiple Sites||Learning if the person who visited site A is the same person who visited site B, in order to serve targeted advertisements.|
|History Disclosure||Querying user history for censored search queries or websites.|
|History Records and other On-disk Information||Seizing the computers of all Tor users in a given area and extracting history records, cache data, hostnames and disk-logged spoofed MAC address history.|
|Location Information||Seeking timezone and locality information to determine if the user originates from a specific region they are trying to control, or focusing in on dissidents or whistleblowers.|
Adversary Positioning Capabilities
|Adservers and/or Malicious Websites||Running websites or contracting ad space from adservers to inject content. Reducing a Tor user's anonymity is also good for marketing purposes. |
|Exit Node or Upstream Router||Running exit nodes or controlling routers upstream of exit nodes. |
|Local Network / ISP / Upstream Router||Injecting malicious content at the upstream router when Tor is disabled in order to correlate Tor and non-Tor activity. Additionally, block Tor or attempt to recognize traffic patterns of specific web pages at the entrance to the Tor network.|
|Physical Access||Constant or intermittent physical access to computer equipment. This may happen to Internet cafe users or those in jurisdictions where equipment is confiscated due to general suspicion or solely for Tor use.|
Adversary Attack Capabilities
|Inserting or Exploiting Plugins||
|Reading and Inserting Identifiers||
With the release of Tor Browser 9.0 [archive] in late-2019, both the Torbutton and Tor Launcher extensions have been tightly integrated into Tor Browser, meaning Torbutton has been moved from the URL bar and neither appears on the
about:addons page. Other changes include the New Identity function shifting to the URL bar and the New Tor Circuit function being accessible via the hamburger menu. As noted by Tor developers [archive]:
Now that the Tor Browser includes a patched version of Firefox, and because we don't have enough developer resources to keep up with the accelerated Firefox release schedule, the toggle model of Torbutton is no longer supported [archive]. Users should be using Tor Browser, not installing Torbutton themselves.
|Anonymity Set Preservation||Tor Browser should not leak any other anonymity set reducing or fingerprinting information (such as user agent, extension presence, and resolution information) automatically via Tor.|
|Disk Avoidance||Tor Browser should not write any Tor-related state to disk, or store it in memory beyond one Tor toggle.|
|Interoperability||Tor Browser should inter-operate with third-party proxy switchers that enable the user to switch between a number of different proxies, with full Tor protection.|
|Location Neutrality||Tor Browser should not leak location-specific information, like the timezone or locale via Tor.|
|Proxy Obedience||Tor Browser must not bypass Tor proxy settings.|
|State Separation||Cookies, cache, history, DOM storage, and more accumulated in one Tor state must not be accessible via the network in another Tor state.|
|Update Safety||Tor Browser should not perform unauthenticated updates or upgrades via Tor.|
Tor Browser patches and the integrated Torbutton features can potentially disable some functionality or interfere with the proper operation of some Internet sites, but the vast majority of websites work well. To learn more about former Torbutton, see:
- The Torbutton homepage [archive]
- The Torbutton FAQ [archive]
- Torbutton Design Documentation [archive]
- The Torbutton function design section immediately below.
New Identity Design
- Stops all page activity for each tab.
- Clears the Tor Browser state:
- OCSP state.
- Content and image cache.
- Site-specific zoom.
- Cookies and DOM storage.
- The safe browsing key.
- Google Wi-Fi geolocation token.
- Last opened URL preference (if it exists).
- Searchbox and findbox text.
- Purge session history.
- HTTP authentication.
- SSL session IDs.
- Crypto tokens.
- Site-specific content preferences.
- Undo tab history.
- Offline storage.
- Domain isolator state.
- NoScript's site and temporary permissions.
- All other browser site permissions.
- Closes all remaining HTTP keep-alive connections.
- Sends Tor the "newnym" signal to issue a new Tor circuit.
After this process above, 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). When the final window is closed, any blob:UUID URLs that were created by websites are purged. 
New Tor Circuit Design
The "New Tor Circuit for this Site" feature sends the "newnym" signal to the Tor control port to cause a new circuit to be created for the current Tor Browser tab.  Other open tabs and windows from the same website will use the new circuit as well once they have reloaded, but connections to other websites on separate tabs are not affected. 
Security Slider Design
The Security Level preference tab and Tor Project manual describe the exact effect of each level and which features are disabled or partially disabled. Note that as of Tor Browser release v8.5, the security slider function has shifted from Torbutton to the taskbar ("shield" icon).  
Table: Security Slider Settings 
Disabled Tor Browser Functions
Open Network Settings
The regular Tor Browser Bundle from The Tor Project (without Whonix ™) allows networking settings to be changed inside Tor via the Open Network Settings menu option. It has the same effect as editing Tor's torrc configuration file.
In Whonix ™, the environment variable export
TOR_NO_DISPLAY_NETWORK_SETTINGS=1 has been set [archive] to disable the
Tor Browser →
Open Network Settings... menu item. It is not useful and confusing to have in the Whonix-Workstation ™ because:  
- In Whonix ™, there is only limited access to Tor's control port (see Control Port Filter Proxy for more information).
- For security reasons, Tor must be manually configured via /usr/local/etc/torrc.d/50_user.conf in Whonix-Gateway ™, and not inside Whonix-Workstation ™ (see VPN/Tunnel support for more information).
Tor Circuit View
Normally this option in Tor Browser shows the three Tor relays used for the website in the current tab. This includes the IP addresses of each and the countries they are located in, and whether a bridge is being used (see below). The node immediately above the destination website reflects the Tor exit relay. 
Figure: Tor Circuit View - Disabled in Whonix 
The Control Port Filter Proxy configuration in Whonix ™ intentionally does not whitelist the Tor control protocol commands that would be required for Tor Circuit View to function. This information is made unavailable to Whonix-Workstation ™ because Whonix-Workstation ™ should not have access to IP address information. If unavailable it cannot leak. Otherwise malicious or broken applications could leak it. Users might also unintentionally make screenshots of this information. One of the main advantages of Whonix ™ is, that there is no way to determine the real external IP address of the user from within Whonix-Workstation ™. Therefore also the IP address of the Tor entry guard or bridge as well as Tor middle relay should be inaccessible from Whonix-Workstation ™. Otherwise this information might aid an attacker who gained remote code execution capability within Whonix-Workstation ™.
As noted in the SecBrowser chapter:
SecBrowser is a derivative of the Tor Browser Bundle (which itself is a derivative of Mozilla Firefox) but without Tor. This means unlike Tor Browser, SecBrowser does not route traffic over the Tor network, which in common parlance is referred to as "clearnet" traffic. Even without the aid of the Tor network, SecBrowser still benefits from the numerous patches that Tor developers merged into the code base.
For users of Debian,  Kicksecure, Qubes and Windows, SecBrowser is a viable option for improved privacy and security when undertaking clearnet browsing. Benefits include: disabled WebRTC, Tor's security slider, NoScript and HTTPS Everywhere add-ons are installed by default, improved DNS and proxy configuration obedience, and reproducible builds. On Linux platforms, SecBrowser is also automatically sandboxed by Firejail.
If you are interested in running SecBrowser, then refer to these resources:
It is unclear whether setting a custom homepage [archive] in Tor Browser settings will currently work. Previous attempts lead to the Whonix ™ default homepage being loaded on startup, even though a different homepage was manually set. The custom homepage only appeared following use of the New Identity function. 
The whonix-welcome-page [archive] package currently sets the environment variable [archive] TOR_DEFAULT_HOMEPAGE to /usr/share/homepage/whonix-welcome-page/whonix.html when setting the Tor Browser homepage. This is done via the bash script file [archive]  associated with the package. In light of this design, there are three possible options for a user-set custom homepage (untested):
- Attempting to purge the whonix-welcome-page package.  This solution is difficult due to technical limitations as explained on the Whonix ™ Debian Packages page.
- Modifying /usr/lib/whonix-welcome-page/env_var.sh.  Unfortunately these changes will revert after an upgrade.
- Setting the environment variable TOR_DEFAULT_HOMEPAGE to a custom value. This would have a similar effect as setting environment variables as outlined in Tor Browser Transparent Proxying.
Verify New Identity
If attempts to create a New Identity fail, then a related Tor Browser notification should appear once it realizes it cannot connect to Tor's ControlPort. If this error notification does not appear, then it likely means there are no problems.
After Tor Browser is restarted, click "IP Check" on the landing page. This will redirect to https://check.torproject.org [archive] automatically, but the URL can be manually entered if preferred. In most, but not all cases  a new Tor exit relay will be received, with a different IP address being reported.
On Whonix-Gateway ™, examine the Control Port Filter Proxy log while using Tor Browser's New Identity feature.
sudo journalctl -f -u onion-grater
If the output is similar to the following.
Aug 16 05:30:19 host onion-grater: 10.137.0.10:41334 (filter: 30_autogenerated): → SIGNAL NEWNYM Aug 16 05:30:19 host onion-grater: 10.137.0.10:41334 (filter: 30_autogenerated): <- 250 OK
Then the Control Port Filter Proxy received both the request from Tor Browser and Tor confirmation that it worked.
Get a New Identity without Tor ControlPort Access
Simulate Tor Browser's New Identity functionality via these steps.
- Close Tor Browser.
- Get a new identity in Whonix-Gateway ™ using nyx.
- Start Tor Browser again.
The procedure is complete.
Remove Proxy Settings
To remove Tor Browser proxy settings (set no proxy), apply the following instructions.
Change Proxy Settings
Complete the following steps inside Whonix-Workstation ™ (
This process can be repeated with web socks proxies, but it is redundant and does not provide any advantage over the former types. The reason is because only Tor Browser is modified and no other programs are being tunneled through it.
Backup and Restore
In the old browser folder
~/.tb/tor-browser search for the following files:
~/.tb/tor-browser/Browser/TorBrowser/Data/Browser/profile.default/key4.db- This file stores the key database for passwords. To transfer saved passwords, this file and the one immediately below must be copied.
~/.tb/tor-browser/Browser/TorBrowser/Data/Browser/profile.default/logins.json- Saved passwords.
~/.tb/tor-browser/Browser/TorBrowser/Data/Browser/profile.default/places.sqlite- Bookmarks, downloads and browsing history.
Either backup these files or backup the whole browser folder, which is safer. Afterwards, copy them over after re-downloading Tor Browser.
Restore Backup instructions are untested and possibly incomplete.
When restoring a backup, sometimes a fix is necessary due to lost file permissions. Note that the fix below has not yet been tested.
To apply a general permission fix, run.
sudo chown --recursive user:user /home/user
Retrieve a list of executable files from a functional Tor Browser version. Ideally it should be the same version as the one you are attempting to restore, possibly in a separate VM.
find ~/.tb/tor-browser/ -type f -executable -print
chmod +x all of these files.
In the collapsible section you can find a list created in June 2019. It might be outdated by now so you might have to create your own. Please press on Expand on the right.
chmod +x /home/user/.tb/tor-browser/Browser/libmozavcodec.so chmod +x /home/user/.tb/tor-browser/Browser/libplds4.so chmod +x /home/user/.tb/tor-browser/Browser/libnspr4.so chmod +x /home/user/.tb/tor-browser/Browser/libsmime3.so chmod +x /home/user/.tb/tor-browser/Browser/updater chmod +x /home/user/.tb/tor-browser/Browser/libxul.so chmod +x /home/user/.tb/tor-browser/Browser/libssl3.so chmod +x /home/user/.tb/tor-browser/Browser/libmozgtk.so chmod +x /home/user/.tb/tor-browser/Browser/plugin-container chmod +x /home/user/.tb/tor-browser/Browser/gtk2/libmozgtk.so chmod +x /home/user/.tb/tor-browser/Browser/libnss3.so chmod +x /home/user/.tb/tor-browser/Browser/liblgpllibs.so chmod +x /home/user/.tb/tor-browser/Browser/execdesktop chmod +x /home/user/.tb/tor-browser/Browser/abicheck chmod +x /home/user/.tb/tor-browser/Browser/libmozavutil.so chmod +x /home/user/.tb/tor-browser/Browser/libmozsqlite3.so chmod +x /home/user/.tb/tor-browser/Browser/libnssdbm3.so chmod +x /home/user/.tb/tor-browser/Browser/libnssckbi.so chmod +x /home/user/.tb/tor-browser/Browser/libsoftokn3.so chmod +x /home/user/.tb/tor-browser/Browser/libmozsandbox.so chmod +x /home/user/.tb/tor-browser/Browser/firefox.real chmod +x /home/user/.tb/tor-browser/Browser/libnssutil3.so chmod +x /home/user/.tb/tor-browser/Browser/libfreeblpriv3.so chmod +x /home/user/.tb/tor-browser/Browser/start-tor-browser chmod +x /home/user/.tb/tor-browser/Browser/libplc4.so chmod +x /home/user/.tb/tor-browser/Browser/start-tor-browser.desktop chmod +x /home/user/.tb/tor-browser/Browser/firefox chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/libssl.so.1.0.0 chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/libstdc++/libstdc++.so.6 chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/libevent-2.1.so.6 chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fteproxy-lib/libgmp.so.10 chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/zope/interface/_zope_interface_coptimizations.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fteproxy/tests/test_record_layer.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fteproxy/cli.py /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/obfs4proxy chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/meek-client chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fteproxy.wrapper chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/meek-client-torbrowser chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fteproxy.bin chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/test_bit_ops.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test4.regex chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test3.dfa chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test1.dfa chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test6.dfa chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test4.dfa chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test6.regex chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test5.dfa chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test2.regex chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/__init__.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test2.dfa chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test1.regex chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test5.regex chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/dfas/test3.regex chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/__init__.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/test_encrypter.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/tests/test_encoder.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/cDFA.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/encoder.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/conf.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/encrypter.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/rank_unrank.cc chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/rank_unrank.h chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/bit_ops.py chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/fte/cDFA.cc chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/obfsproxy.bin chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/twisted/runner/portmap.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/twisted/python/sendmsg.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/twisted/test/raiser.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Util/strxor.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Util/_counter.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Cipher/_AES.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Cipher/_ARC4.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Cipher/_XOR.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Cipher/_ARC2.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Cipher/_DES.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Cipher/_CAST.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Cipher/_DES3.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Cipher/_Blowfish.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Hash/_SHA256.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Hash/_SHA512.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Hash/_MD2.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Hash/_RIPEMD160.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Hash/_SHA384.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Hash/_SHA224.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/PluggableTransports/Crypto/Hash/_MD4.so chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/libcrypto.so.1.0.0 chmod +x /home/user/.tb/tor-browser/Browser/TorBrowser/Tor/tor chmod +x /home/user/.tb/tor-browser/start-tor-browser.desktop
Local Connections Exception Threat Analysis
The configured exception means a small trade-off in privacy, but it is much safer than using another browser. 
tor-launcher vs torbrowser-launcher
tor-launcher and torbrowser-launcher are two completely different things with similar names:
- tor-launcher [archive] (screenshots [archive] (w [archive])) is a Tor Controller that has replaced Vidalia [archive]. It is an add-on that is included in the Tor Browser Bundle (TBB) by default.
- torbrowser-launcher [archive] (screenshot [archive]) is an application to download Tor Browser, and is an alternative to Tor Browser Updater (Whonix ™) (tb-updater [archive]).
In theory it is possible to remove tor-launcher from TBB, but this would not make any difference. Taking this step is untested and seems unlikely to provide any additional advantages. For that reason, it is best to leave it enabled so the platform has the same tested and functional setup as everyone else.
tor-launcher is not yet available for use in Whonix-Gateway ™. 
Tor Browser Updater (Whonix ™) (tb-updater [archive]) is installed by default and specifically designed to be functional when installed alongside torbrowser-launcher. A possible long-term development goal in Whonix ™ is to deprecate tb-updater and instead install torbrowser-launcher by default. See this forum development discussion [archive] if that is of interest.
Platform-specific Issues: Qubes-Whonix ™
Running Tor Browser in Qubes TemplateVM or DisposableVM Template
To understand why, please press on Expand on the right.
- Tor Browser should be used in its stock configuration with as few modifications as possible. This is in accordance with upstream recommendations by The Tor Project.
- Internet connections are established if Tor Browser is started in a DisposableVM Template -- this risks a compromise of the template and all DisposableVMs based upon it.
- Various files are created when Tor Browser starts -- these might make an individual pseudonymous rather than anonymous, even if software has been designed against this. It is undesirable to have the same pseudonym linked to all TemplateBasedVMs based on a singular TemplateVM.
- It is far safer to start Tor Browser for the first time in a TemplateBasedVM, rather than the TemplateVM. It is unrealistic to expect Tor Browser will perform perfectly, without any critical bugs being revealed later on. Current and past Tor Browser issues support this assertion; for example, see here [archive] and here [archive].
- See also Unsafe Tor Browser Habits.
tb-updater in Qubes TemplateVM
Tor Browser is installed by default in Whonix-Workstation ™.
Whonix-Workstation ™ builds by default automatically run Tor Browser Downloader by Whonix ™ (tb-updater package) (update-torbrowser) following its initial installation within chroot. If the attempt to run the tb-updater package is unsuccessful, then it will fail closed by default and nothing will be installed. As a consequence, this could lead to an error while building Whonix ™ images from source code or when installing Whonix ™ from the repository. Although this is undesirable behavior, developers have still decided to install Tor Browser by default in Whonix-Workstation ™. This means the only way to ensure Tor Browser is really installed by default is to also fail closed when necessary.
Qubes-Whonix-Workstation ™ TemplateVMs by default automatically run update-torbrowser during upgrades of Tor Browser Downloader by Whonix ™ (tb-updater package). If the update-torbrowser process fails, it will fail open by default. In this case, a terminal message will inform that no new Tor Browser could be downloaded, but apt-get will terminate normally. This is necessary to implement the Qubes-Whonix ™ feature ensuring an up-to-date version of Tor Browser [archive] is available in freshly created AppVMs. 
If an update failure occurs, this only poses a small inconvenience. The problem is easily solved by one of the following methods:
- Running Tor Browser Downloader by Whonix ™ in Whonix-Workstation ™ TemplateVM (
whonix-ws) or in a TemplateBased AppVM like
- Using the Internal Updater in a TemplateBased AppVM like
- Manually downloading Tor Browser in a TemplateBased AppVM like
Optional Package Configuration
Actions of the tb-updater package can be optionally configured.
Disable Automatic Update Downloads
By default, during the Debian maintainer postinst script run in Qubes-Whonix-Workstation ™ TemplateVMs, the folders /var/cache/tb-binary/.cache/tb/ and /var/cache/tb-binary/.tb/tor-browser will be deleted if they exist. tb-updater will then download files to /var/cache/tb-binary/.cache/tb/
/var/cache/tb-binary/.cache/tb/ /var/cache/tb-binary/.cache/tb/temp /var/cache/tb-binary/.cache/tb/temp/pv_wrapper_fifo /var/cache/tb-binary/.cache/tb/temp/tbb_remote_folder /var/cache/tb-binary/.cache/tb/temp/tar_fifo /var/cache/tb-binary/.cache/tb/temp/sha256_output /var/cache/tb-binary/.cache/tb/files /var/cache/tb-binary/.cache/tb/files/sha256sums-unsigned-build.txt.asc /var/cache/tb-binary/.cache/tb/files/sha256sums-unsigned-build.txt /var/cache/tb-binary/.cache/tb/last_used_gpg_bash_lib_output_signed_on_date /var/cache/tb-binary/.cache/tb/tbb_version_last_downloaded_save_file /var/cache/tb-binary/.cache/tb/RecommendedTBBVersions /var/cache/tb-binary/.cache/tb/last_used_gpg_bash_lib_output_signed_on_unixtime /var/cache/tb-binary/.cache/tb/gpgtmpdir /var/cache/tb-binary/.cache/tb/gpgtmpdir/pubring.kbx /var/cache/tb-binary/.cache/tb/gpgtmpdir/private-keys-v1.d /var/cache/tb-binary/.cache/tb/gpgtmpdir/trustdb.gpg /var/cache/tb-binary/.cache/tb/gpgtmpdir/gpg_bash_lib_internal_gpg_verify_output_file /var/cache/tb-binary/.cache/tb/gpgtmpdir/pubring.kbx~ /var/cache/tb-binary/.cache/tb/gpgtmpdir/gpg_bash_lib_internal_gpg_verify_status_fd_file
After gpg verification, tb-updater will extract the Tor Browser archive to /var/cache/tb-binary/.tb
In essence, when a Qubes-Whonix-Workstation ™ AppVM is booted for the first time, the systemd unit file /lib/systemd/system/tb-updater-first-boot.service  runs /usr/lib/tb-updater/first-boot-home-population.  That script copies /var/cache/tb-binary to /home/user
The result is.
ls -la /home/user/.tb
drwxr-xr-x 6 user user 4096 Jun 8 01:17 . drwx------ 20 user user 4096 Jun 8 01:17 .. -rw-r--r-- 1 user user 0 Jun 8 01:17 first-boot-home-population.done drwxr-xr-x 3 user user 4096 Jun 8 01:17 tor-browser
ls -la /home/user/.cache/tb
drwxr-xr-x 5 user user 4096 Jun 8 01:17 . drwxr-xr-x 3 user user 4096 Jun 8 01:17 .. -rw-r--r-- 1 user user 167 Jun 8 01:17 RecommendedTBBVersions drwxr-xr-x 2 user user 4096 Jun 8 01:17 files drwx------ 3 user user 4096 Jun 8 01:17 gpgtmpdir -rw-r--r-- 1 user user 26 Jun 8 01:17 last_used_gpg_bash_lib_output_signed_on_date -rw-r--r-- 1 user user 11 Jun 8 01:17 last_used_gpg_bash_lib_output_signed_on_unixtime -rw-r--r-- 1 user user 6 Jun 8 01:17 tbb_version_last_downloaded_save_file drwxr-xr-x 2 user user 4096 Jun 8 01:17 temp
Creating Whonix ™ Using the Build Script
If Qubes-Whonix ™ is built with the available script and it should fail open in general, then before building in chroot a file /etc/torbrowser.d/50_user.conf must be created with the following content.
If Qubes-Whonix ™ is built with the available script and skipping the initial download of Tor Browser is preferred, then before building Whonix ™ in chroot a file /etc/torbrowser.d/50_user.conf must be created with the following content.
tb-updater in Qubes DisposableVM Template
The only safe place to run Tor Browser Downloader by Whonix ™ is in either:
- The TemplateVM (
- The AppVM which is based on this template (
The reason is because Tor Browser is stored in folder
/var/cache/tb-binary which is non-persistent in Qubes' DisposableVM Template (
whonix-ws-15-dvm), but persistent in Qubes' TemplateVM (
Table: Qubes R4 Inheritance and Persistence
|Inheritance ||Persistence |
|DisposableVM Template [archive] ||
Updating Tor Browser in Qubes' TemplateVM
whonix-ws-15 is sufficient to make a copy of the latest Tor Browser available to all newly created AppVMs based upon it.
DisposableVM Template Customization
To start Tor Browser from the command line or in debugging mode in a Qubes DisposableVM Template, choose any of the following options below.
Forum discussion: How to customize Tor Browser in a Whonix ™ TemplateBased DVM? [archive]
Option 1: DisposableVM Template Method
Using this method, customization would only apply to the DisposableVM Template and any DispVMs based on that DisposableVM Template.
Option 2: TemplateVM Method
Using this method, customization this way would apply to all AppVMs and DispVM based on this TemplateVM.
Option 3: Manual Method
It's possible to ignore most of what Whonix ™ implemented related to Tor Browser and going back to square one, doing it all manually.
Advantage of this method is that whatever Whonix ™ implemented will probably not cause any issues. Disadvantage is slightly reduced usability (such as superfluous Qubes start menu entry to be ignored).
Split Tor Browser for Qubes
Platform-specific Issues: Whonix ™ Custom Linux Workstation
For instructions on how to configure Tor Browser in a Whonix ™-Custom-Linux-Workstation, see: Whonix ™-Linux-Workstation Tor Browser Settings.
Platform-specific Issues: Windows
Tor Browser Update: Technical Details
Updating Tor Browser works differently in Debian and other Linux distributions generally, since it cannot be upgraded with apt-get package sources like most other applications (Whonix ™ is based on Debian). The reason is there are unresolved upstream issues, namely deb packages and/or a deb repository with Tor Browser are not provided:
Tor Browser Developer Georg Koppen (gk) has stated: 
We don't have plans to pick this up, but maybe someone from the community...
The usual process for general, non-Whonix ™ Linux platforms such as for example Debian supported by The Tor Project is:
- Navigate to torproject.org
- Download Tor Browser for the relevant platform.
- Verify Tor Browser.
- Extract Tor Browser inside the home folder.
- Launch Tor Browser.
This process is simplified by programs such as torbrowser-launcher (for Debian users) and tb-updater (for Debian and Whonix ™ users), yet Tor Browser is still installed inside of the home folder. For this reason, Tor Browser cannot be updated by package management tools like apt-get.
torbrowser-launcher and tb-updater are Tor Browser installers. torbrowser-launcher (for Debian users) and tb-updater are not Tor Browser updaters. The difference between an installer and an updater is that an installer is incapable of preserving user data after updates -- only an updater can achieve that. In the long term, tb-updater will likely be renamed to tpo-downloader.
Another issue is that Tor Browser mixes binaries and user data into the same folder. Usually binaries used by users in Linux distributions generally reside in folder
/usr/bin and user data resides in folder
/home/user. This is further complicated since Tor Browser folder structure has changed over time. Future changes might happen. Therefore it would be unwise for a downstream Linux distribution such as Whonix ™ to attempt to separate binaries and user data. Since Tor Browser comes with its own internal updater and folder structure might change in future, updates might break or user data might become inaccessible if such attempts were made.
The Tor Project requires Tor Browser to be installed inside of the home folder as explained earlier; see Linux Generally. Qubes TemplateBasedAppVMs have their own home folder, independent from the TemplateVM they are based on. This means updates of a Qubes TemplateVM will not update Tor Browser which is already installed in a Qubes TemplateBasedAppVMs home folder. In short, Tor Browser updates are a more cumbersome task in Qubes OS due to Qubes-specific design choices and technical limitations.
Due to these restrictions, the safest configuration that Whonix ™ could implement [archive] is to ensure that new AppVMs and DispVMs are created with a copy of the latest Tor Browser version. In essence:
- When tb-updater is run in a Qubes TemplateVM, it stores Tor Browser in folder
- When a TemplateBasedAppVM starts and it has never copied Tor Browser before (likely only at first boot), and there is no copy of Tor Browser in
/home/user, Tor Browser is copied from
- Existing copies of Tor Browser in the home folder are not overwritten. This is due to an explicit design goal to avoid data loss; see tb-updater in Qubes Template VM for technical details.
Since Tor Browser mixes binaries and user data into the same folder, special configurations such as Qubes DisposableVM Template_Customization are more complicated than for other software. This is because either folder
/var/cache/tb-binary is being kept up to date or user data is being preserved. There is no maintainable way for Whonix ™ to separate Tor Browser binaries from user data.
Footnotes / References
- https://2019.www.torproject.org/projects/torbrowser/design/#Implementation [archive]
- This has also informed the development of the Torbutton extension.
- https://2019.www.torproject.org/projects/torbrowser/design/#adversary [archive]
- Partially explaining the unholy alliance between the corporate sector and government.
- This has already been observed.
- For instance, there is an estimated 29 bit-identifier based on the browser and desktop window resolution information alone.
- This attack is somewhat mitigated by the ocean of Tor traffic, which rapidly increases the rate of false positives when larger traffic sets are analyzed.
- https://2019.www.torproject.org/projects/torbrowser/design/#components [archive]
- https://2019.www.torproject.org/docs/torbutton/en/design/index.html.en#requirements [archive]
- Some of the design features have been deprecated due to changes in the Tor / Tor Browser design.
- https://trac.torproject.org/projects/tor/ticket/523 [archive]
- https://2019.www.torproject.org/projects/torbrowser/design/#new-identity [archive]
- https://trac.torproject.org/projects/tor/ticket/9442 [archive]
- https://tb-manual.torproject.org/managing-identities/ [archive]
- https://blog.torproject.org/new-release-tor-browser-85 [archive]
- https://trac.torproject.org/projects/tor/ticket/29825 [archive]
- https://tb-manual.torproject.org/en-US/security-slider.html [archive]
- https://trac.torproject.org/projects/tor/ticket/19652 [archive]
- https://trac.torproject.org/projects/tor/ticket/14100 [archive]
- https://tails.boum.org/doc/anonymous_internet/Tor_Browser/index.en.html [archive]
- New Release: Tor Browser 8.09a9 [archive] License: Creative Commons Attribution 3.0 United States License [archive]
- SecBrowser ™ can be manually configured in macOS in a similar fashion to SecBrowser ™ in Microsoft Windows.
- This is a potential bug since the custom homepage does not overrule the TOR_DEFAULT_HOMEPAGE environment variable. No bug has yet been reported.
- Also /usr/lib/whonix-welcome-page/env_var.sh
sudo apt-get purge whonix-welcome-page
/usr/lib/whonix-welcome-page/env_var.shin an editor with root rights. (Qubes-Whonix ™: In TemplateVM)
- Getting a new circuit does not guarantee receiving a new exit relay; this is normal behavior. Also see: Stream Isolation.
- This term was coined in context of a Tor Transparent Proxy [archive]. It acts as a simple gateway that routes all connections through Tor, but does not provide Stream Isolation.
- Unless this environment variable is manually unset before starting Tor Browser.
- The regular Tor Browser Bundle from The Tor Project (without Whonix ™) allows networking settings to changed inside Tor via the
Open Network Settingsmenu option. It has the same effect as editing Tor's config file torrc. In Whonix ™, the environment variable
export TOR_NO_DISPLAY_NETWORK_SETTINGS=1has been set [archive] to disable the
Open Network Settings...menu item. It is not useful and confusing to have in the Whonix-Workstation ™ because:
- In Whonix ™, there is only limited access to Tor's control port (see Dev/CPFP for more information).
- For security reasons, Tor must be manually configured in /usr/local/etc/torrc.d/50_user.conf on the Whonix-Gateway ™, and not from the Whonix-Workstation ™ (see VPN/Tunnel support for more information).
- https://trac.torproject.org/projects/tor/ticket/10419#comment:37 [archive]
- https://phabricator.whonix.org/T118 [archive]
- Which is in turn inherited from updated TemplateVMs.
- In the tb-updater package.
- https://github.com/Whonix/tb-updater/blob/master/lib/systemd/system/tb-updater-first-boot.service [archive]
- https://github.com/Whonix/tb-updater/blob/master/usr/lib/tb-updater/first-boot-home-population [archive]
- Upon creation.
- Following shutdown.
- https://github.com/QubesOS/qubes-issues/issues/4175 [archive]
- This is to prevent mounting
sudo mkdir -p /usr/local/lib/systemd/system/
sudo ln -s /dev/null /usr/local/lib/systemd/system/tb-updater-dispvm.service
This is probably because Qubes mounts /usr/local too late to be regarded by systemd.
- This is to prevent mounting
torbrowser(Tor Browser Starter by Whonix ™ developers) in DisposableVM Template it will first copy
/var/cache/tb-binary/.tb/tor-browserto user home folder
/var/cache/tb-binary/.tb/tor-browserwas previously created by Tor Browser Downloader (by Whonix ™ developers).) Second, it will start the Tor Browser binary from folder
Due to technical limitations. Because whole folder
/var/cache/tb-binary/.tb/tor-browseris replaced. This is not an intentional user freedom restriction or security feature.
- https://trac.torproject.org/projects/tor/ticket/5236#comment:45 [archive]
Whonix ™ Tor Browser Advanced Topics wiki page Copyright (C) Amnesia <amnesia at boum dot org>
Whonix ™ Tor Browser Advanced Topics wiki page Copyright (C) 2012 - 2020 ENCRYPTED SUPPORT LP <firstname.lastname@example.org>
This program comes with ABSOLUTELY NO WARRANTY; for details see the wiki source code.
This is free software, and you are welcome to redistribute it under certain conditions; see the wiki source code for details.
This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation. Policy of Whonix Website and Whonix Chat and Policy On Nonfreedom Software applies.
Copyright (C) 2012 - 2020 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee [archive] of the Open Invention Network [archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)