Chapter 2. Circumventing Censorship with a Tor Bridge

In this chapter, you'll configure your BeagleBone Black (BBB) to run a bridge in the Tor network. This bridge will allow you and others to access the Internet more anonymously and provide an anti-censorship gateway. We'll add a simple hardware control interface to BBB so that we can see and adjust the bandwidth usage of the bridge in real time. We'll call this project BeagleBridge.

This chapter will discuss the following topics:

• An introduction to Tor

• The difference between a Tor relay and bridge

• Obfuscated Tor proxies

• How to download and install Tor on BBB

• How to configure BBB as a Tor bridge running an obfuscated proxy

• How to add hardware controls to adjust the bridge from a front panel

Learning about Tor

In this project, you will learn how to use Tor, a tool and network designed to protect your anonymity online. Tor originally developed from research, sponsored by the U.S. Naval Research Laboratory, on onion routing (Dingledine, Mathewson, and Syverson, 2004). In onion routing, the client builds a circuit of nodes in an overlay network, which is a network built on top of an existing network. The Tor network is an overlay network that runs on the Internet, although it can run on separate networks. The client sends a message to each node, which is specifically encrypted for that node, asking the node to send it to the next node in the circuit. Each node peels back a layer of encryption and forwards the result to the next hop in the circuit, and hence, the onion analogy. The last node contains the client's actual message, which is forwarded to the destination server.

Onion routing provides anonymity because the destination server does not know the IP address of the client...

Installing Tor on BBB

The instructions provided in the following sections are geared towards the user running BeagleBridge on a home network. The bridge will consume some otherwise unused bandwidth and donate it to the Tor network. You should check your ISP's Terms of Service before running a server to see whether it's permitted. Also, you'll need to configure port forwarding from your home router. As there are numerous devices, each with their own configuration mechanism, you should consult your router's manual on how to enable port forwarding.

Installing Tor from the development repository

The Tor images in the official Debian repository are not as up to date as those from the Tor Project. We'll use the Tor Project's development repository to retrieve the latest software. This is especially important when you are running a bridge, as the bridge and the pluggable transport software are updated frequently.

Note

The latest instructions as well as the latest GPG fingerprint can be found on the...

Understanding Tor exit policies

A bridge, by definition, is the entry point to the Tor network. As such, the exit policy, which will allow traffic to exit the Tor network from the server, should be the following:

ExitPolicy reject *:*

This prevents your server from running as an exit node. If you do decide to run an exit node, be prepared to receive some complaints from your ISP if you are running it on a home network. This is why the Tor Project and the Electronic Frontier Foundation recommend that you don't run an exit relay on a home network. A thorough, legal FAQ prepared by the Electronic Frontier Foundation can be found at https://www.torproject.org/eff/tor-legal-faq.html.en.

Setting bridge-specific settings

There are three bridge specific settings: BridgeRelay, ServerTransportPlugin, and ExtORPort. The BridgeRelay setting is the key setting that defines your relay as a bridge. Your bridge's meta information is published in the bridge database instead of the public directory server, which keeps your bridge's IP less public than a Tor relay's IP address. ServerTransportPlugin defines which pluggable transport proxy your bridge supports. Currently, ScrambleSuit is the latest promising pluggable transport technology. However, obfs3, which is the transport enabled in our bridge configuration example, is slightly more mature and it is the more conservative recommendation. Lastly, ExtORPort allows the gathering and reporting of bridge statistics to the Tor Project.

Note

For those who are interested in running the ScrambleSuit obfsproxy, take a look at the following link on how to configure your bridge: https://lists.torproject.org/pipermail/torrelays/ 2014-February/003886...

Starting your new Tor bridge

With the time updated and the configuration set, it's time to turn on the bridge. At the moment, the bridge should be able to make a connection to the Tor network, but it will not be able to accept incoming connections as we have not yet configured port forwarding from your router. However, the obfsproxy port is randomly assigned, so we need to run the bridge first to find the port. Restart the Tor service with the following command:

sudo service tor restart

Next, let's check the log to see whether Tor has started correctly:

tail -n 20 /var/log/tor/notices.log

If you see something like the following, then your Tor client's behavior is working:

Mar 25 21:37:43.000 [notice] Tor has successfully opened a circuit. Looks like client functionality is working.
Mar 25 21:37:43.000 [notice] Bootstrapped 100%: Done.

Enabling port forwarding

We know that we need to forward port 9001, as it is the ORPort, but we need to know which port the obfsproxy software runs on. This will be logged in the same file and will be discovered by searching the Tor log with the following command:

grep obfs3 /var/log/tor/notices.log

The previous command should yield the following search result:

Mar 05 01:56:04.000 [notice] Registered server transport 'obfs3' at '0.0.0.0:59519'

The obfsproxy port for our obfs3 service is on 59519. From your home router, configure port forwarding from 9001, and configure port forwarding from 59519 from your external IP to BBB. It will also help if you give your BBB a static internal IP. Consult your router's manual for directions. Alternatively, you can specify the port with the following line in the /etc/tor/torrc file:

ServerTransportListenAddr obfs3 0.0.0.0:xxxx

Replace the x's with the desired port address. However, it's best to let obfsproxy pick a random address; otherwise, the Tor Project...

Adding physical interfaces to the bridge

Now you have a Tor bridge running and you can stop here. If you do, you'd be missing out on the ability to combine software with custom hardware on BBB. Our BBB Tor bridge currently has no visual feedback, so it's not obvious that it's working. Also, the only means to control the bridge is to log in to BBB over SSH and manipulate the configuration options. The Tor bridge is an appliance and it needs appliance controls. In this section, we'll add a front panel, which will give us an easy method to control the bridge's bandwidth and a quick indicator to know that the software hasn't crashed. In the following section, we'll add the software to interface with our bridge and control the hardware.

Note

If you decide to run a Tor relay, there are websites such as Tor atlas (https://atlas.torproject.org/) that will produce bandwidth graphs and display other information about your relay. Another tool that will also display information about your bridge is Globe...

Determining your bandwidth with speedtest-cli

In order to adjust the bandwidth rate, we first need to know how much bandwidth our bridge has. Fortunately, there is a nice script to run a speed test from your command line that is appropriately called speedtest-cli. This is installed with the following command:

sudo pip install git+https://github.com/sivel/speedtest-cli.git

Run the test with the following command:

speedtest-cli --simple > speedtest.txt

If you inspect the output file, you should see something like the following:

Ping: 107.686 ms
Download: 28.23 Mbit/s
Upload: 5.37 Mbit/s

We'll use the results in this file as the basis for our bandwidth adjustment. At the moment, we only need to remember its location for later use.

Controlling the bridge with the Stem library

The bridge is controlled using the Stem library, which communicates with the Tor process over the Tor control protocol. The setup is managed in the BeagleBridge class. After establishing a connection with the Tor process, this class registers two event listeners for the Bandwidth and Configuration changed event. The bandwidth event is triggered each second and reports, via the print_bw callback, the bytes used in the last second. This information is used to draw the bandwidth graph. The following callback function shows how the callback interacts with the LCD:

def make_bw_callback(test,lcd):
  '''Returns a callback function for the bandwidth event'''
  def print_bw(event):
    '''Obtains the bandwidth used from the last second from the
       bridge, normalizes it to the total bandwidth, and draw 
       that information to the display'''
    up = int(test.get_up_ratio(event.written))
    down = int(test.get_down_ratio(event.read))
    lcd.display_graph...

Connecting to your obfuscated bridge

With BeagleBridge, you have your own entry point in the Tor network. You can download and install the Tor browser and configure it to use your bridge. This is useful anytime you find yourself on a restricted or hostile network and want to access the Internet more anonymously. However, if you use your BeagleBridge, passive attackers could learn the IP address to which you are connecting, which happens to be your home network. The traffic is obfuscated, but it may look suspicious over time. It might be better to use a random bridge address obtained via Tor. Even if you don't directly connect to your own bridge, your bridge is helping to contribute resources to the Tor network, which helps everybody access a censor-free Internet. To connect to your bridge, launch the Tor browser and click on Open Settings as it starts up. Then, answer with a Yes to questions about whether your connection is censored. Select Enter Custom Bridges and enter your bridge as follows...

Continuing with Tor-related projects

This project is just the first step in learning Tor. If you want to route more traffic with BBB, you can switch from a bridge to a public relay. Relays receive more traffic but are also more public. Your IP address will be listed as a public bridge, and some websites will refuse to serve you content even if you are running a nonexit relay.

You can also run a Tor hidden service on the BeagleBone. Using Tor with a client helps to anonymize your IP address to a server, but a Tor hidden service hides the server's IP address from a client. It would be an interesting project for a BeagleBone if you had a service that you want accessible only through Tor.

Hardware-wise, consider placing the BeagleBone and front panel in a dedicated enclosure. See whether there is a local hackerspace around you, and they may be able to help you make a nice laser-cut enclosure! If you don't have a laser cutter, you can use a SparkFun Electronics box like the one in the following...

Summary

In this chapter, you learned about Tor and how to circumvent Internet censorship by running a Tor bridge on BBB. We've also shown how to add some basic hardware controls to BBB in order to create a front panel interface. Lastly, through some Python code, we were able to tie the hardware controls and the Tor bridge together.

In the next chapter, we'll take a closer look at specialized cryptographic hardware available for BBB and show you how to use each of these devices.