Client authorization is a method to make an Onion Service private and authenticated. It requires Tor clients to provide an authentication credential in order to connect to the Onion Service. For v3 Onion Services, this method works with a pair of keys (a public and a private). The service side is configured with a public key and the client can only access it with a private key.

Note: Once you have configured client authorization, anyone with the address will not be able to access it from this point on. If no authorization is configured, the service will be accessible to anyone with the onion address.

Configuring v3 Onion Services

Service side

To configure client authorization on the service side, the <HiddenServiceDir>/authorized_clients/ directory needs to exist. Following the instructions described in the section Setup will automatically create this directory. Client authorization will only be enabled for the service if tor successfully loads at least one authorization file.

For now, you need to create the keys yourself with a script (like these written in Bash, Rust or Python) or manually.

To manually generate the keys, you need to install openssl version 1.1+ and basez.

Step 1. Generate a key using the algorithm x25519:

 $ openssl genpkey -algorithm x25519 -out /tmp/k1.prv.pem

If you get an error message, something has gone wrong and you cannot continue until you've figured out why this didn't work.

Step 2. Format the keys into base32:

Private key

$ cat /tmp/k1.prv.pem | grep -v " PRIVATE KEY" | base64pem -d | tail --bytes=32 | base32 | sed 's/=//g' > /tmp/k1.prv.key

Public key

$ openssl pkey -in /tmp/k1.prv.pem -pubout | grep -v " PUBLIC KEY" | base64pem -d | tail --bytes=32 | base32 | sed 's/=//g' > /tmp/k1.pub.key

Step 3. Copy the public key:

 $ cat /tmp/k1.pub.key

Step 4. Create an authorized client file:

Format the client authentication and create a new file in <HiddenServiceDir>/authorized_clients/ directory. Each file in that directory should be suffixed with ".auth" (i.e. "alice.auth"; the file name is irrelevant) and its content format must be:

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

The supported values for <auth-type> are: "descriptor".

The supported values for <key-type> are: "x25519".

The <base32-encoded-public-key> is the base32 representation of the raw key bytes only (32 bytes for x25519).

For example, the file /var/lib/tor/hidden_service/authorized_clients/alice.auth should look like:

 descriptor:x25519:N2NU7BSRL6YODZCYPN4CREB54TYLKGIE2KYOQWLFYC23ZJVCE5DQ

If you are planning to have more authenticated clients, each file must contain one line only. Any malformed file will be ignored.

Step 5. Restart the tor service:

 $ sudo systemctl reload tor

If you get an error message, something has gone wrong and you cannot continue until you've figured out why this didn't work.

Important: Revoking a client can be done by removing their ".auth" file, however the revocation will be in effect only after the tor process gets restarted.

Client side

To access a version 3 Onion Service with client authorization as a client, make sure you have ClientOnionAuthDir set in your torrc. For example, add this line to /etc/tor/torrc:

 ClientOnionAuthDir /var/lib/tor/onion_auth

Then, in the <ClientOnionAuthDir> directory, create an .auth_private file for the Onion Service corresponding to this key (i.e. 'bob_onion.auth_private'). The content of the <ClientOnionAuthDir>/<user>.auth_private file should look like this:

 <56-char-onion-addr-without-.onion-part>:descriptor:x25519:<x25519 private key in base32>

For example:

 rh5d6reakhpvuxe2t3next6um6iiq4jf43m7gmdrphfhopfpnoglzcyd:descriptor:x25519:ZDUVQQ7IKBXSGR2WWOBNM3VP5ELNOYSSINDK7CAUN2WD7A3EKZWQ

If you manually generated the key pair following the instructions in this page, you can copy and use the private key created in Step 2. Then restart tor and you should be able to connect to the Onion Service address.

If you are generating a private key for an onion site, the user does not necessarily need to edit Tor Browser's torrc. It is possible to enter the private key directly in the Tor Browser interface.

For more information about client authentication, please see Tor manual.