Onion service (v3)
Onion services, formerly called hidden services, are internet services whose location is hidden using the Tor network. Version 3 uses 56-character addresses based on Ed25519 public keys.
An onion service (previously called a hidden service) is an internet service reachable only through the Tor network. Both the service and the user remain anonymous: the service does not reveal its IP address, and the user does not reveal theirs. Onion services use a self-authenticating naming scheme derived from a public key, so no certificate authority is required to prove the identity of the server.
Version 3 of the protocol, specified in Tor Proposal 224 and standardised in rend-spec-v3.txt, replaced the earlier version 2 protocol in July 2021. Version 3 uses modern elliptic-curve cryptography and 56-character addresses.
Background
Onion services were introduced in Tor in 2004. The original design (v2) used 1024-bit
RSA keys and encoded a truncated hash of the public key into a 16-character address such as
duskgytldkxiuqc6.onion. By 2017 cryptographic advances and operational attacks
on the directory system made v2 unsuitable, and the Tor Project announced a long-planned
successor.
Address format
A v3 address is 56 characters of base32 followed by the suffix
.onion, for a total of 62 characters. The 56 base32 characters encode:
- a 32-byte Ed25519 public key,
- a 2-byte truncated SHA3-256 checksum, and
- a 1-byte version field (
0x03).
Because the address is derived from the public key, a client can verify that it is talking to the correct service without any external certificate.
Protocol overview
A v3 onion service publishes a signed descriptor to a set of six hash-ring directory relays (HSDirs). The descriptor lists three introduction points — relays at which the service listens for new connections. A client that wants to connect:
- fetches the descriptor from an HSDir using the service’s blinded public key as a lookup index;
- chooses a rendezvous point relay at random and sends it a one-time cookie;
- contacts an introduction point and tells the service where the rendezvous point is;
- service and client each build a three-hop circuit to the rendezvous point and perform an authenticated handshake there.
The resulting path is six hops long. Neither party learns the other’s IP address, and the HSDirs learn only a blinded identifier.
Comparison with v2
| Property | v2 (deprecated) | v3 (current) |
|---|---|---|
| Address length | 16 chars | 56 chars |
| Public key | RSA-1024 | Ed25519 (256-bit) |
| Directory lookup | Predictable | Blinded, time-based |
| Service enumeration | Possible | Not possible |
| Client authorisation | Weak | Standardised |
Security considerations
The redesign closed several classes of attack. In v2, HSDirs could enumerate all onion services by harvesting lookup addresses; in v3 the lookup identifier is blinded on a daily schedule and is of no use outside the current period. Weak RSA-1024 keys were replaced by Ed25519, and the protocol was simplified to reduce implementation errors.
Residual risks remain in the service application layer: misconfiguration, outdated software, information leaks in HTTP headers or TLS certificates, and targeted exploitation of the server environment. Operational security for the host — isolation, patching, keeping PGP signing keys offline — is at least as important as the protocol itself.
Adoption
Support for v2 was removed from Tor 0.4.6.x in July 2021. All major onion services, from BBC Future and The New York Times to Facebook, moved to v3 before the deadline. Tor Browser displays an alert if a user attempts to visit a v2 address.
References
- Mathewson, Nick (2017). “Next-generation onion services.” blog.torproject.org.
- Dingledine, Roger (2020). “Onion Service version 2 deprecation timeline.” blog.torproject.org.
- Tor specifications: rend-spec-v3.txt. gitweb.torproject.org/torspec.git.