Onion services are services that can only be accessed over Tor. Running an Onion Service gives your users all the security of HTTPS with the added privacy benefits of Tor Browser.

Why Onion Services?

Onion services offer various privacy and security benefits to their users.

Location hiding

An Onion Service's IP address is protected. Onion services are an overlay network on top of TCP/IP, so in some sense IP addresses are not even meaningful to Onion Services: they are not even used in the protocol.

End-to-end authentication

When a user visits a particular onion, they know that the content they are seeing can only come from that particular onion. No impersonation is possible, which is generally not the case. Usually, reaching a website does not mean that a man-in-the-middle did not reroute to some other location (e.g. DNS attacks).

End-to-end encryption

Onion service traffic is encrypted from the client to the onion host. This is like getting strong SSL/HTTPS for free.

NAT punching

Is your network filtered and you can't open ports on your firewall? This could happen if you are in a university campus, an office, an airport, or pretty much anywhere. Onion services don't need open ports because they punch through NAT. They only establish outgoing connections.

The Onion Service Protocol: Overview

Now the question becomes what kind of protocol is needed to achieve all these properties? Usually, people connect to an IP address and are done, but how can you connect to something that does not have an IP address?

In particular, an Onion Service's address looks like this: vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd.onion

This looks weird and random because it's the identity public key of the Onion Service. That's one of the reasons we can achieve the security properties above.

The Onion Service protocol uses the Tor network so that the client can introduce itself to the service, and then set up a rendezvous point with the service over the Tor network. Here is a detailed breakdown of how this happens:

Act 1: Where the Onion Service sets up its introduction points

Let's imagine that your local newspaper decides to set up an Onion Service (using SecureDrop) to receive anonymous tips. As the first step in the protocol, the Onion Service will contact a bunch of Tor relays and ask them to act as its introduction points by establishing long-term circuits to them. These circuits are anonymized circuits, so the server does not reveal the service location to the introduction points.

The Onion Service will hide and protect itself behind the Tor network by only allowing access through three introduction points that it connects to through a two-hop Tor circuit.

Onion Services: Step 1

Act 2: Where the Onion Service publishes its descriptors

Now that the introduction points are set up, we need to create a way for clients to be able to find them.

For this reason, the Onion Service assembles an Onion Service descriptor, containing a list of its introduction points (and "authentication keys"), and signs this descriptor 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.

The Onion Service upload that signed descriptor to a distributed hash table, which is part of the Tor network, so that clients can also get it. It uses an anonymized Tor circuit to do this upload so that it does not reveal its location.

Onion Services: Step 2

Act 3: Where a client wants to visit the Onion Service

Say you want to anonymously send some tax fraud data to your local newspaper through its SecureDrop. You find the onion address for the newspaper's SecureDrop from a public website or friend.

Onion Services: Step 3

Act 4: Where the client introduces itself to the Onion Service

All the previous steps were just set up for the Onion Service so that it's reachable by clients. Now let's fast-forward to the point where an actual client wants to visit the service.

In this case, the client has the onion address of SecureDrop and want to visit it, so they connect to the service with Tor Browser. Now the next thing that needs to happen is that the client goes to the distributed hash table from Step 2 and ask for the signed descriptor of SecureDrop's Onion Service.

Onion Services: Step 4

Act 5: Where the client verify onion address signature

When the client receives the signed descriptor, they verify the signature of the descriptor using the public key that is encoded in the onion address. This provides the end-to-end authentication security property, since we are now sure that this descriptor could only be produced by that Onion Service and no one else.

And inside the descriptor, there are the introduction points that allow the client to introduce themselves to SecureDrop's Onion Service.

Onion Services: Step 5

Act 6: Where the client establishes a rendezvous point

Before the introduction takes place, the client (in this case, you) picks a Tor relay and establishes a circuit to it. The client asks the relay to become their rendezvous point and give it an "one-time secret" that will be used as part of the rendezvous procedure.

Onion Services: Step 6

Act 7: Where the Onion Service rendezvous with the client

The introduction point passes your details (secret string and rendezvous address) on to the Onion Service, which runs multiple verification processes to decide whether you're trustworthy or not.

Onion Services: Step 7

Act 8: Where the rendezvous point verifies the client's secret

The Onion Service connects to the rendezvous point (through an anonymized circuit) and sends the "one-time secret" to it. The rendezvous point makes one final verification to match the secret strings from you and service (the latter also comes from you but has been relayed through the service).

The rendezvous point simply relays (end-to-end encrypted) messages from client to service and vice versa.

Onion Services: Step 8

Act 9: Where the Onion Service rendezvous with the client

In general, the complete connection between client and Onion Service consists of 6 relays: 3 of them were picked by the client, with the third being the rendezvous point, and the other 3 were picked by the Onion Service. This provides location hiding to this connection.

Finally, using the rendezvous point, a Tor circuit is formed between you and your newspaper's SecureDrop Onion Service.

Onion Services: Step 9

Further resources

This was just a high-level overview of the Tor Onion Services protocol. Here are some more resources if you want to learn more: