[#2096] updated documentation

3 files changed, 206 insertions, 41 deletions

diff --git a/doc/sphinx/arm/ext-gss-tsig.rst b/doc/sphinx/arm/ext-gss-tsig.rst
index 20c3c86bea..126ce339a2 100644
--- a/doc/sphinx/arm/ext-gss-tsig.rst
+++ b/doc/sphinx/arm/ext-gss-tsig.rst
@@ -15,13 +15,18 @@ GSS-TSIG Overview
 -----------------
 
 Kea provides a support for DNS updates, which can be protected using
-Transaction Signatures (or TSIG). This protection
-is often adequate. However, some systems, in particular Active Directory (AD)
-on Microsoft Windows systems, chose to adopt more complex GSS-TSIG
-approach that offers additional capabilities as using negotiated dynamic keys.
+Transaction Signatures (or TSIG). This protection is often adequate.
+However some systems, in particular Active Directory (AD) on Microsoft
+Windows systems, chose to adopt more complex GSS-TSIG approach that offers
+additional capabilities as using negotiated dynamic keys.
 
 Kea provides the support of GSS-TSIG to protect DNS updates sent by
 the Kea DHCP-DDNS (aka D2) server in a premium hook, called `gss_tsig`.
+
+.. note::
+
+    This library is still in the experimental phase. Use with care!
+
 The GSS-TSIG is defined in `RFC 3645 <https://tools.ietf.org/html/rfc3645>`__.
 The GSS-TSIG protocol itself is an implementation of generic GSS-API v2
 services, defined in `RFC 2743 <https://tools.ietf.org/html/rfc2743>`__.
@@ -129,8 +134,8 @@ detection, similar to this:
 The gss_tsig was developed using the MIT Kerberos 5 implementation but
 Heimdal is supported too. Note that Heimdal is picky about security
 sensitive file permissions and is known to emit an unclear error message.
-It is a good idea to keep these files as plain, with one link and and
-no access for the group or other users.
+It is a good idea to keep these files as plain, with one link and no
+access for the group or other users.
 
 The krb5-config script should provide an ``--all`` option which
 identifies the implementation: in any report about the GSS-TSIG report
@@ -153,16 +158,168 @@ To be done. One critical detail: there are two kinds of key tables
 (keytab files): the system one used by servers and client tables
 used by clients. For Kerberos 5 Kea is a **client**.
 
+Install the Kerberos 5 client library and kadmin tool:
+
+.. code-block:: console
+
+    sudo apt install krb5-kdc krb5-admin-server
+
+The principals for the DNS server (the service protected by the
+GSS-TSIG TKEY) and for the DNS client must be created.
+
+The following examples use the ``EXAMPLE.ORG`` realm to demonstrate required
+configuration steps and settings.
+
+The Kerberos 5 client library must be configured (to accept incoming requests)
+for the realm ``EXAMPLE.ORG`` by updating the ``krb5.conf`` file
+(e.g. on Linux: /etc/krb5.conf):
+
+.. code-block:: ini
+
+    [libdefaults]
+        default_realm = EXAMPLE.ORG
+        kdc_timesync = 1
+        ccache_type = 4
+        forwardable = true
+        proxiable = true
+
+    [realms]
+        EXAMPLE.ORG = {
+                kdc = kdc.example.org
+                admin_server = kdc.example.org
+        }
+
+In addition to the ``krb5.conf`` file, the ``kdc.conf`` file can be used
+(e.g. on Linux: /etc/krb5kdc/kdc.conf):
+
+.. code-block:: ini
+
+    [kdcdefaults]
+        kdc_ports = 750,88
+
+    [realms]
+        EXAMPLE.ORG = {
+            database_name = /var/lib/krb5kdc/principal
+            admin_keytab = FILE:/etc/krb5kdc/kadm5.keytab
+            acl_file = /etc/krb5kdc/kadm5.acl
+            key_stash_file = /etc/krb5kdc/stash
+            kdc_ports = 750,88
+            max_life = 10h 0m 0s
+            max_renewable_life = 7d 0h 0m 0s
+            master_key_type = des3-hmac-sha1
+            #supported_enctypes = aes256-cts:normal aes128-cts:normal
+            default_principal_flags = +preauth
+        }
+
+The kadmind daemon ACL (Access Control List) must be configured to give
+permissions to the DNS client principal to access the Kerberos 5 database.
+(e.g. on Linux: /etc/krb5kdc/kadm5.acl):
+
+.. code-block:: ini
+
+    DHCP/admin.example.org@EXAMPLE.ORG       *
+
+The admin password for the default realm must be set:
+
+.. code-block:: console
+
+    printf "realm_password\nrealm_password" | krb5_newrealm
+
+The DNS server principal (used by the Bind 9 DNS server to provide
+authentication):
+
+.. code-block:: console
+
+    kadmin.local -q "addprinc -randkey DNS/server.example.org"
+
+The DNS client principal (used by the Kea DDNS server):
+
+.. code-block:: console
+
+    kadmin.local -q "addprinc -pw client_princ_password DHCP/admin.example.org"
+
+The keytab file for the DNS server principal must be exported so that
+they can be used by the Bind 9 DNS server.
+The exported keytab file name is ``dns.keytab``.
+
+.. code-block:: console
+
+    kadmin.local -q "ktadd -k /tmp/dns.keytab DNS/server.example.org"
+
+Finally, the krb5-admin-server must be restarted:
+
+.. code-block:: console
+
+    systemctl restart krb5-admin-server.service
+
 Bind 9 with GSS-TSIG Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To be done.
+The Bind 9 DNS server must be configured to use GSS-TSIG and to use the
+previously exported keytab file ``dns.keytab`` by updating the ``named.conf``
+file:
 
+.. code-block:: console
 
-Microsoft Active Directory Setup
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    options {
+        ...
+        directory "/var/cache/bind";
+        dnssec-validation auto;
+        tkey-gssapi-keytab "/etc/bind/dns.keytab";
+    };
+    zone "example.org" {
+        type master;
+        file "/var/lib/bind/db.example.org";
+        update-policy {
+            grant "DHCP/admin.example.org@EXAMPLE.ORG" zonesub any;
+        };
+    };
+    zone "84.102.10.in-addr.arpa" {
+        type master;
+        file "/etc/bind/db.10";
+    };
+
+The zone files should have an entry for the server principal FQDN
+``server.example.org``.
+
+The ``/etc/bind/db.10`` file:
 
-To be done.
+.. code-block:: console
+
+    ;
+    ; BIND reverse data file for local loopback interface
+    ;
+    $TTL    604800                      ; 1 week
+    @       IN      SOA      server.example.org. root.example.org. (
+                             2          ; Serial
+                             604800     ; Refresh
+                             86400      ; Retry
+                             2419200    ; Expire
+                             604800     ; Negative Cache TTL
+                             )
+    ;
+    @       IN      NS      ns.
+    40      IN      PTR     ns.example.org.
+
+The ``/var/lib/bind/db.example.org`` file:
+
+.. code-block:: console
+
+    $ORIGIN .
+    $TTL                604800             ; 1 week
+    example.org         IN SOA  server.example.org. root.example.org. (
+                                8          ; serial
+                                604800     ; refresh (1 week)
+                                86400      ; retry (1 day)
+                                2419200    ; expire (4 weeks)
+                                604800     ; minimum (1 week)
+                                )
+                        NS      example.org.
+                        A       ${BIND9_IP_ADDR}
+                        AAAA    ::1
+    $ORIGIN example.org.
+    kdc                 A       ${KDC_IP_ADDR}
+    server              A       ${BIND9_IP_ADDR}
 
 .. _gss-tsig-using:
 
@@ -671,4 +828,3 @@ An example response informing about 2 GSS-TSIG keys for server 'foo' being purge
         "result": 0,
         "text": "2 purged keys for GSS-TSIG server[foo]"
     }
-
diff --git a/doc/sphinx/arm/install.rst b/doc/sphinx/arm/install.rst
index 3762126d9d..9d552dfc90 100644
--- a/doc/sphinx/arm/install.rst
+++ b/doc/sphinx/arm/install.rst
@@ -85,32 +85,37 @@ the system:
 
 -  The MySQL client and the client development libraries, when using the
    ``--with-mysql`` configuration flag to build the Kea MySQL database
-   backend. In this case, an instance of the MySQL server running
-   locally or on a machine reachable over a network is required.
-   Running unit tests requires a local MySQL server.
+   backend. In this case, an instance of the MySQL server running locally
+   or on a machine reachable over a network is required. Note that running
+   the unit tests requires a local MySQL server.
 
--  The PostgreSQL client and the client development libraries, when
-   using the ``--with-pgsql`` configuration flag to build the Kea PostgreSQL
-   database backend. In this case, an instance of the PostgreSQL server
-   running locally or on a machine reachable over a network is
-   required. Running unit tests requires a local PostgreSQL server.
+-  The PostgreSQL client and the client development libraries, when using the
+   ``--with-pgsql`` configuration flag to build the Kea PostgreSQL database
+   backend. In this case an instance of the PostgreSQL server running locally
+   or on a machine reachable over a network is required. Note that running
+   the unit tests requires a local PostgreSQL server.
 
--  The cpp-driver from DataStax, when using the ``--with-cql``
+-  The cpp-driver from DataStax is needed when using the ``--with-cql``
    configuration flag to build Kea with the Cassandra database backend.
-   In this case, an instance of the Cassandra server running locally or
-   on a machine reachable over a network is required. Running unit
-   tests requires a local Cassandra server.
+   In this case, an instance of the Cassandra server running locally
+   or on a machine reachable over a network is required. Note that running
+   the unit tests requires a local Cassandra server.
 
--  The FreeRADIUS client library, if connecting to a RADIUS server.
+-  The FreeRADIUS client library is required to connect to a RADIUS server.
    This is specified using the ``--with-freeradius`` configuration switch.
 
--  Sysrepo v1.4.140 and libyang v1.0.240, when connecting to a Sysrepo
-   datastore; earlier versions are no longer supported. When compiling from
+-  Sysrepo v1.4.140 and libyang v1.0.240 are needed to connect to a Sysrepo
+   datastore. Earlier versions are no longer supported. When compiling from
    sources, the configure switches that can be used are ``--with-libyang`` and
-   ``--with-sysrepo``, without any parameters. If these dependencies were installed
-   in custom paths, the switches must be pointed to them.
+   ``--with-sysrepo`` without any parameters. If these dependencies were
+   installed in custom paths, point the switches to them.
 
--  googletest (version 1.8 or later), when using the ``--with-gtest``
+-  The MIT Kerberos 5 or Heimdal libraries are needed by Kea DDNS server to sign
+   and verify DNS updates using GSS-TSIG. The configuration switch which enables
+   this functionality is ``--with-gssapi`` without any parameters. If these
+   dependencies were installed in custom paths, point the switch to them.
+
+-  googletest (version 1.8 or later) is required when using the ``--with-gtest``
    configuration option to build the unit tests.
 
 -  The documentation generation tools `Sphinx <https://www.sphinx-doc.org/>`_,
@@ -121,8 +126,6 @@ the system:
    are needed. If LaTeX packages are missing, Kea skips PDF generation and produces
    only HTML documents.
 
--  The Kerberos 5 libraries, when using the ``--with-gssapi`` configuration flag.
-
 Visit ISC's Knowledgebase at https://kb.isc.org/docs/installing-kea for
 system-specific installation tips.
 
@@ -429,9 +432,9 @@ Install MySQL according to the instructions for the system. The client
 development libraries must be installed.
 
 Build and install Kea as described in :ref:`installation`,
-with the following modification. To enable the MySQL database code, at
-the "configure" step (see :ref:`configure`),
-the ``--with-mysql`` switch should be specified:
+with the following modification. To enable the MySQL database code, at the
+"configure" step (see :ref:`configure`), the ``--with-mysql`` switch should be
+specified:
 
 .. code-block:: console
 
@@ -456,8 +459,9 @@ client development libraries must be installed. Client development
 libraries are often packaged as "libpq".
 
 Build and install Kea as described in :ref:`installation`,
-with the following modification. To enable the PostgreSQL database code,
-at the "configure" step (see :ref:`configure`), the ``--with-pgsql`` switch should be specified:
+with the following modification. To enable the PostgreSQL database code, at the
+"configure" step (see :ref:`configure`), the ``--with-pgsql`` switch should be
+specified:
 
 .. code-block:: console
 
diff --git a/platforms.rst b/platforms.rst
index 7305cb12b1..d57b7541d1 100644
--- a/platforms.rst
+++ b/platforms.rst
@@ -118,8 +118,13 @@ Some optional features of Kea have additional dependencies.
    is running. This is an optional dependency; Kea can be built
    without RADIUS support.
 
--  Kea provides a NETCONF interface with the
-   kea-netconf agent. This Kea module is built optionally and requires
-   Sysrepo software when used. Building Kea with NETCONF support
-   requires many dependencies to be installed, which are described in
-   more detail in :ref:`netconf-install`.
+-  Kea provides a NETCONF interface with the kea-netconf agent. This Kea module
+   requires Sysrepo software when used. Building Kea with NETCONF support
+   requires many dependencies to be installed, which are described in more
+   detail in :ref:`netconf-install`. This is an optional dependency; Kea can be
+   built without NETCONF support.
+
+-  To sign and verify DNS updates, Kea DDNS server uses GSS-TSIG and requires
+   MIT Kerberos 5 or Heimdal libraries. The dependencies required to be
+   installed are described in more detail in :ref:`gss-tsig-install`. This is an
+   optional dependency; Kea can be built without GSS-TSIG support.