Commit a5f18aac authored by Thomas Markwalder's avatar Thomas Markwalder
Browse files

[3432] Updated Admin guide for TSIG key configuration

Updated the admin guilde and minor change to dhcp-ddns.spec file.
parent 64bf0016
......@@ -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>
......
......@@ -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);
//@}
......
......@@ -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",
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment