From: Francis Dupont <fdupont@isc.org>
Date: Wed, 18 Aug 2021 07:27:12 +0000 (+0200)
Subject: [#2018] Ported install doc
X-Git-Tag: Kea-1.9.11~74
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=63cca800e8c8f4472b48af26bd9c8a397f7fd762;p=thirdparty%2Fkea.git

[#2018] Ported install doc
---

diff --git a/doc/sphinx/arm/gss-tsig.rst b/doc/sphinx/arm/gss-tsig.rst
new file mode 100644
index 0000000000..5f632f16e5
--- /dev/null
+++ b/doc/sphinx/arm/gss-tsig.rst
@@ -0,0 +1,111 @@
+.. _gss-tsig:
+
+****************
+GSS-TSIG Support
+****************
+
+.. _gss-tsig-overview:
+
+GSS-TSIG Overview
+=================
+
+Kea provides in a premium hook the support of GSS-TSIG to protect DNS
+updates sent by the Kea DHCP-DDNS (aka D2) server.
+
+GSS-TSIG uses a GSS-API for Kerberos 5 with SPENO library such as
+the MIT Kerberos 5 or the Heimdal libraries.
+
+.. note:
+
+    This is a work in progress.
+
+.. _gss-tsig-install:
+
+Installing GSS-TSIG
+===================
+
+This is a page explaining how to install Kea with GSS-TSIG support.
+
+This procedure was tested on Ubuntu 20.10 and 21.04:
+
+1.  Get the kea sources, this will do the trick extracting to ``kea/``
+    directory:
+
+.. code-block:: console
+
+    $ git clone https://gitlab.isc.org/isc-projects/kea.git
+
+2.  Get the premium sources - go to
+    https://gitlab.isc.org/isc-external/kea-gss-tsig and click download
+    or clone from there, using either https or git. Using git requires
+    setting up SSH keys which you can do on your own in your
+    `gitlab preferences <https://gitlab.isc.org/-/profile/keys>`__.
+    Extract to ``kea/premium/`` directory.
+
+3. Run autoreconf:
+
+.. code-block:: console
+
+    autoreconf -i
+
+4. Make sure ``./configure --help`` shows the ``--with-gssapi`` option.
+
+5. Install either MIT (``libkrb5-dev``) or Heimdal (``heimdal-dev``) library,
+   for instance:
+
+.. code-block:: console
+
+    sudo apt install libkrb5-dev
+
+6. Run configure with the ``--with-gssapi`` option:
+
+.. code-block:: console
+
+    ./configure --with-gssapi
+
+.. note:
+
+    It is ``--with-gssapi`` (without dash between gss and api) to keep
+    consistency with BIND 9 option.
+
+The ``--with-gssapi`` requires ``krb5-config`` tool to be present. This
+tool is provided by both MIT Kerberos 5 and Heimdal, on some systems
+where both Kerberos 5 and Heimdal are installed it is a symbolic link
+to one of them. If it's not in your standard location, you may specify
+it with ``--with-gssapi=/path/to/krb5-config``. Since this is an early
+prototype, it is strongly recommended to use default installation
+locations as provided by packages.
+
+The ``./configure`` script should complete with a successful GSS-API
+detection, similar to this:
+
+::
+
+    GSS-API support:
+      GSSAPI_CFLAGS:         -isystem /usr/include/mit-krb5
+      GSSAPI_LIBS:           -L/usr/lib/x86_64-linux-gnu/mit-krb5 -Wl,-Bsymbolic-functions -Wl,-z,relro -lgssapi_krb5 -lkrb5 -lk5crypto -lcom_err
+
+7.  Compile as usual ``make -jX`` where X is the number of CPU cores
+    available.
+
+8.  After compilation, the gss_tsig hook is available in the
+    ``premium/src/hooks/d2/gss_tsig`` directory.
+    It can be loaded by the D2.
+
+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 but emits an unclear error message. Anyway
+it is a good idea to keep these files as plain, with one link and 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
+please add the result of the ``--all`` option of the krb5-config used
+to configure Kea.
+
+.. _gss-tsig-using:
+
+Using GSS-TSIG
+==============
+
+To be done.
diff --git a/doc/sphinx/arm/rst_arm_sources.mk b/doc/sphinx/arm/rst_arm_sources.mk
index 19501c2c4f..6fe10a5430 100644
--- a/doc/sphinx/arm/rst_arm_sources.mk
+++ b/doc/sphinx/arm/rst_arm_sources.mk
@@ -10,6 +10,7 @@ rst_arm_sources += arm/database-connectivity.rst
 rst_arm_sources += arm/ddns.rst
 rst_arm_sources += arm/dhcp4-srv.rst
 rst_arm_sources += arm/dhcp6-srv.rst
+rst_arm_sources += arm/gss-tsig.rst
 rst_arm_sources += arm/hammer.rst
 rst_arm_sources += arm/hooks-bootp.rst
 rst_arm_sources += arm/hooks-cb-cmds.rst
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index ded3a1e99c..6c4230231c 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -44,6 +44,7 @@ Kea, can be found in ISC's `Knowledgebase <https://kea.readthedocs.io>`_.
    arm/logging
    arm/shell
    arm/netconf
+   arm/gss-tsig
    arm/stork
    arm/security