How the Tor Hidden Service Protocol Works - Technical Deep Dive

When a hidden service starts, Tor selects several relay nodes from the Tor network to serve as introduction points. The hidden service establishes persistent Tor circuits to each introduction point. These circuits are maintained throughout the service's operation; if an introduction circuit breaks, Tor establishes a new one to the same or a different relay.

Introduction points do not know the location or identity of the hidden service they are serving. They know only their onion layer circuit key for the circuit connecting to the service. From the introduction point's perspective, it is simply a relay that maintains a circuit with an unknown origin. The introduction point receives encrypted connection requests from clients and forwards them toward the service through the circuit, but cannot read the contents because they are encrypted to the service's public key.

For v3 hidden services, introduction point encryption uses the service's ed25519 public key derived from the hs_ed25519_secret_key file. Each introduction point is given a signed authorization that proves it is a legitimate introduction point for this service, preventing other relays from claiming to be introduction points for a service they do not have a circuit with.

After establishing introduction point circuits, the hidden service publishes a descriptor to the hidden service directory (HSDirs). HSDirs are specific relays in the Tor network that store descriptors based on a time-varying algorithm. The responsible HSDirs change every 24 hours based on the shared random value published by directory authorities.

The descriptor contains the service's introduction point addresses and the information clients need to establish a rendezvous. For v3 services, the descriptor is encrypted so that only Tor clients can decrypt the full contents; introduction point addresses are not visible to third parties who observe the HSDir storing the descriptor.

Finding the correct HSDirs to publish to is deterministic: given the service's public key and the current time period, both the service and any client can independently calculate which specific relays are the responsible HSDirs. This determinism is what makes directory lookups efficient without requiring a centralized routing table.

When a Tor client wants to connect to a hidden service, it first calculates which HSDirs are responsible for that service in the current time period using the same deterministic algorithm. It downloads the descriptor from one of those HSDirs through a Tor circuit.

The client selects a rendezvous point from the Tor network - a relay that will mediate the connection between client and service without either party knowing the other's location. The client builds a Tor circuit to the rendezvous point and sends it a randomly generated cookie value over this circuit. The client then sends an introduction request to one of the service's introduction points, also through a separate Tor circuit.

The introduction request contains the rendezvous point address, the cookie, and information encrypted to the service's public key. This encrypted payload is the DH exchange data the service needs to derive shared session keys. The introduction point forwards the request toward the service through the circuit it has maintained.

The hidden service receives the introduction request through its circuit to the introduction point. It decrypts the payload using its private key, extracts the rendezvous point address and cookie, and builds a new Tor circuit to the rendezvous point. It sends the rendezvous point the cookie (proving it is the intended recipient of the original client request) and its DH public value for the session key exchange.

The rendezvous point matches the cookie from the service's message with the cookie it received from the client earlier. It then joins the two circuits together: the client-to-rendezvous circuit and the service-to-rendezvous circuit are merged into a single end-to-end circuit. From this point, the client and service can communicate through the joined circuit as if they had a direct connection, though six hops separate them.

The rendezvous point knows only that two Tor circuits have been joined together. It cannot determine the origin of either circuit - it does not know the client's real IP or the service's location. The cookie is a one-time value that prevents replay attacks but reveals nothing about the parties' identities. This architecture is what provides the mutual anonymity guarantee that makes hidden services useful for both operators and users.

Onion v3 uses X25519 for Diffie-Hellman key exchange, ed25519 for signing and the service identity key, SHA-3 (specifically SHAKE256) for hash functions, and AES-256-CTR for stream encryption. These choices reflect 2020-era best practices in public key cryptography and are significantly stronger than the RSA-1024 and SHA-1 used in v2 addresses that were deprecated in 2021.

The 56-character onion v3 address encodes the ed25519 public key, a checksum, and a version identifier in Base32. The address is self-authenticating: a Tor client that knows the onion address knows the service's public key and can verify that any descriptor or connection attempt is authorized by the correct key without consulting any external authority. This eliminates the need for certificate authorities or DNS and prevents the man-in-the-middle attacks that plague certificate-based trust systems.

Forward secrecy is provided through ephemeral X25519 key exchange for each session. Even if the service's long-term ed25519 private key is compromised in the future, past session traffic encrypted with ephemeral keys cannot be decrypted. This is in contrast to RSA-based systems where a compromised long-term key enables decryption of previously recorded traffic.