draft-ietf-dnsind-dns-error-00.txt R. Watson INTERNET-DRAFT TIS O. Gudmundsson TIS 8 March 1998 Expires in six months Error Record (ERR) for DNS Status of this Document This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress." To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). Abstract The DNS protocol defines a 4-bit RCODE field in the header of the DNS envelope. This field is used to indicate the completion status of requests. Defined values exist to describe successful completion as well as a variety of error conditions that could result from DNS server operations. As DNS has been expanded to perform additional functions, the number of possible error conditions has increased significantly, and the field no longer has space for new error codes to be added. To address this problem, a new RR type is defined. The Error Record contains a machine-readable extended error value, as well as an optional human-readable ASCII text string. Additionally, it contains a domain-name source field to identify the entity generating the error condition. This RR may also be used in non- error conditions to provide extended information about server responses, such as security information on specific records in the response. Watson [Page 1] Internet DRAFT Error Record for DNS 8 March 1998 1. Introduction The Domain Name System (DNS) [RFC1034, RFC1035] is a replicated hierarchical distributed database system that provides information fundamental to Internet operations, such as name <=> address translation and mail handling information. With recent additions, it can now also provide this information in a secure manner [RFC2065, TSIG], as well as support dynamic changes to its contents [RFC2136, RFC2137]. These features (and others) have resulted in much greater functionality, but also many more possible error conditions. The database requires synchronization and atomicity of update, as well as the ability to report various problems with an update request. With DNS Security and Transaction Signatures, authorization to complete or deliver a request can fail for a variety of reasons. The ability to report these problems in an accurate manner is vital for the maintenance of the system, as the inability to diagnose a serious configuration problem may lead to a loss of service for members of the Internet population. The DNS protocol defines a 4-bit response code field set in the DNS envelope for server responses to indicate successful completion of a request or provide a functional justification for the failure to perform an operation. This space is insufficient for storage of the more complicated errors possible with additional features, as well as not providing any indication of the actual source of the error. As some operations may involve passing a request packet through a series of servers, SERVFAIL may not be sufficient information to correct the problem without extensive debugging. 1.1 Keywords Used The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. 2. Error Record Format To provide storage for the error message information, a new RR type is defined with mnemonic ERR. ERR is a meta-RR and it cannot be stored; its type code is TBD. ERR is pronounced with a rolling Icelandic "r". For the existing defined RCODE values, the ERR record exists to provide source and debugging information, and is optional. For RCODE of EXTERR (value TBD), an ERR MUST be included to define the error condition. Additional ERR records MAY also be included. When RCODE is NOERROR (0), ERR records MAY be used to provide optional information. Watson [Page 2] Internet DRAFT Error Record for DNS 8 March 1998 2.1 Record Format: NAME The domain-name of the server reporting the error. This must be the fully qualified domain name of the entity. TYPE ERR CLASS IN TTL Serial Number Arithmetic value of the time the message was generated in seconds since Jan 1, 1970 UTC. RdLen (variable) RDATA Field Name Data Type Notes ------------------------ ------------ -------------------------- Error Code u_int16_t For existing RCODE values, Error Code should be set to the RCODE value. For RCODE of EXTERR, an IANA- assigned value will be used. Referred Dname domain-name A domain name specifying another entity or key involved in the error. Use of this field varies by error. Type u_int16_t For messages associated with a particular RR Name/ Type, this will allow differentiation. This is useful in the context of Dynamic Update, for example. This should be set to 0 where unused. Message Size u_int8_t Number of octets in the error message. Message octet stream The user-readable error message. Other Data undefined Ignore any following RDATA * All multi-octet integer values are in Network Byte Order Watson [Page 3] Internet DRAFT Error Record for DNS 8 March 1998 2.2 Example RCODE SERVFAIL (2) NAME DNS-1.PROVIDER.XX. TYPE ERR CLASS IN TTL 869769589 RdLen 72 RDATA Field Name Contents -------------- -------------- Error Code 2 Referred Name FLEDGE.WATSON.ORG. Type 0 Message Size 58 Message Server Failure: Timeout on forwarded request (BIND 8.1.1) 3. Error Message Generation When an error occurs, the entity generating the error has the option of reporting the error to the client. A normal packet is constructed, with the RCODE in the header set appropriately. If the RCODE is EXTERR, it MUST attach an ERR record. Otherwise, the ERR record is optional. ERR records MAY be placed in any section of a DNS packet where resources records can occur. Informational ERR records are expected to be interspersed with existing RRs or RRsets, and in the event an ERR record is associated with another record, it MUST follow that record. For example, an ERR record might indicate the security status of an A record, in which case it would follow that resource record in the Answer section. When ERR RRs are not associated with another RR, they MUST be placed in the Additional Data section. For example, a Server Failure error packet would have RCODE of SERVFAIL (2), and an ERR RR (such as seen in the above example) in the Additional Data section. If a packate containing required error codes it too long for a UDP packet, the message MUST be truncated, and the TC bit set, indicating that the client should retry over TCP to retrieve the complete answer. In constructing the ERR RRs, the fully qualified domain name of the entity generating the message SHOULD be used as the resource record name. In all identified cases, this will be a name server. The class MUST be IN, and the TTL must be set to the time (in seconds since Jan 1, 1970 UTC) that the error occurred. Watson [Page 4] Internet DRAFT Error Record for DNS 8 March 1998 Inside the RDATA of the RR, the Error Code SHUOLD be set either to the existing RCODE value, or in the case of NOERROR or EXTERR, to the IANA-assigned Error Code for the error or message type being reported. If multiple error messages are included, and only one uses an RCODE-defined value, that value MUST be used in the packet's RCODE field. If multiple RCODE-defined values are present, the first of these values MUST used for the packet header RCODE field. This provides backwards compatibility, as existing DNS operations abort on the first error discovered, and that error is reported. The referral domain name depends on the type of message being transmitted. Referral name values for common RCODEs are described in Section 7. The message text will be stored in an octet-stream of up to 255 octets in length. The message MUST be interpreted as USASCII text. The length of the message will be stored in the Message Size field. 3.1 Message Text Format To provide a more consistent message format, the following formatting SHOULD be applied to the message field in the RR: IANA-registered text: specific error text (software version identifier) The IANA-registered text SHOULD be consistent with the registered Error Code value (Section 6). The specific error text SHOULD be further debugging information that will be interpreted by a user or administrator. Client software SHOULD not attempt to parse and interpret the specific text field. The software version identifier is optional, but if server software chooses to provide an identifier, it SHOULD do so consistently. Clients MAY optionally parse the software version identifier, but this information is intended for manual debugging. Client behavior on receiving an extended error message SHOULD depend on the error received. Clients are not required to display extended error information to the user, although they MAY do so in the event of a serious failure. Interpretation of the text message SHOULD NOT be relied upon by the server: the resolver or update software is only required to interpret the Error Code itself. 4.Storage Considerations ERR RRs are transient in nature, and SHOULD NOT be stored or reused beyond the query that they are created for. In particular, DNS servers MUST NOT cache the ERR records and return them to other clients. Watson [Page 5] Internet DRAFT Error Record for DNS 8 March 1998 5. Additional RCODE Values Mnemonic Value Description ------------- ------- -------------------- EXTERR TBD Error RR(s) attached 6. Reserved Error Codes Range Mnemonic ValueRequired Name ----------- ------------------------------------------ 0..15 Existing RCODE Values NOERROR 0 (invalid value) FORMERR 1 Format Error SERVFAIL 2 Server Failure NXDOMAIN 3 Non-existent Domain NOTIMP 4 Function Not Implemented REFUSED 5 Action Refused YXDOMAIN 6 Name that ought not exist does exist XRRSET 7 RRset that ought not exist does exist XRRSET 8 RRset that ought to exist does not NOTAUTH 9 Server Not Authoritative for Zone NOTZONE 10 Name not in Zone EXTERR TBD (invalid value) 16-63 Reserved for RCODE Extension 64-4095 Error Message assigned by IANA 4096-8191 Information Message assigned by IANA 8192-16383 Error Message for Servers (IANA Blocks) 16384-32767 Information Message for Servers (IANA Blocks) 32768-65535 Private (for general undefined use) Values 16-63 are reserved for possible extension of the RCODE bit- range. In the event that it is determined that additional RCODE values are required, this bit space in an ERR RR could be used to extend the RCODE space. Values 64-4095 are reserved for use similar to existing RCODE values. They will be assigned by IANA, one per error, and have an associated mnemonic, as well as a registered required message text. Values 4096-8191 are reserved for informational messages optionally provided to clarify information from the server. For example, such a Watson [Page 6] Internet DRAFT Error Record for DNS 8 March 1998 message could be used to indicate the authentication status of a RR in a packet marked as containing unauthenticated data. Values 8192-16383 are reserved for allocation by IANA in blocks to specific server software. These values may be used for debugging the server software, or for communication between these servers in a non- standard manner. For example, error 8193 could be used by BIND to indicate a failure in a particular block of code when authenticating a request, and the text of the error message could identify the line of code and variable values. These values SHOULD be used for error messages. Values 16384-32767 are for information messages specific to server software, and allocated in blocks by IANA similar to the 8192-16383 range. Values 32767-65535 are reserved for private use. These values do not require allocation by IANA, but on receiving such a message from an unidentified server, no assumptions SHOULD be made as to meaning. 7. Referral Name Use in Existing RCODEs In many cases, the referral name is useful in clarifying existing RCODE responses. Mnemonic Use of Referral Name ----------- ----------------------------- NOERROR (invalid value) FORMERR (not useful) SERVFAIL Name of server not responding, if applicable NXDOMAIN Domain name not found (Type field if applicable) NOTIMP (not useful) REFUSED If a key error, the name of the key YXDOMAIN Domain name that was found (Type field if applicable) YXRRSET Domain name that was found NXRRSET Domain name that was not found NOTAUTH Zone name EXTERR (invalid value) Watson [Page 7] Internet DRAFT Error Record for DNS 8 March 1998 8. Security Considerations As with all DNS packet data, ERR RRs are subject to modification or spoofing if appropriate measures are not taken (such as DNSSEC SIG(0) or TSIG) to protect the data and transaction integrity. For the purposes of signature generation, ERR records should be treated as normal DNS data, and included in the signature. As a result, ERR records MUST NOT be added to packets that have already been signed, as this will cause packet verification to fail. ERR records MUST NOT be included in an RRset during DNSsec signature verification, as this dynamic data will not have been signed with the zone or dynamic update key. It is important that debugging information delivered to the client not be confidential, as no privacy protection is current defined for DNS. Some caution SHOULD be used in the logging and display of ERR error message text, as malicious entities might insert unreadable binary data or control codes, causing problems on terminal-oriented displays. Information messages MUST NOT be used by the server to determine the status of RRset authentication unless the transmission is protected by some authentication mechanism (such as TSIG or SIG(0)), and the information comes from a trusted host. 9. References [RFC1034] P. Mockapetris, "Domain Names - Concepts and Facilities", RFC 1034, ISI, November 1987. [RFC1035] P. Mockapetris, "Domain Names - Implementation and Specification," RFC 1034, ISI, November 1987. [RFC2065] D. Eastlake, C. Kaufman, "Domain System Security Extensions," RFC 2065, CyberCash & Irix, January 1997. [RFC2136] P. Vixie, S. Thomson, Y. Rekhter, J. Bound, "Dynamic Updates in the Domain Name System," RFC 2136, ISC, Bellcore, Cisco, DEC, April 1997. [RFC2137] D. Eastlake, "Secure Domain Name System Dynamic Update", RFC 2137, Cybercash, April 1997. [TSIG] P. Vixie, O. Gudmundsson, D. Eastlake, "Secret Key Transaction Signatures for DNS," Watson [Page 8] Internet DRAFT Error Record for DNS 8 March 1998 draft-ietf-dnsind-tsig-02, ISC, TIS, CyberCash, 10. Author's Addresses Robert Watson Olafur Gudmundsson 7100 Marbury Rd. Trusted Information Systems Bethesda, MD 20817 3060 Washington Road, Route 97 +1 301 229 2822 Glenwood, MD 21738 +1 301 854 6889 Watson [Page 9]