RFC 2845
Secret Key Transaction Authentication for DNS (TSIG)
Secret Key Transaction Authentication for DNS (TSIG) π
Okay bestie, RFC 2845 is here and it is a whole vibe π Here's the title block, so you know what you're looking at:
- Working group: Network Working Group
- Category: Standards Track
- Authors: P. Vixie (ISC), O. Gudmundsson (NAI Labs), D. Eastlake 3rd (Motorola), B. Wellington (Nominum)
- Date: May 2000
- Updates: RFC 1035 π§
- Obsoletes: nothing listed, so it doesn't replace any earlier RFC
Status of This Memo β¨
This doc is an Internet standards track protocol for the Internet community, and it's asking everyone to talk about it and suggest improvements π For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited, so share it with your whole group chat π«Ά
Copyright Notice πΈ
Copyright (C) The Internet Society (2000). All Rights Reserved.
Abstract π
This protocol gives you transaction-level authentication using shared secrets and one-way hashing. You can use it to prove that a dynamic update is coming from an approved client, or to prove that a response is coming from an approved recursive name server. It's giving security with zero drama π
There's no part of this doc about getting the shared secrets to each side. The idea is that a network administrator sets up name servers and clients by hand, using some out-of-band method like sneaker-net, until a secure automated way to distribute keys shows up π¦
1 - Introduction π
1.1. The Domain Name System (DNS) [RFC1034, RFC1035] is a replicated hierarchical distributed database system. It's the backbone for stuff like name <=> address translation and mail handling info, so it's basically essential to how the Internet runs π DNS got extended [RFC2535] to add data origin authentication and public key distribution, all built on public key cryptography and public key based digital signatures. Real talk though, to make this practical you usually need a lot of local caching of keys, plus tracing authentication through multiple keys and signatures back to a pre-trusted locally configured key π
1.2. Here's the tea: the [RFC2535] scheme has a problem with common DNS implementations, which include simple "stub" resolvers that don't have caches. These stubs usually lean on a caching DNS server on another host. It's impractical for stubs to do general [RFC2535] authentication, so they'd naturally depend on their caching DNS server to do that for them. To do this securely, you need secure communication of queries and responses π [RFC2535] has public key transaction signatures to cover this, but those are super expensive to generate computationally. They need the same complicated public key logic that's impractical for stubs, so it's not it π This document specifies the use of a message authentication code (MAC), specifically HMAC-MD5 (a keyed hash function). It gives an efficient way to do point-to-point authentication and integrity checking for transactions β¨
1.3. Another spot where straight [RFC2535] public key mechanisms may be impractical is authenticating dynamic update [RFC2136] requests. [RFC2535] does provide for request signatures, but like transaction signatures, they need computationally expensive public key cryptography and complex authentication logic π Secure Domain Name System Dynamic Update ([RFC2137]) describes how different keys are used in dynamically updated zones. This document's secret-key-based MACs can authenticate DNS update requests as well as transaction responses, which makes them a lightweight alternative to the protocol described in [RFC2137] π§
1.4. There's also a further use for this mechanism: protecting zone transfers. In that case, the data covered would be the whole zone transfer, including any glue records sent. The protocol described by [RFC2535] doesn't protect glue records and unsigned records unless SIG(0) (transaction signature) is used π
1.5. The authentication mechanism proposed here uses shared secret keys to establish a trust relationship between two entities. These keys need to be protected in a way similar to private keys, or a third party could masquerade as one of the intended parties (forge MACs). There's an urgent need for simple and efficient authentication between clients and local servers, and this proposal is built to handle that π It's unsuitable for general server to server authentication, though, for servers that talk to many other servers, because key management would get unwieldy as the number of shared keys goes up quadratically. It is suitable for lots of resolvers on hosts that only talk to a few recursive servers πΈ
1.6. A server acting as an indirect caching resolver (a "forwarder" in common usage) might use transaction-based authentication when it talks to its small number of preconfigured "upstream" servers π¦ Other uses of DNS secret key authentication, and possible systems for automatic secret key distribution, may be proposed in separate future documents β¨
1.7. New Assigned Numbers π
RRTYPE = TSIG (250)
ERROR = 0..15 (a DNS RCODE)
ERROR = 16 (BADSIG)
ERROR = 17 (BADKEY)
ERROR = 18 (BADTIME)
1.8. The key words "MUST", "REQUIRED", "SHOULD", "RECOMMENDED", and "MAY" in this document are to be interpreted as described in [RFC 2119] π
2 - TSIG RR Format π¦
2.1 TSIG RR Type
To get secret key authentication going, we use a new RR type whose mnemonic is TSIG and whose type code is 250 π TSIG is a meta-RR and MUST not be cached. TSIG RRs are used for authentication between DNS entities that have already set up a shared secret key. They're dynamically computed to cover one particular DNS transaction, so they're not DNS RRs in the usual sense π«Ά
2.2 TSIG Calculation
Since TSIG RRs are tied to one DNS request/response, there's no point in storing or retransmitting them. So the TSIG RR gets thrown out once it's been used to authenticate a DNS message ποΈ The only message digest algorithm specified in this document is "HMAC-MD5" (see [RFC1321], [RFC2104]). The "HMAC-MD5" algorithm is mandatory to implement for interoperability π Other algorithms can be specified at a later date. Names and definitions of new algorithms MUST be registered with IANA. And all multi-octet integers in the TSIG record are sent in network byte order (see [RFC1035 2.3.2]) π₯
2.3. Record Format
Here's how the fields work, and yes, the details matter π§ The record is laid out like this:
NAME
TYPE TSIG (250: Transaction SIGnature)
CLASS ANY
TTL 0
RdLen (variable)
RDATA
NAME is the name of the key, written in domain name syntax. It should reflect the names of the hosts and uniquely identify the key among a set of keys these two hosts may share at any given time. For example, if hosts A.site.example and B.example.net share a key, the key name could be <id>.A.site.example, <id>.B.example.net, or <id>.A.site.example.B.example.net. It should be possible for more than one key to be in simultaneous use among a set of interacting hosts. The name only needs to be meaningful to the communicating hosts, but a meaningful mnemonic name like the ones above is strongly recommended π
The name may be used as a local index to the key involved, and it is recommended that it be globally unique. When a key is just shared between two hosts, the name only needs to be meaningful to them, but it is recommended that the key name be mnemonic and include the resolver and server host names, in that order πΈ
RDATA has these fields:
Field Name Data Type Notes
--------------------------------------------------------------
Algorithm Name domain-name Name of the algorithm
in domain name syntax.
Time Signed u_int48_t seconds since 1-Jan-70 UTC.
Fudge u_int16_t seconds of error permitted
in Time Signed.
MAC Size u_int16_t number of octets in MAC.
MAC octet stream defined by Algorithm Name.
Original ID u_int16_t original message ID
Error u_int16_t expanded RCODE covering
TSIG processing.
Other Len u_int16_t length, in octets, of
Other Data.
Other Data octet stream empty unless Error == BADTIME
2.4. Example
Let's see it in action with HOST.EXAMPLE. π
NAME HOST.EXAMPLE.
TYPE TSIG
CLASS ANY
TTL 0
RdLen as appropriate
RDATA
Field Name Contents
-------------------------------------
Algorithm Name SAMPLE-ALG.EXAMPLE.
Time Signed 853804800
Fudge 300
MAC Size as appropriate
MAC as appropriate
Original ID as appropriate
Error 0 (NOERROR)
Other Len 0
Other Data empty
3. Protocol Operation β¨
3.1. Effects of adding TSIG to outgoing message π
okay so once the outgoing message is all put together, you can run the keyed message digest operation π. The resulting digest then gets stored in a TSIG, which is tacked onto the end of the additional data section (and the ARCOUNT goes up by one to show it's there) π. If adding the TSIG record would cause the message to get truncated, the server MUST alter the response so a TSIG can still be included π. This response only has the question and a TSIG record in it, with the TC bit set and RCODE 0 (NOERROR) π. The client SHOULD retry the request over TCP at this point (per [RFC1035 4.2.2]) π¦. Bestie, that's the glow-up path when things don't fit β¨.
3.2. TSIG processing on incoming messages π
if an incoming message has a TSIG record, it MUST be the last record in the additional section π. Multiple TSIG records are not allowed, no cap π ββοΈ. If the TSIG shows up anywhere else, the packet gets dropped and a response with RCODE 1 (FORMERR) MUST be returned π. When a message arrives with a TSIG RR in the right spot, that TSIG RR gets copied somewhere safe, removed from the DNS Message, and taken off the DNS message header's ARCOUNT π§. Then the keyed message digest operation happens π₯. If the recipient doesn't know the algorithm name or the key name, or the message digests don't match, the whole DNS message MUST be discarded π. If the message is a query, a response with RCODE 9 (NOTAUTH) MUST be sent back to the originator, carrying TSIG ERROR 17 (BADKEY) or TSIG ERROR 16 (BADSIG) πΈ. If there's no key available to sign this message, it MUST be sent unsigned (MAC size == 0 and empty MAC) π«Ά. A message SHOULD be generated in the system operations log to warn the ops staff about a possible security incident in progress π¨. Care should be taken to make sure that logging this kind of event doesn't open the system up to a denial of service attack π€. Not me being dramatic about logs, but this is serious ngl π.
β οΈ Heads up: logging is a whole vibe, but if you log every bad signature without thinking, an attacker can flood your logs and make everything else a mess. Protect the logs too! π‘οΈ
3.3. Time values used in TSIG calculations β°
the data that gets digested includes the two timer values in the TSIG header, and that's how we defend against replay attacks π¦. Without this, an attacker could replay old messages and just update the "Time Signed" and "Fudge" fields so the message looks brand new. Iconic behaviour from the bad guys π. This data is called "TSIG Timers", and for digest calculation it's used in its "on the wire" format, in this order: Time Signed first, then Fudge π. Here's an example:
Field Name Value Wire Format Meaning
----------------------------------------------------------------------
Time Signed 853804800 00 00 32 e4 07 00 Tue Jan 21 00:00:00 1997
Fudge 300 01 2C 5 minutes
3.4. TSIG Variables and Coverage π§©
when you're generating or verifying the contents of a TSIG record, the following data gets digested, in network byte order or wire format, whichever fits π.
3.4.1. DNS Message π¦
this is a whole and complete DNS message in wire format, from before the TSIG RR gets added to the additional data section and before the DNS Message Header's ARCOUNT field gets incremented to include the TSIG RR π. If the message ID is different from the original message ID, the original message ID gets swapped in as the message ID π. This could happen when forwarding a dynamic update request, for example π.
3.4.2. TSIG Variables π
Source Field Name Notes
-----------------------------------------------------------------------
TSIG RR NAME Key name, in canonical wire format
TSIG RR CLASS (Always ANY in the current specification)
TSIG RR TTL (Always 0 in the current specification)
TSIG RDATA Algorithm Name in canonical wire format
TSIG RDATA Time Signed in network byte order
TSIG RDATA Fudge in network byte order
TSIG RDATA Error in network byte order
TSIG RDATA Other Len in network byte order
TSIG RDATA Other Data exactly as transmitted
the RR RDLEN and the RDATA MAC Length are NOT part of the hash, because they're not guaranteed to be knowable before the MAC is generated π. The Original ID field isn't in this section either, since it was already swapped in for the message ID in the DNS header and hashed π«Ά. For each label type, there must be a defined "Canonical wire format" that says how to write a label in an unambiguous way β¨. For label type 00, that's defined in [RFC2535], and for label type 01, it's defined in [RFC2673] π. Using label types other than 00 and 01 isn't defined for this spec, so don't go there π ββοΈ.
3.4.3. Request MAC π
when you're generating the MAC for a response, the request MAC must be included in the digest π. The request's MAC gets digested in wire format, with these fields:
Field Type Description
---------------------------------------------------
MAC Length u_int16_t in network byte order
MAC Data octet stream exactly as transmitted
3.5. Padding π«§
digested components get fed into the hashing function as one continuous octet stream, with no interfield padding πΈ. Clean and simple, periodt π .
4 - Protocol Details β¨
4.1. TSIG generation on requests
okay bestie, the client does the message digest operation π , tacks a TSIG record onto the additional data section, and then sends the request off to the server π¦. The client MUST store the message digest from the request while it's waiting for an answer π«Ά. The digest components for a request are:
DNS Message (request)
TSIG Variables (request)
Note that some older name servers will not accept requests with a nonempty additional data section π. Clients SHOULD only attempt signed transactions with servers who are known to support TSIG and share some secret key with the client -- so, this is not a problem in practice β¨.
4.2. TSIG on Answers
When a server has generated a response to a signed request, it signs the response using the same algorithm and key π. The server MUST not generate a signed response to an unsigned request π . The digest components are:
Request MAC
DNS Message (response)
TSIG Variables (response)
4.3. TSIG on TSIG Error returns
When a server detects an error relating to the key or MAC, the server SHOULD send back an unsigned error message (MAC size == 0 and empty MAC) π. If an error is detected relating to the TSIG validity period, the server SHOULD send back a signed error message βοΈ. The digest components are:
Request MAC (if the request MAC validated)
DNS Message (response)
TSIG Variables (response)
The reason that the request is not included in this digest in some cases is to make it possible for the client to verify the error π§. If the error is not a TSIG error, the response MUST be generated as specified in [4.2].
4.4. TSIG on TCP connection
A DNS TCP session can include multiple DNS envelopes π¨. This is, for example, commonly used by zone transfer π. Using TSIG on such a connection can protect the connection from hijacking and provide data integrity π‘οΈ. The TSIG MUST be included on the first and last DNS envelopes. It can be optionally placed on any intermediary envelopes. It is expensive to include it on every envelope, but it MUST be placed on at least every 100'th envelope. The first envelope is processed as a standard answer, and subsequent messages have the following digest components:
Prior Digest (running)
DNS Messages (any unsigned messages since the last TSIG)
TSIG Timers (current message)
This allows the client to rapidly detect when the session has been altered, and at that point it can close the connection and retry πββοΈ. If a client TSIG verification fails, the client MUST close the connection. If the client does not receive TSIG records frequently enough (as specified above), it SHOULD assume the connection has been hijacked and it SHOULD close the connection. The client SHOULD treat this the same way as they would any other interrupted transfer (although the exact behavior is not specified) π€·ββοΈ.
4.5. Server TSIG checks
Upon receipt of a message, the server will check if there is a TSIG RR π. If one exists, the server is REQUIRED to return a TSIG RR in the response. The server MUST perform the following checks in the following order: check KEY, check TIME values, check MAC. no skipping, periodt π.
4.5.1. KEY check and error handling
If a non-forwarding server does not recognize the key used by the client, the server MUST generate an error response with RCODE 9 (NOTAUTH) and TSIG ERROR 17 (BADKEY) πβ. This response MUST be unsigned as specified in [4.3]. The server SHOULD log the error.
4.5.2. TIME check and error handling
If the server time is outside the time interval specified by the request (which is: Time Signed, plus/minus Fudge) β°, the server MUST generate an error response with RCODE 9 (NOTAUTH) and TSIG ERROR 18 (BADTIME). The server SHOULD also cache the most recent time signed value in a message generated by a key, and SHOULD return BADTIME if a message received later has an earlier time signed value. A response indicating a BADTIME error MUST be signed by the same key as the request. It MUST include the client's current time in the time signed field, the server's current time (a u_int48_t) in the other data field, and 6 in the other data length field. This is done so that the client can verify a message with a BADTIME error without the verification failing due to another BADTIME error π«Ά. The data signed is specified in [4.3]. The server SHOULD log the error.
4.5.3. MAC check and error handling
If a TSIG fails to verify, the server MUST generate an error response as specified in [4.3] with RCODE 9 (NOTAUTH) and TSIG ERROR 16 (BADSIG) π₯. This response MUST be unsigned as specified in [4.3]. The server SHOULD log the error.
4.6. Client processing of answer
When a client receives a response from a server and expects to see a TSIG, it first checks if the TSIG RR is present in the response π. Otherwise, the response is treated as having a format error and discarded ποΈ. The client then extracts the TSIG, adjusts the ARCOUNT, and calculates the keyed digest in the same way as the server. If the TSIG does not validate, that response MUST be discarded, unless the RCODE is 9 (NOTAUTH), in which case the client SHOULD attempt to verify the response as if it were a TSIG Error response, as specified in [4.3]. A message containing an unsigned TSIG record, or a TSIG record which fails verification, SHOULD not be considered an acceptable response. The client SHOULD log an error and continue to wait for a signed response until the request times out β³.
4.6.1. Key error handling
If an RCODE on a response is 9 (NOTAUTH), and the response TSIG validates, and the TSIG key is different from the key used on the request, then this is a KEY error ππ¨. The client MAY retry the request using the key specified by the server. This should never occur, as a server MUST NOT sign a response with a different key than the one that signed the request π
ββοΈ.
4.6.2. Time error handling
If the response RCODE is 9 (NOTAUTH) and the TSIG ERROR is 18 (BADTIME), or the current time does not fall in the range specified in the TSIG record, then this is a TIME error β°π¬. This is an indication that the client and server clocks are not synchronized. In this case, the client SHOULD log the event. DNS resolvers MUST NOT adjust any clocks in the client based on BADTIME errors, but the server's time in the other data field SHOULD be logged π.
4.6.3. MAC error handling
If the response RCODE is 9 (NOTAUTH) and TSIG ERROR is 16 (BADSIG), this is a MAC error. The client MAY retry the request with a new request ID, but it would be better to try a different shared key if one is available π. Client SHOULD keep track of how many MAC errors are associated with each key. Clients SHOULD log this event π.
4.7. Special considerations for forwarding servers
A server acting as a forwarding server of a DNS message SHOULD check for the existence of a TSIG record π΅οΈ. If the name on the TSIG is not of a secret that the server shares with the originator, the server MUST forward the message unchanged, including the TSIG π¬. If the name of the TSIG is of a key this server shares with the originator, it MUST process the TSIG. If the TSIG passes all checks, the forwarding server MUST, if possible, include a TSIG of its own, to the destination or the next forwarder π. If no transaction security is available to the destination and the response has the AD flag (see [RFC2535]), the forwarder MUST unset the AD flag before adding the TSIG to the answer π«.
5 - Shared Secrets β¨
5.1. Secret keys are very sensitive information, and all available steps should be taken to protect them on every host on which they are stored π. Generally, such hosts need to be physically protected. If they are multi-user machines, great care should be taken that unprivileged users have no access to keying material π. Resolvers often run unprivileged, which means all users of a host would be able to see whatever configuration data is used by the resolver.
5.2. A name server usually runs privileged, which means its configuration data need not be visible to all users of the host. For this reason, a host that implements transaction-based authentication should probably be configured with a "stub resolver" and a local caching and forwarding name server π§. This presents a special problem for [RFC2136], which otherwise depends on clients to communicate only with a zone's authoritative name servers.
5.3. Use of strong random shared secrets is essential to the security of TSIG πͺ. See [RFC1750] for a discussion of this issue. The secret should be at least as long as the keyed message digest, i.e., 16 bytes for HMAC-MD5 or 20 bytes for HMAC-SHA1 π².
6 - Security Considerations β¨
Okay, this section is serious business, so read it like it's your group chat's most important drama ππ¨
6.1. The approach specified here is computationally much less expensive than the signatures specified in [RFC2535] π§ . As long as the shared secret key is not compromised, strong authentication is provided for the last hop from a local name server to the user resolver π.
6.2. Secret keys should be changed periodically π. If the client host has been compromised, the server should suspend the use of all secrets known to that client π·. If possible, secrets should be stored in encrypted form. Secrets should never be transmitted in the clear over any network π ββοΈ. This document does not address the issue of how to distribute secrets. Secrets should never be shared by more than two entities π.
6.3. This mechanism does not authenticate source data, only its transmission between two parties who share some secret. The original source data can come from a compromised zone master, or it can be corrupted during transit from an authentic zone master to some "caching forwarder" π΅. However, if the server is faithfully performing the full [RFC2535] security checks, then only security checked data will be available to the client β .
6.4. A fudge value that is too large may leave the server open to replay attacks π¨. A fudge value that is too small may cause failures if machines are not time synchronized or there are unexpected network delays β±οΈ. The recommended value in most situations is 300 seconds β.
7 - IANA Considerations β¨
IANA is expected to create and maintain a registry of algorithm names to be used as "Algorithm Names," as defined in Section 2.3 π. The initial value should be "HMAC-MD5.SIG-ALG.REG.INT." Algorithm names are text strings encoded using the syntax of a domain name. There is no structure required other than that names for different algorithms must be unique when compared as DNS names, i.e., comparison is case insensitive π€. Note that the initial value mentioned above is not a domain name, and therefore need not be a registered name within the DNS. New algorithms are assigned using the IETF Consensus policy defined in RFC 2434. The algorithm name HMAC-MD5.SIG-ALG.REG.INT looks like a FQDN for historical reasons, but future algorithm names are expected to be simple (i.e., single-component) names π.
IANA is expected to create and maintain a registry of "TSIG Error values" to be used for "Error" values, as defined in section 2.3 π. Initial values should be those defined in section 1.7. New TSIG error codes for the TSIG error field are assigned using the IETF Consensus policy defined in RFC 2434 π.
8. References π
[RFC1034]Mockapetris, P., "Domain Names - Concepts and Facilities", STD 13, RFC 1034, November 1987. πΈ[RFC1035]Mockapetris, P., "Domain Names - Implementation and Specification", STD 13, RFC 1034, November 1987. π§[RFC1321]Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April 1992. π[RFC1750]Eastlake, D., Crocker, S. and J. Schiller, "Randomness Recommendations for Security", RFC 1750, December 1995. π²[RFC2104]Krawczyk, H., Bellare, M. and R. Canetti, "HMAC-MD5: Keyed-MD5 for Message Authentication", RFC 2104, February 1997. ποΈ[RFC2119]Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. π[RFC2136]Vixie, P., Thomson, S., Rekhter, Y. and J. Bound "Dynamic Updates in the Domain Name System", RFC 2136, April 1997. π[RFC2137]Eastlake 3rd, D., "Secure Domain Name System Dynamic Update", RFC 2137, April 1997. π‘οΈ[RFC2535]Eastlake, D., "Domain Name System Security Extensions", RFC 2535, March 1999. π¦[RFC2673]Crawford, M., "Binary Labels in the Domain Name System", RFC 2673, August 1999. π·οΈ
9. Authors' Addresses π
These are the four people who wrote this, bestie, so you know exactly who to thank (or ping) π«Ά
Paul Vixie
Internet Software Consortium
950 Charter Street
Redwood City, CA 94063
Phone: +1 650 779 7001
EMail: vixie@isc.org
Olafur Gudmundsson
NAI Labs
3060 Washington Road, Route 97
Glenwood, MD 21738
Phone: +1 443 259 2389
EMail: ogud@tislabs.com
Donald E. Eastlake 3rd
Motorola
140 Forest Avenue
Hudson, MA 01749 USA
Phone: +1 508 261 5434
EMail: dee3@torque.pothole.com
Brian Wellington
Nominum, Inc.
950 Charter Street
Redwood City, CA 94063
Phone: +1 650 779 6022
EMail: Brian.Wellington@nominum.com
10. Full Copyright Statement βοΈ
Copyright (C) The Internet Society (2000). All Rights Reserved. π
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. π
This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. π
Acknowledgement π
Funding for the RFC Editor function is currently provided by the Internet Society. β¨
π¦ where this page comes from
- ietf: rfc2845 2000-05
- π girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms