Secret Key Transaction Authentication for DNS (TSIG)
obsoletes
- rfc-2845 — Secret Key Transaction Authentication for DNS (TSIG)
- rfc-4635 — HMAC SHA (Hashed Message Authentication Code, Secure Hash Algorithm) TSIG Algorithm Identifiers
also
- std-93
Extracted elements (28)
RFC 2845 required time values to be checked before the request MAC, allowing some implementations to use an invalid request MAC in a signed reply when time validation failed (CVE-2017-3142, CVE-2017-3143, CVE-2017-11104). This document fixes this by mandating that the request MAC is treated as invalid until validated, and that any answer using an unvalidated MAC must be unsigned.
TSIG is unsuitable for general server-to-server authentication among many servers because the number of required shared keys grows quadratically. It is well-suited for resolvers communicating with a small number of recursive servers or for primary-to-secondary zone transfer authentication.
TSIG uses shared-secret HMAC rather than DNSSEC public key signatures because stub resolvers lack caches and the computational cost of public key operations is impractical for them. TSIG also provides a lightweight alternative for authenticating dynamic updates where DNSSEC's public key infrastructure is equally expensive.
Although hmac-sha1 support is mandatory for backward compatibility, existing deployments SHOULD be migrated to hmac-sha256 or other SHA-2 algorithms because SHA-1 collisions have been demonstrated. HMAC-MD5 MUST NOT be used.
A forwarding server that does not share the TSIG key MUST forward the message unchanged including the TSIG. If the server shares the key, it MUST process the TSIG and, if checks pass, MUST include its own TSIG toward the destination. If the response has the AD flag set and no transaction security is available, the forwarder MUST clear the AD flag.
A server MUST NOT generate a signed response to an unsigned request (except for TKEY responses explicitly specified by the key establishment algorithm), and MUST NOT sign a response when the key is invalid or MAC validation fails.
DNS resolvers MUST NOT adjust any clocks in the client based on BADTIME errors. The server's time in the Other Data field SHOULD be logged for diagnostic purposes.
For TCP multi-message responses (e.g., zone transfers), the TSIG MUST be included on all DNS messages. For backward compatibility, a verifying client MUST accept up to 99 intermediary messages without a TSIG but MUST verify that both the first and last message contain a TSIG.
If a non-forwarding server does not recognize the key or algorithm, it MUST generate an error response with RCODE 9 (NOTAUTH) and TSIG ERROR 17 (BADKEY). This response MUST be unsigned.
If a TSIG is received with truncation permitted by Section 5.2.2.1 but the MAC is too short for local policy, RCODE 9 (NOTAUTH) and TSIG ERROR 22 (BADTRUNC) MUST be returned.
If the server time is outside the interval (Time Signed ± Fudge), the server MUST return RCODE 9 (NOTAUTH) with TSIG ERROR 18 (BADTIME). A BADTIME error response MUST be signed with the same key, MUST include client's current time in Time Signed, and MUST include the server's current time as a 48-bit integer in Other Data.
Implementations that support TSIG MUST implement HMAC-SHA1 and HMAC-SHA256. HMAC-MD5 use is MUST NOT; hmac-sha1 use is NOT RECOMMENDED; hmac-sha256 use is RECOMMENDED. SHA-1 truncated to 96 bits SHOULD be implemented for compatibility.
MAC truncation rules: if MAC Size exceeds the keyed hash output length, the message MUST be dropped with FORMERR. If MAC Size is less than max(10 octets, half the hash length), the message MUST be dropped with FORMERR (except in specific error responses where MAC Size may be zero).
The server MUST verify the MAC by independent computation and comparison. If verification fails, the server MUST return RCODE 9 (NOTAUTH) with TSIG ERROR 16 (BADSIG) and MUST NOT sign the error response.
The TSIG RR MUST be the only TSIG RR in the message and MUST be the last record in the additional data section. If multiple TSIG records are detected or one is present in any other position, the DNS message is dropped and a response with RCODE 1 (FORMERR) MUST be returned.
Upon receipt of a TSIG message, a server MUST validate in the following order: (1) check key, (2) check MAC, (3) check time values, (4) check truncation policy. This ordering was changed from RFC 2845 to fix a security vulnerability where invalid MACs could be used in signed replies.
When a local policy permits a truncated MAC for a given algorithm, it SHOULD also permit lesser truncation (longer MAC) up to full output length. A reply SHOULD carry a MAC at least as long as the MAC in the corresponding request.
When a server detects a key or MAC error, it SHOULD send back an unsigned error message (MAC Size == 0 and empty MAC) and MUST NOT send back a signed error message. For time validity or truncation policy errors, the server SHOULD send back a signed error message.
For second and subsequent TCP messages in a multi-message response, the MAC digest input comprises: Prior MAC (MAC from the last TSIG-bearing message), DNS Messages (all unsigned messages since the last TSIG concatenated with the current message), and TSIG Timers (Time Signed + Fudge for the current message only).
MAC computation for a response MUST include, in order: the validated request MAC (as MAC Size + MAC Data in wire format), the complete DNS message (with TSIG RR removed and ARCOUNT decremented), and the TSIG Variables (NAME, CLASS, TTL, Algorithm Name, Time Signed, Fudge, Error, Other Len, Other Data).
TSIG is an RR type with code 250 used for transaction-level authentication between DNS entities sharing a secret key. It is a meta-RR that MUST NOT be cached and is dynamically computed to cover a particular DNS transaction; it is discarded once used.
TSIG RR fixed fields: TYPE MUST be 250 (TSIG), CLASS MUST be ANY, TTL MUST be 0. The NAME field holds the key identifier in domain name syntax and SHOULD be globally unique to allow identification among a set of interacting hosts.
IANA maintains a DNS RCODEs registry including 'TSIG Error values'. This document defines BADSIG (16), BADKEY (17), BADTIME (18), and BADTRUNC (22) for use in the TSIG RR Error field. New error codes are assigned per RFC 6895.
IANA maintains the 'TSIG Algorithm Names' registry [IANA-TSIG] of algorithm identifiers encoded as domain names and compared case-insensitively. New algorithms are assigned via IETF Review. This document updates the registry with all algorithms listed in Table 3.
A Fudge value that is too large leaves the server open to replay attacks; one that is too small may cause failures due to clock skew or network delay. The RECOMMENDED Fudge value in most situations is 300 seconds.
Shared secret keys must be protected like private keys. Secrets SHOULD NOT be shared by more than two entities, as any additional party knowing the key can impersonate any other party in the group. Secrets should never be transmitted in the clear and SHOULD be at least as long as the keyed hash output.
To prevent cross-algorithm attacks, there SHOULD only be one algorithm associated with any given key name. Unsigned error responses can be spoofed by attackers; clients should log these and continue waiting for a signed response until timeout.
The TSIG RDATA contains: Algorithm Name (domain name wire format, MUST NOT be compressed), Time Signed (unsigned 48-bit integer, seconds since epoch), Fudge (unsigned 16-bit integer, allowed clock skew in seconds), MAC Size (unsigned 16-bit), MAC (variable octets), Original ID (unsigned 16-bit), Error (unsigned 16-bit), Other Len (unsigned 16-bit), and Other Data (variable octets).