Jump to: navigation, search

Tor Browser/Advanced Users

Tor Browser Adversary Model[edit]

The Tor Browser design has carefully considered the goals, capabilities and types of attacks undertaken by adversaries and planned accordingly.

The design specifications address: proxy obedience, state separation, disk avoidance, application data isolation, cross-origin identifier unlinkability, cross-origin fingerprinting unlinkability, long-term unlinkability via the "New Identity" button, and other security measures to address many of the risks outlined below. [1] [2]

Adversary Goals[edit]

Goals of the adversary include: [3] [4]

  • Bypassing proxy settings: Directly compromising and bypassing Tor, or having the user connect to specific IP addresses.
  • Correlating Tor and non-Tor activity: If a proxy bypass is not possible, correlation of Tor and non-Tor activity is sought via cookies, cache identifiers, JavaScript events and Cascading Style Sheets (CSS).
  • History disclosure: Querying user history for censored search queries or websites.
  • Correlating activity across multiple sites: Learning if the user who visited site A is the same user who visited site B, in order to serve targeted advertisements.
  • 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.
  • 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.
  • 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.

Adversary Positioning Capabilities[edit]

Adversary positioning capabilities include: [5] [6]

  • Exit node or upstream router: Running exit nodes or controlling routers upstream of exit nodes. [7]
  • 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. [8]
  • Local Network / ISP / upstream router: Injecting malicious content at the user's 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[edit]


Inserting JavaScript

  • Extracting fingerprinting information: Available fonts, DOM objects to ascertain the user agent, WebGL to reveal the video card in use, and high precision timing information to reveal the CPU and interpreter speed.
  • Executing history disclosure attacks: Query the history of different attributes of visited links for specific queries, sites, or for profiling of users (gender, interests etc.).
  • Querying: The user's timezone via the date object and reducing the anonymity set by querying the navigator object for operating system, CPU, location and user agent information.


Inserting or Exploiting Plugins

  • Using plugins: Perform network activity that is independent of browser (or its own) proxy settings in order to obtain a user's non-Tor IP address.
  • Using active plugin exploits: Leak the non-Tor IP address.
  • Enumerating: The list of plugins to fingerprint the user.
  • Gathering information: Use plugins capable of extracting font lists, interface addresses and other machine information.
  • Retrieving: Unique plugin identifiers.


Inserting CSS

  • Using CSS pop-ups: Correlate Tor and non-Tor activity and reveal a user's non-Tor IP address.
  • Using CSS and JavaScript: Perform CSS-only history disclosure attacks.
  • CSS media queries: Gather information about desktop size, widget size, display type, DPI, user agent type and other information.


Reading and Inserting Identifiers

  • Storing identifiers: HTTP auth, DOM storage, cached scripts, other elements with embedded identifiers, client certificates and TLS session IDs.
  • Performing a man-in-the-middle (MITM) attack: Inject elements to both read and inject cookies for arbitrary domains (affecting even SSL/TLS secured websites).


Other Attacks

  • Creating arbitrary cached content: Reading the browser cache which stores unique identifiers.
  • Observing request behavior: Fingerprinting is aided by observing the user agent, Accept-* headers, pipeline usage, and request ordering. Fingerprinting is worsened by custom filters like AdBlock and UBlock Origin.
  • Fingerprinting: Using the large number of browser attributes to reduce the anonymity set, or even uniquely fingerprinting individual users. [11]
  • Website traffic fingerprinting: Attempting to recognize the encrypted traffic patterns of specific websites, either between the user and the Guard node, or at the Guard node itself. [12]
  • Remotely or locally exploiting the browser and/or OS: Exploiting the browser, plugin or OS vulnerabilities to install malware or surveillance software, or physically access the machine to do the same.

Torbutton Design[edit]

Torbutton's functions in Tor Browser behavior are gradually being moved into direct Firefox patches, [13] but it is designed to address: [14] [15]

  • 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.
  • Disk avoidance: Tor Browser should not write any Tor-related state to disk, or store it in memory beyond one Tor toggle.
  • Location neutrality: Tor Browser should not leak location-specific information, like the timezone or locale via Tor.
  • 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.
  • Update safety: Tor Browser should not perform unauthenticated updates or upgrades via Tor.
  • Interoperability: Torbutton should inter-operate with third-party proxy switchers that enable the user to switch between a number of different proxies, with full Tor protection.


Tor Browser patches and the Torbutton extension 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 Torbutton, see:

New Identity Design[edit]

The Tor Browser design document describes the full features provided by this extension: [16] [17]

  • Disables Javascript and plugins on all tabs and windows.
  • 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. [18]

New Tor Circuit Design[edit]

The "New Tor Circuit for this Site" Torbutton feature sends the "newnym" signal to the Tor control port to cause a new circuit to be created for the current Tor Browser tab. [19] 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. [20]

Security Slider Design[edit]

The Tor Project manual describes the exact effect of each level and which features are disabled or partially disabled: [21]

High

At this level, HTML5 video and audio media become click-to-play via NoScript; all JavaScript performance optimizations are disabled; some mathematical equations may not display properly; some font rendering features are disabled; some types of image are disabled; Javascript is disabled by default on all sites; most video and audio formats are disabled; and some fonts and icons may not display correctly.

Medium
At this level, HTML5 video and audio media become click-to-play via NoScript; all JavaScript performance optimizations are disabled; some mathematical equations may not display properly; some font rendering features are disabled; some types of image are disabled; and JavaScript is disabled by default on all non-HTTPS sites.

Low

At this level, all browser features are enabled. This is the most usable option.

Disabled Torbutton Functions[edit]

Open Network Settings[edit]


The regular Tor Browser Bundle from The Tor Project (without Whonix) allows networking settings to changed inside Tor via the Open Network Settings menu option. It has the same effect as editing Tor's torrc config file.

In Whonix, the environment variable export TOR_NO_DISPLAY_NETWORK_SETTINGS=1 has been set to disable the TorButton -> Open Network Settings... menu item. It is not useful and confusing to have in the Whonix-Workstation because: [22] [23]

  • 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 /etc/tor/torrc on the Whonix-Gateway, and not from the Whonix-Workstation (see VPN/Tunnel support for more information).

Tor Circuit View[edit]


Normally, this option in Torbutton 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 "Internet" node reflects the Tor exit relay. [24]

Figure: Tor Circuit View - Disabled in Whonix

Tor Circuit View.png

Sandboxed Tor Browser[edit]

Introduction[edit]


#Tor Browser Hardened
The "hardened" Tor Browser has been deprecated and major features like Selfrando memory randomization are now part of the alpha series and planned for eventual mainline adoption. Consequently, The Tor Project recommends users seeking a higher security solution should default to the sandboxed Tor Browser: [25] [26]

While the Sandboxed Tor Browser is currently in an experimental state itself, we feel that it provides much better safeguards against exploitation than the features we shipped in the hardened series.

A sandbox is a secure environment for running Tor Browser which mitigates exploit vectors which would otherwise deanonymize the user or infect their computer. For instance, sandboxing reduces the opportunities for an attacker to easily identify real IP and MAC addresses, install malware, or browse user files.[27] In simple terms, Tor Browser runs in a limited awareness container that is prevented from interacting with the rest of the user's computer. The spate of recent attacks on 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 stable or alpha Tor Browser series, but it is incompatible with grsec kernels. [28]

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:[29]

  • Foreign language support.
  • The meek pluggable transport.
  • 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.
  • Compatibility of 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]

Tor Browser Sandbox Dependencies[edit]

Several dependencies are required in order to install and run the sandbox:

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


1. Boot Whonix-Workstation

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. 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 since v0.0.3 of the sandbox.

4. 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 Tor Browser Sandbox[edit]

1. Download the Sandbox Binary and Key File


In the Whonix-Workstation, open a terminal and run.

curl --remote-name http://rqef5a5mebgq46y5.onion/torbrowser/7.0a4/sandbox-0.0.6-linux64.zip

Download the signature file.

curl --remote-name http://rqef5a5mebgq46y5.onion/torbrowser/7.0a4/sandbox-0.0.6-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.6-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 a bad signature warning is received, delete the files, rotate the Tor circuits, and download them again.

3. Unzip the Sandbox

In the terminal, run.

unzip sandbox-0.0.6-linux64.zip

Launch Sandboxed Tor Browser[edit]

To start the sandbox, open a terminal and run.

cd sandbox

./sandboxed-tor-browser

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

env

The output should show.

TOR_CONTROL_PORT=9151

Is set as an environment variable.

Important notes:

  • sandboxed-tor-browser is also a Tor Browser downloader similar to tb-updater / 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 v0.0.2 of the sandbox.
  • 64-bit only support since sandbox v0.0.3 means it is only compatible with Whonix 14 (the next Whonix release).

Sandboxing Tor Browser in Qubes-Whonix[edit]


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

Tor Browser without Tor[edit]

TODO: Finalize user instructions for Tor Browser without Tor.

Custom Homepage[edit]

It is unclear whether setting a custom homepage in Tor Browser settings will currently work. Previous user 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. [31]

Technical Background

The whonix-welcome-page package currently sets the environment variable 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 [32] associated with the package.

User-set Custom Homepage Solutions

Three possible options are available (untested):

  • Attempting to purge the whonix-welcome-page package. [33] 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. [34] 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.

Custom Configurations[edit]


Verify New Identity[edit]


If user attempts to create a New Identity fail, then a Torbutton notification to this effect should appear once the extension 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 Test Tor Network Settings on the about:tor page. This will link to https://check.torproject.org automatically, but users can also manually visit the page if preferred. In most, but not all cases [35] the user should get a new Tor exit relay, with a different IP address being reported.

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

Whonix 13:

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

If the output is something like this. TODO: update log output

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 the Control Port Filter Proxy received the request from Tor Browser and got Tor confirmation that it worked.

Whonix: It's either the next over next.

Whonix 14 early builds:

sudo journalctl -f -u control-port-filter-proxy

Whonix 14 later builds:

sudo journalctl -f -u onion-grater

Get a New Identity without Tor ControlPort Access[edit]


Simulate TorButton's functionality via these steps.

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

Proxy Settings[edit]

Remove Proxy Settings[edit]

To remove Tor Browser proxy settings (set no proxy), apply the following instructions.

Introduction

This configuration causes Tor Browser to no longer use proxy settings. With no proxy, Tor Browser uses the (VM) system's default networking. This is identical to any other application inside the Whonix-Workstation that has not been explicitly configured to use Tor via socks proxy settings or a socksifier. This setting is also called transparent torification. [36]

Note: This action will break both the Stream Isolation for Tor Browser and Tor Browser's tab isolation by socks user name. This worsens the web fingerprint and causes the user to be pseudonymous, rather than anonymous. To mitigate these risks, consider using More than one Tor Browser in Whonix, or better yet, Multiple Whonix-Workstations.

If these settings are changed, expect Tor Button to show a red sign and state "Tor Disabled" if a mouse is hovered over it.

To enable transparent torification (no proxy setting), set the TOR_TRANSPROXY=1 environment variable. There are several methods, but the #/etc/environment Method is the simplest one.

For other methods with finer granulated settings, please press on Expand on the right.

<span id="
od"></span> Command Line Method

Navigate to the Tor Browser folder.

cd ~/tor-browser_en-US

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

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

start-tor-browser Method

This only applies to a single instance of the Tor Browser folder that is configured. This method may not persist when Tor Browser is updated.

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

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

Set.

export TOR_TRANSPROXY=1

/etc/environment Method

This will apply to the whole environment, including any possible custom locations of Tor Browser installation folders. [37]

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 line.

TOR_TRANSPROXY=1

Save and reboot.

Undo

Reverting this change is undocumented. Simply unsetting that environment variable will not work due to Tor Browser limitations. The easiest way to undo this setting is to install a fresh instance of Tor Browser (please contribute to these instructions)!

Ignore Tor Button's Open Network Settings

Whonix has disabled the Open Network Settings... menu option in Tor Button. Read the footnote for further information. [38]

Change Proxy Settings[edit]


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

Note: This action will break both the Stream Isolation for Tor Browser and Tor Browser's tab isolation by socks user name. This worsens the web fingerprint and causes the user to be pseudonymous, rather than anonymous. To mitigate these risks, consider using More than one Tor Browser in Whonix, or better yet, Multiple Whonix-Workstations.

Complete the following steps inside Whonix-Workstation.

1. Install the FoxyProxy add-on in Tor Browser.

2. Change Tor Browser Settings.

  • Double-click the Default proxy in FoxyProxy and set up 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]


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.

In Whonix, there are no embedded devices attached to an internal network; it is isolated and untrusted. However, malicious Javascript can reveal to an attacker that a service is running on a localhost port. Consequently, this can reduce the user's anonymity set. Further, daemons listening on the localhost can be maliciously misconfigured, but this has limited impact because traffic is still forced through Whonix-Gateway.

For further reading on this topic, see this related Whonix Forum topic and Tor Browser bug report.

The configured exception means a small trade-off in privacy, but it is much safer than using another browser. [40]

tor-launcher vs torbrowser-launcher[edit]

tor-launcher and torbrowser-launcher are two completely different things with similar names:

tor-launcher[edit]

Users should not be concerned that tor-launcher might result in a Tor over Tor scenario, as this is prevented by Whonix proxy settings. By default, tor-launcher is disabled in Whonix-Workstation.

In theory, a user could 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 user has the same tested and functional setup as everyone else.

tor-launcher is not yet available for use in Whonix-Gateway. [41]

torbrowser-launcher[edit]

Tor Browser Updater (Whonix) (tb-updater) 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 if that is of interest.

Platform-specific Issues[edit]

Qubes-Whonix[edit]

Running Tor Browser in Qubes TemplateVM[edit]


To understand why, please press on Expand on the right.

  • Users are expected to use Tor Browser in its stock configuration with as few modifications as possible. This is in accordance with upstream recommendations by The Tor Project.
  • Users risk connecting to the Internet with the browser [42] and thereby compromising the TemplateVM and all TemplateBasedVMs based on that TemplateVM.
  • Starting Tor Browser creates various files. Any of these files might make the user pseudonymous rather than anonymous, even if they are designed against this. The user does not want all TemplateBasedVMs based on that TemplateVM to be linked to the same pseudonym.
  • It is far safer to start Tor Browser for the first time in the TemplateBasedVM, rather than TemplateVM. The user cannot expect Tor Browser to be perfect and for no bugs to be revealed later on. The current and past Tor Browser issues support this assertion, see here and here.

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 the reader is interested in the reasons why, see here and here.

Beginning with Whonix 13, Qubes-Whonix-Workstation builds by default automatically run the 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, meaning the package itself will fail to install. As a consequence, this could lead to an error while building Whonix images from source code or when installing Whonix from the repository. This is undesirable behavior, but it has been decided to still install Tor Browser by default in Qubes-Whonix-Workstation. The only way to ensure Tor Browser is really installed by default is to also fail closed when necessary.

Beginning with Whonix 13, 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 event, the user will be informed in the terminal that no new Tor Browser could be downloaded, but apt-get will terminate normally. This is necessary to implement the Qubes-Whonix feature ensuring up-to-date versions of Tor Browser in newly created AppVMs are inherited from updated TemplateVMs.

If a failure is experienced, the user can still update Tor Browser using Tor Browser Internal Updater or by manually downloading Tor Browser. This is a small inconvenience and not a matter of major concern.

Actions of the tp-updater package can be optionally configured by the user.

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 in the Qubes-Whonix-Workstation TemplateVM, by default a hard-coded [43] version Tor Browser tarball and signature is automatically downloaded. In order to disable this, add.

tb_install_follow=false

Save.

Technical Details

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/.

find /var/cache/tb-binary/.cache/tb/
/var/cache/tb-binary/.cache/
/var/cache/tb-binary/.cache/tb
/var/cache/tb-binary/.cache/tb/files
/var/cache/tb-binary/.cache/tb/files/sha256sums.txt.asc
/var/cache/tb-binary/.cache/tb/files/tor-browser-linux64-5.5.4_en-US.tar.xz
/var/cache/tb-binary/.cache/tb/files/sha256sums.txt
/var/cache/tb-binary/.cache/tb/temp
/var/cache/tb-binary/.cache/tb/temp/tar_fifo
/var/cache/tb-binary/.cache/tb/temp/tor_check_bootstrap_helper_bootstrap_file
/var/cache/tb-binary/.cache/tb/temp/sha256_output
/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/gpgtmpdir
/var/cache/tb-binary/.cache/tb/gpgtmpdir/secring.gpg
/var/cache/tb-binary/.cache/tb/gpgtmpdir/pubring.gpg~
/var/cache/tb-binary/.cache/tb/gpgtmpdir/pubring.gpg
/var/cache/tb-binary/.cache/tb/gpgtmpdir/gpg_bash_lib_internal_gpg_verify_status_fd_file
/var/cache/tb-binary/.cache/tb/gpgtmpdir/trustdb.gpg
/var/cache/tb-binary/.cache/tb/gpgtmpdir/gpg_bash_lib_internal_gpg_verify_output_file

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

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

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 [44] runs /usr/lib/tb-updater/first-boot-home-population. [45] That script copies /var/cache/tb-binary to /home/user.

The result is.

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

Creating Whonix Using the Build Script

If users build Qubes-Whonix with the build script and want to fail open in general, then before building in chroot, a file /etc/torbrowser.d/50_user.conf must be created with the following content.

anon_shared_inst_tb=open

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

tb_install_in_chroot=false

Split Tor Browser for Qubes[edit]

TODO: Try, review and document Qubes' Split Tor Browser.

Whonix-Custom-Linux-Workstation[edit]


These instructions have been tested with Tor Browser v6.0.1. Connectivity might break in later Tor Browser versions, particularly if Tor Browser developers modify how networking in Tor Browser is configured. [46]

1. Manually Download and Install Tor Browser

2. 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

Add.

## 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
TOR_SKIP_LAUNCH=1

## 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.
TOR_NO_DISPLAY_NETWORK_SETTINGS=1

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

Save and reboot.

From this point, only the browser component of Tor Browser will be started.

3. Verify Environment Variables

env

The output should show.

TOR_NO_DISPLAY_NETWORK_SETTINGS=1
TOR_SKIP_CONTROLPORTTEST=1
TOR_SKIP_LAUNCH=1

4. Configure Network Settings [47]

Now the file ~/.tb/tor-browser/Browser/TorBrowser/Data/Browser/profile.default/user.js must be created. This presupposes Tor Browser has been installed as per step 1 and that a folder ~/.tb/tor-browser exists. If Tor Browser was installed to another folder, the the path must been adjusted.

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

Add.

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

Save.

The process is now complete.

Windows[edit]


These steps are required to use Tor Browser when operating a Custom-Whonix-Workstation, specifically a Windows-Whonix-Workstation.

1. Install Tor Browser


2. Use Tor Browser without Bundled Tor

Create a new text file in the folder where Tor Browser was extracted. For example, the file could have the following name.

Start TB without Tor.bat

Add the following content to that file. [48]

SET TOR_SKIP_LAUNCH=1

"Start Tor Browser.lnk"

Save.

3. Configure Network Settings

Start Tor Browser.

The following links for removing and changing proxy settings do not apply one-to-one for Windows! Removal of proxy settings is best avoided, while changing proxy settings is a better choice.

How this is accomplished on Windows is currently undocumented, but user contributions to finish these instructions are most welcome.

  • Type: SOCKSv5.
  • IP address:
    • Qubes-Whonix
      • If Qubes Tools in the custom workstation are:
        • Installed: Find out the IP address of Qubes-Whonix-Gateway by running qubesdb-read /qubes-gateway inside the custom workstation.
        • Not installed: 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. [49] This means after restarting sys-whonix, the connection might break and the IP address setting may need to be manually updated.
    • Non-Qubes-Whonix: 10.152.152.10
  • Port: 9100.
  • Do not change the No Proxies for setting.


4. Figure Out Missing Instructions

Missing instructions need to be ported from Linux-specific to Windows-specific, see Whonix-Custom-Linux-Workstation.

The process is now complete.

Debugging[edit]

Open a terminal.

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

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

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

Start Menu -> Applications -> System -> Konsole

Navigate to the Tor Browser folder.

cd ~/.tb/tor-browser/Browser

Start Tor Browser from the command line in debug mode.

./start-tor-browser --debug

Type into the address bar.

about:config

Search for the settings below and set their values to match.

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

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

Close Tor Browser.

Restart Tor Browser.

./start-tor-browser --debug

[50]

Footnotes / References[edit]

  1. https://www.torproject.org/projects/torbrowser/design/#Implementation
  2. This has also informed the development of the Torbutton extension.
  3. https://www.torproject.org/docs/torbutton/en/design/index.html.en#adversary
  4. https://www.torproject.org/projects/torbrowser/design/#adversary
  5. https://www.torproject.org/docs/torbutton/en/design/index.html.en#adversary
  6. https://www.torproject.org/projects/torbrowser/design/#adversary
  7. This has already been observed.
  8. Partially explaining the unholy alliance between the corporate sector and government.
  9. https://www.torproject.org/docs/torbutton/en/design/index.html.en#adversary
  10. https://www.torproject.org/projects/torbrowser/design/#adversary
  11. For instance, there is an estimated 29 bit-identifier based on the browser and desktop window resolution information alone.
  12. 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.
  13. https://www.torproject.org/projects/torbrowser/design/#components
  14. https://www.torproject.org/docs/torbutton/en/design/index.html.en#requirements
  15. Some of the design features have been deprecated due to changes in the Tor / Tor Browser design.
  16. https://trac.torproject.org/projects/tor/ticket/523
  17. https://www.torproject.org/projects/torbrowser/design/#new-identity
  18. https://www.torproject.org/projects/torbrowser/design/#new-identity
  19. https://trac.torproject.org/projects/tor/ticket/9442
  20. https://tb-manual.torproject.org/en-US/managing-identities.html
  21. https://tb-manual.torproject.org/en-US/security-slider.html
  22. https://trac.torproject.org/projects/tor/ticket/19652
  23. https://trac.torproject.org/projects/tor/ticket/14100
  24. https://tails.boum.org/doc/anonymous_internet/Tor_Browser/index.en.html
  25. https://blog.torproject.org/blog/discontinuing-hardened-tor-browser-series
  26. Special debug builds will now be used instead of shipping ASan in regular builds. This is beneficial because ASan has a debugging, rather than a security focus, and is extremely resource intensive.
  27. https://blog.torproject.org/blog/q-and-yawning-angel
  28. https://blog.torproject.org/blog/tor-browser-65a6-hardened-released
  29. https://trac.torproject.org/projects/tor/wiki/doc/TorBrowser/Sandbox/Linux
  30. https://forums.whonix.org/t/tor-browser-sandbox-linux-alpha-coming-soon/3060
  31. This is a potential bug since the user-set custom homepage does not overrule the TOR_DEFAULT_HOMEPAGE environment variable. No bug has yet been reported.
  32. Also /usr/lib/whonix-welcome-page/env_var.sh
  33. sudo apt-get purge whonix-welcome-page
  34. kdesudo kate /usr/lib/whonix-welcome-page/env_var.sh
  35. Getting a new circuit doesn't guarantee getting a new exit relay (this is normal). Also see Stream_Isolation.
  36. This term was coined in context of a Tor Transparent Proxy. It acts as a simple gateway that routes all connections through Tor, but does not provide Stream Isolation.
  37. Unless this environment variable is manually unset before starting Tor Browser.
  38. The regular Tor Browser Bundle from The Tor Project (without Whonix) allows networking settings to changed inside Tor via the Open Network Settings menu option. It has the same effect as editing Tor's config file torrc. In Whonix, the environment variable export TOR_NO_DISPLAY_NETWORK_SETTINGS=1 has been set to disable the TorButton -> 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 /etc/tor/torrc on the Whonix-Gateway, and not from the Whonix-Workstation (see VPN/Tunnel support for more information).
  39. Circuit isolation by SOCKS proxy may be breaking other proxies or non-proxies
  40. https://trac.torproject.org/projects/tor/ticket/10419#comment:37
  41. https://phabricator.whonix.org/T118
  42. Open issue: https://phabricator.whonix.org/T372
  43. In the tb-updater package.
  44. https://github.com/Whonix/tb-updater/blob/master/lib/systemd/system/tb-updater-first-boot.service
  45. https://github.com/Whonix/tb-updater/blob/master/usr/lib/tb-updater/first-boot-home-population
  46. Once Tor Browser moves to SocksSocket, these instructions will certainly no longer work. References:
  47. Learn more about the network settings.
    • Type: SOCKSv5.
    • IP address:
      • Qubes-Whonix
        • If Qubes Tools in the custom workstation are:
          • Installed: Find out the IP address of Qubes-Whonix-Gateway by running qubesdb-read /qubes-gateway inside the custom workstation.
          • Not installed: 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 the IP address setting may need to be manually updated.
      • Non-Qubes-Whonix: 10.152.152.10
    • Port: 9100.
    • Do not change the No Proxies for setting.
    ## 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
    TOR_SOCKS_HOST="10.152.152.10"
    TOR_SOCKS_PORT="9150"
    
  48. It is necessary 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.
  49. Qubes feature request: Optional static IP addresses.
  50. https://www.torproject.org/docs/torbutton/en/design/

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

License[edit]

Whonix Tor Browser wiki page Copyright (C) Amnesia <amnesia at boum dot org>
Whonix Tor Browser wiki page Copyright (C) 2012 - 2017 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:

Did you know that anyone can edit the Whonix wiki to improve it?


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, the content of this page is copyrighted and licensed under the same Libre Software license as Whonix itself. (Why?)