Knowledge Base ISC Main Website Ask a Question/Contact ISC
DNS over TLS
Author: Francis Dupont Reference Number: AA-01386 Views: 26528 Created: 2016-06-04 12:07 Last Updated: 2018-07-10 21:45 0 Rating/ Voters

RFC 7858 specifies DNS over TLS (Transport Layer Security). This article explains how to provide a DNS over TLS service using bind9 and stunnel ( The setup of a privacy aggregator is at the end.

bind9 configuration: nothing special but if you want to limit external insecure access to the service you can play with listen-on clause address and port, acl or even system firewall as bind9 provides no per transport protocol access control.

stunnel setup for the opportunistic privacy profile:

  • create a X.509 public key certificate, for instance by:

    openssl genrsa -out dns.key 1024

    openssl req -new -key dns.key -out dns.crt -x509

    this creates a self-signed certificate, enough for clients performing no authentication.

  • create a stunnel configuration dnstls.conf:


    accept = 853

    connect =

    cert = dns.crt

    key = dns.key

    The service_name should be dns according to documentation. The DNS over TLS well know port is 853, stunnel will accept any TLS connection on this port and forward content in TCP to (localhost) on port 53 (dns).

  • launch stunnel in daemon mode using the configuration file:

  • stunnel dnstls.conf

stunnel setup for the the out-of-band key-pinned privacy profile:

  • you should use a real X.509 CA but for experiments you can create a CA certificate by:

    openssl genrsa -out ca.key 1024

    openssl req -new -key ca.key -out ca.crt -x509 -extensions v3_ca

  • create a X.509 public key certificate in a X.509 Certificate Authority, for instance the homemade CA: 

    openssl genrsa -out dns.key 1024

    openssl req -new -key dns.key -out dns.req

    openssl x509 -req -in dns.req -out dns.crt -CA ca.crt -CAkey ca.key -CAcreateserial

  • add in stunnel configuration:

    CAfile = ca.crt

    this makes stunnel to add the CA certificate to the chain during TLS handshake (as it is supposed to do).
  • launch stunnel in daemon mode

 how to test the service using getdns ( ).

  • install (or configure and compile) getdns with the getdns_query tool you can find in src/test of the distribution.
  • if you'd like to authenticate the server, the CA must be known. The simplest way to do it is:

    $ export SSL_CERT_FILE=.../ca.crt

    % setenv SSL_CERT_FILE .../ca.crt

    if you have a shell or a c-shell filling the ... by the path where the OpenSSL library can find the CA certificate.
  • For key-pinning you have to compute the sha256 pin, according to you can use from the key:
    openssl rsa -in dns.key -outform der -pubout | openssl dgst -sha256 -binary | openssl enc -base64
    or from the certificate:
    openssl x509 -in dns.crt -pubkey -noout | openssl rsa -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
  • A typical call could be:
    getdns_query -s a @ -l L
    -l L ask for TLS transport (vs. U for UDP or T for TCP)
  • or with key-pinning:

    getdns_query -s a @ -l -L -K 'pin-sha256="KAGwR1fXzY4JJtBP1yYoAisc+4yNomT6VrFPwkMi5qE="' -m

    -K specifies a public key pin, -m requires authentication (vs -n for no authentication).

bind9 setup for a privacy aggregator uses for instance:

options {


    forwarders { port 1053; };

    forward only;


server {

    tcp-only yes;



forwarders makes all queries to be forwarded to the designated service on another port, forward only disables fallback to standard resolution, the tcp-only clause in the server entry enforces the use of TCP transport (note this feature was added in version 9.11).

stunnel setup for a privacy aggregator is in client mode with for instance:


client = yes

accept = localhost:1053

connect = <server>:853

To test the privacy aggregator setup: <client_hosts> --- *:53 <named> localhost:1053 <stunnel> ---- *:853 <unbound> an unbound configuration could be:




    ssl-port: 853

    ssl-service-key: dns.key

    ssl-service-pen: dns.crt

    do-udp: no

© 2001-2018 Internet Systems Consortium

For assistance with problems and questions for which you have not been able to find an answer in our Knowledge Base, we recommend searching our community mailing list archives and/or posting your question there (you will need to register there first for your posts to be accepted). The bind-users and the dhcp-users lists particularly have a long-standing and active membership.

ISC relies on the financial support of the community to fund the development of its open source software products. If you would like to support future product evolution and maintenance as well having peace of mind knowing that our team of experts are poised to provide you with individual technical assistance whenever you call upon them, then please consider our Professional Subscription Support services - details can be found on our main website.

  • There is no feedback for this article
Quick Jump Menu