From: Francis Dupont <fdupont@isc.org>
Date: Thu, 19 Aug 2021 13:09:51 +0000 (+0200)
Subject: [#2018] Added protocols with ref and schemas
X-Git-Tag: Kea-1.9.11~61
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c407640dec70b86bb6d0ba19a4acdf773e2031fa;p=thirdparty%2Fkea.git

[#2018] Added protocols with ref and schemas
---

diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am
index 96cba12ded..86bec84b99 100644
--- a/doc/sphinx/Makefile.am
+++ b/doc/sphinx/Makefile.am
@@ -137,6 +137,12 @@ EXTRA_DIST += uml/requestLease4.uml
 EXTRA_DIST += uml/select4.png
 EXTRA_DIST += uml/select4.svg
 EXTRA_DIST += uml/select4.uml
+EXTRA_DIST += uml/tkey.png
+EXTRA_DIST += uml/tkey.svg
+EXTRA_DIST += uml/tkey.uml
+EXTRA_DIST += uml/update.png
+EXTRA_DIST += uml/update.svg
+EXTRA_DIST += uml/update.uml
 
 PDFLATEX_AND_OPTS=$(PDFLATEX) -interaction nonstopmode
 
diff --git a/doc/sphinx/arm/ext-gss-tsig.rst b/doc/sphinx/arm/ext-gss-tsig.rst
index 27c957e00d..47aa6aaad4 100644
--- a/doc/sphinx/arm/ext-gss-tsig.rst
+++ b/doc/sphinx/arm/ext-gss-tsig.rst
@@ -9,9 +9,8 @@ GSS-TSIG
 GSS-TSIG Overview
 -----------------
 
-Kea provides a support for DNS updates (as defined in `RFC 2136 <https://tools.ietf.org/html/rfc2136>`__),
-which can be protected using Transaction Signatures (or TSIG) as defined in
-`RFC 2845 <https://tools.ietf.org/html/rfc2845>`__). This protection
+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.
@@ -22,6 +21,39 @@ 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>`__.
 
+More exactly many protocols are involved:
+ - 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 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 negotation
+ - 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 the 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
+ - GSS-TSIG `RFC 3645 <https://tools.ietf.org/html/rfc3645>`__ which
+   is the application of GSS-API to TSIG
+
+To summary 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 used by GSS-TSIG to protect updates:
+
+.. figure:: ../uml/update.*
+
 The Kea implementation of GSS-TSIG uses a GSS-API for Kerberos 5 with
 SPNEGO library.  Two implementations meet this criteria: MIT Kerberos
 5 and the Heimdal libraries.
diff --git a/doc/sphinx/uml/tkey.png b/doc/sphinx/uml/tkey.png
new file mode 100644
index 0000000000..c10ec7cf08
Binary files /dev/null and b/doc/sphinx/uml/tkey.png differ
diff --git a/doc/sphinx/uml/tkey.svg b/doc/sphinx/uml/tkey.svg
new file mode 100644
index 0000000000..6bfb43f03d
--- /dev/null
+++ b/doc/sphinx/uml/tkey.svg
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="197px" preserveAspectRatio="none" style="width:308px;height:197px;background:#FFFFFF;" version="1.1" viewBox="0 0 308 197" width="308px" zoomAndPan="magnify"><defs><filter height="300%" id="fz1ehskz14z05" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><text fill="#000000" font-family="sans-serif" font-size="18" lengthAdjust="spacing" textLength="283" x="9" y="29.4023">TKEY Exchange (GSS-TSIG hook)</text><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="70.5" x2="70.5" y1="75.6875" y2="154.3086"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="240.5" x2="240.5" y1="75.6875" y2="154.3086"/><rect fill="#FEFECE" filter="url(#fz1ehskz14z05)" height="30.4883" style="stroke:#A80036;stroke-width:1.5;" width="108" x="14.5" y="40.1992"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="94" x="21.5" y="60.7344">Kea D2 server</text><rect fill="#FEFECE" filter="url(#fz1ehskz14z05)" height="30.4883" style="stroke:#A80036;stroke-width:1.5;" width="108" x="14.5" y="153.3086"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="94" x="21.5" y="173.8438">Kea D2 server</text><rect fill="#FEFECE" filter="url(#fz1ehskz14z05)" height="30.4883" style="stroke:#A80036;stroke-width:1.5;" width="88" x="194.5" y="40.1992"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="74" x="201.5" y="60.7344">DNS server</text><rect fill="#FEFECE" filter="url(#fz1ehskz14z05)" height="30.4883" style="stroke:#A80036;stroke-width:1.5;" width="88" x="194.5" y="153.3086"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="74" x="201.5" y="173.8438">DNS server</text><polygon fill="#A80036" points="228.5,102.998,238.5,106.998,228.5,110.998,232.5,106.998" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;" x1="70.5" x2="234.5" y1="106.998" y2="106.998"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="82" x="77.5" y="102.2559">TKEY request</text><polygon fill="#A80036" points="81.5,132.3086,71.5,136.3086,81.5,140.3086,77.5,136.3086" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;" x1="75.5" x2="239.5" y1="136.3086" y2="136.3086"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="146" x="87.5" y="131.5664">TKEY response (signed)</text><!--MD5=[7d4889a5feeb1588c9f7e0e768327f46]
+@startuml
+
+title TKEY Exchange (GSS-TSIG hook)
+
+participant "Kea D2 server" as Kea
+participant "DNS server" as DNS
+
+Kea -> DNS: TKEY request
+DNS -> Kea: TKEY response (signed)
+
+@enduml
+
+PlantUML version 1.2021.9(Sun Jul 25 12:13:56 CEST 2021)
+(GPL source distribution)
+Java Runtime: OpenJDK Runtime Environment
+JVM: OpenJDK 64-Bit Server VM
+Default Encoding: UTF-8
+Language: en
+Country: US
+--></g></svg>
\ No newline at end of file
diff --git a/doc/sphinx/uml/tkey.uml b/doc/sphinx/uml/tkey.uml
new file mode 100644
index 0000000000..4cc33e58b7
--- /dev/null
+++ b/doc/sphinx/uml/tkey.uml
@@ -0,0 +1,11 @@
+@startuml
+
+title TKEY Exchange (GSS-TSIG hook)
+
+participant "Kea D2 server" as Kea
+participant "DNS server" as DNS
+
+Kea -> DNS: TKEY request
+DNS -> Kea: TKEY response (signed)
+
+@enduml
diff --git a/doc/sphinx/uml/update.png b/doc/sphinx/uml/update.png
new file mode 100644
index 0000000000..9b0520e732
Binary files /dev/null and b/doc/sphinx/uml/update.png differ
diff --git a/doc/sphinx/uml/update.svg b/doc/sphinx/uml/update.svg
new file mode 100644
index 0000000000..7fb4947414
--- /dev/null
+++ b/doc/sphinx/uml/update.svg
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" contentScriptType="application/ecmascript" contentStyleType="text/css" height="197px" preserveAspectRatio="none" style="width:367px;height:197px;background:#FFFFFF;" version="1.1" viewBox="0 0 367 197" width="367px" zoomAndPan="magnify"><defs><filter height="300%" id="f1k5dkaewnu0nj" width="300%" x="-1" y="-1"><feGaussianBlur result="blurOut" stdDeviation="2.0"/><feColorMatrix in="blurOut" result="blurOut2" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 .4 0"/><feOffset dx="4.0" dy="4.0" in="blurOut2" result="blurOut3"/><feBlend in="SourceGraphic" in2="blurOut3" mode="normal"/></filter></defs><g><text fill="#000000" font-family="sans-serif" font-size="18" lengthAdjust="spacing" textLength="342" x="9" y="29.4023">DNS Update Exchange (GSS-TSIG hook)</text><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="78.5" x2="78.5" y1="75.6875" y2="154.3086"/><line style="stroke:#A80036;stroke-width:1.0;stroke-dasharray:5.0,5.0;" x1="291.5" x2="291.5" y1="75.6875" y2="154.3086"/><rect fill="#FEFECE" filter="url(#f1k5dkaewnu0nj)" height="30.4883" style="stroke:#A80036;stroke-width:1.5;" width="108" x="22.5" y="40.1992"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="94" x="29.5" y="60.7344">Kea D2 server</text><rect fill="#FEFECE" filter="url(#f1k5dkaewnu0nj)" height="30.4883" style="stroke:#A80036;stroke-width:1.5;" width="108" x="22.5" y="153.3086"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="94" x="29.5" y="173.8438">Kea D2 server</text><rect fill="#FEFECE" filter="url(#f1k5dkaewnu0nj)" height="30.4883" style="stroke:#A80036;stroke-width:1.5;" width="88" x="245.5" y="40.1992"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="74" x="252.5" y="60.7344">DNS server</text><rect fill="#FEFECE" filter="url(#f1k5dkaewnu0nj)" height="30.4883" style="stroke:#A80036;stroke-width:1.5;" width="88" x="245.5" y="153.3086"/><text fill="#000000" font-family="sans-serif" font-size="14" lengthAdjust="spacing" textLength="74" x="252.5" y="173.8438">DNS server</text><polygon fill="#A80036" points="279.5,102.998,289.5,106.998,279.5,110.998,283.5,106.998" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;" x1="78.5" x2="285.5" y1="106.998" y2="106.998"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="179" x="85.5" y="102.2559">DNS update request (signed)</text><polygon fill="#A80036" points="89.5,132.3086,79.5,136.3086,89.5,140.3086,85.5,136.3086" style="stroke:#A80036;stroke-width:1.0;"/><line style="stroke:#A80036;stroke-width:1.0;" x1="83.5" x2="290.5" y1="136.3086" y2="136.3086"/><text fill="#000000" font-family="sans-serif" font-size="13" lengthAdjust="spacing" textLength="189" x="95.5" y="131.5664">DNS update response (signed)</text><!--MD5=[1878df8bb6338e54fcd61a1faf1a5cc0]
+@startuml
+
+title DNS Update Exchange (GSS-TSIG hook)
+
+participant "Kea D2 server" as Kea
+participant "DNS server" as DNS
+
+Kea -> DNS: DNS update request (signed)
+DNS -> Kea: DNS update response (signed)
+
+@enduml
+
+PlantUML version 1.2021.9(Sun Jul 25 12:13:56 CEST 2021)
+(GPL source distribution)
+Java Runtime: OpenJDK Runtime Environment
+JVM: OpenJDK 64-Bit Server VM
+Default Encoding: UTF-8
+Language: en
+Country: US
+--></g></svg>
\ No newline at end of file
diff --git a/doc/sphinx/uml/update.uml b/doc/sphinx/uml/update.uml
new file mode 100644
index 0000000000..9738f30ade
--- /dev/null
+++ b/doc/sphinx/uml/update.uml
@@ -0,0 +1,11 @@
+@startuml
+
+title DNS Update Exchange (GSS-TSIG hook)
+
+participant "Kea D2 server" as Kea
+participant "DNS server" as DNS
+
+Kea -> DNS: DNS update request (signed)
+DNS -> Kea: DNS update response (signed)
+
+@enduml