Friday, July 19, 2013

HOWTO: Tor2Web on Debian

What is Tor2Web?

Tor2Web is an open source software that allows the general public to browse Tor hidden services, which are servers running anonymously behind the Tor network. These servers could be web servers, email servers or any other services, and are normally accessed only via the Tor software, but if for some reason you cannot install it, or need a quick look, tor2web provides this kind of easy access via standard web browsers.

Tor's hidden services (HSs) usually look like this http://sx3jvhfgzhw44p3x.onion (Wikileak's HS), but with tor2web, you can create a general public proxy where people enter the HS like this or bind your tor2web node to a specific HS (yours or someone else's) so that when someone accesses your tor2web domain name, it will only view your specific HS.

In all cases, Tor2Web cannot be used alone. You still need a 2nd node that has the HS running on it. This guide will not cover how to setup a HS. You can refer to Tor's guide for that. Never run both the HS & tor2web on the same node!

Why Use Tor2Web?

Tor2Web is part of a bigger project called GlobaLeaks, but one can use tor2web to provide access to banned/blocked material or provide services anonymously, not related to whistle-blowing, like an anonymous chat service. Taking down the tor2web node doesn't affect the HS & it's always easy to bring up a new tor2web node.

Another reason is to simply hide your stuff. With news of governments snooping on everyone and everything, one doesn't feel safe anymore. They could use anything against you at any point in the future. So, by running a HS, you can run your own email server or file server, and not worry about some law enforcement goons seizing your hardware and disrupting your work, even if you're collateral damage (like when Mega Upload servers were seized, many other websites were also affected).

Of course, one cannot attain full anonymity without taking all possible precautions such as registering the host/VPS/domain name using Tor to not be tracked to you, paying for the services using Bitcoins, and SSH into your system from behind Tor.


  1. Debian Squeeze (6) or Wheezy (7)
  2. tor
  3. python2.7
  4. python-Twisted version 13.1.x
  5. tor2web
tor2web v3.0 uses Python Twisted as a webserver rather than a standalone webserver like Nginx.

Note: This guide has slight differences from the Tor2Web guide. Feel free to refer to both and modify as you please.

1) Debian

Some Virtual Private Server (VPS) providers do not support Wheezy, but tor2web needs packages only available in Wheezy. You will have to install a lot of packages from Wheezy to be able to use python2.7 and its requirements, but you don't need to run a dist-upgrade. So, in the end, your distribution will still be Squeeze.

If you're already running Wheezy, then you can simply ignore the parts about adding Wheezy's specific repositories and removing them later.

1.1) Initial Sources

Modify the file /etc/apt/sources.lst with your favorite editor (vi, vim, emacs, nano, pico)
deb             squeeze main contrib non-free
deb    squeeze/updates main contrib non-free
deb squeeze-backports main
deb squeeze-backports-sloppy main
deb squeeze main
deb /

Replace "squeeze" with "wheezy" if that's what you're running, but ignore the backports lines as you don't need them.

Your sources above could be from a different mirror for Debian's packages. Always use the closest mirror to your host.

1.2) Upgrading the box

You need to be root to run these commands, or have "sudo" installed with the correct privileges.

The last command will upgrade your host to the latest packages of your distribution. It's always good to stay up to date and avoid buggy packages.

sudo apt-get update
sudo apt-get upgrade

1.3) Add Wheezy repositories

Modify the file /etc/apt/sources.lst with your favorite editor (vi, vim, emacs, nano, pico) again, and add Wheezy repos
deb             wheezy main contrib non-free
deb    wheezy/updates main contrib non-free

2) Tor

Import Tor's keyring to authenticate the packages and install Tor.

Note: If you're running as root, or you don't have sudo installed, simply remove "sudo" from the 2nd command above.

sudo apt-get update
sudo apt-get install debian-keyring debian-archive-keyring
sudo apt-get update

gpg --keyserver --recv 886DDD89
gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -

sudo apt-get install
sudo apt-get update
sudo apt-get install tor

Now you should have tor installed. You check the service status using: service tor status

3) Python

Check if you already have python installed and which version:
python --version
python2.7 --version

Now to install python and some of its fellow packages:
sudo apt-get install -t wheezy python2.7 python-pip python-dev wget ca-certificates

If you're running Squeeze, you'll be asked to also install glibc, and during the install you'll be asked to restart the services associated with it. If this is a fresh host, it's safe to say "Yes" if it's a production box with services running live, choose "No." This will also upgrade & install a lot of packages from Wheezy, as python-pip is dependent on them.

If you have multiple versions of python installed (2.6, 2.7 & 3.x), you'll need to change the default to 2.7:
update-alternatives --install /usr/bin/python python /usr/bin/python2.7 10

If you need to change the default later on, run this:
update-alternatives --config python

4) Tor2Web

First to grab the tor2web requirements and install them:
sudo pip install -r requirements.txt
sudo apt-get install tor2web
sudo service tor2web status
sudo service tor2web stop

Now that you have tor2web installed, and stopped, you need to create certificates for session encryption between the tor2web node and the user's browser.

when running the 2nd openssl command, make sure the Common Name (FQDN) is the same as the domain name that will be used to access the tor2web server. If you're planning to access it by IP, use the IP here.

The 3rd command will create a certificate valid for a year (365 days). If you want it to live longer, increase the number of days.

The last command will take a long time to generate the file. If your computer is faster than your host, run it on your computer then copy it there.

cd /home/tor2web/certs/
openssl genrsa -aes256 -out tor2web-key.pem 4096
openssl req -new -key tor2web-key.pem -out tor2web-csr.pem
openssl x509 -req -days 365 -in tor2web-csr.pem -signkey tor2web-key.pem -out tor2web-intermediate.pem
openssl dhparam -out tor2web-dh.pem 4096

Don't change the file names as tor2web is coded to use them as is.

The certificates created will require you to enter the password whenever you [re]start the tor2web service. This is good in case your server was hijacked & your certs were taken, they cannot be used unless someone knows the password (which shouldn't be the same as the root password!).

If you don't care, then you can create a certificate without a password:
openssl rsa -in tor2web-key.pem -out tor2web-key.pem.insecure
mv tor2web-key.pem
mv tor2web-key.pem.insecure  tor2web-key.pem

5) Configuring Tor and Tor2Web

Limit tor to the local host IP and prevent external connections, by modifying /etc/tor/torrc and add this line:

Copy the example file into a new one:
cp /etc/tor2web.conf.example /etc/tor2web.conf

Modify /etc/tor2web.conf
nodename = whatever you want here. It can be the IP since it's unique

listen_ipv4 = IP of your VPS
listen_ipv6 = IP of your VPS, if you want to use IPv6
Change these to the IPs. If you don't want to bind by IPv6 or IPv4, comment the line out by adding a # sign at the beginning of the line. One of them must be present.

listen_port_http = 80
listen_port_https = 443
You cannot comment out http port, as tor2web will automatically redirect to https, but you can change the default ports.

basehost = this should be the root domain name ( not or any subdomain, unless you happen to be running behind a subdomain). It can also be an IP. If you do not use the exact name/IP that the tor2web service will be accessed from, tor2web will not function.

Sockshost =
socksport = 9050
These should match the SocksPort config in /etc/tor/torrc file.

cipher_list = DHE-RSA-AES256-SHA
I do not trust the others, as DSS is not quite common and is only used by Microsoft for some reason, and RC4 can be misused at times.

onion = hidden service name: name.onion (jntlesnev5o7zysa.onion - piratebay's HS)
blockcrawl = True
Using mode Translation means you'll bind tor2web to a specific hidden service defined in the onion option. If you want tor2web to function as a general proxy, leave the default options. The blockcrawl option blocks search engines.

I commented out the email notification options as I don't really care about notifications.

#mirror = ...
comment it out unless you happen to be running multiple tor2web nodes and want this one to list them in the banner.

6) Clean Up & Run the Services

If you're running Squeeze, remove the Wheezy main repo and only keep the security one to prevent upgrading the entire host to Wheezy.

Now run the tor2web service: (it will run tor for you)
service tor2web restart

You'll be asked to input the password of the certificate every time you [re]start the service, unless you have removed the password. Read the caution about it above.

It's always a good idea to NEVER ssh into your hidden service node using its real IP from your tor2web node. Should your tor2web node ever get seized or compromised, you do not want anyone looking at the logs or history to find the IP of your hidden service, as it won't hidden anymore.

7) Help

If you need my help setting up a HS, never contact me with your personal email and do not ask for help in the comments section. Create a fake email or use I don't want to know why you're setting it up or what kind of material you're hosting. The less I know, the better for the both of us.

You can ask anonymously on my blog about generic config or a problem you're having, but if you need specific help, send me an email with no details and then we'll agree on how to proceed.

8) Sources