Defining a TSIG Key

7.10.1 Problem

You want to define a TSIG key for use in authenticating remote name servers and dynamic updaters.

7.10.2 Solution

Add a key statement to the name server's named.conf file defining the new TSIG key. For example:

key dhcp-server.foo.example { algorithm hmac-md5; secret "OqprPEyzGITP0T7FcES7Wg=="; };

The first argument is the name of the key -- in this case, dhcp-server.foo.example. The key is often named after one or both of the hosts that use it. The algorithm substatement specifies the cryptographic algorithm the key is used with; for TSIG, it is always hmac-md5. The secret is the base 64 encoding of the binary TSIG key.

You can generate the key with dnssec-keygen or dnskeygen, programs included in the BIND 9 and BIND 8 distributions, respectively. To generate the key above, I used the command:

$ dnssec-keygen -a HMAC-MD5 -b 128 -n HOST dhcp-server.foo.example Kdhcp-server.foo.example.+157+19185

The argument to the -a ("algorithm") option specified the cryptographic algorithm as HMAC-MD5, while the argument to -b ("bit length") specified the length of the key to generate, in bits. The -n ("nametype") option specified this key as a host key, and the only non-option argument specified the name of the key. The program then printed a string to standard output (Kdhcp-server.foo.example.+157+19185) that identified the name of a file it wrote the key to. (The name of the file is actually that string with ".key" appended.) The file contained:

dhcp-server.foo.example. IN KEY 512 3 157 OqprPEyzGITP0T7FcES7Wg==

The last field is the base 64 encoding of the random, 128-bit key it generated.

The key statement should be identical -- including both the name of the key and the secret -- in the named.conf file of both name servers (or the name server and updater) that will use it.

7.10.3 Discussion

Defining a TSIG key doesn't do anything useful by itself; it just makes the key available for the name server to use. The key still needs to be applied to some security mechanism, as in an allow-transfer substatement (Section 7.11).

It's safest to define unique TSIG keys for use between any two name servers, so that the compromise of one TSIG key doesn't cause a broader security failure.

The maximum length of a TSIG key is 512 bits. Longer keys are harder to break, but 128 bits should be ample for all but the most paranoid administrators.

dnskeygen takes very similar arguments to dnssec-keygen; check the manual page for details. And if you can't figure out how to use dnskeygen, you can always build dnssec-keygen and use it to generate TSIG keys for your BIND 8 name server.

TSIG requires time synchronization between the name servers or the name server and updater that will use it. Getting the clocks within about five minutes of each other is all that's necessary, though. You can do that with any respectable time synchronization service, from rdate to NTP.

7.10.4 See Also

Section 3.11, for securing dynamic updates with TSIG, and Section 7.11, for securing zone transfers using TSIG.