From cb32baf7ccae4540ace342d6f3da19534c14fe62 Mon Sep 17 00:00:00 2001 From: Stephan de Wit Date: Thu, 10 Mar 2022 13:12:27 +0100 Subject: [PATCH 1/5] unbound: add documentation for custom forwarding and DoT --- source/manual/how-tos/dnscrypt-proxy.rst | 18 +++---- source/manual/unbound.rst | 66 ++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 9 deletions(-) diff --git a/source/manual/how-tos/dnscrypt-proxy.rst b/source/manual/how-tos/dnscrypt-proxy.rst index c54c99ef..168a9953 100644 --- a/source/manual/how-tos/dnscrypt-proxy.rst +++ b/source/manual/how-tos/dnscrypt-proxy.rst @@ -14,17 +14,17 @@ After a page reload you will get a new menu entry under **Services** for DNSCryp When you start the daemon, it looks for a list of public DNS server from here: https://dnscrypt.info/public-servers -Depending on all settings below the list will shortened to your choice, like only IPv4, or logging disabled. +Depending on all settings below the list can be shortened to your choice, like only IPv4, or logging disabled. The fastest two servers will be used for DNS queries. If you use Unbound as your main resolver and want to -send your queries to Unbound first and forward to DNSCrypt-Proxy, just set this in your Unbound Advanced -settings: +send your queries to Unbound first and forward to DNSCrypt-Proxy, just set this in your Unbound Custom Forwarding +entries: -.. code-block:: sh - - do-not-query-localhost: no - forward-zone: - name: "." - forward-addr: 127.0.0.1@5353 +==================================== =============================================================================== +Enabled Checked +Domain +Server IP 127.0.0.1 +Port 5353 +==================================== =============================================================================== ---------------- General Settings diff --git a/source/manual/unbound.rst b/source/manual/unbound.rst index 9246e37a..fff19e49 100644 --- a/source/manual/unbound.rst +++ b/source/manual/unbound.rst @@ -242,6 +242,72 @@ YoYo List https://pgl.yoyo.org/adservers/ Usually once a day is a good enough interval for these type of tasks. + +------------------------- +Custom Forwarding +------------------------- + +Enabling Query Forwarding in Unbound-->General lets Unbound use the configured system nameservers to +forward queries to. Since this does not allow for fine-grained control, the Custom Forwarding section allows for +entering arbitrary nameservers to forward queries to. It is assumed that the nameservers entered here are capable +of handling further recursion for any query. In this section you are able to specify nameservers to forward to +for specific domains queried by clients, catch all domains and specify nondefault ports. + +===================================================================================================================== + +.. note:: + + Keep in mind that if Query Forwarding in Unbound-->General is enabled, the system nameservers will be preferred + over any **catch-all entry** in both Custom Forwarding and DNS-over-TLS, this means that entries with a specific domain + will still be forwarded to the specified nameserver. + + +==================================== =============================================================================== +Enabled Enable query forwarding for this domain. +Domain Domain of the host. All queries for this domain will be forwarded to the + nameserver specified in "Server IP". Leave empty to catch all queries and + forward them to the nameserver. +Server IP Address of the DNS server to be used for recursive resolution. +Port Specify the port used by the DNS server. Default is port 53. Useful when + configuring e.g. :doc:`/manual/how-tos/dnscrypt-proxy` +==================================== =============================================================================== + +------------------------- +DNS over TLS +------------------------- + +DNS over TLS uses the same logic as Custom Forwarding, except it uses TLS for transport. + +===================================================================================================================== + +.. note:: + + Please be aware of interactions between Custom Forwarding and DNS over TLS. Since the same principle as Custom + Forwarding applies, a **catch-all entry** specified in both sections will be considered a duplicate zone. + In our case DNS over TLS will be preferred. + + +==================================== =============================================================================== +Enabled Enable DNS over TLS for this domain. +Domain Domain of the host. All queries for this domain will be forwarded to the + nameserver specified in "Server IP". Leave empty to catch all queries and + forward them to the nameserver. +Server IP Address of the DNS server to be used for recursive resolution. +Port Specify the port used by the DNS server. Always enter port 853 here unless + there is a good reason not to, such as when using an SSH tunnel. +Verify CN The name to use for certificate verification, e.g. "445b9e.dns.nextdns.io" + Used by Unbound to check the TLS authentication certificates. + It is strongly discouraged to omit this field since man-in-the-middle attacks + will still be possible. +==================================== =============================================================================== + +.. tip:: + + To ensure a validated environment, it is a good idea to block all outbound DNS traffic on port 53 using a + firewall rule when using DNS over TLS. Should clients query other nameservers directly themselves, a NAT + redirect rule to 127.0.0.1:53 (the local Unbound service) can be used to force these requests over TLS. + + ------------------------- Statistics ------------------------- From 9d444d3f862fad8d0b540132940d7d490e5f403a Mon Sep 17 00:00:00 2001 From: oittaa <8972248+oittaa@users.noreply.github.com> Date: Wed, 30 Mar 2022 22:57:33 +0200 Subject: [PATCH 2/5] Add DNS over TLS documentation * Based on the current version found from here: https://github.com/opnsense/core/blob/d7188a1ccd02d4ebf677f5118aed360758b14ebb/src/opnsense/mvc/app/controllers/OPNsense/Unbound/forms/dialogDot.xml * Couple of examples for popular DoT resolvers. --- source/manual/unbound.rst | 53 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/source/manual/unbound.rst b/source/manual/unbound.rst index fff19e49..6625ddac 100644 --- a/source/manual/unbound.rst +++ b/source/manual/unbound.rst @@ -379,3 +379,56 @@ This is a sample configuration file to add an option in the server clause: .. Note:: This method replaces the ``Custom options`` settings in the General page of the Unbound configuration, which was removed in version 21.7. + +------------------------- +DNS over TLS +------------------------- + +DNS over TLS (DoT) is a network security protocol for encrypting and wrapping Domain Name System (DNS) queries and answers via the Transport Layer Security (TLS) protocol. The goal of the method is to increase user privacy and security by preventing eavesdropping and manipulation of DNS data via man-in-the-middle attacks. + +===================================================================================================================== + +==================================== =============================================================================== +Domain If a domain is entered here, queries for this specific domain will be forwarded + to the specified server. + Leave blank to forward all queries to the specified server (default). +Server IP IP address of DNS server to forward all requests. +Server Port Port of DNS server, for usual DNS use 53, if you use DoT set it to 853. +Verify CN Verify if CN in certificate matches this value. Please note that if this field + is omitted, Unbound will not perform any certificate verification. Therefore, + man-in-the-middle attacks are still possible. +==================================== =============================================================================== + +Public Resolvers + ++-------------------+-----------------------------------------+-------------+------------------------------+ +| Hosted by | Server IP | Server Port | Verify CN | ++===================+=========================================+=============+==============================+ +| `Cloudflare`_ | 1.1.1.1 | 853 | cloudflare-dns.com | +| +-----------------------------------------+ | | +| | 1.0.0.1 | | | +| +-----------------------------------------+ | | +| | 2606:4700:4700::1111 | | | +| +-----------------------------------------+ | | +| | 2606:4700:4700::1001 | | | ++-------------------+-----------------------------------------+-------------+------------------------------+ +| `Google`_ | 8.8.8.8 | 853 | dns.google | +| +-----------------------------------------+ | | +| | 8.8.4.4 | | | +| +-----------------------------------------+ | | +| | 2001:4860:4860::8888 | | | +| +-----------------------------------------+ | | +| | 2001:4860:4860::8844 | | | ++-------------------+-----------------------------------------+-------------+------------------------------+ +| `Quad9`_ | 9.9.9.9 | 853 | dns.quad9.net | +| +-----------------------------------------+ | | +| | 149.112.112.112 | | | +| +-----------------------------------------+ | | +| | 2620:fe::fe | | | +| +-----------------------------------------+ | | +| | 2620:fe::9 | | | ++-------------------+-----------------------------------------+-------------+------------------------------+ + +.. _Cloudflare: https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-tls/ +.. _Google: https://developers.google.com/speed/public-dns +.. _Quad9: https://www.quad9.net/service/service-addresses-and-features/ From afd0ed7f21f874e41001d1af96a98acf10d40fa3 Mon Sep 17 00:00:00 2001 From: Stephan de Wit Date: Thu, 31 Mar 2022 09:29:00 +0200 Subject: [PATCH 3/5] unbound: move public resolvers table to existing DoT documentation --- source/manual/unbound.rst | 87 +++++++++++++++------------------------ 1 file changed, 34 insertions(+), 53 deletions(-) diff --git a/source/manual/unbound.rst b/source/manual/unbound.rst index 6625ddac..0aeb1a3e 100644 --- a/source/manual/unbound.rst +++ b/source/manual/unbound.rst @@ -308,6 +308,40 @@ Verify CN The name to use for certificate verificati redirect rule to 127.0.0.1:53 (the local Unbound service) can be used to force these requests over TLS. +**Public Resolvers** + ++-------------------+-----------------------------------------+-------------+------------------------------+ +| Hosted by | Server IP | Server Port | Verify CN | ++===================+=========================================+=============+==============================+ +| `Cloudflare`_ | 1.1.1.1 | 853 | cloudflare-dns.com | +| +-----------------------------------------+ | | +| | 1.0.0.1 | | | +| +-----------------------------------------+ | | +| | 2606:4700:4700::1111 | | | +| +-----------------------------------------+ | | +| | 2606:4700:4700::1001 | | | ++-------------------+-----------------------------------------+-------------+------------------------------+ +| `Google`_ | 8.8.8.8 | 853 | dns.google | +| +-----------------------------------------+ | | +| | 8.8.4.4 | | | +| +-----------------------------------------+ | | +| | 2001:4860:4860::8888 | | | +| +-----------------------------------------+ | | +| | 2001:4860:4860::8844 | | | ++-------------------+-----------------------------------------+-------------+------------------------------+ +| `Quad9`_ | 9.9.9.9 | 853 | dns.quad9.net | +| +-----------------------------------------+ | | +| | 149.112.112.112 | | | +| +-----------------------------------------+ | | +| | 2620:fe::fe | | | +| +-----------------------------------------+ | | +| | 2620:fe::9 | | | ++-------------------+-----------------------------------------+-------------+------------------------------+ + +.. _Cloudflare: https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-tls/ +.. _Google: https://developers.google.com/speed/public-dns +.. _Quad9: https://www.quad9.net/service/service-addresses-and-features/ + ------------------------- Statistics ------------------------- @@ -379,56 +413,3 @@ This is a sample configuration file to add an option in the server clause: .. Note:: This method replaces the ``Custom options`` settings in the General page of the Unbound configuration, which was removed in version 21.7. - -------------------------- -DNS over TLS -------------------------- - -DNS over TLS (DoT) is a network security protocol for encrypting and wrapping Domain Name System (DNS) queries and answers via the Transport Layer Security (TLS) protocol. The goal of the method is to increase user privacy and security by preventing eavesdropping and manipulation of DNS data via man-in-the-middle attacks. - -===================================================================================================================== - -==================================== =============================================================================== -Domain If a domain is entered here, queries for this specific domain will be forwarded - to the specified server. - Leave blank to forward all queries to the specified server (default). -Server IP IP address of DNS server to forward all requests. -Server Port Port of DNS server, for usual DNS use 53, if you use DoT set it to 853. -Verify CN Verify if CN in certificate matches this value. Please note that if this field - is omitted, Unbound will not perform any certificate verification. Therefore, - man-in-the-middle attacks are still possible. -==================================== =============================================================================== - -Public Resolvers - -+-------------------+-----------------------------------------+-------------+------------------------------+ -| Hosted by | Server IP | Server Port | Verify CN | -+===================+=========================================+=============+==============================+ -| `Cloudflare`_ | 1.1.1.1 | 853 | cloudflare-dns.com | -| +-----------------------------------------+ | | -| | 1.0.0.1 | | | -| +-----------------------------------------+ | | -| | 2606:4700:4700::1111 | | | -| +-----------------------------------------+ | | -| | 2606:4700:4700::1001 | | | -+-------------------+-----------------------------------------+-------------+------------------------------+ -| `Google`_ | 8.8.8.8 | 853 | dns.google | -| +-----------------------------------------+ | | -| | 8.8.4.4 | | | -| +-----------------------------------------+ | | -| | 2001:4860:4860::8888 | | | -| +-----------------------------------------+ | | -| | 2001:4860:4860::8844 | | | -+-------------------+-----------------------------------------+-------------+------------------------------+ -| `Quad9`_ | 9.9.9.9 | 853 | dns.quad9.net | -| +-----------------------------------------+ | | -| | 149.112.112.112 | | | -| +-----------------------------------------+ | | -| | 2620:fe::fe | | | -| +-----------------------------------------+ | | -| | 2620:fe::9 | | | -+-------------------+-----------------------------------------+-------------+------------------------------+ - -.. _Cloudflare: https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-tls/ -.. _Google: https://developers.google.com/speed/public-dns -.. _Quad9: https://www.quad9.net/service/service-addresses-and-features/ From 6b29967c7a0535d01624d707c78715c64124c511 Mon Sep 17 00:00:00 2001 From: Stephan de Wit Date: Thu, 31 Mar 2022 11:29:45 +0200 Subject: [PATCH 4/5] unbound: update Forwarding and DoT sections to reflect current state --- source/manual/unbound.rst | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/source/manual/unbound.rst b/source/manual/unbound.rst index 0aeb1a3e..9745f638 100644 --- a/source/manual/unbound.rst +++ b/source/manual/unbound.rst @@ -244,24 +244,31 @@ YoYo List https://pgl.yoyo.org/adservers/ ------------------------- -Custom Forwarding -------------------------- +Query Forwarding +------------------------- -Enabling Query Forwarding in Unbound-->General lets Unbound use the configured system nameservers to -forward queries to. Since this does not allow for fine-grained control, the Custom Forwarding section allows for -entering arbitrary nameservers to forward queries to. It is assumed that the nameservers entered here are capable -of handling further recursion for any query. In this section you are able to specify nameservers to forward to -for specific domains queried by clients, catch all domains and specify nondefault ports. +The Query Forwarding section allows for entering arbitrary nameservers to forward queries to. It is assumed +that the nameservers entered here are capable of handling further recursion for any query. In this section +you are able to specify nameservers to forward to for specific domains queried by clients, catch all domains +and specify nondefault ports. ===================================================================================================================== +==================================== =============================================================================== +Use System Namerservers The configured system nameservers will be used to forward queries to. + This will override any entry made in the custom forwarding grid, except for + entries targeting a specific domain. If there are no system nameservers, you + will be prompted to add one in `General `__. + If you expected a DNS server from your WAN and it's not listed, make sure you + set "Allow DNS server list to be overridden by DHCP/PPP on WAN" there as well. +==================================== =============================================================================== + .. note:: - Keep in mind that if Query Forwarding in Unbound-->General is enabled, the system nameservers will be preferred - over any **catch-all entry** in both Custom Forwarding and DNS-over-TLS, this means that entries with a specific domain + Keep in mind that if the "Use System Nameservers" checkbox is checked, the system nameservers will be preferred + over any **catch-all entry** in **both** Query Forwarding and DNS-over-TLS, this means that entries with a specific domain will still be forwarded to the specified nameserver. - ==================================== =============================================================================== Enabled Enable query forwarding for this domain. Domain Domain of the host. All queries for this domain will be forwarded to the @@ -276,13 +283,13 @@ Port Specify the port used by the DNS server. D DNS over TLS ------------------------- -DNS over TLS uses the same logic as Custom Forwarding, except it uses TLS for transport. +DNS over TLS uses the same logic as Query Forwarding, except it uses TLS for transport. ===================================================================================================================== .. note:: - Please be aware of interactions between Custom Forwarding and DNS over TLS. Since the same principle as Custom + Please be aware of interactions between Query Forwarding and DNS over TLS. Since the same principle as Query Forwarding applies, a **catch-all entry** specified in both sections will be considered a duplicate zone. In our case DNS over TLS will be preferred. @@ -295,7 +302,7 @@ Domain Domain of the host. All queries for this d Server IP Address of the DNS server to be used for recursive resolution. Port Specify the port used by the DNS server. Always enter port 853 here unless there is a good reason not to, such as when using an SSH tunnel. -Verify CN The name to use for certificate verification, e.g. "445b9e.dns.nextdns.io" +Verify CN The name to use for certificate verification, e.g. "445b9e.dns.nextdns.io". Used by Unbound to check the TLS authentication certificates. It is strongly discouraged to omit this field since man-in-the-middle attacks will still be possible. From 24045831e94cc09e069d6931cde0aa0c78b452d2 Mon Sep 17 00:00:00 2001 From: Stephan de Wit <33954429+swhite2@users.noreply.github.com> Date: Fri, 1 Apr 2022 14:14:19 +0200 Subject: [PATCH 5/5] unbound: fix typo --- source/manual/unbound.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/manual/unbound.rst b/source/manual/unbound.rst index 9745f638..dbf39ba0 100644 --- a/source/manual/unbound.rst +++ b/source/manual/unbound.rst @@ -255,7 +255,7 @@ and specify nondefault ports. ===================================================================================================================== ==================================== =============================================================================== -Use System Namerservers The configured system nameservers will be used to forward queries to. +Use System Nameservers The configured system nameservers will be used to forward queries to. This will override any entry made in the custom forwarding grid, except for entries targeting a specific domain. If there are no system nameservers, you will be prompted to add one in `General `__.