Tor Hidden Services on OpenBSD with HTTPD

5 min readOct 17, 2020

The following guide will help you stand up a simple web-site hosted behind a TOR V3 Hidden Service using OpenBSD.

Getting Tor up and running

IMPORTANT : Unless otherwise specified all of the commands in this guide should run as root.

Step one is to install Tor and enable the Tor service by issuing the following commands:

pkg_add tor       # Install Tor
rcctl enable tor  # Enable the Tor service

Next we’ll to open up Tor’s configuration in OpenBSD’s default editor…

vi /etc/tor/torrc

…and replace it with the following:

# Log notice and debug messages to explit file locations
# for easy review if things go sideways...
Log notice file /var/log/tor/notices.log
Log debug file /var/log/tor/debug.log

RunAsDaemon 1

DataDirectory /var/tor

HiddenServiceDir /var/tor/hidden_service/
HiddenServicePort 80 127.0.0.1:8080

# Optional : Create per-user onion URLs requiring
# credentialed authentication to access.
# As of Tor version 4.4.x only version 2 hidden services
# support the "stealth" hidden services paradigm.

# HiddenServiceVersion 2
# HiddenServiceAuthorizeClient stealth client_1,client_2

User _tor

Take special note of the notice and debug log file locations in the configuration specified above. You’ll want to examine those if things go sideways.

Also note that our hidden service is configured to proxy HTTP traffic received over the Tor network on port 80 to port 8080 locally. Later we’ll configure OpenBSD’s default web server to serve our site’s content on port 8080 thus completing the circuit.

Next we need to create the log directories we configured above and insure the correct filesystem permissions are set.

mkdir -p /var/tor/hidden_service
chown _tor:_tor /var/tor/hidden_service
chown 700 /var/tor

mkdir /var/log/tor
chown _tor:_tor /var/log/tor
chmod 755 /var/log/tor

Now that Tor is properly installed and configured we can start the Tor service with the following command:

rcctl start tor

If all goes well you’ll receive the response tor(ok).

If you find that this guide somehow led you astray and you manage to figure out what went wrong please let me know in the comments section so I can improve it!

The last step before we proceed to configure the web server is to retrieve the URL of our new hidden service using the following command:

more /var/tor/hidden_service/hostname

The URL produced will look something like the following but a bit longer. I’ve shortened it here to help with formatting.

cepq5isz4xfwd66l2rn5yh2z2r6jzdv.onion

IMPORTANT : Wherever else in this guide you see this URL you’ll need to replace it with the one you will find in your hidden service’s hostname file.

Getting HTTPD up and running

OpenBSD’s standard installation includes a hardened, minimalist web server called HTTPD.

To configure it we’ll create the configuration file like so…

vi /etc/httpd.conf

…and then add the following:

server "cepq5isz4xfwd66l2rn5yh2z2r6jzdv.onion" {
    listen on * port 8080
    root "/htdocs/cepq5isz4xfwd66l2rn5yh2z2r6jzdv.onion"
}

types {
    include "/usr/share/misc/mime.types"
}

Our configuration first specifies the URL of our hidden service. Next it configures the web server to listen for requests on port 8080 which matches the port assignment we configured in our torrc file earlier. Finally it tells the server where the content for our web-site is located on the filesystem.

The choice to use the hidden service’s onion URL as the directory name isn't required but hopefully improves clarity if we want to eventually serve more than one site. It's also important to note here that the path being specified is relative to the /var/www directory which is where HTTPD expects the content it serves to be located.

To test our onion site we’ll create the directory we just configured above and then create the simplest of web-sites:

mkdir /var/www/htdocs/cepq5isz4xfwd66l2rn5yh2z2r6jzdv.onionchmod 755 /var/www/htdocs/cepq5isz4xfwd66l2rn5yh2z2r6jzdvxe5nb.onionecho "<html><body>w00t</body></html>" > /var/www/htdocs/cepq5isz4xfwd66l2rn5yh2z2r6jzdv.onion/index.html

Before we start HTTPD we should insure the configuration is valid by running the following command:

httpd -n

If all goes well you’ll receive the response configuration OK and can proceed to enable and start the HTTPD service:

rcctl enable httpdrcctl start httpd# To get httpd to start automatically after a reboot
# we need to patch the rc.conf file like so. Be aware 
# that this patch may not survive a sysupgrade - if
# you know a better approach let me know! sed -i 's/httpd_flags=NO/httpd_flags=/g' /etc/rc.conf

Testing your hidden service

Tor might take a minute or two to fully bootstrap your hidden service onto the network so wait at least that long before you start to worry that something has gone wrong. To test your hidden service just point a Tor Browser at its onion URL. You can also test it from the command line like so:

pkg_add wget torsockstorsocks wget cepq5isz4xfwd66l2rn5yh2z2r6jzdv.onion

Stealth hidden services

If you paid close attention you might have noticed the mention of stealth hidden services in our torrc file.

The TL;DR is that a stealth hidden service is a special (v2 only) hidden service that:

provides each client its own unique onion URL and
requires these same clients to authenticate by presenting a cookie containing the key corresponding to the onion URL they’ve been assigned

If you decide to enable stealth hidden services you’ll find extra entries in the hidden service’s hostname file for each client you specified the next time you stop and start the Tor service.

To connect to one of these stealth hidden service onion URLs using the Tor Browser you’ll need to configure its torrc file with the corresponding values sourced from these extra entries like so:

HidServAuth onionurl cookiekey  # client: client_1

One great use-case for stealth hidden services is to provide strongly authenticated access to web-based system administration consoles.

And that’s it!

Tor hidden services are often employed to allow web publishers to provide safer access to users living behind the national firewalls of authoritarian regimes. Facebook’s hidden service is just one great example.

Another new feature, onion-location, allows web-site operators to direct visitors using the Tor Browser to their more secure hidden service alternative.

If you think privacy is important then consider donating to either (or both!) the Tor Project or the Electronic Freedom Foundation. You’ll be glad you did!