- This is a short guide to setting up Transaction SIGnatures - (TSIG) based transaction security in BIND. It describes changes - to the configuration file as well as what changes are required for - different features, including the process of creating transaction - keys and using transaction signatures with BIND. + TSIG (Transaction SIGnatures) is a mechanism for authenticating DNS + messages, originally specified in RFC 2845. It allows DNS messages + to be cryptographically signed using a shared secret. TSIG can + be used in any DNS transaction, as a way to restrict access to + certain server functions (e.g., recursive queries) to authorized + clients when IP-based access control is insufficient or needs to + be overridden, or as a way to ensure message authenticity when it + is critical to the integrity of the server, such as with dynamic + UPDATE messages or zone transfers from a master to a slave server.
- BIND primarily supports TSIG for server - to server communication. - This includes zone transfer, notify, and recursive query messages. - Resolvers based on newer versions of BIND 8 have limited support - for TSIG. + This is a guide to setting up TSIG in BIND. + It describes the configuration syntax and the process of creating + TSIG keys.
- TSIG can also be useful for dynamic update. A primary
- server for a dynamic zone should control access to the dynamic
- update service, but IP-based access control is insufficient.
- The cryptographic access control provided by TSIG
- is far superior. The nsupdate
- program supports TSIG via the -k and
- -y command line options or inline by use
- of the key.
-
- A shared secret is generated to be shared between host1 and host2. - An arbitrary key name is chosen: "host1-host2.". The key name must - be the same on both hosts. + named supports TSIG for server-to-server + communication, and some of the tools included with + BIND support it for sending messages to + named:
--k, -l and
+ -y command line options, or via
+ the key command when running
+ interactively.
+ -k and -y command
+ line options.
+ - The following command will generate a 128-bit (16 byte) HMAC-SHA256 - key as described above. Longer keys are better, but shorter keys - are easier to read. Note that the maximum key length is the digest - length, here 256 bits. -
-
- dnssec-keygen -a hmac-sha256 -b 128 -n HOST host1-host2.
-
- The key is in the file Khost1-host2.+163+00000.private.
- Nothing directly uses this file, but the base-64 encoded string
- following "Key:"
- can be extracted from the file and used as a shared secret:
-
Key: La/E5CjG9O+os1jq0a2jdA==-
- The string "La/E5CjG9O+os1jq0a2jdA==" can
- be used as the shared secret.
-
- The shared secret is simply a random sequence of bits, encoded - in base-64. Most ASCII strings are valid base-64 strings (assuming - the length is a multiple of 4 and only valid characters are used), - so the shared secret can be manually generated. -
-- Also, a known string can be run through mmencode or - a similar program to generate base-64 encoded data. -
-
- This is beyond the scope of DNS. A secure transport mechanism
- should be used. This could be secure FTP, ssh, telephone, etc.
+ TSIG keys can be generated using the tsig-keygen
+ command; the output of the command is a key directive
+ suitable for inclusion in named.conf. The
+ key name, algorithm and size can be specified by command line parameters;
+ the defaults are "tsig-key", HMAC-SHA256, and 256 bits, respectively.
- Imagine host1 and host 2
- are
- both servers. The following is added to each server's named.conf file:
+ Any string which is a valid DNS name can be used as a key name.
+ For example, a key to be shared between servers called
+ host1 and host2 could
+ be called "host1-host2.", and this key could be generated using:
-key host1-host2. {
- algorithm hmac-sha256;
- secret "La/E5CjG9O+os1jq0a2jdA==";
+ $ tsig-keygen host1-host2. > host1-host2.key
+
++ This key may then be copied to both hosts. The key name and secret + must be identical on both hosts. + (Note: copying a shared secret from one server to another is beyond + the scope of the DNS. A secure transport mechanism should be used: + secure FTP, SSL, ssh, telephone, encrypted email, etc.) +
++ tsig-keygen can also be run as + ddns-confgen, in which case its output includes + additional configuration text for setting up dynamic DNS in + named. See ddns-confgen(8) + for details. +
+
+ For a key shared between servers called
+ host1 and host2,
+ the following could be added to each server's
+ named.conf file:
+
+key "host1-host2." {
+ algorithm hmac-sha256;
+ secret "DAopyf1mhCbFVZw7pgmNPBoLUq8wEUT7UuPoLENP2HY=";
};
- The secret is the one generated above. Since this is a secret, it
- is recommended that either named.conf be
- non-world readable, or the key directive be added to a non-world
- readable file that is included by named.conf.
+ (This is the same key generated above using
+ tsig-keygen.)
- At this point, the key is recognized. This means that if the
- server receives a message signed by this key, it can verify the
- signature. If the signature is successfully verified, the
- response is signed by the same key.
+ Since this text contains a secret, it
+ is recommended that either named.conf not be
+ world-readable, or that the key directive
+ be stored in a file which is not world-readable, and which is
+ included in named.conf via the
+ include directive.
+
+ Once a key has been added to named.conf and the
+ server has been restarted or reconfigured, the server can recognize
+ the key. If the server receives a message signed by the
+ key, it will be able to verify the signature. If the signature
+ is valid, the response will be signed using the same key.
+
+ TSIG keys that are known to a server can be listed using the + command rndc tsig-list.
- Since keys are shared between two hosts only, the server must
- be told when keys are to be used. The following is added to the named.conf file
- for host1, if the IP address of host2 is
- 10.1.2.3:
+ A server sending a request to another server must be told whether
+ to use a key, and if so, which key to use.
+
+ For example, a key may be specified for each server in the + masters statement in the definition of a + slave zone; in this case, all SOA QUERY messages, NOTIFY + messages, and zone transfer requests (AXFR or IXFR) will be + signed using the specified key. Keys may also be specified + in the also-notify statement of a master + or slave zone, causing NOTIFY messages to be signed using + the specified key. +
++ Keys can also be specified in a server + directive. Adding the following on host1, + if the IP address of host2 is 10.1.2.3, would + cause all requests from host1 + to host2, including normal DNS queries, to be + signed using the host1-host2. key:
server 10.1.2.3 {
- keys { host1-host2. ;};
+ keys { host1-host2. ;};
};
- Multiple keys may be present, but only the first is used. - This directive does not contain any secrets, so it may be in a - world-readable - file. + Multiple keys may be present in the keys + statement, but only the first one is used. As this directive does + not contain secrets, it can be used in a world-readable file.
- If host1 sends a message that is a request - to that address, the message will be signed with the specified key. host1 will - expect any responses to signed messages to be signed with the same - key. + Requests sent by host2 to host1 + would not be signed, unless a similar + server directive were in host2's + configuration file.
- A similar statement must be present in host2's - configuration file (with host1's address) for host2 to - sign request messages to host1. + Whenever any server sends a TSIG-signed DNS request, it will expect + the response to be signed with the same key. If a response is not + signed, or if the signature is not valid, the response will be + rejected.
- BIND allows IP addresses and ranges - to be specified in ACL - definitions and - allow-{ query | transfer | update } - directives. - This has been extended to allow TSIG keys also. The above key would - be denoted key host1-host2. + TSIG keys may be specified in ACL definitions and ACL directives + such as allow-query, allow-transfer + and allow-update. + The above key would be denoted in an ACL element as + key host1-host2.
- An example of an allow-update directive would be: + An example of an allow-update directive using + a TSIG key:
-allow-update { key host1-host2. ;};
+allow-update { !{ !localnets; any; }; key host1-host2. ;};
- This allows dynamic updates to succeed only if the request - was signed by a key named "host1-host2.". + This allows dynamic updates to succeed only if the UPDATE + request comes from an address in localnets, + and if it is signed using the + host1-host2. key.
See the section called “Dynamic Update Policies” for a discussion of @@ -703,85 +724,90 @@ allow-update { key host1-host2. ;};
- The processing of TSIG signed messages can result in - several errors. If a signed message is sent to a non-TSIG aware - server, a FORMERR (format error) will be returned, since the server will not - understand the record. This is a result of misconfiguration, - since the server must be explicitly configured to send a TSIG - signed message to a specific server. -
+ Processing of TSIG-signed messages can result in several errors: + +- If a TSIG aware server receives a message signed by an - unknown key, the response will be unsigned with the TSIG - extended error code set to BADKEY. If a TSIG aware server - receives a message with a signature that does not validate, the - response will be unsigned with the TSIG extended error code set - to BADSIG. If a TSIG aware server receives a message with a time - outside of the allowed range, the response will be signed with - the TSIG extended error code set to BADTIME, and the time values - will be adjusted so that the response can be successfully - verified. In any of these cases, the message's rcode (response code) is set to - NOTAUTH (not authenticated). + In all of the above cases, the server will return a response code + of NOTAUTH (not authenticated).
TKEY - is a mechanism for automatically generating a shared secret - between two hosts. There are several "modes" of - TKEY that specify how the key is generated - or assigned. BIND 9 implements only one of - these modes, the Diffie-Hellman key exchange. Both hosts are - required to have a Diffie-Hellman KEY record (although this - record is not required to be present in a zone). The - TKEY process must use signed messages, - signed either by TSIG or SIG(0). The result of - TKEY is a shared secret that can be used to - sign messages with TSIG. TKEY can also be - used to delete shared secrets that it had previously - generated. +
+ TKEY (Transaction KEY) is a mechanism for automatically negotiating + a shared secret between two hosts, originally specified in RFC 2930.
- The TKEY process is initiated by a - client - or server by sending a signed TKEY - query - (including any appropriate KEYs) to a TKEY-aware server. The - server response, if it indicates success, will contain a - TKEY record and any appropriate keys. - After - this exchange, both participants have enough information to - determine the shared secret; the exact process depends on the - TKEY mode. When using the - Diffie-Hellman - TKEY mode, Diffie-Hellman keys are - exchanged, - and the shared secret is derived by both participants. + There are several TKEY "modes" that specify how a key is to be + generated or assigned. BIND 9 implements only + one of these modes: Diffie-Hellman key exchange. Both hosts are + required to have a KEY record with algorithm DH (though this + record is not required to be present in a zone). +
++ The TKEY process is initiated by a client or server by sending + a query of type TKEY to a TKEY-aware server. The query must include + an appropriate KEY record in the additional section, and + must be signed using either TSIG or SIG(0) with a previously + established key. The server's response, if successful, will + contain a TKEY record in its answer section. After this transaction, + both participants will have enough information to calculate a + shared secret using Diffie-Hellman key exchange. The shared secret + can then be used by to sign subsequent transactions between the + two servers. +
++ TSIG keys known by the server, including TKEY-negotiated keys, can + be listed using rndc tsig-list. +
++ TKEY-negotiated keys can be deleted from a server using + rndc tsig-delete. This can also be done via + the TKEY protocol itself, by sending an authenticated TKEY query + specifying the "key deletion" mode.
- BIND 9 partially supports DNSSEC SIG(0) - transaction signatures as specified in RFC 2535 and RFC 2931. - SIG(0) - uses public/private keys to authenticate messages. Access control + BIND partially supports DNSSEC SIG(0) + transaction signatures as specified in RFC 2535 and RFC 2931. + SIG(0) uses public/private keys to authenticate messages. Access control is performed in the same manner as TSIG keys; privileges can be - granted or denied based on the key name. + granted or denied in ACL directives based on the key name.
When a SIG(0) signed message is received, it will only be - verified if the key is known and trusted by the server; the server - will not attempt to locate and/or validate the key. + verified if the key is known and trusted by the server. The + server will not attempt to recursively fetch or validate the + key.
- SIG(0) signing of multiple-message TCP streams is not - supported. + SIG(0) signing of multiple-message TCP streams is not supported.
The only tool shipped with BIND 9 that diff --git a/doc/arm/Bv9ARM.html b/doc/arm/Bv9ARM.html index 52d7f3c6a8..268b8bea09 100644 --- a/doc/arm/Bv9ARM.html +++ b/doc/arm/Bv9ARM.html @@ -95,12 +95,11 @@