- 1 Bridges Description and User Groups
- 2 Finding a Bridge and Choosing the Right Protocol
- 3 How to Use Bridges in Whonix
- 3.1 Introduction
- 3.2 Option 1: Use Anon Connection Wizard
- 3.3 Option 2: Edit /usr/local/etc/torrc.d/50_user.conf
- 4 Troubleshooting
- 5 Deprecated Tor Pluggable Transports
- 6 See Also
- 7 Footnotes
- 8 License
Bridges Description and User Groups
When Tor is used with Whonix in the default configuration, anybody observing the flow of network traffic from the Internet connection can determine that Tor is being used. Potential observers include the Internet Service Provider (ISP), advanced adversaries, censorship enforcement bodies, and other interested parties.
Tor bridges ("Tor bridge relays") are alternative entry points to the Tor network, not all of which are listed publicly. Using a bridge makes it harder, but not impossible, for the ISP to determine a user is connecting to Tor.
|If a website cannot be reached over Tor, this does not necessarily relate to network level censorship that requires a bridge to be configured; it may relate to blacklisting of Tor IP addresses by the server. Using Tor in combination with a proxy/VPN/SSH tunnel may be necessary in those circumstances.|
Intended User Groups
|Tor non-functionality is often related to local configuration problems rather than ISP or state-level censorship.|
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 user is trying to hide the fact they're hiding 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. It 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
meek_lite pluggable transports 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
|Warning: Bridges are important tools that work in many cases but they are not an absolute protection against the technical progress an adversary might make in identifying Tor users. Using bridges might be advisable to prevent identification as a Tor user, but the Tor Project's documentation on bridges is primarily focused on censorship circumvention, that is, overcoming attempts by ISPs or governments to block Tor use.|
Users falling into one of the three groups described above should consider using Tor bridges in Whonix. Before taking this step, please read The Tor Project's dedicated page about bridges to get a better understanding of their design and operation. It is also recommended to review how Obfsproxy works, since it is the most commonly used application for connecting bridges.
It is important to 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 a user is only concerned with connectivity (getting Whonix connected) and there is no need to Hide Tor and Whonix from your ISP and/or 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 Whonix starts for the first time, it will not automatically connect to the public Tor network, which is beneficial for safety reasons. Users are guided by the Whonix Setup Wizard, which is automatically started.|
When deciding on what kind of bridge to configure, it is recommended to:
- Only use obfuscated bridges, since they are harder to identify than other bridges.
- Use less publicly known bridges, since it is safer. 
- Consider whether Hiding Tor and Whonix from your ISP is advisable in your circumstances.
- Avoid using a meek provider that also runs DNS core servers, like Google's (now defunct) bridge. 
- 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. 
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 - have a greater likelihood of being censored, since they are publicly listed. The Tor Project distributes public bridge addresses in several ways, including from their website and via email. The easiest way to find a list of public bridges is from The Tor Project Bridge Database.
As of early 2017, The Tor Project advice is that the recommended bridge type has been changed: 
... 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 goes on and more obfs4 bridge operators go online, it may be preferable to use obfs4 instead of obfs3, as obfs4: 
... should be able to defend more effectively against active probing.
The Tor Project provides a database of public obfs3 bridges and public obfs4 bridges A more exhaustive list of public obfuscated bridges is available at The Tor Project Bridge Database. It is not recommended to use obfs and obfs2 bridges, which: 
... are now deprecated and were replaced by obfs3 . . . and obfs4.
How to Use Bridges in Whonix
This section will explain how to use obfuscated bridges in Whonix.
|Tip: Until Whonix 14 is released, there is no wizard available to help set up bridges before connecting to Tor. The graphical tor-launcher (screenshots) that some users might know from The Tor Project's Tor Browser cannot be used in Whonix.|
obfs2, obfs3 and obfs4 bridges can currently be configured on Whonix-Gateway. From Whonix 14, meek_lite bridges can also be used in Whonix-Gateway. The process is identical to the steps completed on a Debian platform because Whonix is based on Debian. From Whonix 14, bridges can be configured easily using Anon Connection Wizard. Alternatively, for all Whonix versions, Tor bridges can be configured by editing /etc/tor/torrc within the Whonix-Gateway. Click the expand button to see instructions for each method.
Option 1: Use Anon Connection Wizard
Option 2: Edit /usr/local/etc/torrc.d/50_user.conf
Step 1: Access /usr/local/etc/torrc.d/50_user.conf to Add Bridges
|From Whonix 14 onwards, all user unique Tor configurations should be stored in /usr/local/etc/torrc.d/50_user.conf and not anywhere else. Note that Whonix will not modify /usr/local/etc/torrc.d/50_user.conf once it is created, therefore the user is responsible for adding or removing specific configurations in this file.|
Step 2: Edit /usr/local/etc/torrc.d/50_user.conf
|This step is the same on all Whonix platforms.|
Open /usr/local/etc/torrc.d/50_user.conf in an editor, then copy and paste the following text to enable the use of obfs2, obfs3 and obfs4 bridges.
UseBridges 1 ClientTransportPlugin obfs2,obfs3 exec /usr/bin/obfs4proxy ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy
Beginning with Whonix 14, meek_lite bridges can also be used. To use them, simply add one more line to the /usr/local/etc/torrc.d/50_user.conf. Notice that the bridge type is called meek_lite, not meek which is used in Tor Browser Bundle. 
ClientTransportPlugin meek_lite exec /usr/bin/obfs4proxy
Now add the bridge IP addresses you discovered in the section Finding a Bridge and Choosing the Right Protocol to the file.
Copy and paste those IP addresses to the very bottom of /usr/local/etc/torrc.d/50_user.conf, after the ClientTransportPlugin entries. Make sure to manually type the text "bridge" at the beginning of each line entry.
In the obfs3 and obfs4 examples below:
- Do not copy and paste this list of bridge entries to the torrc file. They will not work.
- Make sure to have already retrieved your own obfs3 bridges or better yet obfs4 bridges from The Tor Project.
- Use either the obfs3 or obfs4 protocol, not both.
- Capitalization in the torrc file matters. For example, bridges will not connect if you type "Bridge" instead of "bridge".
Obfs3 example text to add to /usr/local/etc/torrc.d/50_user.conf.
bridge obfs3 126.96.36.199:22321 4352e58420e68f5e40bf7c74faddccd9d1349413 bridge obfs3 188.8.131.52:38123 4352e58420e68f5e40bf7c74faddccd9d1349413 bridge obfs3 184.108.40.2063:62389 4352e58420e68f5e40bf7c74faddccd9d1349413
Obfs4 example text to add to /usr/local/etc/torrc.d/50_user.conf.
bridge obfs4 220.127.116.11:42086 0EEB10BF4B4FAF56D46E cert=oue8sYYw5wi4n3mf2WDOg iat-mode=0 bridge obfs4 18.104.22.168:43263 DD21A551767816A0C9495 cert=7qzS6KASquPvJU82Fm7qoJw iat-mode=0 bridge obfs4 22.214.171.124:10703 B3B8009D01BB7E5FDFAEC cert=4RaIqGiOytEXm6Hw iat-mode=0
meek_lite example text to add to /usr/local/etc/torrc.d/50_user.conf.
bridge meek_lite 0.0.2.0:2 B9E7141C594AF25699E0079C1F0146F409495296 url=https://d2cly7j4zqgua7.cloudfront.net/ front=a0.awsstatic.com
When /usr/local/etc/torrc.d/50_user.conf editing is finished, save and exit.
<Ctrl-X> --> press Y --> <Enter>
The sample text for a complete obfs4 torrc file is below. Check your file is similar, except for the specific bridge entries.
# This file is part of Whonix # Copyright (C) 2012 - 2013 adrelanos # See the file COPYING for copying conditions. # Use this file for your user customizations. # Please see /usr/local/etc/torrc.d/50_user.conf.examples for help, options, comments etc. # Anything here will override Whonix's own Tor config customizations in /usr/share/tor/tor-service-defaults-torrc # Enable Tor through whonixsetup or manually uncomment "DisableNetwork 0" by # removing the # in front of it. DisableNetwork 0 UseBridges 1 ClientTransportPlugin obfs2,obfs3 exec /usr/bin/obfsproxy managed ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy bridge obfs4 126.96.36.199:42086 0EEB10BF4B4FAF56D46E cert=oue8sYYw5wi4n3mf2WDOg iat-mode=0 bridge obfs4 188.8.131.52:43263 DD21A551767816A0C9495 cert=7qzS6KASquPvJU82Fm7qoJw iat-mode=0 bridge obfs4 184.108.40.206:10703 B3B8009D01BB7E5FDFAEC cert=4RaIqGiOytEXm6Hw iat-mode=0
Step 3: Enable Tor
Follow this procedure if it has not been previously completed.
Enable Tor using the whonix-setup-wizard.
Choose the Enable Tor option. Press next.
Step 4: Have /usr/local/etc/torrc.d/50_user.conf Changes Take Effect
Check Tor Network Connection is Using a Tor Bridge
Concerned bridge users can complete a simple check.
1. Open Arm as follows.
2. Use the right arrow button to navigate to page 2 of 5 in Arm.
3. If a bridge is in use, the circuit information will be similar to this.
192.168.0.1 UNKNOWN 1 / Guard
4. If a bridge is not in use, the circuit information will be similar to this.
IP Nickname 1 / Guard
The IP is the real IP (not 192.168.0.1) of the Guard, and the Nickname is the name of that Guard relay.
5. Exit Arm by pressing the following.
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 220.127.116.11, 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 doesn't 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 Hide Tor and Whonix from your ISP and/or local ISPs do not usually hinder connections to the public Tor network, then something simpler than Bridges can be tried.
The following will limit Tor to establish only connections to the public Tor network relays that listen on ports 80 and 443.
|For Whonix 14 and later releases, all unique Tor configurations should be stored in /usr/local/etc/torrc.d/50_user.conf. Users should not edit /etc/tor/torrc directly.|
Missing ClientTransportPlugin Line
When one is using.
bridge obfs4 ...:... ... cert=... iat-mode=0
But forgot to add the corresponding line.
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy
Then only a warning will be shown in the 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: Not recommended (see footnote). Use the provided obfs4 instructions instead. 
flashproxy: Not recommended (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.
- 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
- Tor manual: PublishServerDescriptor 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.
- meek_lite actually uses a different implementation of obfs4proxy. Forum discussion: https://forums.whonix.org/t/censorship-circumvention-tor-pluggable-transports/2601/3
ClientTransportPlugin fte exec /usr/bin/fteproxy --managed
fte example text to add to /usr/local/etc/torrc.d/50_user.conf.
fte is not yet supported in Whonix 13; wait for the Whonix 14 release. https://phabricator.whonix.org/T520
bridge fte 10.200.100.60:95128 4352e58420e68f5e40bf7c74faddccd9d1349413 bridge fte 300.100.300.80:23521 4352e58420e68f5e40bf7c74faddccd9d1349413
ClientTransportPlugin fte exec /usr/bin/fteproxy --managed
- 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
Quote intrigeri (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 [obfs4 support] instead.
- Old instructions: Deprecated#scramblesuit
- Flashproxy has been removed from Tor Browser. Therefore it can be considered deprecated.
Whonix Bridges wiki page Copyright (C) Amnesia <amnesia at boum dot org>
Whonix Bridges wiki page Copyright (C) 2012 - 2018 ENCRYPTED SUPPORT LP <email@example.com>
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.
https | (forcing) onion
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.