Network Working Group                                         G. Swallow
Internet-Draft                                       Cisco Systems, Inc.
Category: Standards Track
Created: October 6, 2007                                       A. Farrel
Expiration Date: April 6, 2007                        Old Dog Consulting




                      User-Defined Errors for RSVP


              draft-ietf-tsvwg-rsvp-user-error-spec-02.txt


Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.

   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."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.


Abstract

   The Resource ReserVation Protocol (RSVP) defines an ERROR_SPEC object
   for communicating errors.  That object has a defined format that
   permits the definition of 256 error codes.  As RSVP has been
   developed and extended, the convention has been to be conservative in
   defining new error codes.  Further, no provision for user-defined
   errors exists in RSVP.




Swallow & Farrel             Standards Track                    [Page 1]


draft-ietf-tsvwg-rsvp-user-error-spec-02.txt                October 2007


Contents

 1      Introduction  ..............................................   3
 1.1    Conventions  ...............................................   3
 2      User-Defined Error  ........................................   3
 3      USER_ERROR_SPEC Class  .....................................   4
 3.1    Subobjects  ................................................   5
 4      Procedures for Using the User Error Spec  ..................   6
 4.1    Procedures for Sending the User Error Spec  ................   6
 4.2    Procedures for Receiving the User Error Spec  ..............   6
 5      IANA Considerations  .......................................   6
 6      Security Considerations  ...................................   7
 7      Acknowledgments  ...........................................   7
 8      Normative References  ......................................   7
 9      Authors' Addresses  ........................................   8



0. Changes Since Last Revision

[This section to be removed before publication as an RFC.]

   - Use explicit tags for values to be supplied by IANA.
     Sections 2, 3 and 5.

   - Definition of Length field mentioned non-existent L field.
     Section 3.1.























Swallow & Farrel             Standards Track                    [Page 2]


draft-ietf-tsvwg-rsvp-user-error-spec-02.txt                October 2007


1. Introduction

   The Resource ReserVation Protocol (RSVP) [RFC2205] defines an
   ERROR_SPEC object for communicating errors.  That object has a
   defined format that permits the definition of 256 error codes.  As
   RSVP has been developed and extended, the convention has been to be
   conservative in communicating errors.  Further no provision for user
   defined errors exists in RSVP.

   When developing extensions to RSVP, it is often useful for those
   implementing to define error messages to aid both in the initial
   debugging and in testing against older versions or other
   implementations.

   This document defines a new RSVP object to permit user-defined errors
   to be communicated.  This will enable organizations to define errors
   which they can use for internal development.  These error values
   could also be shared with the community at large to aid in promoting
   interoperability between diverse implementations.

   RSVP PathErr and ResvErr messages require the presence of an
   ERROR_SPEC object ([RFC2205]).  [RFC3473] defines the Notify message
   that also requires the presence of an ERROR_SPEC object.  In order to
   not change the mandatory contents of these messages, this document
   defines a new error code value that indicates that the new object is
   present and carries a user-defined error code.

1.1. Conventions

   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 [RFC2119].


2. User-Defined Error

   A new Error Code is defined for use in an ERROR_SPEC object.

      Error Code = <tba-xxx>: User Error Spec

      This error code is used to signal the presence of a
      USER_ERROR_SPEC.  No subcodes are defined.

   When sending this error code, a USER_ERROR_SPEC object MUST be
   included in the PathErr, ResvErr, or Notify message.

[RFC Editor's note: <tba-xxx> = to be assigned by IANA as per Section 5.
 Please replace <tba-xxx> with the number assigned by IANA and remove
 this note.]

Swallow & Farrel             Standards Track                    [Page 3]


draft-ietf-tsvwg-rsvp-user-error-spec-02.txt                October 2007


3. USER_ERROR_SPEC Class

   A new RSVP object class is defined called the the USER_ERROR_SPEC
   Class.  The class number is taken from the range 192 - 247.  This is
   done for backward compatibility.  Existing implementations will
   ignore the object and pass it along according to the rules of
   [RFC2205].

   USER_ERROR_SPEC object: Class = <tba-yyy>, C-Type = 1

[RFC Editor's note: <tba-yyy> = to be assigned by IANA as per Section 5.
 Please replace <tba-yyy> with the number assigned by IANA and remove
 this note.]

      0                   1                   2                   3
      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
     +---------------+---------------+---------------+---------------+
     |                       Enterprise Number                       |
     +---------------+---------------+---------------+---------------+
     |    Sub Org    |  Err Desc Len |        User Error Value       |
     +---------------+---------------+---------------+---------------+
     |                                                               |
     ~                       Error Description                       ~
     |                                                               |
     +---------------+---------------+---------------+---------------+
     |                                                               |
     ~                     User-Defined Subobjects                   ~
     |                                                               |
     +---------------+---------------+---------------+---------------+

     Enterprise Number

        A unique identifier of an organization encoded as a 32-bit
        integer.  Enterprise Numbers are assigned by IANA.

     Sub Org

        A unique identifier of an organization encoded as an 8-bit
        integer.  An organization MAY use this field to create
        independent Error Value spaces.  This is intended to
        facilitate teams which are doing parallel development.  If
        independent spaces are not required, this field SHOULD be
        set to zero.

     Err Desc Len

        The length of the error description in the Error Description
        field in bytes excluding any padding.


Swallow & Farrel             Standards Track                    [Page 4]


draft-ietf-tsvwg-rsvp-user-error-spec-02.txt                October 2007


     User Error Value

        A 16-bit integer. The format and contents are specified by
        the (sub-)organization indicated by the Enterprise Number
        and Sub Org fields.

     Error Description

        A string of characters in US-ASCII padded with nulls (0x00)
        to a multiple of 4 bytes.  While no format is required, it
        is RECOMMENDED that organizations use a published schema for
        this string to promote consistent decoding.

     User-Defined Subobjects

        User-defined subobjects MAY be included.  The generic format of
        subobjects is specified in Section 3.1.  The semantics of a
        subobject is indicated by the Type field, but the semantics,
        format and contents of the Value field are specified by the
        (sub-)organization indicated by the Enterprise Number and
        Sub Org fields of this object.

3.1. Subobjects

      Each subobject is encoded as a TLV in the following format:

      0                   1
      0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-------------//----------------+
     |     Type      |     Length    | (Subobject contents)          |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-------------//----------------+

     Type

        An 8-bit number assigned by the the (sub-)organization
        indicated by the Enterprise Number and Sub Org fields of the
        USER_ERROR_SPEC object.

     Length

        The Length contains the total length of the subobject in bytes,
        including the Type and Length fields.  The Length MUST be at
        least 4, and MUST be a multiple of 4.







Swallow & Farrel             Standards Track                    [Page 5]


draft-ietf-tsvwg-rsvp-user-error-spec-02.txt                October 2007


4. Procedures for Using the User Error Spec

4.1. Procedures for Sending the User Error Spec

   A USER_ERROR_SPEC object MAY be included in any PathErr, ResvErr, or
   Notify message for any defined error code.  The Enterprise Number
   MUST be a valid value assigned by IANA.

   As specified in [RFC2205] and [RFC3473], an ERROR_SPEC object with a
   valid error code MUST be included in all PathErr, ResvErr, and Notify
   messages.  This rule is not changed by these procedures even when a
   USER_ERROR_SPEC object is included.  If no other error code applies,
   the Error Code in the ERROR_SPEC object MUST be set to "User Error
   Spec" as defined in Section 2 of this document.


4.2. Procedures for Receiving the User Error Spec

   It is RECOMMENDED that implementations that receive a PathErr,
   ResvErr, or Notify message carrying a USER_ERROR_SPEC object at a
   minimum log the Enterprise Number, Sub-organization, User Error
   Value, and Error Description.  Implementation capable of interpreting
   the contents of the USER_ERROR_SPEC object SHOULD take appropriate
   action.

   If a message is received containing an ERROR_SPEC object using the
   "User Error Spec" error code, but not containing a USER_ERROR_SPEC
   object, the message SHOULD be treated as malformed and handled
   according to [RFC2205].

   Implementations SHOULD ignore repeated occurences of USER_ERROR_SPEC
   objects, and SHOULD forward them unchanged on any messages that they
   forward.

   Implementations receiving a USER_ERROR_SPEC object on some message
   other than a PathErr, ResvErr, or Notify message SHOULD treat the
   error as a malformed message and process according to [RFC2205].


5. IANA Considerations

   This document makes the following assignments from the RSVP Error
   Codes and Globally-Defined Error Value Sub-Codes registry (pending
   IANA action):

        Value           Name

        <tba-xxx>       User Error Spec


Swallow & Farrel             Standards Track                    [Page 6]


draft-ietf-tsvwg-rsvp-user-error-spec-02.txt                October 2007

   This document makes the following assignments from the RSVP Class
   Names, Class Numbers, and Class Types registry (pending IANA action):

       Number Space     Value       Name

       Class Numbers    <tba-yyy>*  User Error Spec

       Class Type         1         User-Defined Error

   * Assignment is requested from the range 192 through 247


6. Security Considerations

   This document makes no changes to the basic message exchanges of
   [RFC2205] and [RFC3473].  It will result in a small increase in the
   number of error messages sent in cases where messages were previously
   silently dropped due to the lack of an appropriate error code.

   The mechanisms defined in this document may be used by
   implementations to report additional error conditions and information
   arising from security issues and attacks on the RSVP network.


7. Acknowledgments

   The authors would like to thank Elisheva Halevy for motivating this
   document, and Tom Nadeau, and Magnus Westerlund for their review and
   comments.


8. Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2205]  Braden, R., Zhang, L., Berson, S., Herzog, S., and S.
              Jamin, "Resource ReSerVation Protocol (RSVP) -- Version 1
              Functional Specification", RFC 2205, September 1997.

   [RFC3473]  Berger, L., "Generalized Multi-Protocol Label Switching
              (GMPLS) Signaling Resource ReserVation Protocol-Traffic
              Engineering (RSVP-TE) Extensions", RFC 3473, January 2003.








Swallow & Farrel             Standards Track                    [Page 7]


draft-ietf-tsvwg-rsvp-user-error-spec-02.txt                October 2007


9. Authors' Addresses

      George Swallow
      Cisco Systems, Inc.
      EMail: swallow@cisco.com


      Adrian Farrel
      Old Dog Consulting
      EMail: adrian@olddog.co.uk


Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at ietf-
   ipr@ietf.org.

Full Copyright Notice

   Copyright (C) The IETF Trust (2007).  This document is subject to the
   rights, licenses and restrictions contained in BCP 78, and except as
   set forth therein, the authors retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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.

Swallow & Farrel             Standards Track                    [Page 8]