From: Aleš Mrázek <ales.mrazek@nic.cz>
Date: Wed, 12 Jul 2023 13:36:34 +0000 (+0200)
Subject: docs: config: yaml for experimental features
X-Git-Tag: v6.0.2~16^2~5
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=67276ee3219448b1cbf36afa708aeb6c76551534;p=thirdparty%2Fknot-resolver.git

docs: config: yaml for experimental features
---

diff --git a/doc/config-experimental-dot-auth.rst b/doc/config-experimental-dot-auth.rst
new file mode 100644
index 000000000..38b219027
--- /dev/null
+++ b/doc/config-experimental-dot-auth.rst
@@ -0,0 +1,90 @@
+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _config-experimental-dot-auth:
+
+Experimental DNS-over-TLS Auto-discovery
+========================================
+
+This experimental feature provides automatic discovery of authoritative servers' supporting DNS-over-TLS.
+It uses magic NS names to detect SPKI_ fingerprint which is very similar to `dnscurve`_ mechanism.
+
+.. warning:: This protocol and feature is experimental and can be changed or removed at any time. Use at own risk, security properties were not analyzed!
+
+How it works
+------------
+
+It will look for NS target names formatted as:
+``dot-{base32(sha256(SPKI))}....``
+
+For instance, Knot Resolver will detect NS names formatted like this
+
+.. code-block:: none
+
+  example.com NS dot-tpwxmgqdaurcqxqsckxvdq5sty3opxlgcbjj43kumdq62kpqr72a.example.com
+
+and automatically discover that example.com NS supports DoT with the base64-encoded SPKI digest of ``m+12GgMFIiheEhKvUcOynjbn3WYQUp5tVGDh7Snwj/Q=``
+and will associate it with the IPs of ``dot-tpwxmgqdaurcqxqsckxvdq5sty3opxlgcbjj43kumdq62kpqr72a.example.com``.
+
+In that example, the base32 encoded (no padding) version of the sha256 PIN is ``tpwxmgqdaurcqxqsckxvdq5sty3opxlgcbjj43kumdq62kpqr72a``, which when
+converted to base64 translates to ``m+12GgMFIiheEhKvUcOynjbn3WYQUp5tVGDh7Snwj/Q=``.
+
+Generating NS target names
+--------------------------
+
+To generate the NS target name, use the following command to generate the base32 encoded string of the SPKI fingerprint:
+
+.. code-block:: bash
+
+  openssl x509 -in /path/to/cert.pem  -pubkey -noout | \
+  openssl pkey -pubin -outform der | \
+  openssl dgst -sha256 -binary | \
+  base32 | tr -d '=' | tr '[:upper:]' '[:lower:]'
+  tpwxmgqdaurcqxqsckxvdq5sty3opxlgcbjj43kumdq62kpqr72a
+
+Then add a target to your NS with: ``dot-${b32}.a.example.com``
+
+Finally, map ``dot-${b32}.a.example.com`` to the right set of IPs.
+
+.. code-block:: bash
+
+  ...
+  ...
+  ;; QUESTION SECTION:
+  ;example.com.      IN      NS
+
+  ;; AUTHORITY SECTION:
+  example.com. 3600  IN      NS      dot-tpwxmgqdaurcqxqsckxvdq5sty3opxlgcbjj43kumdq62kpqr72a.a.example.com.
+  example.com. 3600  IN      NS      dot-tpwxmgqdaurcqxqsckxvdq5sty3opxlgcbjj43kumdq62kpqr72a.b.example.com.
+
+  ;; ADDITIONAL SECTION:
+  dot-tpwxmgqdaurcqxqsckxvdq5sty3opxlgcbjj43kumdq62kpqr72a.a.example.com. 3600 IN A 192.0.2.1
+  dot-tpwxmgqdaurcqxqsckxvdq5sty3opxlgcbjj43kumdq62kpqr72a.b.example.com. 3600 IN AAAA 2001:DB8::1
+  ...
+  ...
+
+You can enable DoT auto-discovery feature in configuration file.
+
+.. code-block:: yaml
+
+   network:
+     tls:
+       # start an experiment, use with caution
+       auto-discovery: true
+
+This feature requires standard ``basexx`` Lua library which is typically provided by ``lua-basexx`` package.
+
+Caveats
+-------
+
+The feature relies on seeing the reply of the NS query and as such will not work if Knot Resolver uses data from its cache.
+You may need to delete the cache before starting the resolver to work around this.
+
+Auto-discovery also assumes that the NS query answer will return both the NS targets in the Authority section as well as the glue records in the Additional section.
+
+Dependencies
+------------
+
+* `lua-basexx <https://github.com/aiq/basexx>`_ available in LuaRocks
+
+.. _dnscurve: https://dnscurve.org/
+.. _SPKI: https://en.wikipedia.org/wiki/Simple_public-key_infrastructure
diff --git a/doc/config-experimental.rst b/doc/config-experimental.rst
index f709c1c7e..57084a060 100644
--- a/doc/config-experimental.rst
+++ b/doc/config-experimental.rst
@@ -10,5 +10,4 @@ Features in this section may changed, replaced or dropped in any release.
 .. toctree::
    :maxdepth: 1
 
-   daemon-scripting
-   modules-experimental_dot_auth
+   config-experimental-dot-auth
diff --git a/doc/index.rst b/doc/index.rst
index 73084c6d3..95a1f31fe 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -31,6 +31,7 @@ If you are a new user, please start with chapter for :ref:`getting started <gett
    config-logging-monitoring
    config-dnssec
    config-lua
+   config-experimental
 
 .. toctree::
    :caption: Deployment