How to setup Client Authorization for v3 Onion Services

Question

The Tor 0.3.5 series includes client authorization for v3 onion services.

Tor manual:

To configure client authorization on the service side, the "/authorized_clients/" directory needs to exist. 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 are: "descriptor". The supported are: "x25519". The is the base32 representation of the raw key bytes only (32 bytes for x25519).

How can I generate the ".auth" file?

Answer 1

Openssl 1.1.0 or newer that supports x25519 is required.

openssl genpkey -algorithm x25519 -out key.private.pem

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

openssl pkey -in key.private.pem -pubout | grep -v " PUBLIC KEY" | base64pem -d | tail --bytes=32 | base32 | sed 's/=//g' > public.key

On the HS side, create .auth with content

descriptor:x25519:<public.key>

On the client side, create .auth_private with content

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

Answer 2

The earlier answer is basically correct, but terse. For a more complete answer, I would recommend the Anarcho-Tech NYC Collective's guide, "Connecting to an authenticated Onion service" published on their wiki. The section of their guide relevant to your question is "Generating authentication credentials for version 3 Onion services" and is pasted here:

Do this to generate a public/private keypair for use as an authenticated Version 3 Onion service access credential:

1. On a laptop or desktop computer, ensure you have OpenSSL 1.1 or later installed. Links to ready-to-use OpenSSL distributions are available from the OpenSSL wiki. Many GNU/Linux computers already have OpenSSL installed.
2. On the same laptop or desktop computer, ensure you have Base64 and Base32 encoding and decoding utilities available, such as those provided by the basez package or an equivalent.
3. Using OpenSSL 1.1 or later, generate a new X25519 private key. This will produce a PEM-encoded private key file, private-key.pem:

   openssl genpkey -algorithm x25519 -out private-key.pem
   

4. Using the newly generated private key file, generate a corresponding public key file, public-key.pem:

   openssl pkey -in private-key.pem -pubout -outform PEM -out public-key.pem
   

5. Now that you have both the private and public parts of your keypair, first convert the private part from its PEM-encoded format into a Base32 encoded string for use in your Tor client’s .auth_private file:

   cat private-key.pem | \
       grep -v " PRIVATE KEY" | \
       basez --base64pem --decode | \
       tail --bytes 32 | \
       basez --base32 | \
       tr -d '=' > some-onion.auth_private # You can change `some-onion` to a name more meaningful to you.
   

6. At this point, the some-onion.auth_private file (which you can rename if you like) contains only the private key itself, so we need to prepend the Onion domain (without the .onion top-level domain), a colon (:), the keyword descriptor, another field-delimiting colon, and the key type keyword x25519, followed by a final colon. For example, if the Onion address for which this private key will be used to authenticate this client is p53lf57qovyuvwsc6xnrppyply3vtqm7l6pcobkmyqsiofyeznfu5uqd.onion, the final .auth_private file could be constructed like this:

   echo -n "p53lf57qovyuvwsc6xnrppyply3vtqm7l6pcobkmyqsiofyeznfu5uqd:descriptor:x25519:" | \
       cat - some-onion.auth_private
   

7. Finally, prepare the .auth public key file for the Onion service operator by performing a similar preparatory procedure. For the public key's .auth file, you should omit the Onion address itself and merely need to prepend the keyword descriptor, a field-delimiting colon (:), the key type keyword x25519, and a final field-delimiting colon:

   # Prepare the initial `.auth` file.
   cat public-key.pem | \
       grep -v " PUBLIC KEY" | \
       basez --base64pem --decode | \
       tail --bytes 32 | \
       basez --base32 | \
       tr -d '=' > some-client.auth
   # Prepend the Tor descriptor fields to the base32-encoded bytes in the `.auth` file.
   echo -n "descriptor:x25519:" | cat - some-client.auth
   

After this procedure is complete, you will have four files:

1. private-key.pem, which can be deleted,
2. public-key.pem, which can also be deleted,
3. some-onion.auth_private, which you must take responsibility for protecting (it is like your password), and
4. some-client.auth, which you should share with the operator of the Onion service by sending the file to them (over a secure channel such as in a Signal Private Messenger message, if possible).

Next, you will protect your .auth_private file and inform your Tor software where to find it.

Configuring a laptop or desktop computer for authenticated Version 3 Onion services

Do this to connect to an authenticated Version 3 Onion service from your laptop or desktop computer:

1. Install Tor Browser from TorProject.org.
2. Ensure you have a valid .auth_private file. You can either generate one yourself, or in some cases you may have already received one from the operator of your Onion service.
3. Choose or make a sensible folder to store all of your Version 3 Onion service access credential files. For example, a folder called "Onions" in your home folder would work well.
4. Move the .auth_private file into the folder you chose to store your Version 3 Onion service access credential files.
5. Find the filesystem path of the folder you chose to store your Version 3 Onion service access credential files. Make a note of this filesystem path, as we'll use it in a future step.
   • In macOS:
     1. Single-click on the folder to select it.
     2. From the menu bar, choose File → Get Info. The folder Info window will open.
     3. Click on the General section's disclosure triangle to expose the General Information panel.
     4. Select and copy the entire value of the Where line, as shown below, then paste it into your notes:
        
     5. If the folder you chose was Onions in your home folder, your path will probably look something like /Users/YOUR_USER_NAME/Onions.
   • In GNU/Linux, first use the cd command to go to the folder itself, then use the pwd command to find the full filesystem path of the folder. If the folder you chose was Onions in your home folder, your path will probably look something like /home/YOUR_USER_NAME/Onions.
   • In Windows:
     1. Right-click on the folder and choose Properties from the contextual menu.
     2. In the General tab, find and copy the full value of the Location line.
     3. If the folder you chose was Onions in your home folder, your path will probably look something like C:\Users\YOUR_USER_NAME\Onions.
6. Locate the torrc file that you need to edit. The location of this file is slightly different depending on your computer's operating system:

   🔰 In the following file paths, the ~ character or the %HOMEDRIVE%%HOMEPATH% sequence refers to "wherever your home folder is."

   • In macOS, edit ~/Library/Application Support/TorBrowser-Data/Tor/torrc.
     1. Open a new Finder window.
     2. From the Go menu, select Go to folder…
     3. In the Go to the folder text box, paste ~/Library/Application Support/TorBrowser-Data/Tor/ and press the Go button.
     4. The torrc file will be one of the files in the window that opens.
   • In GNU/Linux, edit ~/[path_to_tor_browser]/Browser/TorBrowser/Data/Tor/torrc.
   • In Windows, edit "%HOMEDRIVE%%HOMEPATH%"\Desktop\Tor Browser\Browser\TorBrowser\Data\Tor\torrc.
7. Open the torrc file with a text editor, such as Notepad on Windows or TextEdit.app on macOS. Any text editor will do. However, Microsoft Word and other programs that expect rich text formatting will not work.
8. Add a line to the torrc file that begins with ClientOnionAuthDir and ends with the filesystem path of the folder you chose to store your Version 3 Onion service access credential files that you noted earlier. For example, on a macOS computer, the full line in your torrc file might look like this:

   ClientOnionAuthDir /Users/YOUR_USER_NAME/Onions
   

9. Save the torrc file.
10. Restart (quit and re-launch) Tor Browser.

After re-opening Tor Browser, you should now be able to connect to the .onion address described in your .auth_private file (assuming, of course, that the Onion service hosts a website).

Configuring an Android-based mobile device for authenticated Version 3 Onion services

At the time of this writing, Android cannot connect to authenticated Version 3 Onion services. When available, Orbot may make it possible to connect to authenticated Version 3 Onion services on Android-based mobile devices.

Configuring an Apple iOS device for authenticated Version 3 Onion services

At the time of this writing, iOS cannot connect to authenticated Version 3 Onion services. When available, iCepa may make it possible to connect to Onion services on devices running Apple's iOS.

As mentioned in the above guide, at the time of this writing there is no GUI for configuring access credentials. :(