Migrating v2 to v3 Tor Hidden Services

Tor v2 hidden services used 80-bit RSA key material and 16-character addresses (e.g., xxxxxxxxxxxxxxxx.onion). The v2 protocol had known security weaknesses: weak 1024-bit RSA keys, predictable descriptor timing, and vulnerable HSDir relay selection. Tor v2 was officially deprecated in October 2021 and completely disabled in Tor version 0.4.6. v3 hidden services use Ed25519 keys and 56-character addresses. The v3 protocol includes: 256-bit elliptic curve keys (significantly stronger), blinded key generation for HSDir selection (preventing information leakage about service location), and improved circuit isolation. For services that operated under v2: all v2 .onion addresses are permanently unreachable. Users who know only the old v2 address cannot find the service. The migration challenge is communicating the new v3 address to existing users.

v3 hidden service generation is straightforward. Add to torrc: HiddenServiceDir /var/lib/tor/hidden_service_v3/ and HiddenServicePort 80 127.0.0.1:8080. Restart Tor. The v3 .onion address appears in /var/lib/tor/hidden_service_v3/hostname. To generate a vanity v3 address (one that starts with recognizable characters): use mkp224o tool. Compile mkp224o from source (GitHub: cathugger/mkp224o), run with pattern: ./mkp224o -d keys-dir -n 1 secure (generates an address starting with 'secure'). Copy the generated key files from the keys-dir to the HiddenServiceDir. The address is deterministically derived from the private key - the generated keys produce the desired prefix. For security-critical services, generate the key on an air-gapped machine and transfer the key files securely to the server.

The biggest challenge of v2-to-v3 migration is reaching existing users who only know the old v2 address. Notification strategies: (1) Clearnet website: if the service has a clearnet counterpart, publish the v3 address on the clearnet site with cryptographic signature from the v2 era. (2) PGP-signed announcement: publish a signed announcement to relevant communities, newsgroups, and forums where the service was previously promoted. (3) Collaboration with directories: if the service was listed in directories (Ahmia, Hidden Wiki), submit the updated v3 address to these directories. (4) Social media and community: if there are community channels (forum threads, Telegram groups, social media) that reference the old v2 address, post updates with the new v3 address. For services where users have no other contact information (completely anonymous .onion with no clearnet presence), recovery is limited - only users who proactively search for the new address will find it.

If starting fresh with v3 (no existing v2 users): no continuity concerns. If migrating a service with an existing user base: run the v3 service in parallel with a notification page if v2 were somehow still accessible (it is not in current Tor - this is theoretical). The practical situation: v2 addresses are inaccessible. The migration is effectively starting a new service under a new address. Content continuity: ensure the v3 service contains all content that the v2 service had, ideally with the same URL structure so that users who find the new address can navigate to previously bookmarked content paths. Reputation continuity: the v3 address is a fresh identity with no existing trust signals. Rebuild trust by publishing signed announcements from any previously trusted keys associated with the v2 service.

With the migration to v3, implement security improvements that the v3 protocol enables. Onion Authentication (Client Authorization): restrict access to specific clients using Ed25519 keypairs. This was available in v2 but the underlying cryptography was weaker. With v3, the authorization is built on Ed25519 (same as the hidden service key). Enable for sensitive services: add HiddenServiceAuthorizeClient to torrc (or use the authorized_clients directory for multiple clients). Proof of Work defense: enable for public services that face DDoS: HiddenServicePoWDefensesEnabled 1. PoW requires connecting clients to compute a proof-of-work before creating a circuit, deterring DoS floods. Single onion services: for non-anonymous services where performance matters more than server location privacy, configure SingleHopMode to reduce the circuit to 3 hops (client three hops to service) rather than 6.