section: onion services
---
section_id: onion-services
---
color: primary
---
_template: layout.html
---
title: How do onion services work?
---
subtitle: Learn how onion services work.
---
key: 0
---
html: two-columns-page.html
---
body:

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 (Alice) can introduce itself to the service (Bob), 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

![Onion Services: Step 1](/static/images/onion-services/overview/tor-onion-services-1.png)

As the first step in the protocol, Bob (the onion service) contacts a bunch of Tor relays and asks them to act as his _introduction points_, by establishing long-term circuits to them.
These circuits are anonymized circuits, so Bob does not reveal his locations to his introduction points.

As part of this step, Bob gives its introduction point a special "authentication key", so that if any clients come for introductions later the introduction point can use that key to match them to Bob.

### Act 2: Where the onion service publishes its descriptors

![Onion Services: Step 2](/static/images/onion-services/overview/tor-onion-services-2.png)

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

For this reason, Bob assembles an _onion service descriptor_, containing a list of his introduction points (and their "authentication keys"), and signs this descriptor with his _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**.

Now, Bob uploads that signed descriptor to a _distributed hash table_ which is part of the Tor network, so that clients can also get it.
Bob uses an anonymized Tor circuit to do this upload, so that he does not reveal his location.

### Act 3: Where a client wants to visit the onion service

All the previous steps were just setup 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:

![Onion Services: Step 3](/static/images/onion-services/overview/tor-onion-services-3.png)

In this case, Alice (the client) has the onion address of Bob and she wants to visit it, so she connects to it with her Tor Browser.
Now the next thing that needs to happen is that Alice goes to the _distributed hash table_ from the step above, and ask for the signed descriptor of Bob.

When Alice receives the signed descriptor, she verifies 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 Bob and no one else.
And inside the descriptor there are the introduction points which allow Alice to introduce herself to Bob.

### Act 4: Where the client establishes a rendezvous point

Now before the introduction takes place, Alice picks a Tor relay and establishes a circuit to it.
Alice asks the relay to become her _rendezvous point_ and gives it an "one-time secret" that will be used as part of the rendezvous procedure.

### Act 5: Where the client introduces itself to the onion service

![Onion Services: Step 4](/static/images/onion-services/overview/tor-onion-services-4.png)

Now, Alice goes ahead and connects to one of Bob's introduction points and introduces herself to Bob.
Through this introduction Bob learns Alice's choice of rendezvous point and the "one-time secret".

### Act 6: Where the onion service rendezvous with the client

![Onion Services: Step 5](/static/images/onion-services/overview/tor-onion-services-5.png)

In this last act, the onion service is now aware of Alice's rendezvous point.
The onion service connects to the rendezvous point (through an anonymized circuit) and sends the "one-time secret" to it.

Upon the rendezvous point receiving the "one-time secret" from Bob, it informs Alice that the connection has been **successfuly completed**, and now Alice and Bob can use this circuit to communicate with each other.
The rendezvous point simply relays (end-to-end encrypted) messages from client to service and vice versa.

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:

![Onion Services: Step 6](/static/images/onion-services/overview/tor-onion-services-6.png)

## 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:

- The original Tor design paper describing the original design:
https://svn.torproject.org/svn/projects/design-paper/tor-design.pdf
- The Tor v3 onion services protocol specification.
https://gitweb.torproject.org/torspec.git/tree/rend-spec-v3.txt
- Presentations about onion services
https://www.youtube.com/watch?v=VmsFxBEN3fc
https://www.youtube.com/watch?v=Di7qAVidy1Y
