en
Tor Hidden Service Client Authorization: Private .onion Access Control
Tor v3 hidden services support a cryptographic access control mechanism called client authorization that restricts which clients can connect to the hidden service's introduction points. Without client authorization, any Tor user who knows a .onion address can attempt to connect. With client authorization enabled, clients must possess a matching private key to decrypt the service's introduction point descriptor - clients without the key receive a connection failure even with the correct .onion address. This provides an additional security layer beyond address obscurity, making the hidden service effectively private to a defined set of key holders. Client authorization is used for private business services, personal hidden service deployments, and any scenario where the .onion address itself may be known to unauthorized parties but service access must remain restricted.
Need this done for your project?
We implement, you ship. Async, documented, done in days.
How Client Authorization Works Cryptographically
Tor v3 hidden service descriptors are stored on Hidden Service Directories (HSDir) in the Tor network, encrypted and signed. Client authorization encrypts the introduction point data within the descriptor using a key derived from authorized clients' public keys. Specifically, the descriptor uses an x25519 key pair: the server holds a private key, clients hold their own x25519 key pairs, and the descriptor layer is encrypted so only clients with a valid key can decrypt the introduction points. Without the introduction points, a client cannot complete the rendezvous protocol needed to connect to the service. The x25519 key used for client authorization is separate from the Ed25519 key used for the .onion address itself. Multiple clients can be authorized by including multiple public keys in the authorized_clients directory.
Generating Client Authorization Key Pairs
Generate x25519 key pairs for each authorized client. Using OpenSSL: openssl genpkey -algorithm x25519 -out client_private.pem. Extract the private key material in base32: openssl pkey -in client_private.pem -text -noout shows the raw key bytes which must be base32-encoded. Alternatively, use the standalone tool tor-x25519-keygen (available in some distributions) or a Python script using the cryptography library: from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey; key = X25519PrivateKey.generate(). Extract public key bytes and base32-encode for the authorized_clients file. Some tools like mkp224o include client key generation utilities. The private key goes to the client; the public key goes to the server's authorized_clients directory. Each client has a unique key pair.
Server-Side Configuration
In the HiddenServiceDir (e.g., /var/lib/tor/myservice/), create a subdirectory named authorized_clients/. Each file in this directory contains one client's public key in the format: descriptor:x25519:BASE32ENCODEDPUBLICKEY. The filename is arbitrary (usually an identifier like client1.auth or alice.auth). For example: echo 'descriptor:x25519:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' > /var/lib/tor/myservice/authorized_clients/alice.auth. Set file permissions to match the tor user's ownership (chown -R debian-tor:debian-tor /var/lib/tor/myservice/authorized_clients/). Restart Tor after adding or removing client authorization files. When Tor starts, it reads the authorized_clients directory and builds descriptors encrypted for those clients. Removing a file from authorized_clients revokes that client's access after Tor restarts.
Client-Side Configuration
Each authorized client must configure their Tor to use the client key when connecting to the service. Add to client's torrc: ClientOnionAuthDir /var/lib/tor/auth/. In that directory, create a file for the specific .onion service: the filename should be the .onion hostname with .auth extension. File content format: youronion.onion:descriptor:x25519:BASE32PRIVKEY where BASE32PRIVKEY is the client's base32-encoded private key (not the public key). Restart Tor on the client. When the client's Tor attempts to connect to youronion.onion, it automatically uses the configured key to decrypt the introduction point descriptor. Without this configuration, connection attempts to a client-auth-enabled service will time out without explanation.
Multi-Client Management and Key Rotation
Managing multiple authorized clients requires tracking which key file corresponds to which person or system. Maintain a separate access log (not on the hidden service server) mapping key file names to client identities and authorization dates. To revoke access: delete the client's .auth file from authorized_clients/ and restart Tor. The revoked client immediately loses the ability to resolve introduction points. For key rotation, generate new key pairs for each client, add new keys to authorized_clients/, distribute new private keys to clients securely, confirm clients can connect with new keys, then remove old key files and restart Tor. For high-security environments, rotate keys quarterly or after any suspected compromise. Never reuse key pairs across different services.
Related Services
Why Anubiz Host
100% async — no calls, no meetings
Delivered in days, not weeks
Full documentation included
Production-grade from day one
Security-first approach
Post-delivery support included
Ready to get started?
Skip the research. Tell us what you need, and we'll scope it, implement it, and hand it back — fully documented and production-ready.