idnits 2.17.1 draft-ietf-tsvwg-rsvp-user-error-spec-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 17. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 395. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 368. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 375. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 381. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'ASCII' Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group G. Swallow 3 Internet-Draft Cisco Systems, Inc. 4 Category: Standards Track 5 Created: May 31, 2008 A. Farrel 6 Expiration Date: November 31, 2008 Old Dog Consulting 8 User-Defined Errors for RSVP 10 draft-ietf-tsvwg-rsvp-user-error-spec-08.txt 12 Status of this Memo 14 By submitting this Internet-Draft, each author represents that any 15 applicable patent or other IPR claims of which he or she is aware 16 have been or will be disclosed, and any of which he or she becomes 17 aware will be disclosed, in accordance with Section 6 of BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 Abstract 37 The Resource ReserVation Protocol (RSVP) defines an ERROR_SPEC object 38 for communicating errors. That object has a defined format that 39 permits the definition of 256 error codes. As RSVP has been 40 developed and extended, the convention has been to be conservative in 41 defining new error codes. Further, no provision for user-defined 42 errors exists in RSVP. 44 This document defines a USER_ERROR_SPEC to be used in addition to the 45 ERROR_SPEC to carry additional user information related to errors. 47 1. Introduction 49 The Resource ReserVation Protocol (RSVP) [RFC2205] defines an 50 ERROR_SPEC object for communicating errors. That object has a 51 defined format that permits the definition of 256 error codes. As 52 RSVP has been developed and extended, the convention has been to be 53 conservative in communicating errors. Further no provision for user 54 defined errors exists in RSVP. 56 When developing extensions to RSVP, it is often useful for those 57 implementing to define error messages to aid both in the initial 58 debugging and in testing against older versions or other 59 implementations. 61 This document defines a new RSVP object to permit user-defined errors 62 to be communicated. This will enable organizations to define errors 63 which they can use for internal development. These error values 64 could also be shared with the community at large to aid in promoting 65 interoperability between diverse implementations. 67 RSVP PathErr and ResvErr messages require the presence of an 68 ERROR_SPEC object ([RFC2205]). [RFC3473] defines the Notify message 69 that also requires the presence of an ERROR_SPEC object. In order to 70 not change the mandatory contents of these messages, this document 71 defines a new error code value that indicates that the new object is 72 present and carries a user-defined error code. 74 Note that the ResvConf message defined in [RFC2205] also carries an 75 ERROR_SPEC object. But this usage of the object does not carry 76 meaningful Error Codes or Error Values and so the extensions defined 77 in this document are not applicable to that message. 79 1.1. Conventions 81 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 82 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 83 document are to be interpreted as described in RFC 2119 [RFC2119]. 85 2. User-Defined Error 87 A new Error Code is defined for use in an ERROR_SPEC object. 89 Error Code = : User Error Spec 91 This error code is used to signal the presence of a 92 USER_ERROR_SPEC. One Error Value is defined as follows. 94 Error Value 0 = Further details in User Error Spec 96 Further error values may be defined in future specifications. 98 When sending this error code, a USER_ERROR_SPEC object MUST be 99 included in the PathErr, ResvErr, or Notify message. 101 [RFC Editor's note: = to be assigned by IANA as per Section 5. 102 Please replace with the number assigned by IANA and remove 103 this note.] 105 3. USER_ERROR_SPEC Class 107 A new RSVP object class called USER_ERROR_SPEC is defined. To support 108 backwards compatibility, its class number is in the range 192-247. As 109 defined in [RFC2205], implementations that do not understand such an 110 object will forward it unmodified. 112 USER_ERROR_SPEC object: Class = , C-Type = 1 114 [RFC Editor's note: = to be assigned by IANA as per Section 5. 115 Please replace with the number assigned by IANA and remove 116 this note.] 118 0 1 2 3 119 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 120 +---------------+---------------+---------------+---------------+ 121 | Enterprise Number | 122 +---------------+---------------+---------------+---------------+ 123 | Sub Org | Err Desc Len | User Error Value | 124 +---------------+---------------+---------------+---------------+ 125 | | 126 ~ Error Description ~ 127 | | 128 +---------------+---------------+---------------+---------------+ 129 | | 130 ~ User-Defined Subobjects ~ 131 | | 132 +---------------+---------------+---------------+---------------+ 133 Enterprise Number 135 A unique identifier of an organization encoded as a 32-bit 136 integer. Enterprise Numbers (sometimes known as Private 137 Enterprise Numbers) are assigned by IANA and managed on a first 138 come first served basis through the IANA registry named 139 "Enterprise Numbers" [RFC2578]. 141 Sub Org 143 A unique identifier of an organization encoded as an 8-bit 144 integer. An organization MAY use this field to create 145 independent Error Value spaces. This is intended to 146 facilitate teams which are doing parallel development. If 147 independent spaces are not required, this field SHOULD be 148 set to zero. 150 Err Desc Len 152 The length of the error description in the Error Description 153 field in bytes excluding any padding. Zero is a valid length if 154 no error description is supplied. 156 User Error Value 158 A 16-bit integer. The meaning is specified by the 159 (sub-)organization indicated by the Enterprise Number and Sub 160 Org fields. 162 Error Description 164 A string of characters padded with nulls (0x00) to a multiple of 165 4 bytes. According to the guidance in [RFC2277], this string 166 MUST use UTF-8/Net-Unicode encoding [RFC5198]. Furthermore, it 167 is RECOMMENDED that implementations limit the strngs that they 168 generate to single-line printable US-ASCII [ASCII] whenever 169 feasible to improve the likelihood of easy use by the recipient. 171 If the Err Desc Len is zero then no bytes are supplied. 173 Note that the content of this field is implementation-specific. 174 It is typically printable, but might not be shown to all users 175 in all implementations (because of character set choice). 176 Therefore, the content of the field SHOULD be limited to 177 supplementary information and SHOULD NOT contain information 178 critical to operating the network. Criticial information is 179 present in the User Error Value field. 181 User-Defined Subobjects 183 User-defined subobjects MAY be included. The generic format of 184 subobjects is specified in Section 3.1. The semantics of a 185 subobject is indicated by the Type field, but the semantics, 186 format and contents of the Value field are specified by the 187 (sub-)organization indicated by the Enterprise Number and 188 Sub Org fields of this object. 190 3.1. Subobjects 192 Each subobject is encoded as a TLV in the following format: 194 0 1 195 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 196 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-------------//----------------+ 197 | Type | Length | (Subobject contents) | 198 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-------------//----------------+ 200 Type 202 An 8-bit number assigned by the the (sub-)organization 203 indicated by the Enterprise Number and Sub Org fields of the 204 USER_ERROR_SPEC object. 206 Length 208 The Length contains the total length of the subobject in bytes, 209 including the Type and Length fields. The Length MUST be at 210 least 4, and MUST be a multiple of 4. 212 4. Procedures for Using the User Error Spec 214 4.1. Procedures for Sending the User Error Spec 216 A USER_ERROR_SPEC object MAY be included in any PathErr, ResvErr, or 217 Notify message for any defined error code. The Enterprise Number 218 MUST be a valid value assigned by IANA from the "Enterprise Numbers" 219 registry. 221 As specified in [RFC2205] and [RFC3473], an ERROR_SPEC object with a 222 valid error code MUST be included in all PathErr, ResvErr, and Notify 223 messages. This rule is not changed by these procedures even when a 224 USER_ERROR_SPEC object is included. If no other error code applies, 225 the Error Code in the ERROR_SPEC object MUST be set to "User Error 226 Spec" as defined in Section 2 of this document. When the Error Code 227 in the ERROR_SPEC object is set to "User Error Spec", the Error Value 228 sub-code SHOULD be set to "Further details in User Error Spec" as 229 defined in Section 2, but further Error Value sub-codes may be 230 defined in future specifications. 232 4.2. Procedures for Receiving the User Error Spec 234 It is RECOMMENDED that implementations that receive a PathErr, 235 ResvErr, or Notify message carrying a USER_ERROR_SPEC object at a 236 minimum log the Enterprise Number, Sub-organization, User Error 237 Value, and Error Description. Note that the character set used for 238 the Error Description may mean that it might not be suitable for 239 display of logging in all systems. Implementations capable of 240 interpreting the contents of the USER_ERROR_SPEC object SHOULD take 241 further action based on the reported error. 243 Implementations that are not UTF-8 capable that receive a 244 USER_ERROR_SPEC object SHOULD handle the Error Descriprion according 245 to the procedures set out in [RFC5137]. 247 If a message is received containing an ERROR_SPEC object using the 248 "User Error Spec" error code, but not containing a USER_ERROR_SPEC 249 object, the message MUST be treated as malformed and handled 250 according to [RFC2205]. 252 Implementations SHOULD ignore repeated occurences of USER_ERROR_SPEC 253 objects, and SHOULD forward them unchanged on any messages that they 254 forward. This provides for forward compatiblity. 256 Implementations receiving a USER_ERROR_SPEC object on some message 257 other than a PathErr, ResvErr, or Notify message MUST treat the 258 error as a malformed message and process according to [RFC2205]. 260 5. IANA Considerations 262 5.1. RSVP Error Codes 264 This document makes the following assignments from the RSVP Error 265 Codes and Globally-Defined Error Value Sub-Codes registry (pending 266 IANA action): 268 Error Code Meaning 270 User Error Spec 272 One Error Value sub-code is defined for use with this Error Code as 273 follows: 275 0 = Further details in User Error Spec 277 5.2. RSVP Objects 279 This document makes the following assignments from the RSVP Class 280 Names, Class Numbers, and Class Types registry (pending IANA action): 282 Number Space Value Name 284 Class Numbers * User Error Spec 286 Class Type 1 User-Defined Error 288 * Assignment is requested from the range 192 through 247 290 6. Security Considerations 292 This document makes no changes to the basic message exchanges of 293 [RFC2205] and [RFC3473]. It will result in a small increase in the 294 number of error messages sent in cases where messages were previously 295 silently dropped due to the lack of an appropriate error code. 297 The mechanisms defined in this document may be used by 298 implementations to report additional error conditions and information 299 arising from security issues and attacks on the RSVP network. 301 Note that the use of a character string that will be displayed or 302 logged opens the potential for certain security attacks through the 303 use of overruns or embedded control characters. Implementations 304 SHOULD take precautions against overruns, and (especially where the 305 full characterset of [RFC5198] is not supported, SHOULD use the 306 procedures set out in [RFC5137] to handle unexpected or unknown 307 control characters. 309 7. Acknowledgments 311 The authors would like to thank Elisheva Halevy for motivating this 312 document. Thanks to Tom Nadeau, Magnus Westerlund, Hannes Tschofenig, 313 Bruce Davie, Jukka Manner, Francois Le Faucheur, Lars Eggert, and Tom 314 Petch for their review and comments. 316 8. References 318 8.1. Normative References 320 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 321 Requirement Levels", BCP 14, RFC 2119, March 1997. 323 [RFC2205] Braden, R., Zhang, L., Berson, S., Herzog, S., and S. 324 Jamin, "Resource ReSerVation Protocol (RSVP) -- Version 1 325 Functional Specification", RFC 2205, September 1997. 327 [RFC3473] Berger, L., "Generalized Multi-Protocol Label Switching 328 (GMPLS) Signaling Resource ReserVation Protocol-Traffic 329 Engineering (RSVP-TE) Extensions", RFC 3473, January 2003. 331 [RFC5137] Klensin, J., "ASCII Escaping of Unicode Characters", 332 RFC 5137, BCP 137, February 2008. 334 [RFC5198] Klensin, J., and Padlipsky, M., "Unicode Format for 335 Network Interchange", RFC 5198, March 2008. 337 [ASCII] American National Standards Institute, "USA Code for 338 Information Interchange", ANSI X3.4, 1968. 340 8.2. Informative References 342 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 343 Languages", RFC 2277, BCP 18, January 1998. 345 [RFC2578] McCloghrie, K., Perkins, D., and J. Schoenwaelder, 346 "Structure of Management Information Version 2 (SMIv2)", 347 STD 58, RFC 2578, April 1999. 349 9. Authors' Addresses 351 George Swallow 352 Cisco Systems, Inc. 353 EMail: swallow@cisco.com 355 Adrian Farrel 356 Old Dog Consulting 357 EMail: adrian@olddog.co.uk 359 10. Intellectual Property 361 The IETF takes no position regarding the validity or scope of any 362 Intellectual Property Rights or other rights that might be claimed to 363 pertain to the implementation or use of the technology described in 364 this document or the extent to which any license under such rights 365 might or might not be available; nor does it represent that it has 366 made any independent effort to identify any such rights. Information 367 on the procedures with respect to rights in RFC documents can be 368 found in BCP 78 and BCP 79. 370 Copies of IPR disclosures made to the IETF Secretariat and any 371 assurances of licenses to be made available, or the result of an 372 attempt made to obtain a general license or permission for the use of 373 such proprietary rights by implementers or users of this 374 specification can be obtained from the IETF on-line IPR repository at 375 http://www.ietf.org/ipr. 377 The IETF invites any interested party to bring to its attention any 378 copyrights, patents or patent applications, or other proprietary 379 rights that may cover technology that may be required to implement 380 this standard. Please address the information to the IETF at ietf- 381 ipr@ietf.org. 383 Full Copyright Notice 385 Copyright (C) The IETF Trust (2008). This document is subject to the 386 rights, licenses and restrictions contained in BCP 78, and except as 387 set forth therein, the authors retain all their rights. 389 This document and the information contained herein are provided on an 390 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 391 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 392 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 393 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 394 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 395 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.