Tor Browser Basics
- 1 Introduction
- 2 Anonymity vs Pseudonymity
- 3 Encryption
- 4 Tor Browser Add-Ons
- 5 Torbutton
- 6 Tor Browser: How-To
- 6.1 Start Tor Browser
- 6.2 File Downloads
- 6.3 Browser Language
- 6.4 Local Connections
- 6.5 Bypass Tor Censorship
- 6.6 Harden Tor Browser
- 7 Update Tor Browser
- 7.1 Introduction
- 7.2 Tor Browser Downloader by Whonix
- 7.3 Tor Browser Internal Updater
- 7.4 Tor Browser Manual Update
- 8 Unsafe Tor Browser Habits
- 9 Whonix Tor Browser Differences
- 10 Glossary and Key Terminology
- 11 Advanced Users
- 12 Footnotes / References
- 13 License
Warning: Only Tor Browser is recommended for use in Whonix when browsing the Internet. 
Tor Browser  is a fork of the Mozilla Firefox ESR web browser. It is developed by The Tor Project and optimized and designed for Tor, anonymity and security. Many users will have browsed with Firefox and be familiar with the user interface that resembles those found in other popular, modern browsers. 
Before using Tor Browser users are strongly encouraged to read this entire wiki entry so it is used effectively and safely on the Whonix platform. Advanced users may also be interested in the Tor Browser Adversary Model. Regularly consult the Tor Project blog to stay in tune with Tor / Tor Browser news and the latest release information.
Anonymity vs Pseudonymity
Warning: Using regular browsers is pseudonymous rather than anonymous.
If browsers other than Tor Browser are used in Whonix, the IP address and Domain Name Service (DNS) requests  are still protected. However, only Tor Browser provides protocol level cleanup, which includes unique features like proxy obedience, state separation, network isolation, and anonymity set preservation.
In stark contrast to regular browsers, Tor Browser is optimized for anonymity and has a plethora of privacy-enhancing patches and add-ons.  By sharing the Fingerprint with around two million other people, Tor Browser users "blend in" with the larger population and better protect their privacy.
It is important to understand the difference between HTTP and HTTPS: 
HTTPS (also called HTTP over Transport Layer Security (TLS), HTTP over SSL, and HTTP Secure) is a communications protocol for secure communication over a computer network which is widely used on the Internet. HTTPS consists of communication over Hypertext Transfer Protocol (HTTP) within a connection encrypted by Transport Layer Security, or its predecessor, Secure Sockets Layer. The main motivation for HTTPS is authentication of the visited website and protection of the privacy and integrity of the exchanged data.
HTTPS advantages include: 
- Authentication of the website and web server the user is communicating with.
- Protection against man-in-the-middle attacks.
- Bidirectional encryption of communications between a client and server. This protects against eavesdropping and tampering with / forging of communication contents.
- A reasonable expectation that the website being communicated with is genuine. 
In the context of Tor Browser, this means HTTPS should be preferred over HTTP so communication is encrypted while browsing the Internet. While traffic is encrypted throughout the Tor network, the exit relay (third of three servers) can see traffic sent into Tor if it is plain HTTP. If HTTPS is used, the exit relay will only know the destination address. 
As an example, the screenshot below is how the browser looks when visiting the Whonix website. 
Figure: A Secure Connection to www.whonix.org
Take notice of the small area on the left-hand side of the address bar. Indicators of an encrypted connection are
www.whonix.org is highlighted with a padlock and "Secure Connection" in green writing, and the URL begins with https:// instead of http://.
Try to only use services providing HTTPS when sensitive information is sent or received. Otherwise, passwords, financial / personal information or other sensitive data can be easily stolen or intercepted by eavesdroppers. HTTP webpage contents can also be modified on its way to the browser for malicious purposes.
HTTP / HTTPS Connections with and without Tor
The following figures from EFF provide an overview of HTTP / HTTPS connections with and without Tor, and what information is visible to various third parties. The descriptors are as follows: 
Potentially visible data includes: the site you are visiting (SITE.COM), your username and password (USER/PW), the data you are transmitting (DATA), your IP address (LOCATION), and whether or not you are using Tor (TOR).
Figure: Tor and HTTPS
Figure: Tor and No HTTPS
Figure: No Tor and HTTPS
Figure: No Tor and No HTTPS
Onion Services Encryption
Whenever possible, users are encouraged to stay within the Tor network for communications and web browsing via available .onion addresses. These services are commonly referred to as onion services (formerly "hidden services"), even when their location is publicly known. 
Onion Services Advantages
URLs ending in the .onion extension provide a superior level of security and privacy, since the connection forms a tunnel which is encrypted (end-to-end) using a random rendezvous point within the Tor network; HTTPS is not required. These connections also incorporate perfect forward secrecy (PFS). PFS means the compromise of long-term keys does not compromise past session keys. As a consequence, past encrypted communications and sessions cannot be retrieved and decrypted if long-term secrets keys or passwords are compromised in the future by adversaries. 
Other primary benefits of onion services include: 
- Prevention of passive surveillance by both network observers and the Tor exit node which is possible when using plain Tor + HTTPS. Adversaries cannot (easily) determine which destination the users are connecting from/to.
- Onion services establish "rendezvous points" in the Tor network for web services whereby neither the hosting service or the user know each other's network identity.
- Onion services can be combined with SSL/TLS to provide additional protection. Only a handful of services currently provide this service, including DuckDuckGo: https://3g2upl4pq6kufc4m.onion and ProtonMail: https://protonirockerxow.onion.  
- Onion services do not use the insecure DNS system. Strong authentication comes from the self-authenticating address: the address itself forms a cryptographic proof of the .onion's identity.  
To learn more about how onion services work, refer to the technical description.
Tor Browser Add-Ons
HTTPS Everywhere is a Firefox extension shipped in Tor Browser and produced as a collaboration between The Tor Project and the Electronic Frontier Foundation. It helps to encrypt user communications with a number of major sites.
Many sites on the Internet offer some limited support for encryption over HTTPS, but make it difficult to use. For instance, sites may default to unencrypted HTTP or fill encrypted pages with links that return to the unencrypted version of site. The HTTPS Everywhere extension addresses these problems by rewriting all site requests to HTTPS.
To learn more about HTTPS Everywhere, visit:
NoScript is a free, open source extension that comes bundled with Tor Browser and other Mozilla-based web browsers. NoScript can provide significant protection for users, depending on its configuration: 
NoScript protects against cross-site scripting, which otherwise enables attackers to inject malicious client-side scripts into web pages being viewed, bypassing the same-origin policy. The same-origin policy refers to web browsers usually only allowing scripts in the first web page to access data in a second web page if they have the same origin (URL scheme, hostname and port number). 
Security vs Usability Trade-off
The Torbutton extension's Security Slider (see further below) also involves a security versus usability trade-off. Higher slider levels improve security and reduce usability, while the opposite is true of other settings. Fingerprinting risks are greatly reduced at higher slider levels, but some site functionality may also be lost.
NoScript Custom Setting Persistence
The Tor Project has introduced a new preference in Tor Browser version 8.5a2 allowing you to save your custom NoScript settings between browser restarts. This setting is turned off by default meaning custom NoScript settings will not persist across successive Tor Browser sessions. In order to use this new preference you must have Tor Browser alpha version 8.5a2 or later installed. You can install the alpha version of Tor Browser using "Tor Browser Downloader" inside Whonix-Workstation.
To save NoScript settings across browser sessions:
In Tor Browser address bar:
"Type" about:config ->
"Press" enter ->
"Choose" I accept the risk! ->
"Type" extensions.torbutton.noscript_persist ->
"Toggle" to True
Note: Defining custom settings in NoScript will override the current Tor Browser Security Slider setting. When
extensions.torbutton.noscript_persist is set to "True", these changes will persist across Tor Browser restarts. However, if the user changes the security slider setting, all custom per-site settings are lost, even with the persistent NoSript preference enabled. Alternatively when
extensions.torbutton.noscript_persist is set to "False", NoScript settings will be reset after Tor Browser syncs with the position of the Tor Browser Security Slider.
Warning: This preference sacrifices privacy for convenience and is therefore not recommended. While scripts do not need to be enabled or disabled constantly on sites that are frequently visited across Tor Browser restarts, a number of anonymity risks are introduced outlined below: 
1. Disk hygiene: Tor Browser is designed to prevent persistent storage of history records and other on-disk information. This setting violates that design principle by allowing the storage of NoScript Per-site Permissions and increases the chance of an adversary extracting valuable information from that data.
2. Long-term fingerprinting vectors: Persistent per-site settings allows websites to profile Tor Browser users, particularly if first-party isolation is not enforced. For example, consider the negative anonymity impact of whitelisting Google or Facebook, as their advertisements and widgets are ubiquitous.
3. Expert opinion: Experienced Tor developers have stated that enabling this preference is dangerous and caution is required. 
As Tor Browser is based on Firefox, any browser add-on that is compatible with Firefox can also be installed in Tor Browser. In this context, add-ons are the collective name given to extensions, themes and plugins: 
- Extensions add new features to Firefox or modify existing ones, like video downloaders, ad blockers and so on.
- Themes change the appearance of the browser, such as buttons, menus and the background image.
- Plugins add support for Internet content and often include patented formats like Flash and Silverlight which are used for video, audio, online games and more.
Non-default Add-on Risks
The Tor Project explicitly warns against using non-default add-ons with Tor Browser: 
However, the only add-ons that have been tested for use with Tor Browser are those included by default. Installing any other browser add-ons may break functionality in Tor Browser or cause more serious problems that affect your privacy and security. It is strongly discouraged to install additional add-ons, and the Tor Project will not offer support for these configurations.
Video websites, such as Vimeo make use of the Flash Player plugin to display video content. Unfortunately, this software operates independently of Tor Browser and cannot easily be made to obey Tor Browser’s proxy settings. It can therefore reveal your real location and IP address to the website operators, or to an outside observer. For this reason, Flash is disabled by default in Tor Browser, and enabling it is not recommended.
The problem with non-default add-ons is that they are often comprised of non-free software, which can lead to the linkage of activities conducted under one pseudonym. They also worsen fingerprinting and open up attack vectors in the form of remote exploits.
This advice holds true even though Whonix is configured to prevent these applications (along with malware) from leaking the real external IP address, even if they are mis-configured (see Features). Before installing non-default add-ons, first consider the various alternatives such as HTML5 or online media converters. 
Torbutton is the component in Tor Browser that takes care of application-level security and privacy concerns in Firefox. To keep you safe, Torbutton disables many types of active content.
It is recommended that users learn more about Fingerprinting and Data Collection Techniques to better understand the potential threats. Advanced users can also review detailed information about the Torbutton design and its various functions here.
New Identity Function
The "New Identity" menu option sends the protocol command "signal newnym" to Tor's ControlPort. This clears the browser state, closes tabs, and obtains a fresh Tor circuit for future requests. 
Warning: The New Identity feature will likely create a new Tor exit relay and a new IP address, but this is not guaranteed.
Sometimes Tor only replaces the middle relay while using the same Tor exit relay; this is by design and the Tor default. Further, "signal newnym" does not interfere with long-lived connections such as an IRC connection.
New Identity is not yet perfect and there are open bugs; this is not a Whonix-specific issue.  For greater security, it is better to completely close Tor Browser and restart it. In Qubes-Whonix, the safest option when performing sensitive activities is using a Whonix-Workstation DisposableVM. When the activities are complete, the DispVM is shutdown and a new one is created for use with further activities
There are two ways to use the Torbutton New Identity feature.
Left-click the Hamburger Icon->
Select "New Identity"
New Tor Circuit Function
The "New Tor Circuit for this Site" Torbutton feature causes a new circuit to be created for the current Tor Browser tab, including other open tabs or windows from the same website. 
Warning: This feature does not attempt to clear Tor browsing session data or unlink activity, unlike the "New Identity" feature.
If it is really necessary to separate contextual identities, it is always safer to close and then restart Tor Browser.
Potential use cases for this feature include: 
- The Tor exit relay is located in a country which negatively affects the presentation of the website due to language localization.
- The site is censored due to the current Tor exit relay in use (caused by Tor IP address blacklisting).
- To bypass Google CAPTCHA or reCAPTHA systems protecting sites from abuse if these are showing unsolvable captcha or no captcha at all.
- Connections to websites become unresponsive or slow.
- To change the Tor exit relay IP address without losing all open tabs.
To use it:
Left-click the Hamburger Icon ->
Select "New Tor Circuit for this Site"
Advanced users who want to learn more about this function should refer to the New Tor Circuit Design entry.
Tor Browser includes a “Security Slider” that lets the user disable certain web features that can be used to compromise security and anonymity. Currently there are three levels: "Safest", "Safer" and "Standard". Users have to make a trade-off between security, usability and privacy. At the higher levels the slider will prevent some sites from working properly. 
To use this feature:
Click Torbutton ->
Click "Security Settings..." ->
Select desired security level
To learn more about the exact effect of each setting level, refer to the Security Slider design entry.
Check for Tor Browser Update
Torbutton will notify if a Tor Browser update is available; see Tor Browser Internal Updater for further information and screenshots of this process. Note that multiple methods exist for updating Tor Browser.
To use the Torbutton menu option:
Click Torbutton ->
Click "Check for Tor Browser Update..."
Readers who are interested in why Torbutton's "Open Networking Settings" and "Tor Circuit View" features have been disabled in Whonix can learn more here.
Tor Browser: How-To
Start Tor Browser
From the Menu
Start Tor Browser.
From the Command Line
To start Tor Browser from the command line, please press Expand on the right.
Open a terminal.
The user has two options. To start Tor Browser "normally" from the terminal. 
In Debugging Mode
To generate debugging output if problems are experienced with Tor Browser (also see Debugging), to start Tor Browser from the command line in debugging mode, please press Expand on the right.
Open a terminal.
Successful Tor Browser Connection
If Tor Browser successfully launches and connects to the Tor network, Check Torproject should show the following message.
Figure: Successful Tor Browser Connection
Whonix protects against these threats outlined below, such as files that inadvertently or maliciously attempt to reveal the real IP address of the user, or third-party, external applications that can leak information outside of Tor. However, users should always engage in best safety practices.
Do not Open Documents Downloaded via Tor while Online
The Tor Project explicitly warns users not to open documents handled by external applications, since in the normal case they may contain Internet resources that may be downloaded outside of Tor by the application that opens them. 
This warning is not strictly relevant to Whonix users since all traffic is forced over the Whonix-Gateway and the IP address will not be leaked. Despite this fact, for greater safety users should open files such as PDFs and word processing documents in offline VMs.
Malicious files or links to files pose a greater threat; potential compromise of the user's system. Therefore users should heed the Whonix advice to not open random links or files in the Whonix-Workstation. Instead, in Qubes-Whonix it is preferable to sanitize the PDF or open the file or link in a DisposableVM. Non-Qubes-Whonix users should only open the file in a separate, offline Whonix-Workstation.
Do not Torrent over Tor
See File Sharing.
Preventing SSLStrip Attacks
If clicking or pasting a download link, make sure it is
Users often mistakenly believe that a secure, green padlock and a
https:// URL makes any download from that particular website secure. This is not the case because the website might be redirecting to
http. In fact, an SSLstrip attack might succeed if a link is pasted or typed into the address bar without the
https:// component (e.g.
torproject.org instead of
In this instance, it is impossible to confirm if the file is being downloaded over
https://. Potentially, a SSLstrip attack might have made the download take place over plain
http. The reason is a padlock is not visible; it just appears empty.
To avoid this risk and similar threats, always explicitly type or paste
https:// in the URL / address bar. The SSL certificate button or padlock will not appear in this instance, but that is nothing to be concerned about. Unfortunately, few users follow this sage advice; instead most mistakenly believe pasting or typing www.torproject.org into the address bar is safe.
For even greater safety, download files from onion services (.onion addresses) whenever possible. Improved security is provided by onion service downloads, since the connection is encrypted end-to-end (with PFS), targeting of individuals is difficult, and adversaries cannot easily determine where the user is connecting to or from.
Also, if files are already available in repositories, then prefer mechanisms which simplify and automate software upgrades and installations (like apt-get functions), rather than download Internet resources. Avoid installing unsigned software and be sure to always verify key fingerprints and digital signatures of signed software from the Internet, before importing keys or completing installations. For more on safely installing software, See; Installing Software Best Practices.
Finally, consider using multiple Whonix-Workstations when downloading and installing additional software, to better compartmentalize user activities and minimize the threat of misbehaving applications.
For those who regularly download Internet files, Tor Browser's default download folder is inconvenient. For example, if the sample image below was downloaded with Tor Browser, the download path is /home/user/.tb/tor-browser/Browser/Downloads by default. It is time-consuming to navigate to this folder so far down the directory tree.
Figure: Default Tor Browser Download Folder
To make things simpler, the following steps change Tor Browser preferences so files are saved directly inside /home/user/Downloads
1. Navigate to Tor Browser preferences.
Choose one of the following three methods:
Click the "hamburger" symbol->
Navigate to the Edit menu->
click General tab
about:preferencesin the Tor Browser address bar.
Figure: Tor Browser Preferences
2. Select the
Save files to download option.
Figure: Custom Download Path Option
3. Change the default download folder location.
It is recommended to set /home/user/Downloads as the custom path.
Figure: Set the Custom Download Path
User files will now be downloaded to the /home/user/Downloads folder. Navigate to this folder using either Dolphin or Konsole.
To access files that were stored inside the "wrong" download folder, please press Expand on the right.
1. Start Dolphin.
2. Enable the hidden files view.
To show hidden files:
Navigate to the View menu ->
click Show Hidden Files
Figure: Hidden Files in Dolphin
3. Navigate to the downloaded files.
Double-click the .tb folder
Figure: Hidden Tor Browser Folder
Use the following path:
Figure: Default Tor Browser Download Folder
Now it is possible to review the downloaded files.
Figure: Downloaded Files
In late-2018, the stable and experimental Tor Browser binaries with additional language packs support 25 languages. Recent additions include: Catalan, Irish, Indonesian, Icelandic, Norwegian, Danish, Hebrew, Swedish and Traditional Chinese.   For instructions on changing the Tor Browser interface to a language other than English, see Tor Browser Language. 
Sometimes it is necessary to access the local application interface on
127.0.0.1 in order to run specific applications like I2P.  Due to potential fingerprinting and information leakage risks, this behavior is no longer possible in Tor Browser unless an exception is configured.  
To configure an exception for local connections in Tor Browser: 
General Tab ->
Network Proxy | Settings... ->
No Proxy for: "127.0.0.1" ->
The configured exception means a small trade-off in privacy, but it is much safer than using another browser (see Local Connections Exception Threat Analysis).
Web HTTP(S)/SOCKS proxies have different instructions and will not work with these steps, see Tor Browser Proxy Configuration.
For better anonymity:
- Set passwords for web interfaces listening on the localhost.
- Run sensitive daemons with local WebGUIs on a separate, dedicated Whonix-Workstation and virtual network instance. TODO: expand or link how to do that
Bypass Tor Censorship
This section outlines how to bypass Tor blocks by destination websites. Users who are blocked from connecting to the Tor network at the ISP level instead require bridges or other circumvention tools.
A number of websites or services actively block Tor users via:
- A DNS query-based list used to tag IP addresses.
- Blocking software like Akamai and Cloudflare.
- Other individual blocks.
There are various ad-hoc methods available to try and circumvent blocks. In most cases it is unnecessary to create a tunnel which pairs Whonix with other protocols (such as a VPN) in order to access the content.
The following services fetch content via other websites, which is a privacy trade-off. Further, only some services are effective with embedded, non-static content or support specific file types like PDF, .exe and mp3. 
Table: Tor Censorship Circumvention Options 
|Service||URL||Comment||Non-static Embedded Content||PDF, .exe, mp3|
|The Internet Archive's WaybackMachine||web.archive.org/save/_embed/<URL>||Archive.org respects robots.txt restrictions, works best with JS enabled||No||Yes|
|Archive.fo||archive.fo/?run=1&url=<URL> And their official onion service: archivecaslytosk.onion/?run=1&url=<URL>||Ideal for news sites, doesn't require JS||No||No|
|Google Cache||webcache.googleusercontent.com/search?q=cache:<URL without "http://">||Google sometimes blocks these requests||No - static only||No|
|Startpage.com||(1) Find the URL by searching, (2) Click on the proxy option "
||Not always efficacious||No||No|
|Searx.me||(1) Find the URL by searching, (2) Click on the proxied option||Not always efficacious||No||No|
|Online Proxies||hide.me/en/proxy, www.proxysite.com/, www.proxysite.club/ ||-||Yes||Yes|
The Tor Project also recommends: 
To avoid captchas that are sometimes required when visiting YouTube, use hooktube.com/ (behind Cloudflare).
imgur.com blocks Tor uploads, to upload images on an imgur domain go to a stackexchange website (for example tor.stackexchange.com), click on Ask a Question, use the image upload tooltip to upload the image, the resulting url will have a i.stack.imgur.com/... form.
Harden Tor Browser
Anonymity and safety can be materially improved via: AppArmor, Tor Browser settings, sandboxing, multiple Tor Browser instances, and operation of Whonix-Workstation DisposableVMs (Qubes-Whonix) or multiple Whonix-Workstations.
Tor Browser provides reasonable security in its stock configuration. However, mitigating the risk of Tor Browser security breaches makes sense, because it is an untrusted application with a huge attack surface; it is frequently attacked successfully in the wild by adversaries.
Tor Browser Series and Settings
- Series: For greater security, consider using the alpha Tor Browser release. This incorporates Selfrando load-time memory randomization protection and other security features. Both the stable and alpha Tor Browser series now benefit from Mozilla's content level sandboxing, as well as being multi-process (e10s) compatible.
Multiple Tor Browser Instances and Whonix-Workstations
- Multiple Tor Browser Instances: To better separate different contextual identities, consider starting multiple Tor Browser instances and running them through different SocksPorts. This method is less secure than the method outlined below.
- Multiple Whonix-Workstations: For tasks requiring different identities and/or additional software, it is recommended to compartmentalize activities and use two or more Whonix-Workstation VMs. In this way, an exploit in Tor Browser in one Whonix-Workstation cannot simultaneously read the user's identity in another VM (for example, an IRC account).  This method is less secure than using a Whonix-Workstation DisposableVM with Tor Browser (see below).
Sandboxing and DisposableVMs
- Sandboxing: The Tor Project's official sandboxed Tor Browser is compatible with Whonix 14 and later releases, however it is no longer recommended since The Tor Project has officially abandoned its development.  Firejail can be used as an alternative sandboxing measure to restrict the Tor Browser process.
- Whonix-Workstation DisposableVMs: One of the safest configurations is to assume future compromise and run all instances of Tor Browser in an uncustomized Whonix-Workstation DisposableVM in Qubes-Whonix. This configuration creates fresh Whonix-Workstation and Tor Browser instances for discrete Internet activities, while ensuring that previous, potentially compromised versions of both are destroyed. 
AppArmor can help protect the user's system and data. It confines programs according to a set of rules that specify what files a given program can access, and with what privileges. This also provides some protection against zero-day attacks and exploits via unknown application flaws.
To mitigate the threat of specific attacks against Tor Browser, Whonix's Tor Browser AppArmor profile can be easily applied.
If AppArmor is applied, Tor Browser can only read and write to a limited number of folders. Permission denied errors are quite common, for example when trying to download files directly to the home folder.
The workaround for denied errors is saving files from Tor Browser to the ~/Downloads folder that is located within the home folder. In order to upload files with Tor Browser, first copy them to that folder.
Update the package lists.
sudo apt-get update
Install the apparmor-profile-torbrowser package.
sudo apt-get install apparmor-profile-torbrowser
Update Tor Browser
Unfortunately, updating Tor Browser is more complex than regular system updates due to technical limitations outside of Whonix's control.  However, by applying the following instructions it is possible to keep Tor Browser up to date at all times.
There are three options for updating Tor Browser in Whonix:
- The Whonix Tor Browser Downloader. 
- Tor Browser's Internal Updater. 
- Tor Browser manual updates.
The first two methods are suitable in most situations. Manual updates are only required if the Whonix Tor Browser update script ever breaks. Never continue to use an outdated version of Tor Browser, otherwise serious security flaws may degrade anonymity or result in a VM compromise. 
It is recommended to follow The Tor Project blog to stay informed about recent updates.
Tor Browser Downloader by Whonix
Note: Tor Browser Downloader (Whonix) is really just a downloader, not a updater. This means it is incapable of retaining user data, for example bookmarks and passwords. In order to keep user data, use the Internal Updater method instead.
To use Tor Browser Downloader (Whonix), follow these instructions in Whonix-Workstation:
There are several steps in this process. First, the downloader will show it is checking for updates.
Figure: Checking for Updates
Next, the downloader will prompt for the preferred Tor Browser version and confirm installation. Take heed of the warning in the confirmation box stating the existing Tor Browser user profile (including bookmarks and passwords) will be lost during this process.
Figure: Download Confirmation
After agreeing to the download process, a progress indicator will be displayed by the downloader. This process can be lengthy depending on the speed of the Tor network connection.
Figure: Downloading Tor Browser
Once the download has finished, the downloader will provide verification (or not) of the cryptographic signature associated with the Tor Browser binary, highlighting the key used to sign it and the date. The downloader will then ask for confirmation to install the package: see Installation Confirmation Notification for steps on identifying a possible targeted attack.
Figure: Tor Browser Installation Confirmation
If the installation process is confirmed, the downloader will extract Tor Browser.
Figure: Extracting Tor Browser
In the final step, the downloader will prompt whether the upgraded Tor Browser should be launched.
Figure: Finalized Tor Browser Installation
(Also available as CLI version.)
Download Confirmation Notification
This step is designed to keep Whonix users safe.
At present there is no reliable and secure way for a program to determine the latest stable version of Tor Browser with reasonable certainty.   When the version format changes, the automated parser of version information could falsely suggest:
- An earlier stable version that is still considered secure.
- An alpha series release.
- A beta Tor Browser build.
- A release candidate or nightly Tor Browser build.
To counter these threats, user intelligence is utilized as a sanity check. The Download Confirmation Notification provides a way to detect such situations and abort the procedure. In this instance, it is recommended to rotate the Tor circuits and attempt the download process again.
Version numbers that are visible under Online versions come from an online resource. The Tor Browser RecommendedTBBVersions versions file is provided by The Tor Project, and is parsed by Whonix's Tor Browser Downloader. The Whonix downloader will indicate that no upgrade is required if the installed Tor Browser version matches the up-to-date online version.
Installation Confirmation Notification
This step is also designed to protect users.
When verifying cryptographic signatures, several important aspects must be considered:
- The signature should be made by a trusted key.
- Trusted keys will have signed other files in the past. It is also necessary to check if the right file was received, and not just any file that was signed by a trusted key.
- Even if the correct file type is received,  it is necessary to check it has a current signature attached and not a historical one. This step counters the threat of indefinite freeze and rollback attacks.
By the time the Installation Confirmation Notification is visible, the verification of the signature (and hash) will have already succeeded. However, the signature creation dates in the figure below must be carefully examined to confirm that an indefinite freeze or downgrade attack did not occur.
Previous Signature Creation Date: When Tor Browser was previously installed by tb-updater, the creation date of the accompanying signature that signed Tor Browser will have been stored. The Previous Signature Creation Date field displays that date.
Last Signature Creation Date: This field displays the date of signature creation for the downloaded file.
Figure: Tor Browser Installation Confirmation
Note: Tor Browser local version number detection is not currently implemented in Whonix.
Do not run Tor Browser in a TemplateVM (
Unfortunately, updating Tor Browser is more complex than regular system updates due to technical limitations outside of Whonix's control.  Applying the following instructions makes it is possible to keep Tor Browser up to date at all times.
New AppVMs and DisposableVMs
In Qubes-Whonix, Tor Browser Downloader by Whonix (
update-torbrowser) is automatically run when the Whonix-Workstation TemplateVM (
tb-updater is updated. Therefore, running Tor Browser Downloader by Whonix inside the TemplateVM (
whonix-ws-14) ensures that new AppVMs and DispVMs are created with a copy of the latest Tor Browser version.
If the Tor Browser Downloader by Whonix package
tb-updater has not been updated yet, users are advised to manually run it in the Whonix-Workstation TemplateVM (
whonix-ws-14). For instructions, see Tor Browser Downloader by Whonix.
For further information on installing, updating and using Tor Browser in Qubes DispVMs, see: How to use DisposableVMs in Qubes-Whonix.
Follow these steps to update Tor Browser in an existing Whonix-Workstation AppVM such as
- Start Tor Browser:
Qubes Start Menu->
Whonix-Workstation AppVM (commonly called anon-whonix)->
- Use Tor Browser Internal Updater.
Tor Browser Internal Updater
Tor Browser upgrades are possible from within the browser.  When a new Tor Browser version is available but the browser has not completed an automatic upgrade in the background (the default), a warning prompt appears recommending an upgrade via Torbutton:
Left-click Torbutton ->
Check for Tor Browser Update...
Figure: Torbutton Update Warning
Tor Browser Manual Update
If the Tor Browser update script is ever broken, it is advised to update manually.
Modern Tor Browser releases are generally easy to install and update on well-supported platforms like Whonix, leading most users to have a comfortable and reliable experience over long periods. However, if/when Tor Browser "breaks", some might find it difficult to perform a manual installation. 
Sometimes Whonix Tor Browser Downloader inside Whonix-Workstation breaks because torproject.org changes the way Tor Browser can be downloaded or verified. This program is maintained by the Whonix team and The Tor Project is not responsible for necessary fixes. Generally, Whonix news will be published within a few days with working instructions on how to fix the problem. If this does not happen, then Whonix developers are unaware of the issue.
Any bugs should be discussed in the Whonix User Help Forum or Bug Tracker. To date, no bugs were ever discovered in Tor Browser that were directly related to Whonix code and which might cause serious problems such as website pages failing to load.
The manual Tor Browser download procedure assumes basic knowledge of:
- Software Verification: Users are expected to know how to PGP-verify the Tor Browser package, using the associated file signature and Tor signing keys (relevant links are provided). 
- Troubleshooting: If Tor Browser problems occur in Whonix such as webpages failing to resolve, then:
- Users are expected to perform the same test on the host (Non-Qubes-Whonix) or in a non-Whonix VM (Qubes-Whonix); see Non-Whonix Tor Browser. This step helps to determine whether the problem is related to Whonix or not.
- It is also sensible to search for the problem on torproject.org's bug tracker and report a bug upstream if it has not been notified yet. In that case, when upstream (TPO) fixes the issue, the issue will most likely also get fixed in Whonix.
Unsafe Tor Browser Habits
It is important to develop a set of safe habits when communicating, browsing or downloading with Tor Browser. Even the world's premier anonymity software cannot protect users if they shoot themselves in the foot.
The following is an inexhaustive list of unsafe behaviors. It is recommended to also read the Whonix Tips on Remaining Anonymous entry, along with Tor Project documentation before using Tor Browser for serious activities necessitating anonymity.
Table: Unsafe Tor Browser Habits
|Category||Unsafe Configuration or Behavior|
|Add-ons||Add non-default add-ons to Tor Browser. |
Configure persistent, customized NoScript settings.
|Anonymity Modes||Mix modes of anonymity. |
Fail to compartmentalize Tor Browser activities.
|Bridges||Expect that Tor relay bridges will absolutely disguise all use of Tor / Tor Browser.|
|Browser Settings||Maximize or change  the default window size setting. |
Change other browser settings if the implications are unknown.
|Communications||Send "anonymous" communications or other data over unencrypted channels using plain HTTP.|
|File Downloads||Torrent over Tor. |
Open documents or other files downloaded by Tor while online.
Open random files or links.
Paste or type download links into the address bar without
Download and install unsigned software from the Internet.
Download and install signed software or import keys without first verifying key fingerprints and digital signatures.
|HTML5 Canvas Image Data||Allow extraction of canvas image data by websites.|
|Identities||Disclose identifying data. |
Maintain long term identities.
Use different online identities at the same time.
|Logins||Login to Google, Facebook or other corporate accounts with a real name or pseudonym.  |
Login to accounts that have ever been used without Tor.
Generally login to banking, financial, personal or other important accounts.
|Local Connections||Configure a local connection exception for applications, unless aware of the risks.|
|Networking||Configure Tor Browser so that it leads to a Tor over Tor scenario.|
|Other Browsers||Use browsers other than Tor Browser with Tor. |
Use a clearnet browser and Tor Browser at the same time.
|Personal Websites and Links||Visit personal websites over Tor. |
Be the first person to spread a personal link.
|Phone Verification||Use (mobile) phone verification.|
|Proxy Settings||Change or remove default proxy settings if unaware of the implications.|
|Qubes-Whonix||Launch Tor Browser in a TemplateVM (|
Launch Tor Browser Downloader in a DVM-TemplateVM (
|Server Connections||Connect to a server anonymously and non-anonymously at the same time.|
|Torbutton||Use the Torbutton "New Identity" and "New Tor Circuit for this Site" functions and expect complete anonymity in the following browsing session.|
|Updates||Ignore download and/or installation confirmation notifications or warnings when updating Tor Browser. |
Use an outdated version of Tor Browser.
|User Mentality||Feel invincible running Tor Browser (irrespective of the platform), due to significant adversary capabilities and interest in unmasking or infecting Tor users.|
Whonix Tor Browser Differences
The regular Tor Browser Bundle and Whonix Tor Browser slightly differ. The reason is Tor Browser must be adjusted by Whonix to work behind Whonix-Gateway. Despite environmental variable adjustments, the network and browser fingerprint remain the same.
The main Whonix Tor Browser differences can be summarized as follows:
- tor-launcher (Tor connection wizard) will not be shown in Whonix-Workstation Tor Browser. Instead, there is Anon Connection Wizard on Whonix-Gateway.
- The Tor Circuit View and Open Network Settings functions have been disabled in Torbutton. The former is unsupported for security reasons,  while the latter would have no effect since Tor must be configured in the Whonix-Gateway.
- The default landing page upon Tor Browser start is set to use a local Whonix resource. 
- Prevent Tor over Tor scenario in the Whonix-Workstation. 
Whonix does not:
- Change Tor Browser's Internal Updater checking mechanism.
- Modify Tor Browser's startup script, default settings and so on. 
- Change or remove proxy settings by default.
Tor Browser Functionality on Different Platforms
The reason is this comparison includes a host of platform-specific differences which confound the result. For example, a more valid comparison would be the differences between:
- TBB on Debian (real Debian, not in Qubes) vs Tor Browser on Non-Qubes-Whonix.
- TBB in a Qubes AppVM based on a Debian TemplateVM vs Tor Browser on Qubes-Whonix.
Similarly, if a user wanted to help with TBB (non-Whonix) development, then these comparisons would be useful:
- TBB on Debian (real Debian, not in Qubes) vs TBB on Windows.
- TBB on different Linux distributions.
- TBB on different Windows platforms.
Glossary and Key Terminology
It is recommended that users become familiar with terms regularly used by The Tor Project and Whonix. One useful resource is the v1.0 Tor glossary which is now available on The Tor Project community wiki page.
Tor vs Tor Browser
Tor is an anonymizer developed by The Tor Project. Tor Browser is a web browser developed by the Tor Project which is optimized for privacy. Please do not confuse Tor with Tor Browser when conversing about Whonix topics.
Tor Browser Transparent Proxying
The Tor Browser "transparent proxying" feature  and/or the environment variable
TOR_TRANSPROXY=1 often cause confusion. It was an unfortunate naming decision by The Tor Project. This feature actually removes proxy settings. With no proxy set, the user's system reverts to its default configuration. The effect of this decision is that Tor Browser will work identically to an unconfigured Firefox browser.
This is potentially dangerous when done outside of Whonix because Tor Browser's transparent proxying feature could result in clearnet traffic; for instance if the gateway does not have a transparent torification feature (like Whonix-Gateway). In the case of Whonix, even if the transparent proxying feature is set, Whonix-Gateway will "torify" traffic and force it through Tor. Similarly, if transparent proxying is set and happens to use a JonDo-Gateway, traffic will be forced through JonDo.
One downside of the transparent proxying feature is that even when it is used inside Whonix, it breaks Tor Browser's top level isolation for each separate tab.
Transparent proxying should not be confused with:
Refer to this wiki entry if any of the following advanced topics are of interest:
- Tor Browser and Torbutton design.
- Tor Browser without Tor.
- Setting a custom homepage.
- A custom Whonix configuration or Workstation is in use.
- Changes to proxy settings are required.
- The difference between tor-launcher and tor-browser launcher.
- Qubes-Whonix topics:
- Split Tor Browser.
- Tor Browser in a DisposableVM.
- Tor Browser in a Qubes DVM Template.
- Tor Browser debugging is required.
Footnotes / References
- For a comprehensive list of reasons, readers are encouraged to review some or all of the references in this section.
A good overview of the browser component is provided by The Tor Project design document.
The Tor Browser is based on Mozilla's Extended Support Release (ESR) Firefox branch. We have a series of patches against this browser to enhance privacy and security. Browser behavior is additionally augmented through the Torbutton extension, though we are in the process of moving this functionality into direct Firefox patches. We also change a number of Firefox preferences from their defaults.
Tor process management and configuration is accomplished through the Tor Launcher add-on, which provides the initial Tor configuration splash screen and bootstrap progress bar. Tor Launcher is also compatible with Thunderbird, Instantbird, and XULRunner.
To provide censorship circumvention in areas where the public Tor network is blocked either by IP, or by protocol fingerprint, we include several Pluggable Transports in the distribution. As of this writing, we include Obfs3proxy, Obfs4proxy, Scramblesuit, meek, and FTE.
- https://web.stanford.edu/class/msande91si/www-spr04/readings/week1/InternetWhitepaper.htm. DNS servers enable the browser to know where resources are located on the Internet, and the corresponding IP address for fetching these.
- See below for a further description of these features.
- HTTPS is not foolproof due to reliance on the Certificate Authority (CA) system that issues digital certificates (private keys) for websites. As a trusted third party, this trust can be abused or the CAs can be subject to adversary attacks.
- This does not however defend against improved cryptanalysis that breaks underlying ciphers being used, for example by the emergence of quantum computers. Only post-quantum ciphers resistant to these attacks will prevail.
- Extra layers of encryption are not really necessary, since a completely encrypted tunnel is already formed (but it certainly does not hurt). Until recently, these certificates would not validate because of the *.onion hostname.
- This is why onion addresses appear absurdly long and random.
- Anti-clickjacking was also previously available to protect against hidden or disguised user interface elements masquerading as trusted web page buttons, links and so on. Unfortunately this is no longer available in NoScript following the shift to Firefox extensions in Tor Browser based on Firefox 60 ESR. This feature provided protection against malicious activation of microphones or webcams, or users being tricked into interacting with hidden elements to steal important financial, personal or other data.
- Having a large user base is important for strong anonymity, as Roger Dingledine explains here.
- The default Tor Browser setting
- For example, most videos can now be viewed in HTML5 which Tor Browser supports and prefers.
- See tbb-linkability and tbb-fingerprinting.
- /usr/bin/torbrowser simply navigates to the Tor Browser folder and runs ./start-tor-browser. The former has more features like reporting error conditions or the absence of a Tor Browser folder, generation of non-zero exit code failures, and more.
- And that website does not:
- Use HTTP Strict Transport Security (HSTS). See also: https://security.stackexchange.com/questions/91092/how-does-bypassing-hsts-with-sslstrip-work-exactly. Without HSTS, sites with non-encrypted resources or sub-domains are vulnerable to SSLstrip.
- Have a HTTPS Everywhere rule in effect.
- Use HSTS preloading.
- Use HTTP Public Key Pinning. See also: https://news.netcraft.com/archives/2016/03/22/secure-websites-shun-http-public-key-pinning.html. HPKP limits trust to a handful of Certificate Authorities, but is not used by many websites due to the risk of site breakage if keys are not managed vigilantly.
- Language packs might be another fingerprinting vector, but this issue requires further investigation.
- Since it uses predetermined ports on the localhost.
- Alternatively the user can remove Tor Browser's proxy settings, but this method is still vulnerable to the same fingerprinting issues as configuring an exception. There are also other factors which will worsen the user's fingerprint, such as the breaking of both stream isolation and the tab isolation by socks user name in Tor Browser.
Ad-hoc Solutions for accessing blocked content on Tor
Content on this site is Copyright The Tor Project, Inc.. Reproduction of content is permitted under a Creative Commons Attribution 3.0 United States License. All use under such license must be accompanied by a clear and prominent attribution that identifies The Tor Project, Inc. as the owner and originator of such content. The Tor Project Inc. reserves the right to change licenses and permissions at any time in its sole discretion.
- See also: hidester.com/proxy and youtubeunblocks.com/
- This does not protect against the sudden loss of networking, which could reveal to the attacker that two activities / accounts suddenly going off-line are probably related.
- This does not protect against potential infection of dom0 or the Whonix-Workstation DisposableVM-Template by advanced adversaries. Traces of user activity may also be left on storage media or in RAM.
- This does not yet notice upgrades done by Tor Browser's Internal Updater.
- Since v5.0, Tor Browser is configured to update itself.
- Finalize RecommendedTBBVersions format
- Counter downgrade / stale mirror attacks on RecommendedTBBVersions - sign / verify tbb versions file
- For a definition of these attacks, see the threat model of TUF (The Update Framework) (w).
- Adversaries capable of breaking SSL could mount these attacks by replacing RecommendedTBBVersions with invalid, frozen or outdated version information.
- Unfortunately, Tor Browser signatures do not yet provide expiration dates in a manner similar to Debian's valid-until field.
- Rollback attacks are possible because the user's computer clock could be wrong, so there is no solid basis for comparison.
- That is, a browser and not a messenger or other application.
- GnuPG (OpenPGP) common misconceptions.
- The name of the file is stored in the hash file and verified to match the downloaded file name and hash.
- It is possible to run Tor Browser Downloader by Whonix inside a DispVM as well -- probably easiest using Tor_Browser#Tor Browser Internal Updater -- and then restart Tor Browser. However, these updates will not persist due to the DispVM design.
- See tb-updater in Qubes Template VM for technical details.
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.
- Before the introduction of Tor Browser's internal updater, manual installation was a difficult task which required the renaming (or deletion) of the old Tor Browser folder before the new version was extracted. If users have little concept of how Tor Browser functions "under the hood", then this logically causes problems when they attempt a manual installation (particularly on the host).
- Whonix is not a standalone package, but a complete operating system. Whonix has a small team, while torproject.org has a much larger community and dedicated, paid support staff. Therefore, Whonix users are expected to learn Tor Browser basics in the first instance.
- This is so Whonix-Workstation does not have access to the information about 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
- The default Tor Browser Bundle uses about:tor as the landing page. See: https://trac.torproject.org/projects/tor/ticket/13835
- In Whonix-Workstation, rinetd listens on 127.0.0.1 9150 and 9151 (Tor Browser's default ports) and forwards them to Whonix-Gateway 10.152.152.10 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.
- No changes have been made to Whonix code to prevent such a warning.
Whonix Tor Browser wiki page Copyright (C) Amnesia <amnesia at boum dot org> Whonix Tor Browser wiki page Copyright (C) 2012 - 2018 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.
Comments will be deleted after some time. Specifically after comments have been addressed in form of wiki enhancements. See Wiki Comments Policy.
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 is provided by ENCRYPTED SUPPORT LP. See Imprint.