Onion v2 to v3 Migration: Complete Hidden Service Upgrade

v2 addresses: 16 characters (80-bit truncated SHA-1 hash of RSA-1024 public key). v3 addresses: 56 characters (Ed25519 public key + version + checksum, base32 encoded). v3 key security: Ed25519 vs RSA-1024. RSA-1024 is considered weak by modern cryptographic standards (potential quantum vulnerability, computationally feasible attack on emerging hardware). Ed25519 uses Curve25519 (elliptic curve) which provides 128-bit security level with much smaller key sizes. v3 uses BLAKE2b for descriptor encryption (replaces SHA-1). v3 hidden service descriptors are encrypted to the client's introduction points, improving metadata privacy versus v2. v3 HS descriptors are published to a different set of HSDir relays using a different algorithm.

v3 key generation is automatic: create an empty HiddenServiceDir directory with correct permissions (chmod 700), add HiddenServiceDir and HiddenServicePort to torrc, restart Tor - Tor generates Ed25519 keys automatically. Key files in the hidden service directory: hs_ed25519_secret_key (private key - protect this file), hs_ed25519_public_key (public key), hostname (contains the .onion address). IMPORTANT: back up hs_ed25519_secret_key immediately after generation. This key IS your .onion address - if lost, the address is permanently lost. Store backups in encrypted storage (GPG-encrypted file in offline storage, hardware security module for high-security deployments).

If migrating a live service (hypothetically from an old v2 address or to a new v3 address for any reason), maintain both addresses simultaneously during transition: run both old and new hidden service configurations in torrc, serve both from the same backend, place a migration notice on the old address pointing to the new .onion address. Communications: update all published references (forum posts, dark web directories, your own website, partner sites) to the new address. Configure the old address to serve a redirect page or a 301 redirect (if your HTTP server supports redirecting to .onion URLs, though browser support for .onion-to-.onion redirects via Tor is complete). Timeline: maintain dual-serving for 3-6 months, then shut down the old address.

Communicating a new .onion address to existing users when you cannot reach them proactively (hidden service, anonymous users) is a challenge. Strategies: place visible notice on the old address before shutting it down, post the new address in regular community channels (forums, social media, darknet directories), maintain a clearnet presence (if acceptable for your service) that lists the current .onion address, use trusted intermediaries to distribute the new address. Verify the new address announcement itself has not been tampered with - PGP-sign address announcements to allow verification. If an attacker posts a fake 'new address' announcement, users following it could be deanonymized by connecting to a honeypot.

After migrating to v3: verify the new .onion address is reachable via Tor Browser (test from multiple circuits). Verify all application functionality works on the new address. Update any internal references to the .onion address in application configuration. Remove v2 configuration from torrc once migration is complete. Verify permissions on the v3 key directory: ls -la /var/lib/tor/hidden_service/ should show mode 700. Archive the backup of hs_ed25519_secret_key securely. Test client authorization if used (v3 client auth is different from any v2 mechanism). Monitor logs for connection attempts to the new v3 address to confirm clients are successfully discovering and using it.