.. SPDX-License-Identifier: GPL-3.0-or-later

.. _config-network-server-tls:

DoT, DoH and DoQ (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 <https://irtf.org/anrw/2019/slides-anrw19-final44.pdf>`_
   or `the article itself <https://dl.acm.org/authorize?N687437>`_.

DoT, DoH and DoQ 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
<https://en.blog.nic.cz/2020/11/25/encrypted-dns-in-knot-resolver-dot-and-doh/>`_.

.. _dns-over-tls:

DNS-over-TLS (DoT)
^^^^^^^^^^^^^^^^^^

DNS-over-TLS server (:rfc:`7858`) can be configured using ``dot`` kind in
:option:`network/listen <network/listen: <list>>`.  It is enabled on localhost by default.

For certificate configuration, refer to :ref:`dot-doh-doq-config-options`.

.. _dns-over-https:

DNS-over-HTTPS (DoH)
^^^^^^^^^^^^^^^^^^^^

.. tip::

   Independent information about political controversies around the
   DoH deployment by default can be found in blog posts `DNS Privacy at IETF
   104 <http://www.potaroo.net/ispcol/2019-04/angst.html>`_ and `More DOH
   <http://www.potaroo.net/ispcol/2019-04/moredoh.html>`_ by Geoff Huston and
   `Centralised DoH is bad for Privacy, in 2019 and beyond
   <https://labs.ripe.net/Members/bert_hubert/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
:option:`network/listen <network/listen: <list>>`.

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

.. code-block:: bash

	$ 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``


.. _dot-doh-doq-config-options:

Configuration options for DoT, DoH and DoQ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::

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

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.

.. code-block:: yaml

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


Knot Resolver respects system-wide cryptographic policies. If you are using a
distro that ships such a package, you may use `crypto-policies
<https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening>`_
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.

.. option:: network/tls:

   .. option:: cert-file: <path>

   .. option:: key-file: <path>

   .. option:: files-watchdog: auto|true|false

      :default: auto

      By default, if you have ``python-watchdog`` installed on your system,
      the certificate files are automatically reloaded on change.
      When you update the certificate files, e.g. using ACME,
      the manager is notified of the changes and commands all workers
      to reload their certificate files.

      If you don't have ``python-watchdog`` installed, this feature is not available
      and you will have to restart the ``knot-resolver`` service manually.

      You can also manually enable (``true``) and disable (``false``) this feature in the config,
      but if it is enabled and ``python-watchdog`` is not installed,
      the resolver will fail to start with a configuration validation error.

   .. option:: 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 :ref:`workers <config-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 <pfs_>`_.

      .. 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 <pfs_>`_. Knot Resolver makes use of this new option when linked against GnuTLS >= 3.7.5.

   .. option:: sticket-secret-file: <path>

      The same as :option:`sticket-secret <sticket-secret: <str>>`, except the secret is read from a (binary) file.

   .. option:: 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.

.. Configuration options for DoH
.. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. .. function:: net.doh_headers([string or table of strings])

..    Selects the headers to be exposed. These headers and their values are
..    available in ``request.qsource.headers``. Comparison
..    is case-insensitive and pseudo-headers are supported as well.

..    The following snippet can be used in the lua module to access headers
..    ``:method`` and ``user-agent``:

..    .. code-block:: lua

..       net.doh_headers({':method', 'user-agent'})

..       ...

..       for i = 1, tonumber(req.qsource.headers.len) do
..         local name = ffi.string(req.qsource.headers.at[i - 1].name)
..         local value = ffi.string(req.qsource.headers.at[i - 1].value)
..         print(name, value)
..       end

.. _pfs: https://en.wikipedia.org/wiki/Forward_secrecy

.. _dns-over-quic:

DNS-over-QUIC (DoQ)
^^^^^^^^^^^^^^^^^^^

.. warning::
    DoQ is currently considered a beta feature,
    and its configuration might change.

    If you encounter any issues or have any questions,
    please do not hesitate to contact us via the standard communication channels.


DNS-over-QUIC server (:rfc:`9250`) can be configured using ``doq`` kind in
:option:`network/listen <network/listen: <list>>`.

For certificate configuration, refer to :ref:`dot-doh-doq-config-options`.

.. option:: network/quic:

    .. option:: max-conns: <1-4096>

    :default: 1024

    The maximum number of active connections each worker is permitted to accept.
    Setting this value too low or too high may negatively affect performance.
    Changing this value requires a worker restart.

    .. option:: max-streams: <1-4096>

    :default: 1024

    The maximum number of concurrent streams a connection can open.
    Setting this value too low or too high may negatively affect performance.
    Changing this value requires a worker restart.

    .. option:: require-retry: true|false

    :default: false

    Require address validation from unknown addresses. Retry requests might
    be sent under certain conditions regardless of this setting.
    Note that enabling this option imposes a 1-RTT delay for verifying
    the return routability of the source address of a client.

    For further details see:
    https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation-using-re
    and https://datatracker.ietf.org/doc/html/rfc9250#name-address-validation
