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 pool.sks-keyservers.net --recv A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89
gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -
  3. The Tor source code is distributed as .deb packages available over both HTTP and HTTPS. To use the HTTPS transport, the apt-transport-https package is required. Install it with:
    sudo apt install apt-transport-https
  4. Add the Tor deb package repositories to your APT source lists. This can be either be done by adding the following lines 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), or to a new file in the /etc/apt/sources.list.d/ directory. Be sure to replace stretch in the source configuration line with the codename for your Debian version (your codename can be found with the command lsb_release -a):
    deb https://deb.torproject.org/torproject.org stretch main
deb-src https://deb.torproject.org/torproject.org stretch main
  5. Now refresh your sources by updating your APT repository cache:
    sudo apt update
  6. 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:
    sudo apt install tor deb.torproject.org-keyring
  7. 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
  8. Build the dependent packages first:
    sudo apt build-dep tor
  9. Create a temporary directory where you can build the Tor package:
    mkdir /tmp/tor-debian-package
  10. Change into that directory:
    cd /tmp/tor-debian-package
  11. Get the Tor source code from the Tor Project’s APT repository:
    apt source tor
  12. Change into the downloaded Tor source code directory:
    cd tor-*
  13. Build Tor from the sources you downloaded, noting that superuser privileges are not required thanks to the fakeroot(1) command:
    debuild -rfakeroot -uc -us
  14. Leave the source directory:
    cd ..
  15. Finally, you can install the new package:
    sudo dpkg -i tor_*.deb
  16. Tor should now be installed and running. Confirm this with:
    sudo ss --listening --tcp --processes --numeric | grep tor

    This should return something like:
    LISTEN   0   128 127.0.0.1:9050   *:*   users:(("tor",pid=18746,fd=6))
  17. 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. The procedure for doing this varies depending on the version of the Onion service rendezvous protocol your Onion service is running. The two version in common use today are the (now deprecated) version 2 and version 3 Tor Onion service rendezvous protocols.

Configuring version 2 authenticated Onion service servers

Version 2 Onion service servers are configured 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.

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 version 2 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/
HiddenServiceVersion 2
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  # Send the signal yourself.
sudo systemctl reload tor # Or, tell systemd to send the signal (recommended).
  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 version 2 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/
HiddenServiceVersion 2
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  # Send the signal yourself.
sudo systemctl reload tor # Or, tell systemd to send the signal (recommended).
  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.

Configuring version 3 authenticated Onion service servers

Starting with Tor version 0.3.5.7, version 3 Onion services support the new client authorization scheme. This Tor version also makes version 3 Onion services the default for new HiddenServiceDir configuration blocks.

Unlike the version 2 protocol, the version 3 protocol is based on public/private keypairs rather than hashed cookie values that acted as passwords. This is good because it means Onion service operators do not need to know the private portion of a given client’s authentication credential, but can be more difficult for clients to set up on their own. Refer to the § Tor client of an authenticated Onion service section of this page for details regarding Tor client configuration. Another difference from the older version 2 protocol is that there is only one “mode” for version 3 Onion services (i.e., similar to version 2’s “stealth” authenticated Onion services), so configuring a version 3 Onion service server no longer uses the HiddenServiceAuthorizeClient directive.

Instead, an authorized_clients/ subdirectory within the Onion service directory is created when a version 3 Onion service starts up. Inside this directory, the Onion service operator should write one .auth file for each authorized client. The contents of these *.auth files should contain one line each, with three fields separated by colons (:):

  1. The first field is the keyword descriptor.
  2. The second field is the type of keypair used by the client. Tor currently only supports the x25519 descriptor key type.
  3. The third field is the public key generated by the client.

For example, for a client named alice, the Onion service’s authorized_clients/alice.auth file might have this content:

descriptor:x25519:SUCXD2A4YRK4JQ37QCIAQXGASQWVLFH45XENCC5YDZFR6RIT6ETA

Once received from the client, send Tor a SIGHUP to rescan the filesystem for authorized_clients/*.auth files:

sudo systemctl reload tor

Any Onion service with at least one valid .auth file will automatically require authorization for all incoming client connections.

Generating Tor version 3 Onion service client keys

Tor version 3 Onion services use X25519 keypairs for client authorization. Both the public and private keys for a given client must then be Base32 encoded and placed into a .auth (public key) file on the Onion service server and a .auth_private (private key) file on the client, respectively.

  1. Ensure you have OpenSSL 1.1 or greater, which provides the necessary cryptographic primitives:
    sudo apt update && sudo apt install openssl
  2. Ensure you have the basez package, which provides the necessary encoding and decoding utilities:
    sudo apt install basez
  3. Generate an X25519 private key using OpenSSL. This will produce a PEM-encoded private key file, private-key.pem:
    openssl genpkey -algorithm x25519 -out private-key.pem
  4. Calculate the public component from the X25519 private key using OpenSSL, producing the PEM-encoded public key file, public-key.pem:
    openssl pkey -in private-key.pem -pubout -outform PEM -out public-key.pem
  5. Convert the X25519 PEM-encoded private key bytes into a Base32 encoded string for use in your Tor client’s .auth_private file:
    cat private-key.pem | \
    grep -v " PRIVATE KEY" | \
    basez --base64pem --decode | \
    tail --bytes 32 | \
    basez --base32 | \
    tr -d '=' > some-onion.auth_private
  6. At this point, the some-onion.auth_private file contains only the private key bytes, but you will also need to prepend the Onion domain (without the .onion top-level domain), a colon (:), the keyword descriptor, another field-delimiting colon, and the key type keyword x25519, followed by a final colon. For example, if the Onion address for which this private key will be used to authenticate this client is p53lf57qovyuvwsc6xnrppyply3vtqm7l6pcobkmyqsiofyeznfu5uqd.onion, the final .auth_private file could be constructed like this:
    echo -n "p53lf57qovyuvwsc6xnrppyply3vtqm7l6pcobkmyqsiofyeznfu5uqd:descriptor:x25519:" | cat - some-onion.auth_private
  7. Finally, prepare the .auth public key file for the Onion service operator by performing a similar preparatory procedure:
    # Prepare the initial `.auth` file.
cat public-key.pem | \
    grep -v " PUBLIC KEY" | \
    basez --base64pem --decode | \
    tail --bytes 32 | \
    basez --base32 | \
    tr -d '=' > some-client.auth
# Prepend the Tor descriptor fields to the base32-encoded bytes in the `.auth` file.
echo -n "descriptor:x25519:" | cat - some-client.auth

After this procedure is complete, you will have four files: private-key.pem, public-key.pem, some-onion.auth_private, and some-client.auth.

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