[#2078] Updated doc

doc/examples/ddns/gss-tsig.json

@@ -77,6 +77,7 @@
             "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
@@ -90,6 +91,7 @@
                 {
                     // 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
                 }
@@ -99,7 +101,7 @@
     ]
 
     // Additional parameters, such as logging, control socket and
-    // others omited for clarity.
+    // others omitted for clarity.
 }
 
 }

doc/sphinx/arm/ddns.rst

@@ -771,11 +771,6 @@ The 172.88.99.10 server will use the foo TSIG key, 172.88.99.11 and
 User Contexts in DDNS
 ---------------------
 
-.. note::
-
-   User contexts were designed for hook libraries, which are not yet
-   supported for DHCP-DDNS server configuration.
-
 See :ref:`user-context` for additional background regarding the user
 context idea.
 

doc/sphinx/arm/ext-gss-tsig.rst

@@ -258,6 +258,7 @@ An excerpt from D2 server is provided below. More examples are available in the
                 "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
@@ -271,6 +272,7 @@ An excerpt from D2 server is provided below. More examples are available in the
                     {
                         // 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
                     }
@@ -280,7 +282,7 @@ An excerpt from D2 server is provided below. More examples are available in the
         ]
 
         // Additional parameters, such as logging, control socket and
-        // others omited for clarity.
+        // others omitted for clarity.
     }
 
     }
@@ -335,3 +337,87 @@ The parameters have the following meaning:
 
 - ``tkey-lifetime`` determines the lifetime of GSS-TSIG keys in the
   TKEY protocol, expressed in seconds. Default value is 3600 (one hour).
+
+- ``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:
+
+- ``id`` assigns an identifier to a DNS server. It is used for statistics
+  and commands. It is required, must be 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 of this list,
+  a D2 DNS server for this domain with the IP address and port is
+  looked for. 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 at 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 will receive updates. The per server server principal takes
+  precedence. It is a mandatory parameter which must be specified at
+  least at the global or the server level.
+
+- ``client-principal`` is the Kerberos principal name of the Kea D2
+  service for this DNS server. The per server client principal takes
+  precedence. It is an optional parameter i.e. to not specify it at
+  both the global and the server level is accepted.
+
+- ``tkey-protocol`` determines which protocol is used to establish the
+  security context with the DNS server. The per server TKEY protocol
+  takes precedence. Default and supported values 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 per server TKEY lifetime takes
+  precedence. Default and supported values 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.
+
+.. _command-gss-tsig:
+
+GSS-TSIG Commands
+-----------------
+
+The GSS-TSIG hook library supports some commands.
+
+To be done (only anchors for external references are provided).
+
+.. _command-gss-tsig-get-all:
+
+The gss-tsig-get-all Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _command-gss-tsig-get:
+
+The gss-tsig-get Command
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _command-gss-tsig-key-get:
+
+The gss-tsig-key-get Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _command-gss-tsig-key-expire:
+
+The gss-tsig-key-expire Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. _command-gss-tsig-key-del:
+
+The gss-tsig-key-del Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+

src/share/api/api_files.mk

@@ -21,6 +21,11 @@ api_files += $(top_srcdir)/src/share/api/config-test.json
 api_files += $(top_srcdir)/src/share/api/config-write.json
 api_files += $(top_srcdir)/src/share/api/dhcp-disable.json
 api_files += $(top_srcdir)/src/share/api/dhcp-enable.json
+api_files += $(top_srcdir)/src/share/api/gss-tsig-get-all.json
+api_files += $(top_srcdir)/src/share/api/gss-tsig-get.json
+api_files += $(top_srcdir)/src/share/api/gss-tsig-key-del.json
+api_files += $(top_srcdir)/src/share/api/gss-tsig-key-expire.json
+api_files += $(top_srcdir)/src/share/api/gss-tsig-key-get.json
 api_files += $(top_srcdir)/src/share/api/ha-continue.json
 api_files += $(top_srcdir)/src/share/api/ha-heartbeat.json
 api_files += $(top_srcdir)/src/share/api/ha-maintenance-cancel.json
@@ -67,12 +72,12 @@ api_files += $(top_srcdir)/src/share/api/network6-list.json
 api_files += $(top_srcdir)/src/share/api/network6-subnet-add.json
 api_files += $(top_srcdir)/src/share/api/network6-subnet-del.json
 api_files += $(top_srcdir)/src/share/api/remote-class4-del.json
-api_files += $(top_srcdir)/src/share/api/remote-class4-get.json
 api_files += $(top_srcdir)/src/share/api/remote-class4-get-all.json
+api_files += $(top_srcdir)/src/share/api/remote-class4-get.json
 api_files += $(top_srcdir)/src/share/api/remote-class4-set.json
 api_files += $(top_srcdir)/src/share/api/remote-class6-del.json
-api_files += $(top_srcdir)/src/share/api/remote-class6-get.json
 api_files += $(top_srcdir)/src/share/api/remote-class6-get-all.json
+api_files += $(top_srcdir)/src/share/api/remote-class6-get.json
 api_files += $(top_srcdir)/src/share/api/remote-class6-set.json
 api_files += $(top_srcdir)/src/share/api/remote-global-parameter4-del.json
 api_files += $(top_srcdir)/src/share/api/remote-global-parameter4-get-all.json

src/share/api/gss-tsig-get-all.json

@@ -0,0 +1,42 @@
+{
+    "access": "read",
+    "avail": "2.0.0",
+    "brief": [ "This command lists GSS-TSIG servers." ],
+    "cmd-syntax": [
+        "{",
+        "    \"command\": \"gss-tsig-get-all\"",
+        "}"
+    ],
+    "description": [ "See <xref linkend=\"command-gss-tsig-get-all\"/>" ],
+    "hook": "gss_tsig",
+    "name": "gss-tsig-get-all",
+    "support": [ "kea-dhcp-ddns" ],
+    "resp-syntax": [
+        "{",
+        "    \"result\": 0,",
+        "    \"text\": \"1 GSS-TSIG servers\",",
+        "    \"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\",",
+        "                        \"expire-date\": \"2021-09-05 13:23:36.281176\",",
+        "                        \"status\": \"not yet ready\",",
+        "                        \"tkey-exchange\": true",
+        "                    }",
+        "                ]",
+        "            }",
+        "        ]",
+        "    }",
+        "}"
+    ]
+}

src/share/api/gss-tsig-get.json

@@ -0,0 +1,43 @@
+{
+    "access": "read",
+    "avail": "2.0.0",
+    "brief": [
+        "This command retrieves information about the specified GSS-TSIG server."
+    ],
+    "cmd-syntax": [
+        "{",
+        "    \"command\": \"gss-tsig-get\",",
+        "    \"arguments\": {",
+        "        \"id\": \"foo\"",
+        "    }",
+        "}"
+    ],
+    "description": [ "See <xref linkend=\"command-gss-tsig-get\"/>" ],
+    "hook": "gss_tsig",
+    "name": "gss-tsig-get",
+    "support": [ "kea-dhcp-ddns" ],
+    "resp-syntax": [
+        "{",
+        "    \"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.\",",
+        "                \"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",
+        "            }",
+        "        ]",
+        "    }",
+        "]"
+    ]
+}

src/share/api/gss-tsig-key-del.json

@@ -0,0 +1,23 @@
+{
+    "access": "write",
+    "avail": "2.0.0",
+    "brief": [ "This command deletes the specified GSS-TSIG key." ],
+    "cmd-syntax": [
+        "{",
+        "    \"command\": \"gss-tsig-key-del\",",
+        "    \"arguments\": {",
+        "        \"key-name\": \"1234.sig-foo.com.\"",
+        "    }",
+        "}"
+    ],
+    "description": [ "See <xref linkend=\"command-gss-tsig-key-del\"/>" ],
+    "hook": "gss_tsig",
+    "name": "gss-tsig-key-del",
+    "support": [ "kea-dhcp-ddns" ],
+    "resp-syntax": [
+        "{",
+        "    \"result\": 0,",
+        "    \"text\": \"GSS-TSIG key '1234.sig-foo.com.' deleted\"",
+        "}"
+    ]
+}

src/share/api/gss-tsig-key-expire.json

@@ -0,0 +1,23 @@
+{
+    "access": "write",
+    "avail": "2.0.0",
+    "brief": [ "This command expires the specified GSS-TSIG key." ],
+    "cmd-syntax": [
+        "{",
+        "    \"command\": \"gss-tsig-key-expire\",",
+        "    \"arguments\": {",
+        "        \"key-name\": \"1234.sig-foo.com.\"",
+        "    }",
+        "}"
+    ],
+    "description": [ "See <xref linkend=\"command-gss-tsig-key-expire\"/>" ],
+    "hook": "gss_tsig",
+    "name": "gss-tsig-key-expire",
+    "support": [ "kea-dhcp-ddns" ],
+    "resp-syntax": [
+        "{",
+        "    \"result\": 0,",
+        "    \"text\": \"GSS-TSIG key '1234.sig-foo.com.' expired\"",
+        "}"
+    ]
+}

src/share/api/gss-tsig-key-get.json

@@ -0,0 +1,32 @@
+{
+    "access": "read",
+    "avail": "2.0.0",
+    "brief": [
+        "This command retrieves information about the specified GSS-TSIG key."
+    ],
+    "cmd-syntax": [
+        "{",
+        "    \"command\": \"gss-tsig-key-get\",",
+        "    \"arguments\": {",
+        "        \"key-name\": \"1234.sig-foo.com.\"",
+        "    }",
+        "}"
+    ],
+    "description": [ "See <xref linkend=\"command-gss-tsig-key-get\"/>" ],
+    "hook": "gss_tsig",
+    "name": "gss-tsig-key-get",
+    "support": [ "kea-dhcp-ddns" ],
+    "resp-syntax": [
+        "{",
+        "    \"result\": 0,",
+        "    \"text\": \"GSS-TSIG key '1234.sig-foo.com.' found\"",
+        "    \"arguments\": {",
+        "        \"name\": \"1234.sig-foo.com.\",",
+        "        \"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",
+        "    }",
+        "}"
+    ]
+}

src/share/api/statistic-get-all.json

@@ -35,6 +35,7 @@
     "name": "statistic-get-all",
     "support": [
         "kea-dhcp4",
-        "kea-dhcp6"
+        "kea-dhcp6",
+        "kea-dhcp-ddns"
     ]
 }

src/share/api/statistic-get.json

@@ -27,6 +27,7 @@
     "name": "statistic-get",
     "support": [
         "kea-dhcp4",
-        "kea-dhcp6"
+        "kea-dhcp6",
+        "kea-dhcp-ddns"
     ]
 }

src/share/api/statistic-reset-all.json

@@ -17,6 +17,7 @@
     "name": "statistic-reset-all",
     "support": [
         "kea-dhcp4",
-        "kea-dhcp6"
+        "kea-dhcp6",
+        "kea-dhcp-ddns"
     ]
 }

src/share/api/statistic-reset.json

@@ -19,6 +19,7 @@
     "name": "statistic-reset",
     "support": [
         "kea-dhcp4",
-        "kea-dhcp6"
+        "kea-dhcp6",
+        "kea-dhcp-ddns"
     ]
 }