Resolving HNS names using DNS-over-HTTPS

Connect Firefox to Handshake in one step

Matthew Zipkin
4 min readNov 21, 2020

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

This configuration will use a DoH server I maintain at

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

You can remove the reliance on the legacy DNS system by hard-coding the IP address of into Firefox, thereby removing the need to look it up using ICANN’s root zone. Start by entering this in the Firefox URL bar:


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

You can also point your iPhone’s DNS at easyhandshake using a type of VPN app called DNS Cloak, which is also open-source, and based on dnscrypt-proxy.

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

You don’t need to use easyhandshake, anyone can run a Handshake DoH server. You might want to run your own so you don’t have to trust me! Here’s how I set up easyhandshake’s DoH:

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


So as mentioned above, this system relies on the legacy certificate authorities like Let’s Encrypt and possibly also the legacy DNS system. We can bypass the legacy DNS lookup, but we are still trusting Let’s Encrypt not to revoke my certificate, or create a malicious entity with a new certificate and try to impersonate In addition, using as your HNS resolver means you are trusting me.

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.