Tor V3 Onion Service Descriptor Handling Explained

Tor version 3 (V3) onion services rely on a decentralized directory system to store and distribute routing information without exposing the identity or location of hidden services. This article explains how Tor’s Hidden Service Directories (HSDirs) store, index, validate, and serve V3 descriptors using blinded public keys, consistent hash rings, multi-layered encryption, and time-based rotation.

The Role of Hidden Service Directories (HSDirs)

The Tor network does not use a centralized server to manage onion service locations. Instead, relays that meet strict uptime and bandwidth criteria receive the HSDir flag from directory authorities. These relays collectively form a Distributed Hash Table (DHT) responsible for storing and providing onion service descriptors upon request.

Key Blinding and Privacy Protection

In legacy V2 onion services, directory relays could see the full onion address, allowing malicious HSDirs to index and snoop on hidden services. Tor V3 prevents this through key blinding:

• Blinded Public Keys: A service derives a temporary blinded public key from its permanent ed25519 master public key combined with the current time period and a network-wide Shared Random Value (SRV).
• Anonymity for Services: The HSDir only sees the blinded public key, making it mathematically impossible for the directory to determine the actual .onion address.
• Access Control: Only users who already know the exact .onion address can compute the same blinded public key to locate and request the descriptor.

Two-Tier Descriptor Architecture

A V3 hidden service descriptor contains the necessary information for a client to establish a connection (such as introduction points). It is split into two layers:

1. Outer Envelope (Unencrypted): Contains metadata required by the HSDir, including the blinded public key, a revision counter, and a cryptographic signature. This allows the HSDir to validate the descriptor without reading its payload.
2. Inner Layer (Encrypted): Contains the actual introduction points and authentication requirements. This payload is encrypted using a key derived from the master onion address (and optionally a client authorization key), ensuring only authorized clients can read the connection details.

The Consistent Hash Ring and Shared Random Value

To determine which HSDirs should store a descriptor, the Tor network utilizes a consistent hash ring:

1. Shared Randomness: Directory authorities generate a daily Shared Random Value (SRV) through a distributed commit-and-reveal protocol.
2. Descriptor Index Calculation: The onion service and client use the SRV, the current time period, and the blinded key to compute a set of descriptor IDs (positions on the hash ring).
3. Responsible Relays: The service selects the HSDirs located closest to these descriptor IDs on the ring and uploads the descriptor to them. When a client wants to connect, it performs the exact same mathematical calculation to find which HSDirs hold the descriptor.

Descriptor Lifecycle and Validation

When an HSDir receives an uploaded descriptor via an HTTP POST request, it performs several security checks before storing it:

• Signature Verification: The directory checks that the descriptor is properly signed by the blinded key.
• Revision Counter Check: To prevent replay attacks and outdated state storage, the directory compares the descriptor’s revision counter against any existing record for that blinded key, overwriting only if the new revision counter is higher.
• Time Expiration: Descriptors are bound to specific time periods. Once a time period rolls over, the blinded keys change, the descriptor locations on the hash ring shift, and outdated descriptors are purged from relay memory.