Tor

Guides on configuring Tor clients and servers, including Onion service ("Location-Hidden Services") for various purposes.

Tor is an anonymizing overlay network known as a mix network (or "mixnet" for short). It sits in between your application(s) and your network connection, providing an extra layer of protection between your (self-hosted) services and the public Internet. Tor is useful for privacy-enhanced communication, cryptographic naming services (through its Onion service or "hidden service" features), and firewall traversing capabilities.

Installing

To install tor “the easy way” on Debian-derived GNU/Linux distributions:

sudo apt update && sudo apt install tor

However, the version of Tor in your Operating System distribution’s package repositories may not be current. As Tor is a critical piece of essential security tooling, we strongly recommend you ensure that the Tor you use is an up-to-date version. This often means you will need to compile the Tor source code yourself.

Installing Tor from source on Debian

The Tor Project maintains simple instructions for building Tor from source, which work reliably on most Debian-derived GNU/Linux Operating Systems. These instructions are duplicated here in our own voice, but refer to the primary source at the linked page for the most up-to-date information.

  1. Install the GnuPG Directory Manager, needed by some versions of GnuPG 2:
    sudo apt install dirmngr
    
  2. Import the Tor Project’s GPG keys to your keyring:
    gpg --keyserver keys.gnupg.net --recv A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89
    gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -
    
  3. Then add this line to the beginning of your /etc/apt/sources.list file (that is, list it at the very top of the file so that it is processed first). Be sure to replace stretch in the source configuration line with the codename for your Debian version:
    deb-src http://deb.torproject.org/torproject.org stretch main
    
  4. Now refresh your sources by updating your APT repository cache:
    sudo apt update
    
  5. The Tor Project also provides a Debian package (.deb file archive) to help you keep their GPG signing key current. It is recommended you use it, but it is not required. Install it with:
    apt install deb.torproject.org-keyring
    
  6. Install the necessary dependencies to build your own .debs and the packages needed to build Tor itself:
    sudo apt install --no-install-recommends build-essential fakeroot devscripts
    
  7. Build the dependent packages first:
    sudo apt build-dep tor
    
  8. Create a temporary directory where you can build the Tor package:
    mkdir /tmp/tor-debian-package
    
  9. Change into that directory:
    cd /tmp/tor-debian-package
    
  10. Get the Tor source code from the Tor Project’s APT repository:
    apt source tor
    
  11. Change into the downloaded Tor source code directory:
    cd tor-*
    
  12. Build Tor from the sources you downloaded, noting that superuser privileges are not required thanks to the fakeroot(1) command:
    debuild -rfakeroot -uc -us
    
  13. Leave the source directory:
    cd ..
    
  14. Finally, you can install the new package:
    sudo dpkg -i tor_*.deb
    
  15. Tor should now be installed and running. Confirm this with:
    sudo ss --listening --tcp --processes --numeric | grep tor
    
  16. Clean up after yourself if you wish to maintain a tidy working directory. :)

From here, you can administer Tor and configure your applications to use it as you normally would. For more information, refer back to the Tor for UNIX installation manual.

Updating Tor from source

You should check for updated versions of the Tor source code at regular intervals, or subscribe to the tor-announce mailing list, where announcements of newly released versions of the Tor source code are broadcast. When you learn that a new version is available, repeat the above procedure to upgrade your Tor installation to its latest version in order to continue obtaining security patches and feature enhancements.

Configuring

This section describes various configurations for Tor. A single Tor instance can act as a client and a server at the same time. Unrestricted Internet access will provide you with many references, so this section is merely intended as a portal where other resources are deemed sufficient. If you do not have uncensored access to the Internet, use the Tor Browser instead of your system’s default Web browser to access the resources linked here.

Tor as an Onion service server

See Tor Project: Onion Service Configuration Instructions.

Tor as an authenticated Onion service server

Tor servers acting as Onion services can require Tor clients to supply client-side authentication credentials (essentially, a client-provided “password”) before they will service requests. These credentials are independent of, and possibly supplemental to, any other authentication mechanism enforced by the given service application itself. Tor servers behaving in this manner are configured as authenticated Onion services, and Tor clients must be pre-configured with appropriate access credentials in order to connect to them.

You can (and, probably, should) configure your Onion service to require clients to authenticate themselves by adding the HiddenServiceAuthorizeClient Tor configuration directive, described in the Tor manual, to your Tor server’s torrc file. Authenticated Onion services that are using version 2 of the Tor Onion service ("rendezvous") protocol can be configured in one of two modes. These modes are basic or stealth.

Note: As of February 2018, client authentication using version 3 of the Onion service ("rendezvous") protocol has not been implemented by Tor developers. Therefore, this section only describes version 2 of the relevant specification. Version 2 is the default version for all Tor servers acting as Onion service servers.

An authenticated Onion service configured in the basic mode has a single .onion address, whereas an authenticated Onion service configured in the stealth mode generates a unique .onion address for each client. The drawback is that stealth Onion services can have a maximum of 16 unique .onion address and authentication cookie pairs, whereas a basic Onion service can generate as many client authentication cookies as needed. Nevertheless, using unique .onion addresses for each client ensures that, should a given client accidentally expose their Onion’s address (for example, by typing the Onion address into a Web browser other than the Tor Browser), no other client is implicated in the use of the same Onion service. For this reason, prefer stealth Onion services unless you have a need to service more than 16 clients with a given Tor server.

Authenticated basic Onion service server

Do this to add basic client authentication enforcement to your Tor Onion service:

  1. Add a third line in addition to the HiddenServiceDir and HiddenServicePort directives in your Tor server’s torrc file. Be sure to replace alice and bob in the configuration snippet below with names for the authorized clients you wish to service.
    HiddenServiceDir /var/lib/tor/hidden_service/
    HiddenServicePort 80 127.0.0.1:8080
    HiddenServiceAuthorizeClient basic alice,bob
    
  2. Verify that your configuration changes are syntactically valid:
    sudo -u debian-tor tor --verify-config # Run `tor(1)` as its own user, never as `root`.
    
  3. Tell Tor to reload its configuration file by sending the Tor daemon process a HUP signal:
    sudo killall -SIGHUP tor
    
  4. Acquire the authorization credentials for a given client, such as alice:
    sudo grep "alice$" /var/lib/tor/hidden_service/hostname
    
  5. Using a secure, out-of-band channel, distribute the resulting access credentials to the entity (human user, or machine) named alice, who must now configure their Tor client as described in Tor client of an authenticated Onion service in order to be granted access to the Onion service thusly configured.

Authenticated stealth Onion service server

Do this to add stealth client authentication enforcement to your Tor Onion service:

  1. Add a third line in addition to the HiddenServiceDir and HiddenServicePort directives in your Tor server’s torrc file. Be sure to replace alice and bob in the configuration snippet below with names for the authorized clients you wish to service.
    HiddenServiceDir /var/lib/tor/hidden_service/
    HiddenServicePort 80 127.0.0.1:8080
    HiddenServiceAuthorizeClient stealth alice,bob
    
  2. Verify that your configuration changes are syntactically valid:
    sudo -u debian-tor tor --verify-config # Run `tor(1)` as its own user, never as `root`.
    
  3. Tell Tor to reload its configuration file by sending the Tor daemon process a HUP signal:
    sudo killall -SIGHUP tor
    
  4. Acquire the authorization credentials for a given client, such as alice:
    sudo grep "alice$" /var/lib/tor/hidden_service/hostname
    
  5. Using a secure, out-of-band channel, distribute the resulting access credentials to the entity (human user, or machine) named alice, who must now configure their Tor client as described in Tor client of an authenticated Onion service in order to be granted access to the Onion service thusly configured.

Tor client of an authenticated Onion service

See AnarchoTechNYC: Connecting to an authenticated Onion service, a Tor client configuration guide written in simple language providing instructions for laypeople regarding how to connect to authenticated Onion services.

Hardening

TK-TODO

Configure system so gethostbyname() returns the Onion address, not localhost

TK-TODO: See github.com/alecmuffett/the-onion-diarie...

Provisioning

The Anarcho-Tech collective provides an Ansible role for provisioning a Tor server that runs on a Raspberry Pi. It can be installed in your local $ANSIBLE_ROLES_PATH (see Ansible Configuration Settings) for use with an Ansible project with:

ansible-galaxy install https://github.com/AnarchoTechNYC/ansible-role-tor/archive/master.tar.gz