Jump to: navigation, search

Tor Browser

(Redirected from Tor Browser/Internal Updater)

Tor Browser, privacy by design. Fighting web fingerprinting and linkability.



It is recommended[1], that you use only Tor Browser for browsing the web in Whonix.

Tor Browser[2][3] is a fork[4] of the Mozilla Firefox[5] web browser, optimized[6] and designed[7] for anonymity, developed by The Tor Project[8]. Given Firefox's popularity, many of you have probably used it before and its user interface is like any other modern web browser.

Here are a few things worth mentioning in the context of Whonix.

Anonymity vs Pseudonymity[edit]

When you were to use other browsers than Tor Browser, your IP/DNS would still be protected by Whonix, but you wouldn't profit from Tor Browser's protocol level cleanup. Using other browsers would be pseudonymous rather than anonymous.

Tor Browser in comparison to other browsers is optimized for anonymity, it contains privacy enhancing patches[9] and add-ons[10]. There are no other browsers other than Tor Browser capable of protocol level cleanup. When you use Tor Browser, you will blend in and share the Fingerprint of other Tor Browser users, which is a good thing.

HTTPS Encryption[edit]

Using HTTPS instead of HTTP encrypts your communication while browsing the web.

All the data exchanged between your browser and the server you are visiting are encrypted. It prevents the Tor exit relay to eavesdrop on your communications.

HTTPS also includes mechanisms to authenticate the server you are communicating with. But those mechanisms can be flawed, as explained on our warning page.

For example, here is how the browser looks like when we try to visit whonix website [11]


Notice the small area on the left of the address bar saying "www.whonix.org" on a green background and the address beginning with "https://" (instead of "http://")

These are the indicators that an encrypted connection using HTTPS[12] is being used.

You should try to only use services providing HTTPS when you are sending or retrieving sensitive information (like passwords), otherwise it's very easy for an eavesdropper to steal whatever information you are sending or to modify the content of a page on its way to your browser.

Here is how your connection looks like according to the following models:- (provided by EFF[13])

- When you use Tor + HTTPS


- When you use only Tor without HTTPS


- When you use HTTPS without Tor


- This is your connection without Tor or HTTPS


HTTPS Everywhere[edit]

HTTPS Everywhere logo

HTTPS Everywhere[14] is a Firefox extension shipped in Tor Browser and produced as a collaboration between The Tor Project[15] and the Electronic Frontier Foundation[16]. It encrypts your communications with a number of major websites. Many sites on the web offer some limited support for encryption over HTTPS, but make it difficult to use. For instance, they may default to unencrypted HTTP, or fill encrypted pages with links that go back to the unencrypted site. The HTTPS Everywhere extension fixes these problems by rewriting all requests to these sites to HTTPS.

To learn more about HTTPS Everywhere you can see:


Tor alone is not enough to protect your anonymity and privacy while browsing the web. All modern web browsers, such as Firefox, support JavaScript[17], Adobe Flash[18], cookies[19] and other features which have been shown to be able to defeat the anonymity [20] provided by the Tor network.

In Tor Browser all such features are handled from inside the browser, because it's a modified version of Firefox Patches[21] and it contains an extension called Torbutton[22]. These do all sorts of things to prevent the above type of attacks. But that comes at a price: since this will disable some functionalities and some sites might not work as intended. Don't worry too much about this, the vast majority of websites works very well.

To learn more about Torbutton you can see:

To learn more about Data Collection Techniques, Fingerprinting you can see:

New Identity Button[edit]

The New Identity button on Tor Browser isn't perfect yet (NOT a Whonix issue), there are open bugs.[23]


click TorButton -> click New Idenity

Please understand New Identity and Tor circuits to learn what this actually does and what its limitations are.

Protection against dangerous JavaScript[edit]

Having all JavaScript disabled by default would disable a lot of harmless and possibly useful JavaScript and render unusable many websites. This would scare away lots of potential users "because it just doesn't work". Torbutton disables all potentially dangerous JavaScript. On the other hand, having a big user base is important for good anonymity as this very interesting mail by Roger Dingledine explains.[24]

That's why JavaScript is enabled by default in Tor Browser. We consider this as a necessary compromise between security and usability and as of today we are not aware of any JavaScript that would compromise Whonix anonymity.

For more technical details you can refer to the Torbutton design document.[25] Another related discussion justifying why JavaScript is enabled by default in Tor Browser was on tor-talk, "Tor Browser disabling Javascript anonymity set reduction".[26]


NoScript logo

NoScript also comes with Tor Browser and provides many protections, even though JavaScript is enabled by default. You shouldn't mess with NoScript settings in Tor Browser unless you exactly know what you are doing.

For more information you can refer to the NoScript website and features.


Maximizing Browser Window[edit]

It is better for privacy and anonymity not to maximize the Tor Browser window. [27]

Tor Browser in Whonix differences[edit]


The regular Tor Browser and Tor Browser in Whonix slightly differ. The environment Tor Browser is running in has been adjusted by Whonix to work behind the Whonix-Gateway. The network and browser fingerprint however, is the same.

Tor Browser's internal update check mechanism is untouched and works fine. Default homepage is

Whonix Proxy Settings[edit]

Short: You don't need to change any proxy settings in Tor Browser.

Long: [28]

(If you want to change or remove proxy settings, see #Change / Remove Proxy Setting.)

More than one Tor Browser in Whonix[edit]

For better isolation of different identities. For advanced users. Moved to the Advanced Security Guide.

Update Tor Browser[edit]


Tor Browser's Internal Updater, built in stock update notification mechanism also works in Whonix. Use it.

Tor Browser Downloader (Whonix) does not notice upgrades done by Tor Browser's Internal Updater.

The Tor Project configured Tor Browser since version 5.0 to update itself. [29]

Additionally it might also be wise to subscribe to blog of the creators of Tor Browser https://blog.torproject.org for news.


Tor Browser Downloader by Whonix[edit]


Tor Browser Downloader (Whonix) is really just a downloader, not a updater. Meaning, it is incapable of keeping user data, for example bookmarks and passwords. If you would like to keep your user data, use Tor Browser Internal Updater instead.

Here are some Tor Browser Downloader (Whonix) Screenshots.

Tor Browser Downloader (Whonix) checking for updates.
Tor Browser Downloader (Whonix) Download Confirmation
Tor Browser Downloader (Whonix) Downloading Tor Browser.
Tor Browser Downloader (Whonix) Installation Confirmation.
Tor Browser Downloader (Whonix) Extracting.
Tor Browser Downloader (Whonix) Finished Installing Tor Browser.

(Also available as CLI version.)

Tor Browser version check and download (after confirmation) in Whonix can be done with:

If you are using Qubes-Whonix, complete the following steps:

Qubes App Launcher (blue/grey "Q") -> Whonix-Workstation AppVM (commonly named anon-whonix) -> Tor Browser Downloader (Whonix)

If you are using a graphical Whonix-Workstation, complete the following steps:

Start Menu -> Applications -> System -> Tor Browser Downloader (Whonix)

If you are using a terminal-only Whonix-Gateway, complete the following steps:


Download Confirmation Screen[edit]

Helps to keep you safe.

There is currently no reliable way for a program to securely determine the latest stable version of Tor Browser with reasonable certainty. [30] [31] When the version format changes, the automated parser of version information could falsely suggest, a still considered secure, stable version that is not the latest stable version, an alpha, beta or rc (release candidate) version. Rather, you could be the target of a denial of service, indefinite freeze or rollback (downgrade) attack. [32] [33]

Therefore the intelligence of the user is utilized as a sanity check. The Download Confirmation Screen enables users to detect such situations and abort.

Version numbers you see under Online versions come from the Tor Browser online RecommendedTBBVersions versions file that is provided by The Tor Project and parsed by Whonix's Tor Browser Downloader. All versions listed in that file are considered up to date, by The Tor Project, which means that no upgrade is required.

TODO: expand

Installation Confirmation Screen[edit]

Helps to keep you safe.

There is currently no reliable way for a program to securely determine if your download of Tor Browser was a target of an indefinite freeze or rollback attack with reasonable certainty. [34] [35]

When verifying cryptographic signatures there are multiple important aspects.

  • For one, the signature should be made by a trusted key.
  • Naturally, trusted keys have signed other files in past as well. So one must make sure to have also received the right file and not just some file that was signed by a trusted key.
  • Finally, even when having received the right type of file [36] it should be made sure, that a current signature has been used and not a historic one to counter indefinite freeze and rollback attacks.

By the time you see the Installation Confirmation Screen, the verification of the signature [37] already succeeded, but again the intelligence of the user has to be utilized to make sure there the user is not target of an indefinite freeze or downgrade attack.

Previous Signature Creation Date: When Tor Browser was previously installed by tb-updater, then tb-updater will have stored the creation date of the accompanying signature the signed Tor Browser. The Previous Signature Creation Date field shows you that date.

Last Signature Creation Date: This field shows you the date of the creation of the signature that was just downloaded.

Here is a screenshot:

[38] [39]

Tor Browser local version number detection is not implemented.

TODO: Expand.

Tor Browser Manual Update[edit]

A future update of Tor Browser by The Tor Project might make Whonix's Tor Browser Updater or Tor Browser running in Whonix-Workstation unusable. In case Tor Browser (Updater) inside Whonix-Workstation breaks, a news with instructions on how to fix the issue will be posted within a few days. If not, the Whonix developers are not aware of the issue.

If the Tor Browser update script is ever broken, you are advised to update manually, see Manually Downloading Tor Browser.

Tor Browser Internal Updater[edit]

Tor Browser's Internal Updater Popup Screenshot:
Tor Browser Internal Updater Popup.png

Tor Browser's Internal Updater Wizard Screenshot:
Tor Browser Internal Updater Wizard.png

Here you can see a screenshot of Tor Browser's menu bar that contains Tor Browser's Internal Updater Update Symbol:
Tor Browser Tor Button Update Symbol.png

Tor Browser's Internal Updater Update Symbol:
The following symbol is quite useful. It indicates, that Torbutton has found out, that there is an update.
Tor Browser Tor Button Update Notification.png

A screenshot of about:tor, that is as useful as the above symbol:
Tor Browser Internal Updater About Tor.png

Start Tor Browser[edit]

Start Tor Browser.

If you are using Qubes-Whonix:

Qubes Start Menu -> Whonix-Workstation AppVM (commonly called anon-whonix) -> Tor Browser

If you are using a Non-Qubes-Whonix:

Start Menu -> Tor Browser

If you are using a terminal (Konsole):


File Downloads[edit]

Lets say you wanted to download this image using Tor Browser. By default the download path going to be /home/user/.tb/tor-browser/Browser/Downloads. It is inconvenient to navigate to this sub sub sub folder.


To make things simpler, save files directly inside /home/user/Downloads.

Go to about:preferences in Tor Browser.


Change the default Download folder.


Change the setting to Safe files to.


Done. Your files should now be downloaded to /home/user/Downloads. You can navigate there using dolphin or konsole.

If you stored files inside the "wrong" sub sub sub folder, and want to access you file anyhow, please press expand on the right.

Start dolphin.

Now in order to go to your downloadable path using dolphin please follow the images. First we need to enable showing hidden files.


Double click on .tb folder.


Get into the following path.


Now you are going to find what you have downloaded.


Not installed by Default[edit]

Reasons why Tor Browser is installed by default in Whonix-Workstation in Qubes-Whonix, but not in Non-Qubes-Whonix. If you are interested in the reasons why, see footnote. [40]

This will change in Whonix 14. [41]

Local Connections[edit]

Note: Accessing local application interfaces on it is no longer possible due to a change in Tor Browser by The Tor Project. The configured exception means a small trade-off in privacy but is much safer than using another browser. (See #Local Connections Exception Threat Analysis.)

To configure an exception for local connections in Tor Browser:

Preferences -> Advanced -> Network | Connection Settings... -> No Proxy for: "". Then, click on "OK" 


Web HTTP(S)/SOCKS proxies have different instructions and will not work with these steps, see Tor Browser Proxy Configuration.


For better anonymity.

  • Surf with JavaScript (JS) disabled in Tor Browser and enable only when needed - mitigates these browser fingerprinting issues completely.
  • Set passwords for WebGUIs listening on localhost.
  • Run sensitive daemons with local WebGUIs on a separate dedicated Whonix-Workstation + virtual network instance.

Browser Plugins / Flash / Java[edit]

See Browser Plugins.

Browser Language[edit]

If you want the browser interface in a different language than English, see Language.

AppArmor Confinement[edit]

To protect the system and your data from some types of attack against Tor Browser, you could consider to install Whonix's Tor Browser AppArmor profile.

As a consequence, it can only read and write to a limited number of folders. This is why you might face Permission denied errors, for example if you try to download files to the home folder. You can save files from Tor Browser to the ~/Downloads folder that is located in the home folder. If you want to upload files with Tor Browser, copy them to that folder first.

Update your package lists.

sudo apt-get update

Install the apparmor-profile-torbrowser package.

sudo apt-get install apparmor-profile-torbrowser

Advanced Topics[edit]

Tor Browser Hardened[edit]

With all major hardening features (selfrando and sandboxing) becoming part of the mainline version of Tor Browser, there is discussion among TBB devs to drop or rename the hardened version name to debug version.[43][44]

Debug features like ASan are not suited for security and are extremely resource intensive.

Note that sandboxing is only available in the 64-bit versions of Tor Browser only.

Tor Browser Sandboxed[edit]


A sandbox is a secure environment in which you can run the Tor Browser to mitigate exploit vectors which would otherwise deanonymize you or infect your computer. For instance, sandboxing reduces the opportunities for an attacker to easily identify real IP and MAC addresses, install malware, or browse your files.[45] In simple terms, the Tor Browser runs in a limited awareness container that is prevented from interacting with the rest of your computer. The spate of recent attacks on the Tor Browser in the wild suggest this is a sensible approach for cautious users or those facing significant risks.

The Tor Browser sandbox is compatible with either the "release", "alpha" or "hardened" Tor Browser series. However, the sandboxed "hardened" Tor Browser is the combination least-tested by Tor developers.[46]

Sandboxing Effects on Tor Browser Functionality[edit]

Sandboxing improves security, but some functionality is lost inadvertently or by design. Also, some functions like sound must be optionally configured. In early 2017, broken items include:[47]

  • Foreign language support;
  • The meek pluggable transport; and
  • Manual checks for Tor Browser updates.

The Tor Browser sandbox is unlikely to ever support:

  • The FTE pluggable transport;
  • Hardware-accelerated 3D rendering;
  • Printing, except to a file;
  • Connections outside of the Tor network; and
  • Compatibility of the "hardened" Tor Browser with a grsec kernel (due to ASAN/Pax conflicts).

Manual configuration changes are required for: audio support, the Tor ciruit display (already disabled in Whonix), and installs/updates of Tor Browser add-ons. By design: fonts are limited to a minimal set, plug-ins like Flash or Silverlight will not work, users will not be able to see downloaded files, and further add-ons cannot be enabled without sandbox configuration changes.

Sandboxing Tor Browser in Non-Qubes-Whonix[edit]

Warning: these instructions are extremely alpha and require a 64-bit version of Whonix (Whonix 14) to work. Testers or advanced users only!

Tor Browser Sandbox Dependencies[edit]

In order to install and run the sandbox you need:

  • Bubblewrap from Debian Jessie backports;
  • A newer (Whonix-14-developers-only) version of the control-port-filter-python for Tor cookie control protocol authentification; and [48]
  • Optional: Libnotify4 for desktop notifications about events.

1. Boot your Whonix-Workstation VM

2. Add jessie-backports to sources.list

   sudo su -c "echo -e 'deb http://http.debian.net/debian jessie-backports main' > /etc/apt/sources.list.d/jessie-backports.list"

Or to use the .onion mirror:

   sudo su -c "echo -e 'deb http://vwakviie2ienjx6t.onion/debian jessie-backports main' > /etc/apt/sources.list.d/jessie-backports.list"

3. Use Apt-pinning Before Installing Dependencies

Apt-Pinning provides a safe mechanism to mix and match packages from different Debian repository branches without breaking your base distribution.

A higher pin priority ensures that only the stable package version is preferred over any other when installing with apt. Note that these files have a .pref extension or none at all.

Open /etc/apt/preferences.d/debian-pinning.pref in an editor with root rights.

If you are using a graphical Whonix or Qubes-Whonix, run:

kdesudo kwrite /etc/apt/preferences.d/debian-pinning.pref

If you are using a terminal-only Whonix, run:

sudo nano /etc/apt/preferences.d/debian-pinning.pref


Package: *
Pin: release a=stable
Pin-Priority: 700

Package: *
Pin: release a=jessie-backports
Pin-Priority: 650

Package: *
Pin: release a=testing
Pin-Priority: 600

Package: *
Pin: release a=unstable
Pin-Priority: 550

Package: *
Pin: release a=experimental
Pin-Priority: 500


4. Update the Package Lists and Install Bubblewrap

   sudo apt-get update
   sudo apt-get -t jessie-backports install bubblewrap

Note: golang is not needed unless manually building the sandbox from source. lib-seccomp dependencies are no longer required for v0.0.3 of the sandbox.

5. Optional: Install Libnotify4 for Desktop Notifications

   sudo apt-get install libnotify4

Note: the Adwaita Gtk+-2.0 theme is already installed in the Whonix template.

Download the Tor Browser Sandbox[edit]

1. Download the Sandbox Binary and Key File

For later releases, the Tor Project sandbox binaries and key files can be found here.

In the Whonix-Workstation VM, open a terminal and run:

   wget https://dist.torproject.org/torbrowser/7.0a1/sandbox-0.0.3-linux64.zip
   wget https://dist.torproject.org/torbrowser/7.0a1/sandbox-0.0.3-linux64.zip.asc

2. Download the Tor Project Signing Key and Verify the Zip File

In the terminal, run:

   gpg --recv-keys "EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290"
   gpg --verify sandbox-0.0.3-linux64.zip.asc

The output should show a good signature from the Tor developers and be similar to this:

   gpg: Signature made Tue 24 Jan 2015 09:29:09 AM CET using RSA key ID D40814E0
   gpg: Good signature from "Tor Browser Developers (signing key) "
   gpg: WARNING: This key is not certified with a trusted signature!
   gpg: There is no indication that the signature belongs to the owner.
   Primary key fingerprint: EF6E 286D DA85 EA2A 4BA7  DE68 4E2C 6E87 9329 8290

If you receive a bad signature warning, delete the files, rotate your Tor circuits, and download them again.

3. Unzip the sandbox

In the terminal, run:

   unzip sandbox-0.0.3-linux64.zip

Launching sandboxed-tor-browser[edit]

To start the sandbox, open a terminal and run:

   cd sandbox

When prompted, select the Tor Browser version you wish to use in your Whonix-Workstation VM. To check the sandboxed-tor-browser is correctly using the system Tor process run:

   env | grep TOR

The output should show:


Is set as an environment variable.

Important notes:

  • sandboxed-tor-browser is also a Tor Browser downloader similar to tb-updated / torbrowser-launcher;
  • Whonix network settings are auto-detected as system Tor. There is no need to manually configure settings;
  • 32-bit support has been deprecated since version 0.0.2 of the sandbox; and
  • 64-bit only support from sandbox version 0.0.3 onwards means it is only compatible with Whonix 14 (the next Whonix release).

Sandboxing Tor Browser in Qubes-Whonix[edit]

The Tor Browser alpha sandbox is currently blocked in Qubes-Whonix due to problems in upgrading to the Whonix-14-developers-only version of the control-port-filter-python. This issue is expected to be resolved with the official release of Whonix 14.

A recommended interim solution is to use Firejail to better contain the Tor Browser application.

Custom Homepage[edit]

This is an advanced topic.

As reported, setting a custom homepage in Tor Browser settings might not work.

Technical background: [49]

To set a custom homepage, you could try to purge the whonix-welcome-page package. [50] But this is difficult due to technical limitations as explained on the Whonix Debian Packages page.

Alternatively, you could modify /usr/lib/whonix-welcome-page/env_var.sh, but these changes would be reverted after upgrade. [51]

Or you could set environment variable TOR_DEFAULT_HOMEPAGE to a custom value. Doing so would be similar setting environment variables as explained in #Transparent Torification - No Proxy - System Default.

Unsupported Tor Browser Features in Whonix[edit]

Tor Circuit View[edit]


This is unsupported for security reasons. [52]


Verify New Identity[edit]

This is an advanced topic. You most likely only need it in custom configurations, such as when using a Whonix-Custom-Workstation.

First of all, should it have failed, TorButton should notice, that it could not connect to Tor's ControlPort and should report, that giving a new identity failed. If you don't get such an error popup, it is a good indication, that there are no issues.

After the browser restarted, on the about:tor page, click "Test Tor Network Settings". It will lead to https://check.torproject.org (check.tpo) (or manually visit check.tpo, it doesn't matter.). In most cases (Not all! [53]) you should have a new exit relay. Check.tpo should report different IP.

On Whonix-Gateway, watch Control Port Filter Proxy's log while using TorButton's New Identity feature.

tail -f /var/log/control-port-filter-python.log

If you see something like this.

2015-12-12 23:59:41,276 - CPFP log - DEBUG - Request: signal newnym
2015-12-12 23:59:41,284 - CPFP log - DEBUG - Answer: 250 OK

Then Control Port Filter Proxy received the request from Tor Browser and got Tor's okay, that it worked.

Get New Identity without Tor ControlPort Access[edit]

This is an advanced topic. You most likely only need it in custom configurations, such as when not using Control Port Filter Proxy.

Simulate, what TorButton would do.

1. Close Tor Browser.
2. Get new identity on Whonix-Gateway using arm.
3. Start Tor Browser again.
4. Done.

Remove Proxy Settings[edit]

This is an advanced topic. You most likely only need it for advanced tunneling scenarios.

To remove Tor Browser proxy settings, i.e setting it to no proxy, apply the following instructions.

Applying this configuration would result in Tor Browser no longer using proxy settings. In other words, setting to no proxy. Thereby Tor Browser would be using the (VM) system's default networking. Just like any other application inside the workstation that is not explicitly configured through socks proxy settings or a socksifier to use Tor. This is also called transparent torification. [54] It would break Stream Isolation for Tor Browser as well as break Tor Browser's tab isolation by socks user name feature, thereby worsen your web fingerprint and be pseudonymous rather than anonymous. (To limit the risks, consider using More than one Tor Browser in Whonix or better Multiple Whonix-Workstations.)

If you change these settings, Tor Button showing a red sign and 'Tor Disabled' if you hover over it by mice is expected.

If you want to set it to no proxy... You could set the TOR_TRANSPROXY=1 environment variable. There are various methods to do so. #/etc/environment Method is the simplest one.

For other methods with more fine granulated settings, please press on expand on the right.

<span id="
od"></span> Command Line Method
Get into your Tor Browser folder.

cd ~/tor-browser_en-US

Every time you start Tor Browser, run the following command to set the TOR_TRANSPROXY=1 environment variable.

TOR_TRANSPROXY=1 ./start-tor-browser.desktop

start-tor-browser Method
This applies to the one instance/folder of Tor Browser that you configure only. This method might not persist when Tor Browser is updated.

Find and open start-tor-browser in the Tor Browser folder in an editor.

Most likely in ~/tor-browser_en-US/Browser/start-tor-browser below #!/usr/bin/env bash.


/etc/environment Method
This applies to the whole environment. I.e. any possible custom locations of Tor Browser installation folders.[55]

Open /etc/environment in an editor with root rights.

If you are using a graphical Whonix or Qubes-Whonix, run:

kdesudo kwrite /etc/environment

If you are using a terminal-only Whonix, run:

sudo nano /etc/environment

Add the following content.




Undoing this setting is undocumented. Simply no longer setting that environment variable will not do the trick. This is because of limitations of Tor Browser. The easiest way to undo these instructions would be to start over with a fresh installation of Tor Browser. Please contribute these instructions.

Forget about Tor Button's Open Network Settings
Forget about Tor Button's -> Open Network Settings. See footnote, if you want to know why.[56]

Change Proxy Settings[edit]

This is an advanced topic. You most likely only need it for advanced tunneling scenarios.

Note that these instructions do not apply to accessing local web-interfaces.

Due to a bug in Tor Browser [57], extra steps are required to use proxies with Tor Browser.

It would break Stream Isolation for Tor Browser as well as break Tor Browser's tab isolation by socks user name feature, thereby worsen your web fingerprint and be pseudonymous rather than anonymous. (To limit the risks, consider using More than one Tor Browser in Whonix or better Multiple Whonix-Workstations.)

Inside Whonix-Workstation.

1. Install FoxyProxy add-on in Tor Browser

2. Change Tor Browser Settings:

  • Double click Default proxy in FoxyProxy and setup the IP and port of the proxy. If configuring a SOCKS proxy check the option and specify the type.
  • Set Mode: Use Proxy "Default" for all URLs

Local Connections Exception Threat Analysis[edit]

This applies to allowing local connections in Tor Browser.

Threat Details

According to this Firefox ticket, JavaScript can be abused to scan internal networks, fingerprint devices, and make malicious commands to those devices if they have a web interface. The configured exception means a small trade-off in privacy but is much safer than using another browser. [58] Read on about steps to further minimize the risks.


There are no embedded devices attached to a Whonix internal network, it is isolated and untrusted. However malicious JavaScript (JS) will be able to tell an attacker that a service is running on a localhost port. This can reduce your anonymity set.

Malicious misconfiguration of daemons listening on localhost is possible but with limited impact because traffic is still forced through Whonix-Gateway.


tor-launcher vs torbrowser-launcher[edit]

Two totally different things with similar names.


In case you are wondering if tor-launcher will result in Tor over Tor... No, because Tor Browser and Whonix play well together. tor-launcher is disabled by default in Whonix-Workstation.

Can or should you remove tor-launcher from TBB? In theory it makes no difference. In practice, it is untested and seems to provide no advantages. Just leave it enabled to have the same tested setup as everyone else.

tor-launcher is not (yet) available for usage in Whonix-Gateway. [59]


Tor Browser Updater (Whonix) (tb-updater) (installed by default in Whonix) is specifically designed to be co-installable with torbrowser-launcher. Maybe one day Whonix will deprecate tb-updater and install torbrowser-launcher by default, see forum development discussion if that is of interest to you.


Tor vs Tor Browser[edit]

Tor is an anonymizer developed by The Tor Project. Tor Browser is a web browser developed by the Tor Project optimized for privacy. Please don't substitute writing Tor when you mean Tor Browser or the confusion will be perfect.

Tor Browser Transparent Proxying[edit]

This Tor Browser "transparent proxying" feature and/or the environment variable TOR_TRANSPROXY=1 causes lots of confusion. It was a bad decision by TPO to call it "transparent proxying". What it actually does, is "set to no proxy settings", i.e "set to system default". Then Tor Browser works network wise just as a unconfigured Firefox / Iceweasel. If the person using this Tor Browser "transparent proxying" feature, happens to not use a gateway with transparent torification features such as Whonix-Gateway, traffic would go through clearnet. If the person using this Tor Browser "transparent proxying" feature, happens to use a torifying gateway such as Whonix-Gateway, traffic happens to go through Tor. If the person using this Tor Browser "transparent proxying" feature, happens to have a JonDo-Gateway, traffic happens to go through JonDo.

Not to be confused with Tor's setting TransPort [address:]port|auto [isolation flags] setting. Not to be confused with TransparentProxy, which is different from an IsolatingProxy.

Qubes specific[edit]

Running Tor Browser in Qubes TemplateVM[edit]

If you want to know why, please press on expand on the right.

tb-updater in Qubes TemplateVM[edit]

Tor Browser is installed by default in Whonix-Workstation in Qubes-Whonix, but not in Non-Qubes-Whonix. If you are interested in the reasons why, see #Not installed by Default Footnote.

Beginning from Whonix 13 by default during Qubes-Whonix-Workstation builds, during the initial installation of #Tor Browser Downloader by Whonix (tb-updater package) (update-torbrowser) within chroot, it will be automatically run. If that fails, it will fail closed by default. This means, the package will fail to install. Therefore this could throw and error while building Whonix images from source code or when installing Whonix from repository. This is not great, but it has been decided to install Tor Browser by default in Qubes-Whonix-Workstation. The only way to ensure it really gets installed by default, is to fail closed by default.

Beginning from Whonix 13 by default in Qubes-Whonix-Workstation TemplateVMs, during upgrades of #Tor Browser Downloader by Whonix (tb-updater package) (update-torbrowser) it will be automatically run. If that fails, it will fail open by default. This means, you will be informed in the terminal, that no new Tor Browser could be downloaded but apt-get will terminate normally. This is required to implement the Qubes-Whonix feature up to date versions of Tor Browsers in newly created AppVMs inherited from updated TemplateVMs.

What should you do if it failed? If you can still update Tor Browser using #Tor Browser Internal Updater or manually re-download Tor Browser, then there is no need for concern and this is only a small inconvenience.

All of this can be configured, if you want to do so...

Open /etc/torbrowser.d/50_user.conf in an editor with root rights.

If you are using a graphical Whonix or Qubes-Whonix, run:

kdesudo kwrite /etc/torbrowser.d/50_user.conf

If you are using a terminal-only Whonix, run:

sudo nano /etc/torbrowser.d/50_user.conf

When the tb-updater package is upgraded, by default in the Qubes-Whonix-Workstation TemplateVM a hardcoded[60] version Tor Browser tarball and signature is automatically downloaded. If you want to disable this, add.



Technical details:

By default in Qubes-Whonix-Workstation TemplateVMs during Debian maintainer postinst script, folders /var/cache/tb-binary/.cache/tb/ and /var/cache/tb-binary/.tb/tor-browser will be deleted if existing. tb-updater will then download files to /var/cache/tb-binary/.cache/tb/.

find /var/cache/tb-binary/.cache/tb/

After gpg verification, tb-updater will extract the Tor Browser archive to /var/cache/tb-binary/.tb.

find /var/cache/tb-binary/.tb

When a Qubes-Whonix-Workstation AppVM is booted for the first time, in essence, 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. This results in...

ls -la /home/user/.tb
output... TODO
ls -la /home/user/.cache/tb
output... TODO

Informations for users creating Whonix using the build script.

If you are building Qubes-Whonix using the build script and want to fail open generally, a file /etc/torbrowser.d/50_user.conf has to be created inside chroot before the build with the following content.


If you are building Qubes-Whonix using the build script and want to skip initial download of Tor Browser during build of Whonix in chroot, a file /etc/torbrowser.d/50_user.conf has to be created inside chroot before the build with the following content.


Whonix-Custom-Linux-Workstation specific[edit]

These instructions are new and you will be an early tester. There could be some connectivity issues.

Please contribute by testing and finishing these instructions!

These instructions were tested using Tor Browser version 6.0.1. Connectivity might break in later Tor Browser versions in case the developers of Tor Browser modify things related to how networking in Tor Browser gets configured. [61]

1) Manually download and install Tor Browser.

2) You have to set multiple environment variables.

Open /etc/environment in an editor with root rights.

If you are using a graphical Whonix or Qubes-Whonix, run:

kdesudo kwrite /etc/environment

If you are using a terminal-only Whonix, run:

sudo nano /etc/environment


## Deactivate tor-launcher,
## a Vidalia replacement as browser extension,
## to prevent running Tor over Tor.
## https://trac.torproject.org/projects/tor/ticket/6009
## https://gitweb.torproject.org/tor-launcher.git

## Environment variable to disable the "TorButton" ->
## "Open Network Settings..." menu item. It is not useful and confusing to have
## on a workstation, because this is forbidden for security reasons. Tor must be
## configured on the gateway.

## environment variable to skip TorButton control port verification
## https://trac.torproject.org/projects/tor/ticket/13079



From now on, only the browser component of Tor Browser will be started.

3) Verify environment variables.

env | grep -i tor

Should show.


4) Configure network settings. [62]

Now you have to create ~/.tb/tor-browser/Browser/TorBrowser/Data/Browser/profile.default/user.js. This supposes you installed Tor Browser as per step 1). It supposes you have a folder ~/.tb/tor-browser. If you installed Tor Browser to another folder of your own choice, you need to adjust the path.

Open ~/.tb/tor-browser/Browser/TorBrowser/Data/Browser/profile.default/user.js in an editor.

If you are using a graphical environment, run:

kwrite ~/.tb/tor-browser/Browser/TorBrowser/Data/Browser/profile.default/user.js

If you are using a terminal (Konsole), run:

nano ~/.tb/tor-browser/Browser/TorBrowser/Data/Browser/profile.default/user.js


user_pref("extensions.torbutton.use_privoxy", false);
user_pref("extensions.torbutton.settings_method", "custom");
user_pref("extensions.torbutton.socks_host", "");
user_pref("extensions.torbutton.socks_port", 9100);
user_pref("network.proxy.socks", "");
user_pref("network.proxy.socks_port", 9100);
user_pref("extensions.torbutton.custom.socks_host", "");
user_pref("extensions.torbutton.custom.socks_port", 9100);
user_pref("extensions.torlauncher.control_host", "");
user_pref("extensions.torlauncher.control_port", 9052);


5) Done.

Windows specific[edit]

Please contribute by testing and finishing these instructions!

When you are using a Custom-Whonix-Workstation, specifically a Windows-Whonix-Workstation and want to use Tor Browser...

1) Install Tor Browser.

2) Use Tor Browser without bundled Tor.

In the folder where you extracted Tor Browser, create a new text file. For example, you could give it the following name.

Start TB without Tor.bat

Add the following content to that file.


"Start Tor Browser.lnk"



3) Configure network settings.

Start Tor Browser. The following links for removing and changing proxy settings do not apply one to one to Windows! removing of proxy settings should be better avoided. changing proxy settings would be better. How to do this on Windows is currently undocumented but you might figure out.

  • Type: SOCKSv5.
  • IP address:
    • Qubes-Whonix:
      • If Qubes Tools in the custom workstation are:
        • Installed: you can find out the IP address of Qubes-Whonix-Gateway by running qubesdb-read /qubes-gateway inside the custom workstation
        • Not installed: you can find out the IP address of Qubes-Whonix-Gateway by running qubesdb-read /qubes-ip inside sys-whonix
      • Unfortunately the IP address will not be static. [64] This means after restarting sys-whonix, the connection might break and you may need to manually update the IP address setting.
    • Non-Qubes-Whonix:
  • Port: 9100
  • You can leave "No Proxies for" as is.

4) Figure out missing instructions. Port them from Linux specific to Windows specific.


5) Done.

Start from Command Line[edit]

cd .tb/tor-browser


1) Start Tor Browser

2) go to about:config

3) search for ___ and set to ___

extensions.torbutton.loglevel | 1
extensions.torlauncher.loglevel | 1

extensions.torbutton.logmethod | 0
extensions.torlauncher.logmethod | 0

4) Close Tor Browser.

5) Restart Tor Browser from command line in debug mode.

cd .tb/torbrowser
./start-tor-browser --debug


Footnotes / References[edit]

  1. Reasons? See below.
  2. https://www.torproject.org/projects/torbrowser.html.en
  3. https://tb-manual.torproject.org/linux/en-US/
  4. https://en.wikipedia.org/wiki/Fork_(software_development)
  5. http://www.mozilla.com/firefox/
  6. https://www.torproject.org/projects/torbrowser/design/
  7. https://www.torproject.org/torbutton/en/design/
  8. https://www.torproject.org/
  9. https://www.torproject.org/projects/torbrowser/design/#firefox-patches
  10. See below.
  11. https://www.whonix.org
  12. https://en.wikipedia.org/wiki/HTTP_Secure
  13. https://www.eff.org/pages/tor-and-https
  14. https://www.eff.org/https-everywhere
  15. https://torproject.org/
  16. https://eff.org/
  17. https://en.wikipedia.org/wiki/JavaScript
  18. https://en.wikipedia.org/wiki/Adobe_Flash
  19. https://en.wikipedia.org/wiki/HTTP_cookie
  20. DoNot#Do_not_confuse_Anonymity_with_Pseudonymity..
  21. https://trac.torproject.org/projects/tor/wiki/doc/TorifyHOWTO/WebBrowsers
  22. https://www.torproject.org/torbutton/
  23. See tbb-linkability and tbb-fingerprinting.
  24. http://www.mail-archive.com/liberationtech@lists.stanford.edu/msg00022.html
  25. https://www.torproject.org/torbutton/en/design/
  26. https://lists.torproject.org/pipermail/tor-talk/2012-May/024227.html
  27. http://forums.whonix.org/t/should-still-recommend-against-maximizing-tor-browser-window
  28. (permalink)
    There is no Tor over Tor in Whonix, which would be recommended against, due to Whonix's environment. Whonix does not modify Tor Browser's startup script, defaults, etc. In Whonix-Workstation rinetd listens on 9150 and 9151 (Tor Browser's default ports) and forwards them to Whonix-Gateway 9150 (where a Tor SocksPort is listening) and 9151 (where Control Port Filter Proxy is listening). Tor does not get started by the tor-launcher Firefox add-on because the TOR_SKIP_LAUNCH environment variable has been set set to 1. See also Dev/anon-ws-disable-stacked-tor.
  29. https://blog.torproject.org/blog/tor-browser-50-released

    Starting with this release, Tor Browser will now also download and apply upgrades in the background, to ensure that users upgrade quicker and with less interaction. This behavior is governed by the about:config pref app.update.auto, but we do not recommend disabling it unless you really know what you're doing.

  30. finalize RecommendedTBBVersions format
  31. counter downgrade / stale mirror attacks on RecommendedTBBVersions - sign / verify tbb versions file
  32. For a definition of these attacks, see TUF (The Update Framework)'s threat model (w).
  33. An adversary capable of breaking SSL could mount such an attacks by replacing RecommendedTBBVersions with invalid, frozen or outdated version information.
  34. This is because Tor Browser signatures do not provide expiration dates yet. (Similar to Debian's valid-until field.
  35. This is because the user's computer clock could be wrong, so there is no rock solid basis for comparison.
  36. i.e. for example, a browser, not a messenger
  37. and hash
  38. gnupg (OpenPGP) common misconceptions
  39. The name of the file is stored in the hash file and verified to match the downloaded name of the file and hash.
  40. Reasons why Tor Browser is installed by default in Whonix-Workstation in Qubes-Whonix, but not in Non-Qubes-Whonix. (link)

    Licensing reasons:
  41. Alternatively, can could remove Tor Browser's proxy settings, but then you would be vulnerable to the same fingerprinting issues (see #Local Connections Exception Threat Analysis). Additionally, you would be vulnerable to the fingerprinting issues that are opened up by remove Tor Browser's proxy settings.
  42. https://forums.whonix.org/t/hardened-tor-browser-bundle-not-as-hardened-you-think-soon-becoming-extinct/3582/3
  43. https://lists.torproject.org/pipermail/tbb-dev/2017-February/000454.html
  44. https://blog.torproject.org/blog/q-and-yawning-angel
  45. https://blog.torproject.org/blog/tor-browser-65a6-hardened-released
  46. https://trac.torproject.org/projects/tor/wiki/doc/TorBrowser/Sandbox/Linux
  47. https://forums.whonix.org/t/tor-browser-sandbox-linux-alpha-coming-soon/3060
  48. The whonix-welcome-page package's file /usr/lib/whonix-welcome-page/env_var.sh sets environment variable to set TorBrowser homepage TOR_DEFAULT_HOMEPAGE to /usr/share/homepage/whonix-welcome-page/whonix.html. Perhaps it could be seen as a bug if Tor Browser if a user set custom homepage does not overrule the TOR_DEFAULT_HOMEPAGE environment variable? TODO: No bug has been reported at trac.torproject.org yet.
  49. sudo apt-get purge whonix-welcome-page.
  50. kdesudo kate /usr/lib/whonix-welcome-page/env_var.sh
  51. We do not want Whonix-Workstation to have access to the information, which Tor middle relay or Tor entry guard [or bridge] are being used. See also: Dev/Control_Port_Filter_Proxy#Indicator_for_current_Circuit_Status_and_Exit_IP
  52. Getting a new circuit, doesn't guarantee getting a new exit relay. This is normal. See also Stream_Isolation.
  53. That term was coined in context of a Tor Transparent Proxy. A simple gateway that routes all connections through Tor and does not provide Stream Isolation.
  54. Unless you manually unset this environment variable before starting Tor Browser.
  55. When using the regular Tor Browser Bundle from The Tor Project without Whonix, that menu can be used to change network settings inside Tor. It has the same effects as editing Tor's config file torrc.

    Using this graphical user interface isn't possible in Whonix, because for security reasons, in Whonix there is only limited access to Tor's control port. (See Dev/CPFP for more information.) (You could change such settings manually in /etc/tor/torrc on Whonix-Gateway. (See also VPN/Tunnel suppprt for more information.)

    We are setting environment variable export TOR_NO_DISPLAY_NETWORK_SETTINGS=1 to disable the "TorButton" -> "Open Network Settings..." menu item. It is not useful and confusing to have on a workstation, because Tor must be configured on the gateway, which is for security reasons forbidden from the workstation.
  56. Circuit isolation by SOCKS proxy may be breaking other proxies or non-proxies
  57. https://trac.torproject.org/projects/tor/ticket/10419#comment:37
  58. https://phabricator.whonix.org/T118
  59. In the tb-updater package.
  60. Once Tor Browser moves to SocksSocket, this will certainly no longer work. References:
  61. Learn about network settings.
    • Type: SOCKSv5.
    • IP address:
      • Qubes-Whonix:
        • If Qubes Tools in the custom workstation are:
          • Installed: you can find out the IP address of Qubes-Whonix-Gateway by running qubesdb-read /qubes-gateway inside the custom workstation
          • Not installed: you can find out the IP address of Qubes-Whonix-Gateway by running qubesdb-read /qubes-ip inside sys-whonix
        • Unfortunately the IP address will not be static. This means after restarting sys-whonix, the connection might break and you may need to manually update the IP address setting.
      • Non-Qubes-Whonix:
    • Port: 9100
    • You can leave "No Proxies for" as is.
    ## The following TOR_SOCKS_HOST and TOR_SOCKS_PORT variables
    ## do not work flawlessly, due to an upstream bug in Tor Button:
    ##    "TOR_SOCKS_HOST, TOR_SOCKS_PORT regression"
    ##    https://trac.torproject.org/projects/tor/ticket/8336
  62. We just have to set the **SET TOR_SKIP_LAUNCH=1** environment variable, then start Tor Browser. The Tor Browser Launcher add-on will detect this, skip the connection wizard and skip launching Tor.
  63. Qubes feature request: optional static IP addresses.
  64. https://www.torproject.org/docs/torbutton/en/design/

Cite error: <ref> tag defined in <references> has no name attribute.


Whonix Tor Browser wiki page Copyright (C) Amnesia <amnesia at boum dot org>
Whonix Tor Browser wiki page Copyright (C) 2012 -2014 Patrick Schleizer <adrelanos@riseup.net>

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.

Random News:

We are looking for maintainers and developers.

Impressum | Datenschutz | Haftungsausschluss

https | (forcing) onion
Share: Twitter | Facebook | Google+
This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! See Conditions for Contributions to Whonix, then Edit! IP addresses are scrubbed, but editing over Tor is recommended. Edits are held for moderation. Whonix (g+) is a licensee of the Open Invention Network. Unless otherwise noted above, the content of this page is copyrighted and licensed under the same Free (as in speech) license as Whonix itself.