![]() |
Kea 3.1.1
|
Welcome to Kea GSS-TSIG Hooks Library. This documentation is addressed at developers who are interested in internal operation of the library. This file provides information needed to understand and perhaps extend this library.
This documentation is stand-alone: you should have read and understood Kea Developer's Guide and in particular its section about hooks: Hooks Developer's Guide.
The gss_tsig
library provides support for GSS-TSIG.
GSS-TSIG is at the end of different protocols:
To summary the GSS-API with Kerberos 5 using SPNEGO establishes a security context using TKEY to transport opaque tokens between a client and a server. When the security context is established it is used to protect DNS exchanges, typically DNS dynamic updates using GSS-TSIG.
For this hook:
There are 3 important kinds of objects in GSS-API:
So only important operation is to establish a security context. This operation is different in the initiator and the responser sides but is based on the same schema: a function (init for the initiator and accept for the responder) is called with input and output tokens until the returned status is "complete" vs "continue". The output token is sent to the other side which uses it as the input token. The first step is to provide an empty token to the init function.
The gss_tsig
hooks library supports some commands:
The structure of the library is very simple and contains:
GssTsigImpl
(see gss_tsig_impl.h).GssTsigCfg
which stores the mapping between the hook configured DNS servers (DnsServer
) and the kea-dhcp-ddns (D2) configured DNS servers (d2::DnsServerInfoPtr
) in addition to all hook library parameters (see gss_tsig_cfg.h). For a complete list of parameters see the GSS-TSIG ARM section.ManagedKey
which is the GSS-TSIG TKey managed by the hook library (see managed_key.h) and extends the GssTsigKey
(see gss_tsig_key.h) which in turn extends the d2::D2TsigKey
.TKeyExchange
which manages the GSS-TSIG TKey exchange with the DNS server (see tkey_exchange.h).TSIGContext
used to sign and verify GSS-TSIG DNS messages, which extends the dns::TSIGContext
(see gss_tsig_context.h).GssApiBuffer
, GssApiName
, GssApiCred
, GssApiSecCtx
, GssApiOid
, GssApiOidSet
(see gss_tsig_api.h).The select_key hook point is used by the D2 server to select the key for the DNS update for the current server. If GSS-TSIG is not enforced (fallback is set to true), then non GSS-TSIG key (TSIG Key or none) will be used, but if GSS-TSIG is explicitly required (default: fallback is set to false), then the current server is skipped (by setting the NEXT_STEP_SKIP flag). If the current DNS server is not skipped, the respective TKey context (none, simple TSIG or GSS-TSIG) will be used to sign and verify the DNS updates. The d2_srv_configured hook point is used to set up internal io service and validate the hooks library configuration. At this stage the mapping between the hook configured DNS servers and the kea-dhcp-ddns (D2) configured DNS servers is done. The multi_threading_compatible indicate that the hook library is multi-threaded compatible, even though the D2 server does not currently use multiple threads to process DNS updates. The following hook points are used for commands only: get, get_all, lists, key_get, key_expire, key_del, purge, purge_all, rekey, rekey_all.
The hook library will automatically check for expired keys after each rekey-interval
seconds. It will also check if any key has been created more than rekey-interval
seconds ago so that a new key is created before the respective one expires. The rekey-interval
is recommend between 50% and 80% of the tkey-lifetime
value. If any error occurs, the process is scheduled again after retry-interval
seconds. The retry-interval
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 key expiration is also checked whenever a key is searched for the current DNS server, so that no expired key is used.
This stands for all other uses of the system C++11 chrono clock in Kea but for GSS-TSIG this choice raised some questions so the choice of the system clock vs steady clock or high resolution clock is explained here:
The gss_tsig
hooks library is compatible with multi-threading but can be used only by the D2 server which is not yet multi-threaded.