DoT and DoH (encrypted DNS)

Warning

It is important to understand limits of encrypting only DNS traffic. Relevant security analysis can be found in article Simran Patil and Nikita Borisov. 2019. What can you learn from an IP? See slides or the article itself.

DoT and DoH encrypt DNS traffic with Transport Layer Security (TLS) protocol and thus protects DNS traffic from certain types of attacks.

You can learn more about DoT and DoH and their implementation in Knot Resolver in this article.

DNS-over-TLS (DoT)

DNS-over-TLS server (RFC 7858) can be configured using dot kind in network/listen. It is enabled on localhost by default.

For certificate configuration, refer to HTTP status codes.

DNS-over-HTTPS (DoH)

Note

Knot Resolver currently offers two DoH implementations. It is recommended to use this new implementation, which is more reliable, scalable and has fewer dependencies. Make sure to use doh2 kind in network/listen to select this implementation.

Tip

Independent information about political controversies around the DoH deployment by default can be found in blog posts DNS Privacy at IETF 104 and More DOH by Geoff Huston and Centralised DoH is bad for Privacy, in 2019 and beyond by Bert Hubert.

DNS-over-HTTPS server (RFC 8484) can be configured using doh2 kind in network/listen.

This implementation supports HTTP/2 (RFC 7540). Queries can be sent to the /dns-query endpoint, e.g.:

$ kdig @127.0.0.1 +https www.knot-resolver.cz AAAA

Only TLS version 1.3 (or higher) is supported with DNS-over-HTTPS. The additional considerations for TLS 1.2 required by HTTP/2 are not implemented (RFC 7540 Section 9.2).

Warning

Take care when configuring your server to listen on well known HTTPS port. If an unrelated HTTPS service is running on the same port with REUSEPORT enabled, you will end up with both services malfunctioning.

HTTP status codes

As specified by RFC 8484, the resolver responds with status 200 OK whenever it can produce a valid DNS reply for a given query, even in cases where the DNS rcode indicates an error (like NXDOMAIN, SERVFAIL, etc.).

For DoH queries malformed at the HTTP level, the resolver may respond with the following status codes:

  • 400 Bad Request for a generally malformed query, like one not containing a valid DNS packet

  • 404 Not Found when an incorrect HTTP endpoint is queried - the only supported ones are /dns-query and /doh

  • 413 Payload Too Large when the DNS query exceeds its maximum size

  • 415 Unsupported Media Type when the query’s Content-Type header is not application/dns-message

  • 431 Request Header Fields Too Large when a header in the query is too large to process

  • 501 Not Implemented when the query uses a method other than GET, POST, or HEAD

Configuration options for DoT and DoH

Note

These settings affect both DNS-over-TLS and DNS-over-HTTPS (including the legacy implementation).

A self-signed certificate is generated by default. For serious deployments it is strongly recommended to configure your own TLS certificates signed by a trusted CA.

Knot Resolver respects system-wide cryptographic policies. If you are using a distro that ships such a package, you may use crypto-policies to additionally harden DoT/DoH encryption by disabling certain cipher suites, outdated TLS protocols etc.

Please note that Knot Resolver already disallows the usage of TLS 1.1 and lower as per section 9 of RFC 8310. This cannot be overridden by system-wide policies.

network/tls:
cert-file: <path>
key-file: <path>
network:
  tls:
    cert-file: /etc/knot-resolver/server-cert.pem
    key-file: /etc/knot-resolver/server-key.pem

Tip

The certificate files aren’t automatically reloaded on change. If you update the certificate files, e.g. using ACME, you have to either reload or restart the service(s).

sticket-secret: <str>

Optional, secret for TLS session resumption via tickets, by RFC 5077.

The server-side key is rotated roughly once per hour. By default or if called without secret, the key is random. That is good for long-term forward secrecy, but multiple workers won’t be able to resume each other’s sessions.

If you provide the same secret to multiple workers, they will be able to resume each other’s sessions without any further communication between them. This synchronization works only among instances having the same endianness and time_t structure and size (sizeof(time_t)).

For good security the secret must have enough entropy to be hard to guess, and it should still be occasionally rotated manually and securely forgotten, to reduce the scope of privacy leak in case the secret leaks eventually.

Warning

Setting the secret is probably too risky with TLS <= 1.2 and GnuTLS < 3.7.5. GnuTLS 3.7.5 adds an option to disable resumption via tickets for TLS <= 1.2, enabling them only for protocols that do guarantee PFS. Knot Resolver makes use of this new option when linked against GnuTLS >= 3.7.5.

sticket-secret-file: <path>

The same as sticket-secret, except the secret is read from a (binary) file.

padding: true|false|<0-512>
Default:

true

EDNS(0) padding of answers of queries and answers sent over an encrypted channel. If set to true (the default), it will use a sensible default padding scheme, as implemented by libknot if available at compile time. If set to a numeric value >= 2 it will pad the answers to nearest padding boundary, e.g. if set to 64, the answer will have size of a multiple of 64 (64, 128, 192, …). If set to false (or a number < 2), it will disable padding entirely.