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
      <robert+ietf@cyrus.watson.org>  +1 301 854 6889
                                      <ogud@tis.com>









































Watson                                                          [Page 9]