diff options
Diffstat (limited to 'doc/sphinx/arm/ext-gss-tsig.rst')
| -rw-r--r-- | doc/sphinx/arm/ext-gss-tsig.rst | 1303 |
1 files changed, 1303 insertions, 0 deletions
diff --git a/doc/sphinx/arm/ext-gss-tsig.rst b/doc/sphinx/arm/ext-gss-tsig.rst new file mode 100644 index 0000000..404a15e --- /dev/null +++ b/doc/sphinx/arm/ext-gss-tsig.rst @@ -0,0 +1,1303 @@ +.. _gss-tsig: + +GSS-TSIG +======== + +.. _gss-tsig-overview: + +GSS-TSIG Overview +----------------- + +Kea provides 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 servers, have chosen to adopt a more complex GSS-TSIG approach that offers +additional capabilities, such as using negotiated dynamic keys. + +Kea supports GSS-TSIG to protect DNS updates sent by +the Kea DHCP-DDNS (D2) server in a premium hook, called :ischooklib:`libddns_gss_tsig.so`. + +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>`__. + +Many protocols are involved in this mechanism: + + - Kerberos 5 - `RFC 4120 <https://tools.ietf.org/html/rfc4120>`__, which + provides the security framework; + - GSS-API (Generic Security Services Application Program Interface) - + `RFC 2743 <https://tools.ietf.org/html/rfc2743>`__ for the API, + `RFC 2744 <https://tools.ietf.org/html/rfc2743>`__ for the C bindings, and + `RFC 4121 <https://tools.ietf.org/html/rfc4121>`__ for the application + to Kerberos 5; + - SPNEGO (Simple and Protected GSS-API Negotiation Mechanism) - + `RFC 4178 <https://tools.ietf.org/html/rfc4178>`__ for the negotiation; + - DNS update `RFC 2136 <https://tools.ietf.org/html/rfc2136>`__; + - TSIG (Secret Key Transaction Authentication for DNS) - + `RFC 8945 <https://tools.ietf.org/html/rfc8945>`__, which + protects DNS exchanges; + - Secure Domain Name System (DNS) Dynamic Update - + `RFC 3007 <https://tools.ietf.org/html/rfc3007>`__, which is the + application of TSIG to DNS update protection; + - TKEY (Secret Key Establishment for DNS) - + `RFC 2930 <https://tools.ietf.org/html/rfc2930>`__, which establishes + secret keys for TSIG by transmitting crypto payloads between DNS + parties; and + - GSS-TSIG - `RFC 3645 <https://tools.ietf.org/html/rfc3645>`__, which + is the application of GSS-API to TSIG. + +To summarize, GSS-API for Kerberos 5 with SPNEGO and TKEY are used to +negotiate a security context between the Kea D2 server and a DNS server: + +.. figure:: ../uml/tkey.* + +The security context is then used by GSS-TSIG to protect updates: + +.. figure:: ../uml/update.* + +The Kea implementation of GSS-TSIG uses a GSS-API for Kerberos 5 with +the SPNEGO library. Two implementations meet this criteria: MIT Kerberos +5 and Heimdal. + +.. _gss-tsig-install: + +GSS-TSIG Compilation +-------------------- + +The following procedure was tested on Ubuntu 20.10 and 21.04. A similar +approach can be applied to other systems. + +1. Obtain the Kea sources and premium packages, extract the Kea sources, + and then extract the premium packages into the ``premium/`` directory within the Kea + source tree. + +2. Run autoreconf: + +.. code-block:: console + + autoreconf -i + +3. Make sure ``./configure --help`` shows the ``--with-gssapi`` option. + +4. Install either the MIT (``libkrb5-dev``) or the Heimdal (``heimdal-dev``) library, + for instance: + +.. code-block:: console + + sudo apt install libkrb5-dev + +5. Run ``configure`` with the ``--with-gssapi`` option: + +.. code-block:: console + + ./configure --with-gssapi + +.. note: + + It is ``--with-gssapi`` (with no dash between "gss" and "api"), to maintain + consistency with the BIND 9 option. + +The ``--with-gssapi`` parameter requires the ``krb5-config`` tool to be present. This +tool is provided by both MIT Kerberos 5 and Heimdal; however, on some systems +where both Kerberos 5 and Heimdal are installed, it is a symbolic link +to one of them. If the tool is not in the standard location, it can be specified +with ``--with-gssapi=/path/to/krb5-config``. It is strongly recommended +to use the default installation locations provided by the 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 + +6. Compile ``make -jX``, where X is the number of CPU cores + available. + +7. After compilation, :ischooklib:`libddns_gss_tsig.so` is available in the + ``premium/src/hooks/d2/gss_tsig`` directory. It can be loaded by :iscman:`kea-dhcp-ddns`. + +:ischooklib:`libddns_gss_tsig.so` was developed using the MIT Kerberos 5 implementation, but +Heimdal is also supported. 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 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. + +.. _gss-tsig-deployment: + +GSS-TSIG Deployment +------------------- + +Before using GSS-TSIG, a GSS-TSIG capable DNS server, such as BIND 9 +or Microsoft Active Directory (AD), must be deployed. Other +GSS-TSIG capable implementations may work, but have not been tested. + +Kerberos 5 Setup +~~~~~~~~~~~~~~~~ + +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 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 Access Control List (ACL) 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 administrator password for the default realm must be set: + +.. code-block:: console + + krb5_newrealm + +After the following message is displayed, enter +the password for the default realm: + +.. code-block:: console + + This script should be run on the master KDC/admin server to initialize + a Kerberos realm. It will ask you to type in a master key password. + This password will be used to generate a key that is stored in + /etc/krb5kdc/stash. You should try to remember this password, but it + is much more important that it be a strong password than that it be + remembered. However, if you lose the password and /etc/krb5kdc/stash, + you cannot decrypt your Kerberos database. + Loading random data + Initializing database '/var/lib/krb5kdc/principal' for realm 'EXAMPLE.ORG', + master key name 'K/M@EXAMPLE.ORG' + You will be prompted for the database Master Password. + It is important that you NOT FORGET this password. + Enter KDC database master key: + +Then retype the password: + +.. code-block:: console + + Re-enter KDC database master key to verify: + +If successfully applied, the following message is displayed: + +.. code-block:: console + + Now that your realm is set up you may wish to create an administrative + principal using the addprinc subcommand of the kadmin.local program. + Then, this principal can be added to /etc/krb5kdc/kadm5.acl so that + you can use the kadmin program on other computers. Kerberos admin + principals usually belong to a single user and end in /admin. For + example, if jruser is a Kerberos administrator, then in addition to + the normal jruser principal, a jruser/admin principal should be + created. + + Don't forget to set up DNS information so your clients can find your + KDC and admin servers. Doing so is documented in the administration + guide. + +The next step is to create the principals for the BIND 9 DNS server +(the service protected by the GSS-TSIG TKEY) and for the DNS client +(the Kea DHCP-DDNS server). + +The BIND 9 DNS server principal (used for authentication) is created the +following way: + +.. code-block:: console + + kadmin.local -q "addprinc -randkey DNS/server.example.org" + +If successfully created, the following message is displayed: + +.. code-block:: console + + No policy specified for DNS/server.example.org@EXAMPLE.ORG; defaulting to no policy + Authenticating as principal root/admin@EXAMPLE.ORG with password. + Principal "DNS/server.example.org@EXAMPLE.ORG" created. + +The DNS server principal must be exported so that it can be used by the BIND 9 +DNS server. Only this principal is required, and it is exported to the keytab +file with the name ``dns.keytab``. + +.. code-block:: console + + kadmin.local -q "ktadd -k /tmp/dns.keytab DNS/server.example.org" + +If successfully exported, the following message is displayed: + +.. code-block:: console + + Authenticating as principal root/admin@EXAMPLE.ORG with password. + Entry for principal DNS/server.example.org with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/dns.keytab. + Entry for principal DNS/server.example.org with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:/tmp/dns.keytab. + +The DHCP client principal (used by the Kea DHCP-DDNS server) is created the +following way: + +.. code-block:: console + + kadmin.local -q "addprinc -randkey DHCP/admin.example.org" + +If successfully created, the following message is displayed: + +.. code-block:: console + + No policy specified for DHCP/admin.example.org@EXAMPLE.ORG; defaulting to no policy + Authenticating as principal root/admin@EXAMPLE.ORG with password. + Principal "DHCP/admin.example.org@EXAMPLE.ORG" created. + +The DHCP client principal must be exported so that it can be used by the +Kea DHCP-DDNS server and the GSS-TSIG hook library. It is exported to the client +keytab file with the name ``dhcp.keytab``. + +.. code-block:: console + + kadmin.local -q "ktadd -k /tmp/dhcp.keytab DHCP/admin.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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The BIND 9 DNS server must be configured to use GSS-TSIG, and to use the +previously exported DNS server principal from the keytab file ``dns.keytab``. +Updating the ``named.conf`` file is required: + +.. code-block:: console + + options { + ... + directory "/var/cache/bind"; + dnssec-validation auto; + listen-on-v6 { any; }; + 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 needs to be created or updated: + +.. 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 needs to be created or updated: + +.. 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} + +After any configuration change the server must be reloaded or +restarted: + +.. code-block:: console + + systemctl restart named.service + +It is possible to get the status or restart the logs: + +.. code-block:: console + + systemctl status named.service + journalctl -u named | tail -n 30 + +Windows Active Directory Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This sub-section is based on an Amazon AWS provided Microsoft Windows Server +2016 with Active Directory pre-installed, so it describes only the steps used +for GSS-TSIG deployment. (For the complete configuration process, please refer to +Microsoft's documentation or other external resources. We found `this <https://www.tenforums.com/tutorials/51456-windows-server-2016-setup-local-domain-controller.html>`__ tutorial very +useful during configuration of our internal QA testing systems.) + +Two Active Directory (AD) user accounts are needed: + - the first account is used to download AD information, such as + the client key table of Kea + - the second account is mapped to the Kea DHCP client principal + +Kea needs to know: + - the server IP address + - the domain/realm name: the domain is in lower case, the realm in upper + case, both without a final dot + - the server name + +The second account (named ``kea`` below) is used to create a Service +Principal Name (SPN): + +.. code-block:: console + + setspn -S DHCP/kea.<domain> kea + +After a shared secret key is generated and put in a key table file: + +.. code-block:: console + + ktpass -princ DHCP/kea.<domain>@<REALM> -mapuser kea +rndpass -mapop set -ptype KRB5_NT_PRINCIPAL -out dhcp.keytab + +The ``dhcp.keytab`` takes the same usage as for UNIX Kerberos. + +GSS-TSIG Troubleshooting +~~~~~~~~~~~~~~~~~~~~~~~~ + +While testing GSS-TSIG integration with Active Directory we came across +one very cryptic error: + +.. code-block:: console + + INFO [kea-dhcp-ddns.gss-tsig-hooks/4678.139690935890624] GSS_TSIG_VERIFY_FAILED GSS-TSIG verify failed: gss_verify_mic failed with GSSAPI error: + Major = 'A token had an invalid Message Integrity Check (MIC)' (393216), Minor = 'Packet was replayed in wrong direction' (100002). + +In our case, the problem was that the Kea D2 server was trying to perform an update of a reverse +DNS zone while it was not configured. An easy solution is to add a reverse DNS +zone similar to the one configured in Kea. To do that, open the "DNS Manager" and choose +"DNS" from the list; from the dropdown list, choose "Reverse Lookup Zones"; then +click "Action" and "New Zone"; finally, follow the New Zone Wizard to add a new zone. + +The standard requires both anti-replay and sequence services. Experiences with the BIND 9 nsupdate +showed the sequence service led to problems so it is disabled by default in the hook. It seems +the anti-replay service can also lead to problems with Microsoft DNS servers so it is now +configurable. Note that these security services are useless for DNS dynamic update which was +designed to run over UDP so with out of order and duplicated messages. + +.. _gss-tsig-using: + +Using GSS-TSIG +-------------- + +There are a number of steps required to enable the GSS-TSIG mechanism: + +1. :ischooklib:`libddns_gss_tsig.so` must be loaded by :iscman:`kea-dhcp-ddns`. +2. The GSS-TSIG-capable DNS servers must be specified with their parameters. + +An excerpt from a D2 server configuration is provided below; more examples are available in the +``doc/examples/ddns`` directory in the Kea sources. + +.. code-block:: javascript + :linenos: + :emphasize-lines: 57-117 + + + { + "DhcpDdns": { + // The following parameters are used to receive NCRs (NameChangeRequests) + // from the local Kea DHCP server. Make sure your kea-dhcp4 and kea-dhcp6 + // matches this. + "ip-address": "127.0.0.1", + "port": 53001, + "dns-server-timeout" : 1000, + + // Forward zone: secure.example.org. It uses GSS-TSIG. It is served + // by two DNS servers, which listen for DDNS requests at 192.0.2.1 + // and 192.0.2.2. + "forward-ddns": + { + "ddns-domains": + [ + // DdnsDomain for zone "secure.example.org." + { + "name": "secure.example.org.", + "comment": "DdnsDomain example", + "dns-servers": + [ + { // This server has an entry in gss/servers and + // thus will use GSS-TSIG. + "ip-address": "192.0.2.1" + }, + { // This server also has an entry there, so will + // use GSS-TSIG, too. + "ip-address": "192.0.2.2", + "port": 5300 + } + ] + } + ] + }, + + // Reverse zone: we want to update the reverse zone "2.0.192.in-addr.arpa". + "reverse-ddns": + { + "ddns-domains": + [ + { + "name": "2.0.192.in-addr.arpa.", + "dns-servers": + [ + { + // There is a GSS-TSIG definition for this server (see + // DhcpDdns/gss-tsig/servers), so it will use + // Krb/GSS-TSIG. + "ip-address": "192.0.2.1" + } + ] + } + ] + }, + + // The GSS-TSIG hook is loaded and its configuration is specified here. + "hooks-libraries": [ + { + "library": "/opt/lib/libddns_gss_tsig.so", + "parameters": { + // This section governs the GSS-TSIG integration. Each server + // mentioned in forward-ddns and/or reverse-ddns needs to have + // an entry here to be able to use GSS-TSIG defaults (optional, + // if specified they apply to all the GSS-TSIG servers, unless + // overwritten on specific server level). + + "server-principal": "DNS/server.example.org@EXAMPLE.ORG", + "client-principal": "DHCP/admin.example.org@EXAMPLE.ORG", + + // client-keytab and credentials-cache can both be used to + // store client keys. As credentials cache is more flexible, + // it is recommended to use it. Typically, using both at the + // same time may cause problems. + // "client-keytab": "FILE:/etc/dhcp.keytab", // toplevel only + "credentials-cache": "FILE:/etc/ccache", // toplevel only + "gss-replay-flag": true, // GSS anti replay service + "gss-sequence-flag": false, // no GSS sequence service + "tkey-lifetime": 3600, // 1 hour + "rekey-interval": 2700, // 45 minutes + "retry-interval": 120, // 2 minutes + "tkey-protocol": "TCP", + "fallback": false, + + // The list of GSS-TSIG capable servers + "servers": [ + { + // First server (identification is required) + "id": "server1", + "domain-names": [ ], // if not specified or empty, will + // match all domains that want to + // use this IP+port pair + "ip-address": "192.0.2.1", + "port": 53, + "server-principal": "DNS/server1.example.org@EXAMPLE.ORG", + "client-principal": "DHCP/admin1.example.org@EXAMPLE.ORG", + "gss-replay-flag": false, // no GSS anti replay service + "gss-sequence-flag": false, // no GSS sequence service + "tkey-lifetime": 7200, // 2 hours + "rekey-interval": 5400, // 90 minutes + "retry-interval": 240, // 4 minutes + "tkey-protocol": "TCP", + "fallback": true // if no key is available fallback to the + // standard behavior (vs skip this server) + }, + { + // The second server (it has most of the parameters missing + // as those are using the defaults specified above) + "id": "server2", + "ip-address": "192.0.2.2", + "port": 5300 + } + ] + } + } + ] + + // Additional parameters, such as logging, control socket and + // others omitted for clarity. + } + + } + +This configuration file contains a number of extra elements. + +First, a list of forward and/or reverse domains with related DNS servers +identified by their IP+port pairs is defined. If the port is not +specified, the default of 53 is assumed. This is similar to basic mode, with no +authentication done using TSIG keys, with the +exception that static TSIG keys are not referenced by name. + +Second, :ischooklib:`libddns_gss_tsig.so` must be specified on the +``hooks-libraries`` list. This hook takes many parameters. The most important +one is ``servers``, which is a list of GSS-TSIG-capable servers. If there are +several servers and they share some characteristics, the values can be specified +in the ``parameters`` scope as defaults. In the example above, the defaults that apply +to all servers, unless otherwise specified on a per-server scope, are defined in +lines 63 through 68. The defaults can be skipped if there is only one server +defined, or if all servers have different values. + +.. table:: List of available parameters + + +-------------------+----------+---------+---------------------+--------------------------------+ + | Name | Scope | Type | Default value | Description | + | | | | | | + +===================+==========+=========+=====================+================================+ + | client-keytab | global / | string | empty | the Kerberos **client** key | + | | server | | | table | + +-------------------+----------+---------+---------------------+--------------------------------+ + | credentials-cache | global / | string | empty | the Kerberos credentials cache | + | | server | | | | + +-------------------+----------+---------+---------------------+--------------------------------+ + | server-principal | global / | string | empty | the Kerberos principal name of | + | | server | | | the DNS server that will | + | | | | | receive updates | + +-------------------+----------+---------+---------------------+--------------------------------+ + | client-principal | global / | string | empty | the Kerberos principal name of | + | | server | | | the Kea D2 service | + +-------------------+----------+---------+---------------------+--------------------------------+ + | gss-replay-flag | global / | true / | true | require the GSS anti replay | + | | server | false | | service (GSS_C_REPLAY_FLAG) | + +-------------------+----------+---------+---------------------+--------------------------------+ + | gss-sequence-flag | global / | true / | false | require the GSS sequence | + | | server | false | | service (GSS_C_SEQUENCE_FLAG) | + +-------------------+----------+---------+---------------------+--------------------------------+ + | tkey-protocol | global / | string | "TCP" | the protocol used to establish | + | | server | "TCP" / | | the security context with the | + | | | "UDP" | | DNS servers | + +-------------------+----------+---------+---------------------+--------------------------------+ + | tkey-lifetime | global / | uint32 | | 3600 seconds | the lifetime of GSS-TSIG keys | + | | server | | | ( 1 hour ) | | + +-------------------+----------+---------+---------------------+--------------------------------+ + | rekey-interval | global / | uint32 | | 2700 seconds | the time interval the keys are | + | | server | | | ( 45 minutes ) | checked for rekeying | + +-------------------+----------+---------+---------------------+--------------------------------+ + | retry-interval | global / | uint32 | | 120 seconds | the time interval to retry to | + | | server | | | ( 2 minutes ) | create a key if any error | + | | | | | occurred previously | + +-------------------+----------+---------+---------------------+--------------------------------+ + | fallback | global / | true / | false | the behavior to fallback to | + | | server | false | | non-GSS-TSIG when GSS-TSIG | + | | | | | should be used but no GSS-TSIG | + | | | | | key is available. | + +-------------------+----------+---------+---------------------+--------------------------------+ + | exchange-timeout | global / | uint32 | | 3000 milliseconds | the time used to wait for the | + | | server | | | ( 3 seconds ) | GSS-TSIG TKEY exchange to | + | | | | | finish before it timeouts | + +-------------------+----------+---------+---------------------+--------------------------------+ + | user-context | global / | string | empty | the user-provided data in JSON | + | | server | | | format (not used by | + | | | | | the GSS-TSIG hook) | + +-------------------+----------+---------+---------------------+--------------------------------+ + | comment | global / | string | empty | ignored | + | | server | | | | + +-------------------+----------+---------+---------------------+--------------------------------+ + | id | server | string | empty | identifier to a DNS server | + | | | | | (required) | + +-------------------+----------+---------+---------------------+--------------------------------+ + | domain-names | server | list of | empty | the many-to-one relationship | + | | | strings | | between D2 DNS servers and | + | | | | | GSS-TSIG DNS servers | + +-------------------+----------+---------+---------------------+--------------------------------+ + | ip-address | server | IPv4 / | empty | the IP address at which the | + | | | IPv6 | | GSS-TSIG DNS server listens | + | | | address | | for DDNS and TKEY requests | + | | | | | (required) | + +-------------------+----------+---------+---------------------+--------------------------------+ + | port | server | uint16 | 53 | the DNS transport port at | + | | | | | which the GSS-TSIG DNS server | + | | | | | listens for DDNS and TKEY | + | | | | | requests | + +-------------------+----------+---------+---------------------+--------------------------------+ + +The global parameters are described below: + +- ``client-keytab`` specifies the Kerberos **client** key table. + For instance, ``FILE:<filename>`` can be used to point to a specific file. + This parameter can be specified only once, in the parameters scope, + and is the equivalent of setting the ``KRB5_CLIENT_KTNAME`` environment + variable. An empty value is silently ignored. + +- ``credentials-cache`` specifies the Kerberos credentials cache. + For instance, ``FILE:<filename>`` can be used to point to a file or, + if using a directory which supports more than one principal, + ``DIR:<directory-path>``. + This parameter can be specified only once, in the parameters scope, + and is the equivalent of setting the ``KRB5CCNAME`` environment + variable. An empty value is silently ignored. + +- ``server-principal`` is the Kerberos principal name of the DNS + server that receives updates. In other words, this is the + DNS server's name in the Kerberos system. This parameter is + mandatory, and uses the typical Kerberos notation: + ``<SERVICE-NAME>/<server-domain-name>@<REALM>``. + +- ``client-principal`` is the Kerberos principal name of the Kea D2 + service. It is optional, and uses the typical Kerberos notation: + ``<SERVICE-NAME>/<server-domain-name>@<REALM>``. + +- ``gss-replay-flag`` determines if the GSS anti replay service is + required. It is by default but this can be disabled. + +- ``gss-sequence-flag`` determines if the GSS sequence service is + required. It is not by default but is required by the standard + so it can be enabled. + +- ``tkey-protocol`` determines which protocol is used to establish the + security context with the DNS servers. Currently, the only supported + values are TCP (the default) and UDP. + +- ``tkey-lifetime`` determines the lifetime of GSS-TSIG keys in the + TKEY protocol. The value must be greater than the ``rekey-interval`` + value. It is expressed in seconds and defaults to 3600 (one hour). + +- ``rekey-interval`` governs the time interval at which the keys for each configured + server are checked for rekeying, i.e. when a new key is created to replace the + current usable one if its age is greater than the ``rekey-interval`` value. + The value must be smaller than the ``tkey-lifetime`` value (it is recommended + to be set between 50% and 80% of the ``tkey-lifetime`` value). It is expressed in + seconds and defaults to 2700 (45 minutes, or 75% of one hour). + +- ``retry-interval`` governs the time interval at which to retry to create a key if any + error occurred previously for any configured server. The value must be smaller + than the ``rekey-interval`` value, and should be at most 1/3 of the difference + between ``tkey-lifetime`` and ``rekey-interval``. It is expressed in seconds + and defaults to 120 (2 minutes). + +- ``fallback`` governs the behavior when GSS-TSIG should be used (a + matching DNS server is configured) but no GSS-TSIG key is available. + If set to ``false`` (the default), this server is skipped; if + set to ``true``, the DNS server is ignored and the DNS update + is sent with the configured DHCP-DDNS protection (e.g. TSIG key), or + without any protection when none was configured. + +- ``exchange-timeout`` governs the amount of time to wait for the GSS-TSIG TKEY + exchange to finish before the process times out. It is expressed in milliseconds and + defaults to 3000 (3 seconds). + +- ``user-context`` is an optional parameter (see :ref:`user-context` + for a general description of user contexts in Kea). + +- ``comment`` is allowed but currently ignored. + +- ``servers`` specifies the list of DNS servers where GSS-TSIG is enabled. + +The server map parameters are described below: + +- ``id`` assigns an identifier to a DNS server. It is used for statistics + and commands. It is required, and must be both not empty and unique. + +- ``domain-names`` governs the many-to-one relationship between D2 DNS + servers and GSS-TSIG DNS servers: for each domain name on this list, + Kea looks for a D2 DNS server for this domain with the specified IP address + and port. An empty list (the default) means that all domains + match. + +- ``ip-address`` specifies the IP address at which the GSS-TSIG DNS server + listens for DDNS and TKEY requests. It is a mandatory parameter. + +- ``port`` specifies the DNS transport port on which the GSS-TSIG DNS server + listens for DDNS and TKEY requests. It defaults to 53. + +- ``server-principal`` is the Kerberos principal name of the DNS server + that receives updates. The ``server-principal`` parameter set at the per-server + level takes precedence over one set at the global level. It is a mandatory parameter which must be specified at + either the global or the server level. + +- ``client-principal`` is the Kerberos principal name of the Kea D2 + service for this DNS server. The ``client-principal`` parameter set at the per-server + level takes precedence over one set at the global level. It is an optional parameter. + +- ``gss-replay-flag`` determines if the GSS anti replay service is + required. The ``gss-replay-flag`` parameter set at the per-server + level takes precedence over one set at the global level. It is an optional parameter + which defaults to true. + +- ``gss-sequence-flag`` determines if the GSS sequence service is + required. The ``gss-sequence-flag`` parameter set at the per-server + level takes precedence over one set at the global level. It is an optional parameter + which defaults to false. + +- ``tkey-protocol`` determines which protocol is used to establish the + security context with the DNS server. The ``tkey-protocol`` parameter set at the per-server + level takes precedence over one set at the global level. The default and supported values + for the per-server level parameter are the same as + for the global-level parameter. + +- ``tkey-lifetime`` determines the lifetime of GSS-TSIG keys in the + TKEY protocol for the DNS server. The ``tkey-lifetime`` parameter set at the per-server + level takes precedence over one set at the global level. The default and supported values + for the per-server level parameter are the same as + for the global-level parameter. + +- ``rekey-interval`` governs the time interval at which the keys for this particular + server are checked for rekeying, i.e. when a new key is created to replace the + current usable one if its age is greater than the ``rekey-interval`` value. + The value must be smaller than the ``tkey-lifetime`` value (it is recommended + to be set between 50% and 80% of the ``tkey-lifetime`` value). The ``rekey-interval`` + parameter set at the per-server level takes precedence over one set at the global + level. The default and supported values for the per-server level parameter are the same as + for the global-level parameter. + +- ``retry-interval`` governs the time interval at which to retry to create a key if any + error occurred previously for this particular server. The value must be + smaller than the ``rekey-interval`` value, and should be at most 1/3 of the + difference between ``tkey-lifetime`` and ``rekey-interval``. The + ``retry-interval`` parameter set at the per-server level takes precedence over one set at the global + level. The default and supported values for the per-server level parameter are the same as + for the global-level parameter. + +- ``fallback`` governs the behavior when GSS-TSIG should be used (a + matching DNS server is configured) but no GSS-TSIG key is available. + The ``fallback`` parameter set at the per-server level takes precedence over one set at the global + level. The default and supported values for the per-server level parameter are the same as + for the global-level parameter.. + +- ``exchange-timeout`` governs the amount of time to wait for the GSS-TSIG TKEY + exchange to finish before the process times out. The ``exchange-timeout`` parameter + set at the per-server level takes precedence over one set at the global + level. The default and supported values for the per-server level parameter are the same as + for the global-level parameter. + +- ``user-context`` is an optional parameter (see :ref:`user-context` + for a general description of user contexts in Kea). + +- ``comment`` is allowed but currently ignored. + +.. note:: + + Generally it is not recommended to specify both the client keytab (``client-keytab``) + and the credentials cache (``credentials-cache``), although this may + differ between Kerberos implementations. The client keytab is just for + the client key and is typically used to specify the key explicitly in more + static manner, while the credentials cache can be used to store multiple + credentials and can be dynamically updated by the Kerberos library. As such, + the credentials-cache is more flexible and thus the recommended alternative. + + Also note that only the read access right is needed to use the cache. + Fetching credentials and updating the cache requires the write access + right. + + +GSS-TSIG Automatic Key Removal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The server periodically deletes keys after they have been expired more than three times the +length of the maximum key lifetime (the ``tkey-lifetime`` parameter). +The user has the option to purge keys on demand by using the :isccmd:`gss-tsig-purge-all` +command or the :isccmd:`gss-tsig-purge` command. + + +GSS-TSIG Configuration for Deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using Kerberos 5 and BIND 9 as described in :ref:`gss-tsig-deployment`, +the local resolver must point to the BIND 9 ``named`` server address. The +local Kerberos must also be configured by putting the following text into the ``krb5.conf`` file: + +.. 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 + } + +With Windows AD, the DNS service is provided by AD, which also provides +the Kerberos service. The required text in the ``krb5.conf`` file becomes: + +.. code-block:: ini + + [libdefaults] + default_realm = <REALM> + kdc_timesync = 1 + ccache_type = 4 + forwardable = true + proxiable = true + [realms] + ${REALM} = { + kdc = <AD_IP_ADDR> + admin_server = <AD_IP_ADDR> + } + +Even when the GSS-API library can use the secret from the client key +table, it is far better for performance to get and cache credentials. + +This can be done manually via the command: + +.. code-block:: console + + kinit -k -t /tmp/dhcp.keytab DHCP/admin.example.org + +or, when using AD: + +.. code-block:: console + + kinit -k -t /tmp/dhcp.keytab DHCP/kea.<domain> + +The credential cache can be displayed using ``klist``. + +In production, it is better to rely on a Kerberos Credential Manager as +the System Security Services Daemon (``sssd``). + +When using BIND 9, the server principal is in the form "DNS/server.example.org@EXAMPLE.ORG¨; +with AD, the format is "DNS/<server>.<domain>@<REALM>". + +.. _stats-gss-tsig: + +GSS-TSIG Statistics +------------------- + +The GSS-TSIG hook library introduces new statistics at global and +per-DNS-server levels: + +- ``gss-tsig-key-created`` - the number of created GSS-TSIG keys +- ``tkey-sent`` - the number of sent TKEY exchange initial requests +- ``tkey-success`` - the number of TKEY exchanges which completed with a success +- ``tkey-timeout`` - the number of TKEY exchanges which completed on timeout +- ``tkey-error`` - the number of TKEY exchanges which completed with an error other than + a timeout + +The relationship between keys and DNS servers is very different between +the D2 code and static TSIG keys, and GSS-TSIG keys and DNS servers: + + - a static TSIG key can be shared between many DNS servers; + - a GSS-TSIG key is only used by one DNS server inside a dedicated + set of keys. + +.. _commands-gss-tsig: + +GSS-TSIG Commands +----------------- + +The GSS-TSIG hook library supports some commands, which are described below. + +.. isccmd:: gss-tsig-get-all +.. _command-gss-tsig-get-all: + +The ``gss-tsig-get-all`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command lists all the GSS-TSIG servers and keys. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-get-all" + } + +Here is an example of a response returning one GSS-TSIG server and one key: + +.. code-block:: json + + { + "result": 0, + "text": "1 GSS-TSIG servers and 1 keys", + "arguments": { + "gss-tsig-servers": [ + { + "id": "foo", + "ip-address": "192.1.2.3", + "port": 53, + "server-principal": "DNS/foo.com@FOO.COM", + "key-name-suffix": "foo.com.", + "tkey-lifetime": 3600, + "tkey-protocol": "TCP", + "keys": [ + { + "name": "1234.sig-foo.com.", + "inception-date": "2021-09-05 12:23:36.281176", + "server-id": "foo", + "expire-date": "2021-09-05 13:23:36.281176", + "status": "not yet ready", + "tkey-exchange": true + } + ] + }, + { + "id": "bar", + "ip-address": "192.1.2.4", + "port": 53, + "server-principal": "DNS/bar.com@FOO.COM", + "key-name-suffix": "bar.com.", + "tkey-lifetime": 7200, + "tkey-protocol": "UDP", + "keys": [ ] + } + ] + } + } + +.. isccmd:: gss-tsig-get +.. _command-gss-tsig-get: + +The ``gss-tsig-get`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command retrieves information about the specified GSS-TSIG server. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-get", + "arguments": { + "server-id": "foo" + } + } + +Here is an example of a response returning information about the server "foo": + +.. code-block:: json + + { + "result": 0, + "text": "GSS-TSIG server[foo] found", + "arguments": { + "id": "foo", + "ip-address": "192.1.2.3", + "port": 53, + "server-principal": "DNS/foo.com@FOO.COM", + "key-name-suffix": "foo.com.", + "tkey-lifetime": 3600, + "tkey-protocol": "TCP", + "keys": [ + { + "name": "1234.sig-foo.com.", + "server-id": "foo", + "inception-date": "2021-09-05 12:23:36.281176", + "expire-date": "2021-09-05 13:23:36.281176", + "status": "not yet ready", + "tkey-exchange": true + } + ] + } + } + +.. isccmd:: gss-tsig-list +.. _command-gss-tsig-list: + +The ``gss-tsig-list`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command generates a list of GSS-TSIG server IDs and key names. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-list" + } + +Here is an example of a response returning two GSS-TSIG servers and three keys: + +.. code-block:: json + + { + "result": 0, + "text": "2 GSS-TSIG servers and 3 keys", + "arguments": { + "gss-tsig-servers": [ + "foo", + "bar" + ], + "gss-tsig-keys": [ + "1234.example.com.", + "5678.example.com.", + "43888.example.org." + ] + } + } + +.. isccmd:: gss-tsig-key-get +.. _command-gss-tsig-key-get: + +The ``gss-tsig-key-get`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command retrieves information about the specified GSS-TSIG key. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-key-get", + "arguments": { + "key-name": "1234.sig-foo.com." + } + } + +Here is an example of a response returning information about GSS-TSIG key "1234.sig-foo.com.": + +.. code-block:: json + + { + "result": 0, + "text": "GSS-TSIG key '1234.sig-foo.com.' found", + "arguments": { + "name": "1234.sig-foo.com.", + "server-id": "foo", + "inception-date": "2021-09-05 12:23:36.281176", + "expire-date": "2021-09-05 13:23:36.281176", + "status": "not yet ready", + "tkey-exchange": true + } + } + +.. isccmd:: gss-tsig-key-expire +.. _command-gss-tsig-key-expire: + +The ``gss-tsig-key-expire`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command expires the specified GSS-TSIG key. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-key-expire", + "arguments": { + "key-name": "1234.sig-foo.com." + } + } + +Here is an example of a response indicating that GSS-TSIG key "1234.sig-foo.com." has been expired: + +.. code-block:: json + + { + "result": 0, + "text": "GSS-TSIG key '1234.sig-foo.com.' expired" + } + +.. isccmd:: gss-tsig-key-del +.. _command-gss-tsig-key-del: + +The ``gss-tsig-key-del`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command deletes the specified GSS-TSIG key. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-key-del", + "arguments": { + "key-name": "1234.sig-foo.com." + } + } + +Here is an example of a response indicating that GSS-TSIG key "1234.sig-foo.com." has been deleted: + +.. code-block:: json + + { + "result": 0, + "text": "GSS-TSIG key '1234.sig-foo.com.' deleted" + } + +.. isccmd:: gss-tsig-purge-all +.. _command-gss-tsig-purge-all: + +The ``gss-tsig-purge-all`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command removes all unusable GSS-TSIG keys. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-purge-all" + } + +Here is an example of a response indicating that two GSS-TSIG keys have been purged: + +.. code-block:: json + + { + "result": 0, + "text": "2 purged GSS-TSIG keys" + } + +.. isccmd:: gss-tsig-purge +.. _command-gss-tsig-purge: + +The ``gss-tsig-purge`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command removes unusable GSS-TSIG keys for the specified server. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-purge", + "arguments": { + "server-id": "foo" + } + } + +Here is an example of a response indicating that two GSS-TSIG keys for server "foo" have been purged: + +.. code-block:: json + + { + "result": 0, + "text": "2 purged keys for GSS-TSIG server[foo]" + } + +.. isccmd:: gss-tsig-rekey-all +.. _command-gss-tsig-rekey-all: + +The ``gss-tsig-rekey-all`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command unconditionally creates new GSS-TSIG keys (rekeys) for +all DNS servers. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-rekey-all" + } + +Here is an example of a response indicating that a rekey was performed: + +.. code-block:: json + + { + "result": 0, + "text": "rekeyed" + } + +This command is useful when, for instance, the DHCP-DDNS server is +reconnected to the network. + +.. isccmd:: gss-tsig-rekey +.. _command-gss-tsig-rekey: + +The ``gss-tsig-rekey`` Command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This command unconditionally creates new GSS-TSIG keys (rekeys) for +a specified DNS server. + +An example command invocation looks like this: + +.. code-block:: json + + { + "command": "gss-tsig-rekey", + "arguments": { + "server-id": "foo" + } + } + +Here is an example of a response indicating that a rekey was performed: + +.. code-block:: json + + { + "result": 0, + "text": "GSS-TSIG server[foo] rekeyed" + } + +This command is typically used when a DNS server has been rebooted, so +that existing GSS-TSIG keys shared with this server can no longer be used. |