Generating Vanity .onion Addresses for Hidden Services

Onion v3 addresses are derived from the hidden service's Ed25519 public key through a specific encoding: the 32-byte public key is concatenated with a checksum and version byte, then encoded in base32 and appended with .onion. To generate a specific prefix, you must find an Ed25519 key pair whose public key encodes to a base32 string beginning with your desired prefix. Since base32 uses characters a-z and 2-7, desired prefixes must use only these characters. Each additional character in the prefix multiplies the computational search by 32. A 5-character prefix requires checking approximately 33 million keys on average. A 10-character prefix requires approximately 1 quadrillion checks - computationally feasible only with significant GPU resources.

mkp224o (available on GitHub at cathugger/mkp224o) is the most widely used tool for generating Tor v3 vanity addresses. Install: clone the repository, run ./autogen.sh && ./configure && make. Run: ./mkp224o -d outputdir/ prefix. The -d flag specifies where to save found key pairs. When a matching address is found, mkp224o saves the hs_ed25519_secret_key and hs_ed25519_public_key files (in the same format Tor expects in HiddenServiceDir) and the hostname file to the output directory. For short prefixes (4-6 characters), a modern CPU finds matches within minutes to hours. For longer prefixes, GPU acceleration is necessary.

For vanity prefixes longer than 7-8 characters, GPU acceleration becomes practical. mkp224o supports OpenCL for GPU acceleration: compile with --enable-opencl flag. Alternatively, scallion (for older OpenCL GPUs) and Eschalot provide GPU-accelerated vanity generation. A consumer GPU (NVIDIA RTX 3080) performs approximately 1-2 billion key pair derivations per second compared to a CPU's 10-50 million. For a 10-character prefix requiring roughly 10^15 operations, a single RTX 3080 would take approximately 500,000 seconds (6 days). Running multiple GPUs in parallel reduces this proportionally. Renting cloud GPU time (A100, H100 clusters) can accelerate long prefix searches.

Base32 encoding uses characters a-z and 2-7. To incorporate uppercase letters or numbers outside this set, consider how the prefix maps to available characters: the digit 0 is not in base32, so cannot appear in a valid .onion address. Letters are lowercase in standard presentation but are case-insensitive. Meaningful prefixes that fit within base32 charset: words using only a-z, numbers 2-7 interspersed. Calculate expected time before searching: 32^(prefix_length) / searches_per_second = expected_seconds on average. For 6 characters: 32^6 = ~1 billion keys / 50 million per second (CPU) = 20 seconds average. For 8 characters: 32^8 = ~1 trillion / 50 million = ~5.5 hours average.

After finding a matching key pair, deploy it as your hidden service. Copy the contents of the mkp224o output directory (hs_ed25519_secret_key, hs_ed25519_public_key, hostname) to your HiddenServiceDir path on the Tor server (typically /var/lib/tor/your_service/). Set ownership to the tor user and permissions to 700: chown -R debian-tor:debian-tor /var/lib/tor/your_service && chmod 700 /var/lib/tor/your_service. Restart Tor: systemctl restart tor. Verify the address by reading /var/lib/tor/your_service/hostname - it should match your desired vanity prefix. Immediately back up the key files to encrypted offline storage - the vanity address is permanently associated with these keys.