experimental_dot_auth: polish docs

diff --git a/modules/experimental_dot_auth/README.rst b/modules/experimental_dot_auth/README.rst
index ddfd51d38b7a12ed20a1b4a31d21ec7935ffd3c2..79c963b8b298a38276aa3755e6c6e671e5e9107c 100644 (file)
--- a/modules/experimental_dot_auth/README.rst
+++ b/modules/experimental_dot_auth/README.rst
@@ -1,12 +1,12 @@
 .. _mod-experimental_dot_auth:
 
-Experimental DNS-over-TLS (DoT) Auto-discovery
-----------------------------------------------
+Experimental DNS-over-TLS Auto-discovery
+----------------------------------------
 
-DoT module enables automatic discovery of authoritative servers' SPKI
-fingerprint via the use of magic NS names. It is very similar to `dnscurve`_ mechanism.
+This experimental module provides automatic discovery of authoritative servers' supporting DNS-over-TLS.
+The module uses magic NS names to detect SPKI_ fingerprint which is very similar to `dnscurve`_ mechanism.
 
-.. warning:: This module is experimental and can be changed or removed at any time. Use at own risk, security properties were not tested!
+.. warning:: This protocol and module is experimental and can be changed or removed at any time. Use at own risk, security properties were not analyzed!
 
 How it works
 ^^^^^^^^^^^^
@@ -14,19 +14,20 @@ How it works
 The module will look for NS target names formatted as:
 ``dot-{base32(sha256(SPKI))}....``
 
-For instance:
+For instance, Knot Resolver will detect NS names formatted like this
+
+.. code-block:: none
 
-.. code-block:: bash
   example.com NS dot-tpwxmgqdaurcqxqsckxvdq5sty3opxlgcbjj43kumdq62kpqr72a.example.com
 
-will automatically discover that example.com NS supports DoT with the base64-encoded SPKI digest of ``m+12GgMFIiheEhKvUcOynjbn3WYQUp5tVGDh7Snwj/Q=``
+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 targets
-^^^^^^^^^^^^^^^^^^^^^
+Generating NS target names
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To generate the NS target name, use the following command to generate the base32 encoded string of the SPKI fingerprint:
 
@@ -62,19 +63,22 @@ Finally, map ``dot-${b32}.a.example.com`` to the right set of IPs.
 Example configuration
 ^^^^^^^^^^^^^^^^^^^^^
 
-To enable the module, add this stanza to your config:
+To enable the module, add this snippet to your config:
 
 .. code-block:: lua
 
-       -- Load the module
+        -- Start an experiment, use with caution
        modules.load('experimental_dot_auth')
 
+This module requires standard ``basexx`` Lua library which is typically provided by ``lua-basexx`` package.
+
 Caveats
 ^^^^^^^
 
 The module relies on seeing the reply of the NS query and as such will not work
-if Knot Resolver use its cache. You may need to delete the cache before starting ``kresd`` to work around this.
+if Knot Resolver uses data from its cache. You may need to delete the cache before starting ``kresd`` to work around this.
 
 The module 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.
 
 .. _dnscurve: https://dnscurve.org/
+.. _SPKI: https://en.wikipedia.org/wiki/Simple_public-key_infrastructure