:header: "Protocol/service", "net.listen *kind*"
"DNS (unencrypted UDP+TCP, :rfc:`1034`)","``dns``"
- ":ref:`DNS-over-TLS (DoT) <tls-server-config>`","``tls``"
- ":ref:`mod-http-doh`","``doh``"
+ ":ref:`dns-over-tls`","``tls``"
+ ":ref:`dns-over-https`","``doh2``"
":ref:`Web management <mod-http-built-in-services>`","``webmgmt``"
":ref:`Control socket <control-sockets>`","``control``"
+ ":ref:`mod-http-doh`","``doh``"
.. note:: By default, **unencrypted DNS and DNS-over-TLS** are configured to **listen
on localhost**.
:header: "**Network protocol**", "**Configuration command**"
"DNS (UDP+TCP, :rfc:`1034`)","``net.listen('192.0.2.123', 53)``"
- ":ref:`DNS-over-TLS (DoT) <tls-server-config>`","``net.listen('192.0.2.123', 853, { kind = 'tls' })``"
- ":ref:`mod-http-doh`","``net.listen('192.0.2.123', 443, { kind = 'doh' })``"
+ ":ref:`dns-over-tls`","``net.listen('192.0.2.123', 853, { kind = 'tls' })``"
+ ":ref:`dns-over-https`","``net.listen('192.0.2.123', 443, { kind = 'doh2' })``"
":ref:`Web management <mod-http-built-in-services>`","``net.listen('192.0.2.123', 8453, { kind = 'webmgmt' })``"
":ref:`Control socket <control-sockets>`","``net.listen('/tmp/kres.control', nil, { kind = 'control' })``"
net.listen(net.eth0, 853, { kind = 'tls' })
net.listen('192.0.2.1', 53, { freebind = true })
net.listen({'127.0.0.1', '::1'}, 53, { kind = 'dns' })
- net.listen('::', 443, { kind = 'doh' }) -- see http module
+ net.listen('::', 443, { kind = 'doh2' })
net.listen('::', 8453, { kind = 'webmgmt' }) -- see http module
net.listen('/tmp/kresd-socket', nil, { kind = 'webmgmt' }) -- http module supports AF_UNIX
-.. warning:: Make sure you read section :ref:`mod-http-doh` before exposing
- the DNS-over-HTTP protocol to outside.
-
.. warning:: On machines with multiple IP addresses avoid listening on wildcards
``0.0.0.0`` or ``::``. Knot Resolver could answer from different IP
addresses if the network address ranges overlap,
.. _tls-server-config:
-DNS-over-TLS server (DoT)
--------------------------
-DoT encrypts DNS traffic with Transport Security Layer protocol and thus protects DNS traffic from certain types of attacks.
+DoT and DoH (encrypted DNS)
+---------------------------
.. warning::
See `slides <https://irtf.org/anrw/2019/slides-anrw19-final44.pdf>`_
or `the article itself <https://dl.acm.org/authorize?N687437>`_.
-DNS-over-TLS server (:rfc:`7858`) is enabled by default on localhost.
-Information how to configure listening on specific IP addresses is in previous sections:
+DoT and DoH encrypt DNS traffic with Transport Layer Security (TLS) protocol
+and thus protects DNS traffic from certain types of attacks.
+
+.. _dns-over-tls:
+
+DNS-over-TLS (DoT)
+^^^^^^^^^^^^^^^^^^
+
+DNS-over-TLS server (:rfc:`7858`) can be configured using ``tls`` kind in
+:func:`net.listen()`. It is enabled on localhost by default.
+
+For certificate configuration, refer to :ref:`dot-doh-config-options`.
+
+.. _dns-over-https:
+
+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
+ :func:`net.listen()` to select this implementation.
+
+.. warning:: 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
:func:`net.listen()`.
-By default a self-signed certificate is generated. For serious deployments
+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.
+
+.. _dot-doh-config-options:
+
+Configuration options
+^^^^^^^^^^^^^^^^^^^^^
+
+.. note:: These settings affect both DNS-over-TLS and DNS-over-HTTPS (except
+ 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. This is done using function :c:func:`net.tls()`.
.. function:: net.tls([cert_path], [key_path])
- Get/set path to a server TLS certificate and private key for DNS/TLS.
+ Get/set path to a server TLS certificate and private key for DoT and DoH.
Example output:
> net.tls() -- print configured paths
("/etc/knot-resolver/server-cert.pem", "/etc/knot-resolver/server-key.pem")
-.. function:: net.tls_padding([true | false])
-
- Get/set EDNS(0) padding of answers to queries that arrive over TLS
- transport. 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.
-
.. function:: net.tls_sticket_secret([string with pre-shared secret])
Set secret for TLS session resumption via tickets, by :rfc:`5077`.
The same as :func:`net.tls_sticket_secret`,
except the secret is read from a (binary) file.
+
+.. function:: net.tls_padding([true | false])
+
+ Get/set EDNS(0) padding of answers to queries that arrive over TLS
+ transport. 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.
+
daemon-bindings-net_server
daemon-bindings-net_tlssrv
modules-http
- modules-http-doh
Client (retrieving answers from servers)
========================================
+++ /dev/null
-../modules/http/README.doh.rst
\ No newline at end of file
+++ /dev/null
-.. SPDX-License-Identifier: GPL-3.0-or-later
-
-.. _mod-http-doh:
-
-DNS-over-HTTP (DoH)
-===================
-
-.. warning::
-
- * DoH support was added in version 4.0.0 and is subject to change.
- * DoH implementation in Knot Resolver is intended for experimentation
- only as there is insufficient experience with the module
- and the DoH protocol in general.
- * For the time being it is recommended to run DoH endpoint
- on a separate machine which is not handling normal DNS operations.
- * Read about perceived benefits and risks at
- `Mozilla's DoH page <https://support.mozilla.org/en-US/kb/firefox-dns-over-https>`_.
- * 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>`_.
- * 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.
-
-Following section compares several options for running a DoH capable server.
-Make sure you read through this chapter before exposing the DoH service to users.
-
-DoH support in Knot Resolver
-----------------------------
-
-The :ref:`HTTP module <mod-http>` in Knot Resolver also provides support for
-binary DNS-over-HTTP protocol standardized in :rfc:`8484`.
-
-This integrated DoH server has following properties:
-
-:Scenario:
- HTTP module in Knot Resolver configured to provide ``/doh`` endpoint
- (as shown below).
-
-:Advantages:
- - Integrated solution provides management and monitoring in one place.
- - Supports ACLs for DNS traffic based on client's IP address.
-
-:Disadvantages:
- - Exposes Knot Resolver instance to attacks over HTTP.
- - Does not offer fine grained authorization and logging at HTTP level.
- - Let's Encrypt integration is not automated.
-
-
-:ref:`Example configuration <mod-http-example>` is part of examples for generic
-HTTP module. After configuring your endpoint you can reach the DoH endpoint using
-URL ``https://your.resolver.hostname.example/doh``, done!
-
-.. code-block:: bash
-
- # query for www.knot-resolver.cz AAAA
- $ curl -k https://your.resolver.hostname.example/doh?dns=l1sBAAABAAAAAAAAA3d3dw1rbm90LXJlc29sdmVyAmN6AAAcAAE
-
-Please see section :ref:`mod-http-tls` for further details about TLS configuration.
-
-Alternative configurations use HTTP proxies between clients and a Knot Resolver instance:
-
-Normal HTTP proxy
------------------
-:Scenario:
- A standard HTTP-compliant proxy is configured to proxy `GET`
- and `POST` requests to HTTP endpoint `/doh` to a machine
- running Knot Resolver.
-
-:Advantages:
- - Protects Knot Resolver instance from
- `some` types of attacks at HTTP level.
- - Allows fine-grained filtering and logging at HTTP level.
- - Let's Encrypt integration is readily available.
- - Is based on mature software.
-
-:Disadvantages:
- - Fine-grained ACLs for DNS traffic are not available because
- proxy hides IP address of client sending DNS query.
- - More complicated setup with two components (proxy + Knot Resolver).
-
-HTTP proxy with DoH support
----------------------------
-:Scenario:
- HTTP proxy extended with a
- `special module for DNS-over-HTTP <https://github.com/facebookexperimental/doh-proxy>`_.
- The module transforms HTTP requests to standard DNS queries
- which are then processed by Knot Resolver.
- DNS replies from Knot Resolver are then transformed back to HTTP
- encoding by the proxy.
-
-:Advantages:
- - Protects Knot Resolver instance from `all` attacks at HTTP level.
- - Allows fine-grained filtering and logging at HTTP level.
- - Let's Encrypt integration is readily available
- if proxy is based on a standard HTTP software.
-
-:Disadvantages:
- - Fine-grained ACLs for DNS traffic are not available because
- proxy hides IP address of client sending DNS query.
- (Unless proxy and resolver are using non-standard packet extensions like
- `DNS X-Proxied-For <https://datatracker.ietf.org/doc/draft-bellis-dnsop-xpf/>`_.)
- - More complicated setup with three components (proxy + special module + Knot Resolver).
-
-Client configuration
---------------------
-Most common client today is web browser Firefox, which requires manual configuration
-to use your own DNS resolver. Configuration options in Firefox are described at
-`Mozilla support site <https://support.mozilla.org/en-US/kb/firefox-dns-over-https#w_switching-providers>`_.
-
-.. warning::
-
- Make sure you read :ref:`warnings at beginning of this section <mod-http-doh>`.
.. _mod-http:
-HTTP services
-=============
+Other HTTP services
+===================
.. tip:: In most distributions, the ``http`` module is available from a
separate package ``knot-resolver-module-http``. The module isn't packaged
modules to export restful APIs and websocket streams.
One example is statistics module that can stream live metrics on the website,
-or publish metrics on request for Prometheus scraper, and also :ref:`mod-http-doh`.
+or publish metrics on request for Prometheus scraper.
By default this module provides two kinds of endpoints,
and unlimited number of "used-defined kinds" can be added in configuration.
+--------------+---------------------------------------------------------------------------------+
-| **Endpoint** | **Explanation** |
-+--------------+---------------------------------------------------------------------------------+
-| doh | :ref:`mod-http-doh` |
+| **Kind** | **Explanation** |
+--------------+---------------------------------------------------------------------------------+
| webmgmt | :ref:`built-in web management <mod-http-built-in-services>` APIs (includes DoH) |
+--------------+---------------------------------------------------------------------------------+
+| doh | :ref:`mod-http-doh` |
++--------------+---------------------------------------------------------------------------------+
Each network address and port combination can be configured to expose
one kind of endpoint. This is done using the same mechanisms as
they currently won't be shared.
It's assumed that you don't want a self-signed certificate for serious deployments anyway.
+.. _mod-http-doh:
+
+Legacy DNS-over-HTTPS (DoH)
+---------------------------
+
+.. warning:: The DoH implementation using ``http`` module is deprecated. It has
+ known performance and stability issues that won't be fixed. Use
+ :ref:`dns-over-https` instead.
+
+This was an experimental implementation of :rfc:`8484`. It was configured using
+``doh`` kind in :func:`net.listen`. Its configuration (such as certificates)
+took place in ``http.config()``.
+
+Queries were served on ``/doh`` and ``/dns-query`` endpoints.
+
.. _mod-http-built-in-services:
Built-in services
"``/stats``", "Statistics/metrics", "Exported :ref:`metrics <mod-stats-list>` from :ref:`mod-stats` in JSON format."
"``/metrics``", "Prometheus metrics", "Exported metrics for Prometheus_."
"``/trace/:name/:type``", "Tracking", ":ref:`Trace resolution <mod-http-trace>` of a DNS query and return the verbose logs."
- "``/doh``", "DNS-over-HTTP", ":rfc:`8484` endpoint, see :ref:`mod-http-doh`."
+ "``/doh``", "Legacy DNS-over-HTTPS", ":rfc:`8484` endpoint, see :ref:`mod-http-doh`."
+ "``/dns-query``", "Legacy DNS-over-HTTPS", ":rfc:`8484` endpoint, see :ref:`mod-http-doh`."
Dependencies
------------
projects / thirdparty / knot-resolver.git / commitdiff
