Network Working Group G. Swallow Request for Comments: 5284 Cisco Systems, Inc. Category: Standards Track A. Farrel Old Dog Consulting August 2008 User-Defined Errors for RSVP Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited.
AbstractThe 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. This document defines a USER_ERROR_SPEC to be used in addition to the ERROR_SPEC to carry additional user information related to errors. 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 that 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. Note that the ResvConf message defined in [RFC2205] also carries an ERROR_SPEC object. But this usage of the object does not carry meaningful Error Codes or Error Values and so the extensions defined in this document are not applicable to that message. RFC2119]. RFC2205], implementations that do not understand such an object will forward it unmodified. USER_ERROR_SPEC object: Class = 194, C-Type = 1
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 (sometimes known as Private Enterprise Numbers) are assigned by IANA and managed on a first come first served basis through the IANA registry named "Enterprise Numbers" [RFC2578]. 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 that 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. Zero is a valid length if no error description is supplied. User Error Value A 16-bit integer. The meaning is specified by the (sub-)organization indicated by the Enterprise Number and Sub Org fields.
Error Description A string of characters padded with nulls (0x00) to a multiple of 4 bytes. According to the guidance in [RFC2277], this string MUST use UTF-8/Net-Unicode encoding [RFC5198]. Furthermore, it is RECOMMENDED that implementations limit the strings that they generate to single-line printable US-ASCII [ASCII] whenever feasible to improve the likelihood of easy use by the recipient. If the Err Desc Len is zero, then no bytes are supplied. Note that the content of this field is implementation-specific. It is typically printable, but might not be shown to all users in all implementations (because of character set choice). Therefore, the content of the field SHOULD be limited to supplementary information and SHOULD NOT contain information critical to operating the network. Critical information is present in the User Error Value field. 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.
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. 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. When the Error Code in the ERROR_SPEC object is set to "User Error Spec", the Error Value sub-code SHOULD be set to "Further details in User Error Spec" as defined in Section 2, but further Error Value sub-codes may be defined in future specifications. RFC5137]. 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 MUST be treated as malformed and handled according to [RFC2205].
Implementations SHOULD ignore repeated occurrences of USER_ERROR_SPEC objects, and SHOULD forward them unchanged on any messages that they forward. This provides for forward compatibility. Implementations receiving a USER_ERROR_SPEC object on some message other than a PathErr, ResvErr, or Notify message MUST treat the error as a malformed message and process according to [RFC2205]. 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.
Note that the use of a character string that will be displayed or logged opens the potential for certain security attacks through the use of overruns or embedded control characters. Implementations SHOULD take precautions against overruns, and (especially where the full character set of [RFC5198] is not supported, SHOULD use the procedures set out in [RFC5137] to handle unexpected or unknown control characters. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2205] Braden, R., Ed., Zhang, L., Berson, S., Herzog, S., and S. Jamin, "Resource ReSerVation Protocol (RSVP) -- Version 1 Functional Specification", RFC 2205, September 1997. [RFC3473] Berger, L., Ed., "Generalized Multi-Protocol Label Switching (GMPLS) Signaling Resource ReserVation Protocol-Traffic Engineering (RSVP-TE) Extensions", RFC 3473, January 2003. [RFC5137] Klensin, J., "ASCII Escaping of Unicode Characters", BCP 137, RFC 5137, February 2008. [RFC5198] Klensin, J. and M. Padlipsky, "Unicode Format for Network Interchange", RFC 5198, March 2008. [ASCII] American National Standards Institute, "USA Code for Information Interchange", ANSI X3.4, 1968. [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, January 1998. [RFC2578] McCloghrie, K., Perkins, D., and J. Schoenwaelder, "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999.
Full Copyright Statement Copyright (C) The IETF Trust (2008). 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. 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 email@example.com.