Secret Key Transaction Authentication for DNS (TSIG)
obsoleted by
- rfc-8945 — Secret Key Transaction Authentication for DNS (TSIG)
updated by
- rfc-3645 — Generic Security Service Algorithm for Secret Key Transaction Authentication for DNS (GSS-TSIG)
- rfc-4635 — HMAC SHA (Hashed Message Authentication Code, Secure Hash Algorithm) TSIG Algorithm Identifiers
- rfc-6895 — Domain Name System (DNS) IANA Considerations
updates
- rfc-1035 — Domain names - implementation and specification
Extracted elements (25)
Timer values (Time Signed and Fudge) are included in the digest to defend against replay attacks. Without this, an attacker could replay old messages by updating just the Time Signed and Fudge fields to make the message appear fresh.
TSIG is intentionally unsuitable for general server-to-server authentication among many servers because key management becomes unwieldy as the number of shared secrets grows quadratically. It is designed for the common case of a few resolvers each talking to a small number of recursive servers.
TSIG was designed as a lightweight alternative to the computationally expensive public-key signatures in RFC2535. HMAC-MD5 provides efficient point-to-point authentication suitable for stub resolvers and dynamic update clients that cannot perform full public-key cryptography.
Some older name servers will not accept requests with a non-empty additional data section. Clients SHOULD only attempt signed transactions with servers known to support TSIG and share a secret key, avoiding compatibility failures with legacy implementations.
A forwarding server that does not share the key used in the incoming TSIG MUST forward the message unchanged including the TSIG. If it does share the key, it MUST process the TSIG and, if it passes, include its own TSIG to the next destination.
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 so operators can diagnose clock skew.
For TCP sessions, if the client does not receive TSIG records frequently enough, it SHOULD assume the connection has been hijacked and SHOULD close the connection. Subsequent TCP messages use a running digest chaining prior digest, any unsigned messages, and current TSIG Timers.
If a TSIG MAC fails to verify, the server MUST generate an error response with RCODE 9 (NOTAUTH) and TSIG ERROR 16 (BADSIG); this response MUST be unsigned. The server SHOULD log the error.
If a TSIG record cannot be added to a response without truncation, the server MUST alter the response to include only the question and a TSIG record, set the TC bit, and use RCODE 0 (NOERROR). The client SHOULD retry using TCP.
If an incoming message contains a TSIG record, it MUST be the last record in the additional section. Multiple TSIG records are not allowed. If a TSIG record is in any other position, the packet is dropped and a response with RCODE 1 (FORMERR) MUST be returned.
If no transaction security is available to the destination and the response has the AD flag set, the forwarding server MUST unset the AD flag before adding its own TSIG to the answer.
If the algorithm name or key name is unknown, or if message digests do not match, the whole DNS message MUST be discarded. If the message is a query, a response with RCODE 9 (NOTAUTH) MUST be returned with TSIG ERROR 17 (BADKEY) or 16 (BADSIG).
If the server time is outside the interval (Time Signed ± Fudge), the server MUST respond with RCODE 9 (NOTAUTH) and TSIG ERROR 18 (BADTIME). The BADTIME response MUST be signed with the same key as the request and MUST include the server's current time in the Other Data field (6 octets, u_int48_t).
On a TCP connection, TSIG MUST be included on the first and last DNS envelopes. It MUST be placed on at least every 100th envelope. If a client TSIG verification fails, the client MUST close the connection.
The only mandatory message digest algorithm specified is HMAC-MD5 (per RFC1321 and RFC2104). Implementations MUST implement HMAC-MD5 for interoperability; other algorithms may be defined later but MUST be registered with IANA.
The server MUST NOT generate a signed response to an unsigned request. When generating a response to a signed request, the digest components are: Request MAC, DNS Message (response), TSIG Variables (response).
Upon receipt, the server MUST perform checks in this order: check KEY, check TIME values, check MAC. If a server does not recognize the key, it MUST respond with RCODE 9 (NOTAUTH) and TSIG ERROR 17 (BADKEY), unsigned.
The TSIG digest covers: the full DNS message (before TSIG is appended), TSIG Variables (key name, class, TTL, algorithm name, time signed, fudge, error, other len, other data), and for responses also the Request MAC. Components are fed into the hash as a continuous octet stream with no interfield padding.
TSIG is a new DNS RR type with type code 250 (mnemonic TSIG). It is a meta-RR used for transaction-level authentication between DNS entities sharing a secret key; it MUST NOT be cached and is discarded after use.
IANA is to create and maintain a registry of TSIG Error values. Initial values are: 0–15 (DNS RCODEs), 16 (BADSIG), 17 (BADKEY), 18 (BADTIME). New error codes assigned via IETF Consensus.
Shared secret keys must be protected like private keys. Secrets should never be shared by more than two entities, never transmitted in the clear, and should be stored in encrypted form where possible. Compromised client hosts require the server to suspend all secrets known to that client.
Strong random shared secrets are essential; the secret MUST be at least as long as the keyed message digest — 16 bytes for HMAC-MD5, 20 bytes for HMAC-SHA1 (per RFC1750). Secrets should be changed periodically.
The Fudge value trades off security against operational reliability. A too-large Fudge opens the server to replay attacks; a too-small Fudge causes failures on unsynchronized clocks or delayed networks. The recommended value is 300 seconds.
TSIG only authenticates transmission between two parties sharing a secret; it does not authenticate the original source data. A compromised zone master or caching forwarder can still inject corrupt data unless full RFC2535 security checks are performed end-to-end.
TSIG RDATA contains: Algorithm Name (domain-name), Time Signed (u_int48_t, seconds since epoch), Fudge (u_int16_t), MAC Size (u_int16_t), MAC (octet stream), Original ID (u_int16_t), Error (u_int16_t), Other Len (u_int16_t), Other Data (octet stream). All multi-octet integers are in network byte order.