Client Authorization for Private .onion Services

Tor v3 onion services support an authentication layer based on x25519 key pairs. The service operator generates a public/private key pair for each authorized client. The public key is placed in the hidden service's authorized_clients/ directory on the server, while the client adds the private key to their Tor configuration.

When a client attempts to connect, the Tor daemon on the server side checks if the client possesses a valid private key before establishing the connection. If the client does not have the key, the server does not respond — the service appears to not exist at all. This is significantly stronger than application-layer authentication because the filtering happens at the Tor protocol level.

Each authorized client gets their own unique key pair, allowing you to revoke access for individual clients by removing their public key file from the server. You can authorize up to 330 clients per hidden service using this mechanism.

Generate x25519 key pairs for client authorization. You can use the tor command-line tools or a standalone script:

# Install required tools
apt install -y openssl basez

# Generate a key pair for a client
openssl genpkey -algorithm x25519 -out /tmp/client_key.pem

# Extract the private key (base32 for client)
cat /tmp/client_key.pem | \
  openssl pkey -outform DER | tail -c 32 | basez --base32 | \
  tr -d '=' > /tmp/client_private.key

# Extract the public key (base32 for server)
cat /tmp/client_key.pem | \
  openssl pkey -pubout -outform DER | tail -c 32 | basez --base32 | \
  tr -d '=' > /tmp/client_public.key

# On the server — add public key
# File: /var/lib/tor/my_hidden_service/authorized_clients/client1.auth
# Format: descriptor:x25519:PUBLIC_KEY_BASE32
echo "descriptor:x25519:$(cat /tmp/client_public.key)" > \
  /var/lib/tor/my_hidden_service/authorized_clients/client1.auth

# On the client — add to Tor Browser
# In Tor Browser: Settings > Onion Services > Add
# Or in ClientOnionAuthDir:
# Format: your56char.onion:descriptor:x25519:PRIVATE_KEY_BASE32

Restart the Tor service on the server after adding authorized client files. The client can now connect using Tor Browser by entering the .onion address and providing the private key when prompted.

Each authorized client gets their own .auth file in the authorized_clients/ directory. Name files descriptively to track who has access:

# List authorized clients
ls /var/lib/tor/my_hidden_service/authorized_clients/
# alice.auth  bob.auth  charlie.auth

# Revoke access for a specific client
rm /var/lib/tor/my_hidden_service/authorized_clients/bob.auth
systemctl reload tor

# Bob can no longer connect — the service appears non-existent to him

Key rotation is also straightforward. Generate a new key pair for the client, replace the .auth file on the server, and send the new private key to the client over a secure channel. The old key immediately stops working after the Tor service is reloaded.

For services with many clients, consider automating key management with a script that generates key pairs, places public keys on the server, and securely distributes private keys via encrypted channels like PGP-encrypted email or a separate .onion-based key distribution service.

AnubizHost managed Tor hosting includes client authorization setup as part of our service. We generate and configure key pairs for your authorized users, and our control panel lets you add or revoke client access without touching the command line.

Our offshore servers in Iceland, Romania, and Finland ensure your private .onion service operates under strong privacy jurisdictions. Sign up with Bitcoin, Monero, or other cryptocurrencies — no KYC, no identity verification. Whether you need a private admin panel, a restricted intranet, or a secure file-sharing service, AnubizHost provides the infrastructure with Tor client authorization pre-configured.