What Is Tor Hidden Service Client Authorization?

Tor hidden service client authorization is an access-control mechanism that restricts who can connect to an onion service by requiring clients to authenticate using cryptographic key pairs. This article covers the core concept of client authorization, how it encrypts service descriptors to keep onion addresses private, the primary security benefits it provides, and how it is configured on both the server and client sides.

Understanding Client Authorization

By default, Tor onion services (hidden services) are publicly accessible to anyone who possesses the .onion address. While the address itself provides a degree of privacy through obscurity, anyone who discovers the address can attempt to connect to the underlying service.

Tor’s client authorization feature changes this default behavior by adding a layer of asymmetric cryptography. It allows a service operator to configure a whitelist of authorized clients. If an unauthorized user attempts to visit the onion address, they will be unable to locate or connect to the service, effectively making it invisible to anyone without valid credentials.

How Tor Client Authorization Works

In Tor v3 onion services, client authorization relies on asymmetric encryption using Curve25519 (x25519) key pairs:

1. Key Generation: Each authorized client possesses a unique key pair—a public key given to the onion service operator and a private key retained by the client.
2. Descriptor Encryption: When the onion service publishes its descriptor to the Tor distributed hash table (DHT), it encrypts the descriptor using the authorized clients’ public keys.
3. Connection Process: When an authorized client attempts to connect, Tor uses the client’s local private key to decrypt the descriptor. Decrypting the descriptor reveals the introduction points necessary to establish a secure circuit to the onion service.
4. Unauthorized Requests: An unauthorized client lacking the matching private key cannot decrypt the descriptor. As a result, the Tor network reports the service as non-existent or unreachable.

Key Security Benefits

• Resistance to Scanning: Even if an onion address is leaked, unauthorized actors cannot connect to the port or scan the underlying web application.
• Denial of Service (DoS) Mitigation: Because unauthorized traffic cannot establish connection circuits through the introduction points, the service is shielded from untrusted network-level abuse.
• Invisible Services: The service remains effectively nonexistent to anyone not explicitly invited by the operator.
• Decoupled Authentication: Access control occurs at the Tor routing layer before any traffic reaches the application server (such as Apache, Nginx, or SSH).

Configuration Overview

Setting up client authorization requires changes to the torrc configuration files for both the server and the client.

Server-Side Setup

The operator specifies an authorization directory in the server’s torrc file:

HiddenServiceDir /var/lib/tor/my_hidden_service/
HiddenServicePort 80 127.0.0.1:80

Inside the hidden service directory, an authorized_clients folder is created. The operator adds client public keys inside this directory using .auth files formatted as:

<descriptor-type>:key:<base32-encoded-public-key>

Client-Side Setup

The client configures their local Tor instance to use an authorization directory by adding the following directive to their torrc:

ClientOnionAuthDir /var/lib/tor/onion_auth

Inside this directory, the client stores a .auth_private file mapped to the specific onion address:

<onion-address>:descriptor:x25519:<base32-encoded-private-key>

Once configured and the Tor services are reloaded, the client can seamlessly resolve and access the private onion service.