Resolving HNS names using DNS-over-HTTPS

Connect Firefox to Handshake in one step

DNS-over-HTTPS (DoH) is a convenient way to bootstrap devices to the Handshake Naming System. Clearly there is some immediate irony here since DoH relies on both the legacy DNS system and certificate authority, meaning we are using two centralized systems to access one decentralized system. The configuration I will describe here can still offer more privacy, security, and decentralization than other centralized services common among the community, in particular because anyone can run their own DoH server.

Some users may also prefer to configure just one single browser (Firefox) on their computer to resolve Handshake names because it can be done without affecting other browsers (Chrome) on the same system and requires no extra software installation.

Configure Firefox to use for DoH

You just need to enter that URL in your Firefox network settings:

1. Open “Preferences”
2. Scroll down and click “Network Settings”
3. Enable DNS over HTTPS

…and that’s it!

Slightly more advanced: skip legacy DNS


Then, using the table below, search for each setting name from the left and enter the corresponding value on the right:

network.trr.mode  3

Resolving DoH from iOS

After installing the app you have to edit its internal config file:

Here’s that blob at the bottom in a copy-and-paste-able field:


This value is computed from the dnscrypt-proxy Online DNS Stamp calculator:

What it does is compress details about the server into a single URL. Most of the values here you should recognize from the previous section, with the exception of the hash. That is the hash of the certificate authority certificate that “authorizes” the https server. In the case of easyhandshake, we use a Let’s Encrypt certificate.

Once the DNS Cloak configuration is set, you should be able to turn on the DNS service from the front page of the app:

…all done!

Running your own DoH server

First you’ll need an HNS source. I run an hsd full node but you could also run a pruned node or even an SPV node or hnsd. The DoH server is provided by DNS-over-HTTPS, written in Go. After following the installation instructions there, and getting a Let’s Encrypt certificate for your legacy DNS domain, you can create this config file, and save it at


# HTTP listen port
listen = [

# Local address and port for upstream DNS
# If left empty, a local address is automatically chosen.
local_addr = ""

# TLS certification file
cert = "/etc/letsencrypt/live/"

# TLS private key file
key = "/etc/letsencrypt/live/"

# HTTP path for resolve application
path = "/dns-query"

# Upstream DNS resolver
upstream = [

# Upstream timeout
timeout = 10

# Number of tries if upstream DNS fails
tries = 3

Note the local paths for the Let’s Encrypt certificate and private key. You’ll need to change those to match your domain name. Port 8053 is standard for DoH, and port 5350 is the default port for the hsd recursive resolver.

Once this file is done you should be able to sync hsd and then start the DOH server!

$ doh-server -conf=~/dns-over-https/doh-server/doh-server.conf


Finally, while this configuration does connect your devices to Handshake’s name resolution system, it still does not provide TLS. That means you can’t really trust the web content you are browsing to without additional steps like DANE verification.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store