[3432] Updated Admin guide for TSIG key configuration

Updated the admin guilde and minor change to dhcp-ddns.spec file.

doc/guide/bind10-guide.xml

@@ -5301,57 +5301,95 @@ corresponding values in the DHCP servers' "dhcp-ddns" configuration section.
 
       <section id="d2-tsig-key-list-config">
         <title>TSIG Key List</title>
-<note>
-<simpara>
-        While this section may be displayed and edited using bindctl, the use
-        of TSIG in actual communications between D2 and DNS servers is not yet
-        implemented.
-</simpara>
-</note>
         <para>
         DDNS protocol can be conducted with or without TSIG as defined in
         RFC 2845. This configuration section allows the administrator to
-        define the dictionary of TSIG keys to may be used.  To use TSIG
+        define the dictionary of TSIG keys which may be used.  To use TSIG
         when working with a specific DDNS Domain that key must be defined in
-        the TSIG Key List and referenced by name in that domain's entry in
-        the DDNS catalog.
+        the TSIG Key List and referenced by name in that domain's configuration
+        entry.
+
+        When the domain D2 has matched to a change request has a TSIG key
+        associated with it, D2 will use that key to sign DNS update messages
+        sent to and verify repsonses received from DNS server(s). For each TSIG
+        key required by the DNS servers that D2 will be working with there must
+        be a corresponding TSIG key in the TSIG Key list.
         </para>
         <para>
         As one might gather from its name, this section is a list of
-        TSIG keys. Each key has three parameters:
+        TSIG keys. Each entry describes a TSIG key used by one or
+        more DNS servers to authenticate requests and sign responses.
+        Each entry has three parameters:
         <itemizedlist>
           <listitem>
             <simpara>
               <command>name</command> &mdash;
-              is a unique text label used to identify the this key within the
-              list.  It is this value that is used to specify which key (if any)
-              should be used with a specific DNS server. So long as it is
-              unique, its content is arbitrary.  It cannot be blank.
+              is a unique text label used to identify this key within the
+              list.  This value is used to specify which key (if any) should be
+              used when updating a specific domain. So long as it is unique its
+              content is arbitrary, although for clarity and ease of maintenance
+              it is recommended that it match the name used on the DNS server(s).
+              It cannot be blank.
             </simpara>
           </listitem>
           <listitem>
             <simpara>
               <command>algorithm</command> &mdash;
               specifies which hashing algorithm should be used with this
-              key.  This value is not currently used.
+              key.  This value must specify the same algorithm used for the
+              key on the DNS server(s). The supported algorithms are listed below:
+              <itemizedlist>
+                <listitem>
+                   <command>HMAC-MD5</command>
+                </listitem>
+                <listitem>
+                    <command>HMAC-SHA1</command>
+                </listitem>
+                <listitem>
+                  <command>HMAC-SHA224</command>
+              </listitem>
+              <listitem>
+                  <command>HMAC-SHA256</command>
+              </listitem>
+              <listitem>
+                  <command>HMAC-SHA384</command>
+                  </listitem>
+              <listitem>
+                  <command>HMAC-SHA512</command>
+              </listitem>
+              </itemizedlist>
+              This value is not case sensitive.
             </simpara>
           </listitem>
           <listitem>
             <simpara>
               <command>secret</command> &mdash;
-              is used to specify the shared secret key code for this key. This
-              value is not currently used.
+              is used to specify the shared secret key code for this key.  This value is
+              case sensitive and must exactly match the value specified on the DNS server(s).
+              This is a base64 encoded text value that can be located if dnssec public and
+              private key files.
             </simpara>
           </listitem>
         </itemizedlist>
         </para>
         <para>
-        By default, the TSIG Key list is empty:
+        Suppose that a domain D2 will be updating is maintained by a BIND9 DNS server which
+        is using TSIG with that domain.  Suppose further that the entry for the TSIG key in 
+        BIND9's named.conf file looks like this:
+<screen>
+   :
+   key "key.four.example.com." {
+       algorithm hmac-sha224;
+       secret "bZEG7Ow8OgAUPfLWV3aAUQ==";
+   };
+   :
+</screen>
+        By default, the TSIG Key list is empty.
 <screen>
 <userinput>> config show DhcpDdns/tsig_keys</userinput>
 DhcpDdns/tsig_keys  []  list  (default)
 </screen>
-        To create a new key in the list, one must first add a new key element:
+        So we must first create a new key in the list:
 <screen>
 <userinput>> config add DhcpDdns/tsig_keys</userinput>
 </screen>
@@ -5359,17 +5397,19 @@ DhcpDdns/tsig_keys  []  list  (default)
 <screen>
 <userinput>> config show DhcpDdns/tsig_keys[0]</userinput>
 DhcpDdns/tsig_keys[0]/name  ""  string  (default)
-DhcpDdns/tsig_keys[0]/algorithm "hmac_md5"  string  (modified)
+DhcpDdns/tsig_keys[0]/algorithm "HMAC-MD5"  string  (modified)
 DhcpDdns/tsig_keys[0]/secret  ""  string  (default)
 </screen>
-        Populating the key name and secret, while accepting the default value
-        for alogorithm:
+        Now we simple set all three values to match BIND9's key:
 <screen>
-<userinput>> config set DhcpDdns/tsig_keys[0]/name "key1.example.com"</userinput>
-<userinput>> config set DhcpDdns/tsig_keys[0]/secret "123456789"</userinput>
+<userinput>> config set DhcpDdns/tsig_keys[0]/name "key.four.example.com"</userinput>
+<userinput>> config set DhcpDdns/tsig_keys[0]/algorithm "HMAC-SHA224"</userinput>
+<userinput>> config set DhcpDdns/tsig_keys[0]/secret "bZEG7Ow8OgAUPfLWV3aAUQ=="</userinput>
 <userinput>> config commit</userinput>
 </screen>
         </para>
+        These steps would be repeated for each TSIG key needed.  Note that the same TSIG key
+        can be used with more than one domain.
       </section> <!-- "d2-tsig-key-list-config" -->
 
       <section id="d2-forward-ddns-config">
@@ -5387,8 +5427,6 @@ DhcpDdns/forward_ddns/ddns_domains  [] list  (default)
         </para>
         <section id="add-forward-ddns-domain">
           <title>Adding Forward DDNS Domains</title>
-
-
           <para>
           A forward DDNS Domain maps a forward DNS zone to a set of DNS servers
           which maintain the forward DNS data for that zone.  You will need one
@@ -5567,8 +5605,8 @@ DhcpDdns/reverse_ddns/ddns_domains  [] list  (default)
               <simpara>
               <command>key_name</command> &mdash;
               If TSIG should be used with this domain's servers, then this
-              value should be the name of the key from within the TSIG Key List
-              to use.  If the value is blank (the default), TSIG will not be
+              value should be the name of that key from the TSIG Key List.
+              If the value is blank (the default), TSIG will not be
               used in DDNS conversations with this domain's servers.  Currently
               this value is not used as TSIG has not been implemented.
               </simpara>

src/bin/d2/d2_update_message.h

@@ -304,9 +304,9 @@ public:
     ///
     /// @param received_data buffer holding DNS Update message to be parsed.
     /// @param bytes_received the number of bytes in received_data
-    /// @param tsig_ctx A TSIG context that is to be used to verify the
+    /// @param tsig_context A TSIG context that is to be used to verify the
     /// message. If NULL TSIG verification will not be attempted.
-    void fromWire(const void* data, size_t datalen,
+    void fromWire(const void* received_data, size_t bytes_received,
                   dns::TSIGContext* const tsig_context = NULL);
     //@}
 

src/bin/d2/dhcp-ddns.spec

@@ -34,7 +34,7 @@
             "item_name": "tsig_key",
             "item_type": "map",
             "item_optional": false,
-            "item_default": {"algorithm" : "hmac_md5"},
+            "item_default": {"algorithm" : "HMAC-MD5"},
             "map_item_spec": [ 
             {
                 "item_name": "name",