policy TLS_FORWARD: add documentation

diff --git a/daemon/README.rst b/daemon/README.rst
index e7ce3c000b8102d5dc1217302a7c5a391860b823..4222cc3cd7ceb31d66ed194e66ea2bb51b576a0f 100644 (file)
--- a/daemon/README.rst
+++ b/daemon/README.rst
@@ -509,6 +509,8 @@ For when listening on ``localhost`` just doesn't cut it.
 
    Enable/disable using IPv4 for recursion.
 
+.. _tls-server-config:
+
 .. function:: net.listen(addresses, [port = 53, flags = {tls = (port == 853)}])
 
    :return: boolean

diff --git a/modules/policy/README.rst b/modules/policy/README.rst
index 2c082ff198cb222837b8609dbecd173298ccb755..c4e16504b3f6dcfa95a5dd9cd8ce649395b1b2d2 100644 (file)
--- a/modules/policy/README.rst
+++ b/modules/policy/README.rst
@@ -28,7 +28,8 @@ There are several actions available in the ``policy.`` table:
 * ``DENY`` - reply NXDOMAIN authoritatively
 * ``DROP`` - terminate query resolution and return SERVFAIL to the requestor
 * ``TC`` - set TC=1 if the request came through UDP, forcing client to retry with TCP
-* ``FORWARD(ip)`` - solve a query via forwarding to an IP while validating and caching locally;
+* ``FORWARD(ip)`` - resolve a query via forwarding to an IP while validating and caching locally;
+* ``TLS_FORWARD({{ip, authentication}})`` - resolve a query via TLS connection forwarding to an IP while validating and caching locally;
   the parameter can be a single IP (string) or a lua list of up to four IPs.
 * ``STUB(ip)`` - similar to ``FORWARD(ip)`` but *without* attempting DNSSEC validation.
   Each request may be either answered from cache or simply sent to one of the IPs with proxying back the answer.
@@ -43,8 +44,37 @@ Most actions stop the policy matching on the query, but "chain actions" allow to
 
 .. note:: The module (and ``kres``) expects domain names in wire format, not textual representation. So each label in name is prefixed with its length, e.g. "example.com" equals to ``"\7example\3com"``. You can use convenience function ``todname('example.com')`` for automatic conversion.
 
-Examples
-^^^^^^^^
+Forwarding over TLS protocol (DNS-over-TLS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Policy `TLS_FORWARD` allows you to forward queries using `Transport Layer Security`_ protocol, which hides content of your queries before attacker observing network traffic. Further details about this protocol can be found in `RFC 7858`_ and `IETF draft dprive-dtls-and-tls-profiles`_.
+
+Queries affected by `TLS_FORWARD` policy will always be resolved over TLS connection. Knot Resolver does not implement fallback to non-TLS connection, so if TLS connection cannot be established or authenticated according to configuration, the resolution will fail.
+
+To test this feature you need to either :ref:`configure Knot Resolver as DNS-over-TLS server <tls-server-config>`, or pick some public DNS-over-TLS server. Please see `DNS Privacy Project`_ homepage for list of public servers.
+
+TLS Examples
+~~~~~~~~~~~~
+
+.. code-block:: lua
+
+       modules = { 'policy' }
+       -- forward all queries over TLS to the specified server
+       policy.add(policy.all(policy.TLS_FORWARD({{'192.0.2.1', pin='YQ=='}})))
+       -- for brevity, other TLS examples omit policy.add(policy.all())
+       -- single server authenticated using its certificate pin
+         policy.TLS_FORWARD({{'192.0.2.1', pin='YQ=='}})  -- pin is base64-encoded
+       -- single server with multiple valid pins (e.g. anycast)
+         policy.TLS_FORWARD({{'192.0.2.1', pin={'YQ==', 'Wg=='}})
+       -- multiple servers, each with own authenticator
+         policy.TLS_FORWARD({ -- please note that { here starts list of servers
+               {'192.0.2.1', pin='Wg=='},
+               -- server must present certificate issued by specified CA and hostname must match
+               {'2001:DB8::d0c', hostname='res.example.', ca_file='/etc/knot-resolver/tlsca.crt'}
+       })
+
+
+Other examples
+^^^^^^^^^^^^^^
 
 .. code-block:: lua
 
@@ -164,3 +194,7 @@ Most properties (actions, filters) are described above.
 .. _RPZ: https://dnsrpz.info/
 .. _`Pro DNS and BIND`: http://www.zytrax.com/books/dns/ch7/rpz.html
 .. _`Jan-Piet Mens's post`: http://jpmens.net/2011/04/26/how-to-configure-your-bind-resolvers-to-lie-using-response-policy-zones-rpz/
+.. _`Transport Layer Security`: https://en.wikipedia.org/wiki/Transport_Layer_Security
+.. _`DNS Privacy Project`: https://dnsprivacy.org/
+.. _`RFC 7858`: https://tools.ietf.org/html/rfc7858
+.. _`IETF draft dprive-dtls-and-tls-profiles`: https://tools.ietf.org/html/draft-ietf-dprive-dtls-and-tls-profiles