Onioncat and Tor Hidden Services V3

For security reasons the Tor project introduced hidden services version 3 (HSv3) which facilitate stronger cryptography to comply with modern needs for security. Onioncat was developed with version 2 of hidden services which are still in place work as expected. Unfortunately HSv3 do not integrate smoothly into the OnionCat concept but nevertheless, with a few additional steps Onioncat still will run perfect with these new HSv3 services.

This HowTo explains how to setup three systems to connect to each other using HSv3. It does not explain technical details, why everything is done in such a way, it simply shall be a step by step procedure to success.

In the following explanation there are three hosts, named onioncat-A, onioncat-B, and onioncat-C which may be any system anywhere in the Internet. This Howto was based on a clean Debian Linux installations but it shall work straight forward on any other system.

Prerequisites

Make sure the systems are properly connected to the Internet.

Tor’s hidden services where implemented into Tor starting with version 0.3.2. Make sure you have at least this version of Tor installed (run tor --version). If you have an older version on your system but you still want to use HSv3 you have to upgrade your Tor installation. Either use your package manager or download, compile, and install the latest version of Tor from https://dist.torproject.org/ .

Although the necessary feature was implemented into Onioncat many years ago, a tiny bug which came up recently prevented it from working correctly. You need to have Onioncat version 0.2.4 or higher on your system for HSv3 to work properly. Make sure you have at least 0.2.4 installed (run ocat -h to see installed version). Use your package manager to upgrade or download, compile, and install the latest version of Onioncat from https://www.cypherpunk.at/ocat/download/Source/current/ .

Make sure that your system has the ifconfig command installed. Simply run ifconfig as root and see what happens. If it says “ifconfig: command not found” then most probably it is not installed. Modern Linux distributions switched to a different set of network commands (ip) instead, but ifconfig can still be installed. On Debian-based systems ifconfig is found within the net-tools package (install with apt-get install net-tools).

Configure Tor

All of yoour Tor client (which are intended to be used with Onioncat) needs to have a hidden service configured.
Edit the Tor configuration file which typically is found at either /etc/torrc or /usr/local/etc/torrc and add the following three lines to each of the three systems (onioncat-a, onioncat-b, and onioncat-c)

HiddenServiceDir /var/lib/tor/onioncat_hsv3
HiddenServiceVersion 3
HiddenServicePort 8060 127.0.0.1:8060

Now run or restart Tor.

Note: Make sure that Tor connects properly to the Tor network. It typically outputs the following text into its logfile if everything is fine: “Bootstrapped 100% (done): Done“.

Compile Onioncat Hosts File

Now we need to create a hosts file. This is a list of your onion hostnames and the according Onioncat ipv6 addresses. It is a single file which can be shared (meaning copied to) between these three hosts. Because of we setup three hosts, the hosts file contains three lines.

On host “onioncat-a” change into the designated hidden service directory of Tor which is /var/lib/tor/onioncat_hsv3 (e.g. cd /var/lib/tor/onioncat_hsv3). We need root permission to do so. Within the directory we find a file named “hostname”. Display the contents of the file (e.g. cat hostname). It contains a string like this: qr4sshhsbcqfyircxqmi77j5pmgcki4keh5f6kybschqjb7xmas3siqd.onion. This is the unique onion name of the hidden service on host onioncat-a. To find the associated IPv6 address run Onioncat with option -i and this hostname as argument: ocat -i qr4sshhsbcqfyircxqmi77j5pmgcki4keh5f6kybschqjb7xmas3siqd.onion. It will output an IPv6 address which in this case is fd87:d87e:eb43:908f:487:f760:25b9:2203.
Create a new empty text file and add a line containing the IPv6 address followed by the hostname. You can add additional hostnames for your personal convenience if you like and you can add descriptive comments starting with a #.
Lookup the hostname and IPv6 address on each of the three systems and add the names and IP addresses to the same text file (the hosts files). Finally you should end up with a file like this (please note that there is no linebreak after the IP address, i.e. there’s just a single line after each comment):

# onioncat-a
fd87:d87e:eb43:908f:487:f760:25b9:2203 qr4sshhsbcqfyircxqmi77j5pmgcki4keh5f6kybschqjb7xmas3siqd.onion onioncat-a
# onioncat-b
fd87:d87e:eb43:6862:da73:63ad:fa91:f203 jbhu6id5htvwx3kahz6o2ms32bms75fbxjhyy2uonbrnu43dvx5jd4qd.onion onioncat-b
# onioncat-c
fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03 o3cjd437sxzfzobqn7g2ppy3b4j

Copy this file to each of the three hosts, e.g. into the Tor configuration directory at /etc/tor/hosts.oc (or /usr/local/etc/tor/hosts.oc).

Run Onioncat

Now we are ready to run Onioncat. On each host run Onioncat with its own onion hostname as an argument, e.g. on host onioncat-a we start Onioncat as root with the following command (in one line):

ocat -H -g /etc/tor/hosts.oc -U -B qr4sshhsbcqfyircxqmi77j5pmgcki4keh5f6kybschqjb7xmas3siqd.onion

Option -B keeps Onioncat running in foreground which may be convient for the installation and testing procedure. If -B is omitted, Onioncat will fork to the background and the log messages are written to the syslog.

Side note: Option -H enables hostname lookup which is required for the HSv3 lookup in a hosts file. Option -g /etc/tor/hosts.oc sets the path for the hosts file to be used. If this option is omitted, Onioncat will do the lookup in the system hosts file (/etc/hosts). Option -U disables the unidirectional mode. Although this is not necessary in this setup, with this option the time of connection setup is reduced.

Test the Setup

To test the setup open a new shell on one of your systems. You should be able to ping each of the three hosts with the ping6 command:

$ ping6 fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03
 PING fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03(fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03) 56 data bytes
 64 bytes from fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03: icmp_seq=2 ttl=64 time=315 ms
 64 bytes from fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03: icmp_seq=3 ttl=64 time=350 ms
 64 bytes from fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03: icmp_seq=4 ttl=64 time=313 ms
 ^C
 --- fd87:d87e:eb43:d1bf:d1c6:8553:559a:fe03 ping statistics ---
 5 packets transmitted, 3 received, 40% packet loss, time 4035ms
 rtt min/avg/max/mdev = 313.864/326.645/350.502/16.890 ms

$ ping6 fd87:d87e:eb43:6862:da73:63ad:fa91:f203
 PING fd87:d87e:eb43:6862:da73:63ad:fa91:f203(fd87:d87e:eb43:6862:da73:63ad:fa91:f203) 56 data bytes
 64 bytes from fd87:d87e:eb43:6862:da73:63ad:fa91:f203: icmp_seq=3 ttl=64 time=570 ms
 64 bytes from fd87:d87e:eb43:6862:da73:63ad:fa91:f203: icmp_seq=4 ttl=64 time=593 ms
 64 bytes from fd87:d87e:eb43:6862:da73:63ad:fa91:f203: icmp_seq=5 ttl=64 time=618 ms
 64 bytes from fd87:d87e:eb43:6862:da73:63ad:fa91:f203: icmp_seq=6 ttl=64 time=539 ms
 ^C
 --- fd87:d87e:eb43:6862:da73:63ad:fa91:f203 ping statistics ---
7 packets transmitted, 4 received, 42% packet loss, time 6041ms
 rtt min/avg/max/mdev = 539.112/580.280/618.032/29.220 ms

Please note that the first few pings may be lost because of the time Tor needs to create the circuit through the Tor network. Once the connection is open there should be no dataloss. The connections are close be Onioncat after two minutes of inactivity.