Configure (Private) (Obfuscated) Tor Bridges
Bridges Description and User Groups
When Tor is used with Whonix ™ in the default configuration, anybody observing the properties of its application protocol can discover its presence. Potential observers include the Internet Service Provider (ISP), advanced adversaries, censorship enforcement bodies and other interested parties.
Tor bridges ("Tor bridge relays") [archive] are alternative entry points to the Tor network, acting as substitutes to regular Tor guards rather than an additional hop to the 3 hop journey. Not all bridges are obtainable publicly. Using a bridge makes it harder, but not impossible, for the ISP to determine a user is connecting to Tor.
Intended User Groups
For the majority of Whonix ™ users, connecting to Tor with the default configuration is appropriate and will work successfully. The minority of users requiring a bridge normally fall into three categories: 
- Tor is blocked, and some way - any way - to reach the network has to be found. The adversary is not very dangerous, but very annoying.
- Tor may or may not be blocked, but the users are trying to hide the fact they're using Tor. The adversary may be extremely dangerous.
- Other bridge users: Testing whether the bridge works (automated or manual), probing, people using bridges without their knowledge because they came pre-configured in their bundle.
The first group of users is only concerned with circumventing Tor censorship that is based on IP address or fingerprinting of protocols. Circumvention is necessary because Whonix ™ would otherwise be rendered useless for most activities except working offline on documents and so on, since all Internet traffic is routed through Tor by default. This group is not worried about hiding the use of Tor and will need to use bridges or possibly other circumvention tools.
The second user group is unable to safely start Whonix ™ in the default configuration due to Tor being considered dangerous or suspicious in their locality. In this case private bridges or a VPN/SSH tunnel should be utilized instead of public obfuscated bridges, as this makes it harder (not impossible) to detect Tor. 
Note that the
meek_azure pluggable transport may be necessary to deal with highly aggressive ISP censorship or national firewalls, like those found in China and the Middle East.
The third group is only concerned with testing bridge connections.
Before Configuring a Bridge
Users falling into one of the three groups described above should consider using Tor bridges. Before taking this step, please review The Tor Project's dedicated bridges page [archive] to better understand their design and operation. It is also recommended to review how Obfsproxy works [archive], since it is the most commonly used application for connecting bridges.
Always remember that bridges are not bullet-proof. The following is a reminder about bridge versus non-bridge anonymity:
[...] Bridges are less reliable and tend to have lower performance than other entry points. If you live in a uncensored area, they are not necessarily more secure than entry guards. [...]
If that is true, that also means, that bridge users are sufficiently more vulnerable to attacks, which are circumvented by entry guards?
[...] They're probably more vulnerable, but I don't know if I'd say "sufficiently". [...]
If a user is only concerned with connectivity (getting Whonix connected) and local ISPs do not usually hinder connections to the public Tor network, then something simpler than Bridges can be tried; see: Better Connectivity without Real Censorship Circumvention.
Additional Information and Recommendations
When deciding on the type of bridge to configure, it is recommended to:
- Prefer obfuscated bridges [archive], since they are harder to identify than other bridges.
- Use less well-known bridges, since it is safer. 
- Avoid using a meek provider that also runs DNS core servers, like Google's (now defunct) bridge. 
- Note that domain fronting has been pulled by Google and Amazon [archive], limiting the meek pluggable transport options to
meek_azureonly in Anon Connection Wizard.
- For greater safety, use a private obfuscated bridge bridge run by a trusted friend or organization in a different country. In this case "private" means that the bridge is configured with the option PublishServerDescriptor 0. 
Please note that it has been assessed as difficult beyond practicality to Hide Tor use from the Internet Service Provider with proxies, bridges, VPNs or SSH tunnels.
Finding a Bridge and Choosing the Right Protocol
In order to use bridges, the address of at least one bridge must be known in advance. It is preferable to have a private obfuscated bridge because the alternative -- public obfuscated bridges -- are more likely to be censored, since they are publicly listed. The Tor Project distributes public bridge addresses in several ways, including from their website [archive] and via email. The easiest way to find a list of public bridges is from The Tor Project Bridge Database [archive].
... in Tor Browser to obfs4, given that we now have several high capacity obfs4 bridges and obfs4 is more likely to work in more regions than obfs3."
As time has gone on, more obfs4 bridge operators have come online, and obfs4 is now routinely recommended by Tor developers over obfs3, because the former: 
... should be able to defend more effectively against active probing.
The Tor Project provides a database of public obfs4 bridges [archive]. A more exhaustive list of public obfuscated bridges is available at The Tor Project Bridge Database [archive]. obfs and obfs2 bridges are no longer available since they: 
... are now deprecated and were replaced by obfs3 . . . and obfs4.
How to Use Bridges in Whonix ™
Snowflake is: 
...a pluggable transport [archive] that proxies traffic through temporary proxies using WebRTC [archive], a peer-to-peer protocol with built-in NAT punching. It aims to work kind of like flash proxy, but without flash proxy's problems with NAT.
Snowflake configuration in Whonix ™ is only recommended for advanced users because it is difficult to move the
snowflake-client into Whonix-Gateway ™ (Qubes-Whonix:
Check Tor Network Connection is Using a Tor Bridge
Concerned bridge users can complete a simple check.
After configuration, connection problems can relate to firewall settings that block outgoing connections to the ports provided by the bridge. To check the port the bridge is using, see the following example.
In this example, the IP address is 126.96.36.199, while the the port is 22321.
Try using a (private) (obfuscated) bridge that uses port 80 or 443, as these ports are mostly used for web browsing and therefore usually unblocked.
Trying Packet Size and Timing Obfuscation for obfs4
If a provided obfs4 bridge does not work, the user can try enabling packet size and timing obfuscation by changing the
iat-mode value in each last line to either
Better Connectivity without Real Censorship Circumvention
If a user is only concerned with connectivity (getting Whonix connected) and there is no need to attempt to Hide Tor use from the Internet Service Provider and/or local ISPs do not usually hinder connections to the public Tor network, then something simpler than Bridges can be tried.
The following setting only establishes Tor connections to public Tor network relays that listen on ports 80 and 443.
Missing ClientTransportPlugin Line
When a user has configured the following.
bridge obfs4 ...:... ... cert=... iat-mode=0
But forgot to add the corresponding line.
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy
Then warnings will only be shown in logs.
[warn] We were supposed to connect to bridge '...:...' using pluggable transport 'obfs4', but we can't find a pluggable transport proxy supporting 'obfs4'. This can happen if you haven't provided a ClientTransportPlugin line, or if your pluggable transport proxy stopped running.
Missing ClientTransportPlugin Executable
[warn] Could not launch managed proxy executable at '/usr/bin/obfs4proxy' ('No such file or directory').
Deprecated Tor Pluggable Transports
scramblesuit: Unrecommended (see footnote). Use the provided obfs4 instructions instead. 
flashproxy: Unrecommended (see footnote). Use the provided obfs4 instructions instead. 
- Lantern: An alternative censorship circumvention tool documented for Qubes-Whonix ™ only.
- Unfinished: Censorship Circumvention Tools other than bridges.
- Unfinished: Using Tor / Pluggable Transports from the Tor Browser Bundle.
While most of this chapter is dedicated to bridge use, this section clarifies a few concepts about Tor Bridge hosting, although detailed how-to instructions are not provided. To help others you must reside in a country that does not censor Tor and have a reasonably fast connection. The VM or host in use should have port forwarding enabled to allow direct connections because all bridge server types require this, including Snowflake.
Volunteer Snowflake instances run proxies to the bridge and are not bridges themselves. These proxies can be run behind a NAT because clients use the built-in NAT punching properties of WebRTC to connect. The proxies then open a WebSocket connection to the Snowflake bridge and relay data between the WebRTC connection with the client and the bridge. The Snowflake bridges cannot run behind a NAT and are similar to all other existing pluggable transports in this regard. 
Using bridge users' traffic to mask your own onion service traffic is difficult to do properly.  This may be of questionable efficacy if traffic is not heavy and the bridge traffic of other pluggable transports is easily able to be excluded by advanced adversarial traffic analysis.
In order to implement a similar defense using a Snowflake proxy (as opposed to a bridge), a custom client needs to be written that would encapsulate your Tor traffic and send it through a TCP WebSocket connection to the Snowflake bridge. This measure is ineffective for the same reasons bridge cover traffic is not. For other traffic to provide effective cover, client traffic needs to be mixed with concurrent, relayed Tor relay traffic; this may require a relatively high speed main network relay to be in use frequently enough to help. Note that website fingerprinting of client traffic is not a severe enough threat to warrant this type of defense for clearnet-destined tor traffic, but it is helpful to protect against end-to-end correlation attacks.  
Various jurisdictions utilize active probing in order to block circumvention proxies, including different versions of Tor and the detection and blocking of bridges. Perhaps the most infamous example is the probing system used by the "Great Firewall of China" (GFW). The Tor Project first began exploring this issue in October 2011 [archive]. At that time it was discovered that: 
...connections to US-based Tor bridge relays were being regularly cut off after a very short period of time. At the time we performed some basic experimentation and discovered that Chinese IPs (presumably at the behest of the Great Firewall of China, or GFW) would reach out to the US-based bridge and connect to it shortly after the Tor user in China connected, and, if successful, shortly thereafter the connection would be blocked by the GFW. There wasn't time for a detailed investigation and analysis at the time, but that kernel eventually grew into the investigation detailed below. We were, however, able to determine that limiting connections to the bridge relay to only the single IP expected to be its client would, in fact, block the probes and allow the connection to remain open for an extended period (>48 hours in our testing).
The Tor Project identified two types of probing: 
- Garbage binary probes: when an SSL connection took place, arbitrary binary data was sent to the non-China side of connections originating from China to TCP port 443 (HTTPS). Deep packet inspection (DPI) [archive] was suspected because the probe occured soon after the connection was established. 
- Tor probes: China-based Tor clients connecting to US-based bridge relays were probed at 15 minute intervals. The bridge received probes from China-based hosts that: established a TCP connection, performed a SSL negotiation, followed by a SSL renogotiation and the building of a one-hop circuit (including a
To prevent probing, Tor developers then responded by changing the list of supported SSL ciphers included in the "hello" packet sent to Tor clients in China. 
Further investigation of the GFW active probing system in 2015 revealed: 
- Bridges detected and blocked by the GFW remain blocked. However, a small window of opportunity was available around every 25 hours when Tor clients in China could connect to bridges.
- TCP headers of active probes suggest the thousands of IP addresses are controlled by a single source and not independent computers.
- The GFW also targets other circumvention systems like SoftEther and GoAgent. 
- Bridges are probed by the GFW using the standard Tor protocol, as well as obfs2/3.
- Tor probes had increased in frequency from 15 minute intervals to near real-time -- active probes emerged half a second after a bridge connection was established.
- The GFW sensor is unable to reassemble TCP streams.
In 2019, The Tor Project noted: 
When the Great Firewall's active probing attack discovered a bridge, the GFW used to block the bridge by its IP address and port, which conveniently left other transport protocols that ran on the same IP address, say obfs4, reachable. This behavior changed recently, and bridges are now blocked by their IP address. This means that a protocol that is vulnerable to the GFW’s active probing attack (e.g., vanilla Tor, fte, and obfs3) can get the entire bridge blocked—including obfs4, which is resistant to active probing! The new BridgeDB release addresses this issue by only handing out a bridge’s probing-resistant protocols if the bridge supports protocols that are both vulnerable and resistant to active probing. For example, if a bridge supports both vanilla Tor and obfs4, then we only hand obfs4 to users.
Research suggests ScrambleSuit [archive] and obfs4 [archive] can successfully defend against probing attacks, but their ongoing effectiveness will remain an open research question. The take-home message is that Whonix ™ users in heavily censored nations like China and Iran will require an obfs4 bridge or other probe-resistant protocols to try and circumvent censorship.
For further reading on this topic, see:
- Examining How the Great Firewall Discovers Hidden Circumvention Servers [archive]
- The Great Firewall’s active probing circumvention technique with portknocking and SDN [archive]
- Demystifying the Great Firewall of China [archive]
- Analyzing China’s Blocking of Unpublished Tor Bridges [archive]
- How the Great Firewall of China is Blocking Tor [archive]
- Detecting Probe-resistant Proxies [archive]
- https://blog.torproject.org/different-ways-use-bridge [archive]
- Over time, censors have gotten better at detecting Tor network traffic between the client and the first hop, even with the use of more advanced pluggable transports. There is a cyber-censorship arms race in effect.
- Some bridge addresses are freely provided by the Tor website or by email upon request, meaning adversaries likely use these methods to obtain bridge information. The Tor Project has some protection against adversary threats, but they are far from perfect.
- Google sees forty percent of Tor Exits' DNS traffic and so using them as a bridge aids website fingerprinting attacks. That said, there is evidence that website fingerprinting is more difficult to mount than previously thought. See: The Effect of DNS on Tor’s Anonymity [archive]
- Tor manual: PublishServerDescriptor [archive] Without this option set, The Tor Project can learn about the bridge and may distribute its address to others, potentially handing this information to an adversary seeking to generate a list of all known bridges.
- https://trac.torproject.org/projects/tor/ticket/18072 [archive]
- This pluggable transport has been deprecated by The Tor Project in favor of obfs4, meek, Format-Transforming Encryption (FTE) and ScrambleSuit [archive].
- https://blog.torproject.org/blog/recent-and-upcoming-developments-pluggable-transports#obfs2_deprecation [archive]
- https://2019.www.torproject.org/docs/bridges.html.en#PluggableTransports [archive]
- https://2019.www.torproject.org/docs/pluggable-transports.html.en [archive]
The obfs4 protocol was developed and is in the process of being deployed by the Tor Project in response to the vulnerability of the obfs3 protocol to detection via active probing attacks. It is expected to supersede the obfs3 protocol as the front-line Pluggable Transport used by most Tor users.
- https://www.torproject.org/docs/bridges.html.en#PluggableTransports [archive]
Anon Connection Wizard is a graphical user interface (GUI) application. It does not have command line interface (CLI) support yet. [archive] It is therefore unavailable on Whonix-Gateway ™ CLI. Use
setup-distinstead; note that functionality is limited and does not support Bridges.
- https://gitlab.torproject.org/legacy/trac/-/wikis/doc/Snowflake [archive]
- https://trac.torproject.org/projects/tor/ticket/19001 [archive]
The line starting with
ClientTransportPluginwas taken from the Tor Browser folder file.
What is the link to the
torrc-defaultsfile The Tor Project git?
The path was adjusted from
/usr/bin/snowflake-clientto be compatible with these instructions.
The line starting with
Bridgewas taken from this file:
It was previously:
Bridge snowflake 0.0.3.0:1 2B280B23E1107BB62ABFC40DDCC8824814F80A72
snowflake-clientis a standalone binary that can be easily copied. AppArmor has appropriate permissions for Snowflake operation. /etc/apparmor.d/local/system_tor [archive] already contains
- 1 = Enabled: ScrambleSuit-style with bulk throughput optimizations. 2 = Paranoid: Each IAT write will send a length sampled from the length distribution (expensive). See: https://lists.torproject.org/pipermail/tor-commits/2014-August/079402.html [archive]
- https://www.torproject.org/docs/tor-manual.html.en#FascistFirewall [archive]
Quote intrigeri [archive] (Tails developer):
On tor-talk we've been told "You shouldn't prioritise ScrambleSuit because it is superseded by obfs4", and there are now pressing plans in the Tor Project to deprecate obfs2 and obfs3 in favour of obfs4. Hence rejecting this ticket, and focusing on #7980 [archive] [obfs4 support] instead.
- Old instructions: Deprecated#scramblesuit
Flashproxy has been removed from Tor Browser [archive], therefore it can be considered deprecated.
- Old instructions: Deprecated#flashproxy
- https://gitlab.torproject.org/legacy/trac/-/wikis/doc/Snowflake [archive]
- https://github.com/mikeperry-tor/vanguards/blob/master/README_SECURITY.md#the-best-way-to-run-tor-relays-or-bridges-with-your-service [archive]
- https://lists.torproject.org/pipermail/tor-dev/2020-January/014127.html [archive]
- https://2019.www.torproject.org/docs/faq.html.en#BetterAnonymity [archive]
- https://blog.torproject.org/knock-knock-knockin-bridges-doors [archive]
- At that time probing did not occur when the obfsproxy or plain-text protocols were used, presumably because a SSL handshake does not take place.
- They did note that ongoing Chinese censorship efforts would necessitate the development of new Tor protocols, handshakes and extensions over time, such as improved obfsproxy protocols.
- https://blog.torproject.org/learning-more-about-gfws-active-probing-system [archive]
- Suggesting the active probing system is modular in nature and can be configured to detect newer, proxy-based circumvention tools.
- https://blog.torproject.org/new-release-bridgedb-071 [archive]
Whonix ™ Bridges wiki page Copyright (C) Amnesia <amnesia at boum dot org>
Whonix ™ Bridges wiki page Copyright (C) 2012 - 2021 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.