- 1 Bridges: Description and When to Use Them
- 2 Finding a Bridge and Choosing the Right Protocol
- 3 How to Use Bridges in Whonix
- 4 Troubleshooting
- 5 Deprecated Tor Pluggable Transports
- 6 See Also
- 7 Footnotes
- 8 License
Bridges: Description and When to Use Them
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.
This may be a problem for users residing in certain countries. For instance:
- Tor use is blocked by censorship: Since all Internet traffic is routed through Tor, Whonix would be rendered useless for most activities except working offline on documents, etc.
- Tor use is dangerous or considered suspicious: Starting Whonix in the default configuration might land the user in serious trouble.
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.
Users facing one of the situations described above should consider using Tor bridges in Whonix. Prior to taking this step, please read The Tor Project's dedicated page about bridges to get a better understanding of bridges and their operation. Users should also learn how Obfsproxy works, since it is the application that Tor uses to connect bridges.
Bridges are not bullet-proof. Here is a reminder regarding 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 don't usually hinder connections to the public Tor network, then something simpler than Bridges can be tried. See #Better Connectivity without real Censorship Circumvention.
If Tor Use is Dangerous or Deemed Suspicious in your Location
The Tor Project's documentation on bridges mainly focuses on censorship circumvention i.e. overcoming attempts by ISPs or governments to block Tor use. If Tor use is dangerous or deemed suspicious in your location, then using bridges may be advisable to prevent identification as a Tor user.
Note: 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.
Additional Information and Recommendations
1. When Whonix starts for the first time, it won't 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.
2. Only use obfuscated bridges, since they are harder to identify than other bridges.
3. Less publicly known bridges are safer. Unfortunately, since some bridge addresses can be obtained by anyone from the Tor website or by email, adversaries can also get the same bridge information via the same means (and likely do). The Tor Project has some protection against adversary threats, but they are far from perfect.
For greater safety, ideally a trusted friend or organization in a different country would run a private obfuscated bridge for a user. In this case "private" means that the bridge is configured with the option PublishServerDescriptor 0.  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.
See also Hide Tor and Whonix from your ISP!
4. Avoid using a meek provider that also runs DNS core servers, like Google's (now defunct) bridge. Google sees forty percent of Tor Exits' DNS traffic and so using them as a bridge aids website fingerprinting attacks. 
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 (private) obfuscated bridges in Whonix.
Whonix does not yet include a wizard to assist in setting 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. The process is identical to the steps completed on a Debian platform because Whonix is based on Debian. Bridges are configured by simply editing /etc/tor/torrc within the Whonix-Gateway.
Step 1: Access /etc/tor/torrc to Add Bridges
Step 2: Edit /etc/tor/torrc
Note: This step is the same on all Whonix platforms.
Once inside /etc/tor/torrc, scoll all the way to the bottom of the file and copy and paste the following text.
UseBridges 1 ClientTransportPlugin obfs2,obfs3 exec /usr/bin/obfsproxy managed ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy
Now the bridge IP addresses you discovered in the section Finding a Bridge and Choosing the Right Protocol must be added to the file.
Copy and paste those IP addresses to the very bottom of /etc/tor/torrc, after the ClientTransportPlugin entries. Make sure to manually add 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 you 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. Bridges will not connect if you enter "Bridge" instead of "bridge" etc.
Obfs3 example text to add to /etc/tor/torrc.
bridge obfs3 184.108.40.206:22321 4352e58420e68f5e40bf7c74faddccd9d1349413 bridge obfs3 220.127.116.11:38123 4352e58420e68f5e40bf7c74faddccd9d1349413 bridge obfs3 18.104.22.1683:62389 4352e58420e68f5e40bf7c74faddccd9d1349413
Obfs4 example text to add to /etc/tor/torrc.
bridge obfs4 22.214.171.124:42086 0EEB10BF4B4FAF56D46E cert=oue8sYYw5wi4n3mf2WDOg iat-mode=0 bridge obfs4 126.96.36.199:43263 DD21A551767816A0C9495 cert=7qzS6KASquPvJU82Fm7qoJw iat-mode=0 bridge obfs4 188.8.131.52:10703 B3B8009D01BB7E5FDFAEC cert=4RaIqGiOytEXm6Hw iat-mode=0
When /etc/tor/torrc 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 /etc/tor/torrc.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 184.108.40.206:42086 0EEB10BF4B4FAF56D46E cert=oue8sYYw5wi4n3mf2WDOg iat-mode=0 bridge obfs4 220.127.116.11:43263 DD21A551767816A0C9495 cert=7qzS6KASquPvJU82Fm7qoJw iat-mode=0 bridge obfs4 18.104.22.168: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 /etc/tor/torrc Changes Take Effect
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 22.214.171.124, 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 don't 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.
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.
- Tor manual: PublishServerDescriptor
- Although there is evidence that website fingerprinting is more difficult to mount than previously thought. See: The Effect of DNS on Tor’s Anonymity
ClientTransportPlugin fte exec /usr/bin/fteproxy --managed
fte example text to add to /etc/tor/torrc.
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 - 2017 Patrick Schleizer <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.
Impressum | Datenschutz | Haftungsausschluss
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.