CS294S Research Project in Computer Security

Flash Badge

David Fifield, Nate Hardison, Jonathan Ellithorpe


  1. Description
  2. How it Works
    1. High Level Overview
    2. Some Technical Details
  3. How to Use It


The Flash Badge project aims to develop a system whereby users with access to the Tor relays can help other users without access to connect to the Tor system by simply leaving a flash program running in their browser. Web sites who install the Flash Badge on their web pages enable visitors to become ephemeral Tor proxies. The proxy is active while the visitor is viewing the page.

How It Works

Figure 1

High Level Overview

The client (bottom of figure 1) is unable to access the Tor network directly and needs help. The proxy (implemented as flash running in the browser), however, does have access to Tor and wants to help the client.

To get help from the proxy, the client first registers itself (IP address and port) with the facilitator and then waits. Meanwhile, the proxy continuously queries the facilitator for clients to help. When the proxy gets a new client from the facilitator it makes two outgoing connections: one to the client, and the other to a Tor relay. Clients then use the proxies to which they are connected to access the Tor network.

To make using the system as simple as possible for the client, only a slight modification of the Tor configuration file and a script running in the background are required. For users wanting to help clients in need, merely loading a page containing the flash program is all that's necessary.

Some Technical Details

To make such a system "just work" several technical challenges needed to be overcome.

1. NAT traversal

Many clients find themselves behind NATs, preventing proxies from connecting to them from the outside. To get around this problem, a NAT traversal solution called RTFMP was employed. It uses a centralized "cirrus" server to exchange external IP and port information between proxy and client, allowing them to "punch through" each other's NATs.

2. Flash and outgoing connections

For security reasons, flash programs are not allowed to communicate with just anything on the Internet. To make an outgoing connection, the remote destination must serve a cross-domain policy specifying to the connecting flash program that it is allowed to connect. Therefore, cross-domain policies must be served on each of the facilitator, client, and Tor relay components.

3. Facilitator access

The client may find that they are unable to access the facilitator directly (possibly for the same reason(s) they can't access Tor relays directly). To get around this problem, and noting that client to facilitator communication is relatively infrequent and lightweight, multiple popular and publicly available Internet services are used for client and facilitator indirect communication. This solution is also employed to prevent loss of access to the "cirrus" centralized server used in NAT traversal.

4. Simplicity for Tor users

To make everything simple for Tor users, a "connector" python script is run in the background to act as a SOCKS proxy for Tor and takes care of everything necessary to use the flash proxy system. This includes registering with the facilitator (indirectly using popular web services), performing NAT traversal, and serving a cross domain-policy for a connecting proxy. All a Tor user needs to do to use the system, therefore, is to run the connector script and set the connector to be a SOCKS proxy for Tor. The configuration uses the Tor Socks4Proxy option, which requires the unstable release of Tor, version or later.

How to Use It

  1. Download this connector program.

    python connector.py -f tor-facilitator.bamsoftware.com
  2. Stop Tor, if it is already running.

  3. Add these lines to your torrc file:

    UseBridges 1
  4. Start Tor (giving it the path to torrc if necessary).

    tor -f torrc

    Once the output shows bootstrapping complete, you can connect as normal.

    If you get the messages

    [notice] Bootstrapped 10%: Finishing handshake with directory server.
    [notice] no known bridge descriptors running yet; stalling
    try deleting the files in ~/.tor and /var/lib/tor and restarting Tor. This seems to be caused by Tor caching the fact that a bridge is down and not trying to reconnect to it.

Using an SSH tunnel

The proxy is blind to the type of traffic that passes through it. You can connect through an SSH tunnel instead of Tor. SSH demo page.

  1. Start the Flash program, giving it a relay parameter pointing to your SSH server.


  2. Start the connector.

    python connector.py -f facilitator_addr:facilitator_port
  3. Start SSH, giving it a proxy command to connect through the connector.

    ssh -v -N -D 1080 ssh_addr -p ssh_port \
        -o 'ProxyCommand=socat - SOCKS4A:localhost:dummy:0,socksport=9001'

Source code

git clone http://www.bamsoftware.com/git/flashproxy.git

The master branch contains the code seen here. The rtmfp branch contains NAT traversal code using an Adobe RTMFP server.