Table of Contents

• Step 1: Update the System and Install Dependencies
• Step 2: Configure the Tor Hidden Service
• Step 3: Generate the v3 Stealth Auth Keys
• Step 4: Authorize the Client on the Server
• Step 5: Get Your Hidden Service URL
• Step 6: Connect from the Client Side
  • Via Tor Browser (Easiest Method)

Setting Up a Tor v3 Onion Service with Client Authentication #

This guide covers setting up a brand-new Ubuntu/Debian VPS with a Modern Tor v3 Hidden Service and generating Client Authentication Keys from scratch.

Step 1: Update the System and Install Dependencies #

Connect to your new VPS and run these commands to install Tor, OpenSSL, and Python (which we will use for a simple, zero-dependency key generation script).

1sudo apt update && sudo apt upgrade -y
2sudo apt install -y tor openssl python3
3

Step 2: Configure the Tor Hidden Service #

Open your Tor configuration file:

1sudo nano /etc/tor/torrc
2

Scroll to the bottom of the file and paste the following config. This sets up a hidden service routing to a local port (e.g., a local web server running on port 8080):

1HiddenServiceDir /var/lib/tor/hidden_service/
2HiddenServicePort 80 127.0.0.1:8080
3

Save and exit (Ctrl+O, Enter, Ctrl+X). Start Tor so it creates the directory structures automatically:

1sudo systemctl restart tor
2

Step 3: Generate the v3 Stealth Auth Keys #

Because Tor v3 requires a specific 32-byte raw x25519 key pair encoded cleanly into Base32, using raw OpenSSL commands can be clunky. To avoid installing heavy external pip packages on your fresh VPS, use this optimized, raw inline Python snippet to generate the curve25519 keypair and output it in the exact base32 format Tor expects. Run this command to execute the key generator:

 1python3 -c '
 2import os, base64, subprocess
 3
 4def b32(b):
 5    return base64.b32encode(b).decode("utf-8").replace("=", "")
 6
 7# Generate the keypair cleanly via OpenSSL right through Python
 8subprocess.run(["openssl", "genpkey", "-algorithm", "x25519", "-out", "priv.pem"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
 9subprocess.run(["openssl", "pkey", "-in", "priv.pem", "-pubout", "-out", "pub.pem"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
10
11# Read raw bytes bypassing PEM wrappers
12with open("priv.pem", "r") as f:
13    priv_b64 = "".join([line.strip() for line in f if "PRIVATE" not in line])
14with open("pub.pem", "r") as f:
15    pub_b64 = "".join([line.strip() for line in f if "PUBLIC" not in line])
16
17raw_priv = base64.b64decode(priv_b64)[-32:]
18raw_pub = base64.b64decode(pub_b64)[-32:]
19
20print("\n=== GENERATED CREDENTIALS ===")
21print(f"PUBLIC KEY (For Server):  {b32(raw_pub)}")
22print(f"PRIVATE KEY (For Client): {b32(raw_priv)}")
23'
24

Clean up the temporary pem files immediately:

1rm priv.pem pub.pem
2

Keep your terminal open and note down the output keys:

• PUBLIC KEY: (Example: MEE25GRMPHS7NKNV...)
• PRIVATE KEY: (Example: DARUBG4CIQ4FMPT...)

Step 4: Authorize the Client on the Server #

Now, register your client's Public Key inside the hidden service's authorized clients directory. Create a .auth file (you can name it anything, like alice.auth):

1sudo nano /var/lib/tor/hidden_service/authorized_clients/alice.auth
2

Paste the following string inside, replacing YOUR_PUBLIC_KEY_HERE with the actual public key from Step 3:

1descriptor:x25519:YOUR_PUBLIC_KEY_HERE
2

Save and exit. Fix the file permissions so the Tor system user can read it:

1sudo chown -R debian-tor:debian-tor /var/lib/tor/hidden_service/authorized_clients/
2sudo chmod 700 /var/lib/tor/hidden_service/authorized_clients/
3sudo chmod 600 /var/lib/tor/hidden_service/authorized_clients/*.auth
4

Restart Tor to apply changes:

1sudo systemctl restart tor
2

Step 5: Get Your Hidden Service URL #

To find the address you'll use to connect, read the hostname file generated by Tor:

1sudo cat /var/lib/tor/hidden_service/hostname
2

It will output a 56-character string ending in .onion. Copy it down.

Step 6: Connect from the Client Side #

Because your service is now in Stealth Mode, pasting the .onion URL into a standard Tor browser will result in an error until the client provides their private key.

Via Tor Browser (Easiest Method) #

1. Open Tor Browser on your computer.
2. Paste your 56-character .onion address into the URL bar and hit enter.
3. A prompt will instantly block the screen asking for your key.
4. Paste the PRIVATE KEY you generated in Step 3 into the box and click Connect. Your Tor Browser will securely cache this key and seamlessly handle the handshake going forward!