From: Tomas Krizek Date: Thu, 27 Aug 2020 13:01:00 +0000 (+0200) Subject: doc: update doh/doh2 documentation X-Git-Tag: v5.2.0~15^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=dcb520d17ceac8c067e0c82e958335069d7eb924;p=thirdparty%2Fknot-resolver.git doc: update doh/doh2 documentation --- diff --git a/daemon/bindings/net_server.rst b/daemon/bindings/net_server.rst index 2ef58354e..ce847a32f 100644 --- a/daemon/bindings/net_server.rst +++ b/daemon/bindings/net_server.rst @@ -13,10 +13,11 @@ First you need to decide what service should be available on given IP address :header: "Protocol/service", "net.listen *kind*" "DNS (unencrypted UDP+TCP, :rfc:`1034`)","``dns``" - ":ref:`DNS-over-TLS (DoT) `","``tls``" - ":ref:`mod-http-doh`","``doh``" + ":ref:`dns-over-tls`","``tls``" + ":ref:`dns-over-https`","``doh2``" ":ref:`Web management `","``webmgmt``" ":ref:`Control socket `","``control``" + ":ref:`mod-http-doh`","``doh``" .. note:: By default, **unencrypted DNS and DNS-over-TLS** are configured to **listen on localhost**. @@ -37,8 +38,8 @@ First you need to decide what service should be available on given IP address :header: "**Network protocol**", "**Configuration command**" "DNS (UDP+TCP, :rfc:`1034`)","``net.listen('192.0.2.123', 53)``" - ":ref:`DNS-over-TLS (DoT) `","``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 `","``net.listen('192.0.2.123', 8453, { kind = 'webmgmt' })``" ":ref:`Control socket `","``net.listen('/tmp/kres.control', nil, { kind = 'control' })``" @@ -52,13 +53,10 @@ Examples: 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, diff --git a/daemon/bindings/net_tlssrv.rst b/daemon/bindings/net_tlssrv.rst index 382ac0f64..ea8afcf5f 100644 --- a/daemon/bindings/net_tlssrv.rst +++ b/daemon/bindings/net_tlssrv.rst @@ -2,9 +2,8 @@ .. _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:: @@ -14,17 +13,70 @@ DoT encrypts DNS traffic with Transport Security Layer protocol and thus protect See `slides `_ or `the article itself `_. -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 `_ 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 :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: @@ -34,16 +86,6 @@ by a trusted CA. This is done using function :c:func:`net.tls()`. > 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`. @@ -72,3 +114,14 @@ by a trusted CA. This is done using function :c:func:`net.tls()`. 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. + diff --git a/doc/config-network.rst b/doc/config-network.rst index 1d3142f56..2faac0e36 100644 --- a/doc/config-network.rst +++ b/doc/config-network.rst @@ -43,7 +43,6 @@ Server (communication with clients) daemon-bindings-net_server daemon-bindings-net_tlssrv modules-http - modules-http-doh Client (retrieving answers from servers) ======================================== diff --git a/doc/modules-http-doh.rst b/doc/modules-http-doh.rst deleted file mode 120000 index 317d0e1f7..000000000 --- a/doc/modules-http-doh.rst +++ /dev/null @@ -1 +0,0 @@ -../modules/http/README.doh.rst \ No newline at end of file diff --git a/modules/http/README.doh.rst b/modules/http/README.doh.rst deleted file mode 100644 index 279d0db51..000000000 --- a/modules/http/README.doh.rst +++ /dev/null @@ -1,120 +0,0 @@ -.. 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 `_. - * 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 `_. - * 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. - -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 ` 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 ` 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 `_. - 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 `_.) - - 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 `_. - -.. warning:: - - Make sure you read :ref:`warnings at beginning of this section `. diff --git a/modules/http/README.rst b/modules/http/README.rst index 05ad0f3c8..b02b00abf 100644 --- a/modules/http/README.rst +++ b/modules/http/README.rst @@ -2,8 +2,8 @@ .. _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 @@ -14,18 +14,18 @@ server which provides few built-in services and also allows other 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 ` 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 @@ -124,6 +124,21 @@ Major drawback is that current browsers won't do HTTP/2 over insecure connection 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 @@ -137,7 +152,8 @@ The HTTP module has several built-in services to use. "``/stats``", "Statistics/metrics", "Exported :ref:`metrics ` from :ref:`mod-stats` in JSON format." "``/metrics``", "Prometheus metrics", "Exported metrics for Prometheus_." "``/trace/:name/:type``", "Tracking", ":ref:`Trace resolution ` 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 ------------