The following is the GNU All-permissive License as recommended in https://www.gnu.org/licenses/license-recommendations.en.html

Copyright (C) 2024 Free Software Foundation sysadmin@fsf.org

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

Contributions are welcome. See https://savannah.gnu.org/maintenance/fsf/.

Create an Onion Service

[[!toc levels=3]]

[problem] - potential duplicate page

How Onion Services works

Below here is a schema of Onion Services working.

Onion Services overview schema

Briefly:

  1. You want to create an Onion Service. You connect your Onion Service to the Tor network. Your Onion Service establishes a connection through an anonymized circuit (Tor relays) to three introduction points to be reachable. Your Onion Service is hidden and protected itself behind the Tor network.

  2. For a client access to your Onion Service, your Onion Service creates an Onion Service descriptor. This descriptor contains a list of introduction points, next It's signed this with the Onion Service's identity private key. The identity private key used here is the private part of the public key that is encoded in the Onion Service address. Then the Onion Service publishes the descriptor to a distributed hash table (also called Directory) with still an anonymized circuit.

  3. Let's say that the client knows your Onion address. To visit your Onion Service, the client connects to the Tor network with Tor Browser. After the client contact the distributed hash table to get the signed descriptor of your Onion Service to know the three introduction points.

  4. When the client receives the signed descriptor, thanks to the public key embedded in the onion address of your Onion Service, It can verify the signature of the descriptor. It permits to be sure you connect to the real Onion Service and trust the introduction points.

  5. Now the client knows the introduction points to contact your Onion Service, it before determines a Tor relay which becomes a rendez-vous point. Next it sends to the rendez-vous point a secret string called "one-time secret". This secret string will be used later during the meeting between the client and your Onion Service. Then the client sends the rendez-vous point address as well as the secret to your Onion Service through the Tor network and one of three introduction points to ask the Onion Service about this meeting and establish a connection.

  6. When the introduction points receives the rendez-vous point as well the secret string from the client, It passes to your Onion Service and the latter does an all of verifications process to decide if it can trust the client or not.

  7. If your Onion Service trusts the client, It connects to the rendez-vous point via the Tor network and finally It sends the secret string's client to the rendez-vous point. To conclude the rendez-vous point compares the secret string between the client and the Onion Service. If it matches, it creates a connection between the client and your Onion Service and works as a relay. The connection is composed of six relays, three from the Onion Service to the rendez-vous point and three relays where the third is the rendez-vous point for the client.

How to create an Onion Service

There are few steps to create an Onion Service.

1. Open these ports on your firewall: - 443/tcp out toward Tor repository servers, to permit a connection to the Tor repository via HTTPS and download the tor package as well as keyring. - greater than 1024/tcp out toward anywhere, to permit your Onion Service connects to 3 introduction points, a distributed hash table (directory) server and a rendezvous point.

2. Install Tor on your server. According your operating system, the way to install Tor can be different. Here are the steps for a Tor installation on Trisquel. - You must know your CPU architecture. $ dpkg --print-architecture. * Only three CPU architecture type are supported: amd64, arm64 or i386.* - Install apt-transport-https to enable all package managers using the libapt-pkg library to access metadata and packages available in sources accessible over https. # apt install apt-transport-https. - Go to /etc/apt/sources.list.d/ and create a file named tor.list. It permits to enable new repositories, in this case Tor repositories. Then fill this file by the following terms:

deb     [signed-by=/usr/share/keyrings/tor-archive-keyring.gpg] https://deb.torproject.org/torproject.org <DISTRIBUTION> main
deb-src [signed-by=/usr/share/keyrings/tor-archive-keyring.gpg] https://deb.torproject.org/torproject.org <DISTRIBUTION> main

Where <DISTRIBUTION> must be replaced by your Operating System codename. Run this command to know the latter.

# grep -i "UBUNTU_CODENAME" /etc/os-release

With this example the result is focal, so replace <DISTRIBUTION> by focal. - Then add the gpg key used to sign the packages by running the following command. # wget -qO- https://deb.torproject.org/torproject.org/A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89.asc | gpg --dearmor | tee /usr/share/keyrings/tor-archive-keyring.gpg >/dev/null - Now install Tor and tor debian keyring.

# apt update
# apt install tor deb.torproject.org-keyring

3. Have a working web server. You can use for example Apache or Ngnix as a web server. You must configure your server to run your website on localhost:80. You can test your configuration as well as your website in this way:

  • To test the Apache configuration: # apache2ctl -t
  • To test the virtual host configuration: # apache2ctl -t -D DUMP_VHOSTS
  • To test your website, open a web browser and connect to http://localhost/ from your server.

4. Configure Tor. To configure Tor, edit the torrc file. To find it run this command: # find / -type f -name "torrc" 2> /dev/null Then add these lines to set up an Onion Service.

HiddenServiceDir /var/lib/tor/my_website/
HiddenServicePort 80 127.0.0.1:80

The HiddenServiceDir line specifies the directory which should contain information and cryptographic keys for your Onion Service.

The HiddenServicePort line specifies a virtual port (that is, the port that people visiting your Onion Service will be using), and in the above case it says that any traffic incoming to port 80 of your Onion Service should be redirected to 127.0.0.1:80 (which is where the web server is listening).

Note, it's recommended to run Onion Services over Unix sockets instead of a TCP socket. To avoid leaking an Onion Service to a local network. You need to replace the HiddenServicePort line by HiddenServicePort 80 unix:/var/run/tor-my-website.sock

5. Restart Tor and check if it works. Restart Tor, # systemctl restart tor. If Tor starts up again, great. Otherwise, something is wrong. First look at your logfiles for hints.

6. Test your Onion Service.

The Onion address of your Onion Service is available in this file: /var/lib/tor/my_website/hostname. With Tor Browser, try to access to your Onion address.

7. And after ?

It's mandatory to follow this guide of Best Practices for Hosting Onion Services, you must read it and apply it for secure reasons.

If you plan to keep your service available for a long time, you might want to make a backup copy of the private_key file (available in /var/lib/tor/my_website/).

Secure an Onion Service

To secure your Onion Service as well as your server, you must follow this guide from Tor website.

  • Basic recommendations, click here.
  • To secure your server, click here.
  • To improve the security of your Onion Service with Vanguards, click here.
  • To scan your Onion Service to find any vulnerabilities, click here.