README.md

Openssl helper scripts

This directory contains openssl helper scripts which show how to generate a root Certificate Authority (CA) certificate and rootCA signed certificates for trustydns-server and trustydns-proxy. With such certificates you can create a DoH network in which only authorizedd proxies and servers can exchange DoH queries with each other. An alternative of course is to use firewall rules and ip filtering to achieve your access control goals but that's not very flexible and is hard to keep current if you run the proxy on mobile devices.

These scripts are simplistic and are only offered as a guide. You will need to use something far more robust and secure than these helpers when setting up a production environment.

Review site.conf and the make_* scripts

site.conf is the openssl configuration file used by all the helper scripts. You may want to review and edit it for your environment. Be careful - it is an arcane file. You may also wish to review the helper scripts as they have various hard-coded values such as key sizes, key lifetime, email addresses and default domains.

Generating the root CA

The first step is to generate the root CA files from which all other certificates are created:

./make_rootca_cert

This creates rootCA.cert and rootCA.key in PEM format (it also happens to create a few other "database" files in the current directory). The rootCA.cert file is distributed across your deployment as it needs to be supplied to both the proxy and server via this command-line snippet: --tls-other-roots rootCAcert.pem. The rootCA.key file should be well protected.

Generating server certificates

Server certificates are encoded with a domain name so clients can verify the URL domain name against the certificate domain name. Thus make_server_cert is invoked with domain names on the command line. These domain names form the DoH URLs used by the proxy and server.

./make_server_cert rootCA.cert rootCA.key mydoh1.example.net mydoh2.example.net

You will of course need a unique server certificate for each DoH server you wish to run. A unique pair of cert/key files are generated for each domain name by this script.

These key and certificate files are supplied to the server with the --tls-key and --tls-cert options respectively.

Creating proxy certificates

Unlike server certificates, proxy certificates do not have any uniquely identifying attributes such as domain names. Instead trustydns-server validates clients by confirming that they have been generated by the rootCA identified with the --tls-other-roots option. If not, the connection is rejected.

./make_proxy_cert rootCA.cert rootCA.key

Creates proxy.key and proxy.cert files in PEM format. While these files can be shared amongst proxy deployments, it's not a good idea to do so as that makes future revocation pretty inconvenient.

The generated key and certificate files are supplied to the proxy with the --tls-key and --tls-cert options respectively. Both daemons will also need --tls-other-roots set to identify the rootCA certificate. You should also have --log-tls-errors set when first testing private certificates as the failure modes are mostly closed connections and timeouts.