RFC 5284

User-Defined Errors for RSVP

📅 published August 2008, from ietf

User-Defined Errors for RSVP 💖

okay bestie, grab a drink because this RFC is about giving RSVP its own custom error messages 💅🦋

  • Number: RFC 5284 🎀
  • Category: Standards Track ✨
  • Date: August 2008 🌸
  • Network Working Group 🧚
  • Authors: G. Swallow (Cisco Systems, Inc.) and A. Farrel (Old Dog Consulting) 👑
  • Obsoletes / Updates: nothing listed in the title block 🙈

Status of This Memo ✨

this doc is an Internet standards track protocol for the Internet community 💜 it's also asking for discussion and suggestions for improvements, so talk to the group! 🫶 to check the current standardization state and status of this protocol, look at the current edition of the "Internet Official Protocol Standards" (STD 1) 📚 and yes, distribution of this memo is unlimited 🌈

Abstract 🦋

okay so RSVP has an ERROR_SPEC object for communicating errors 📨 and that object's format only has room for 256 error codes 😭 as RSVP has grown, the vibe has been to be super conservative about adding new error codes 🙈 and the ugly truth is RSVP has no way at all for users to define their own errors 💀

so this document defines a USER_ERROR_SPEC that gets used alongside the ERROR_SPEC to carry extra user info about errors ✨ it's giving "plus-one" energy 🔥

1. Introduction 🌸

ok so the Resource ReserVation Protocol (RSVP) [RFC2205] has that ERROR_SPEC object for communicating errors 📨 its defined format permits 256 error codes, and just like the Abstract said, RSVP has stayed conservative about communicating errors as it's been developed and extended 💅 and once again, RSVP has no provision for user defined errors. literally none 💀

when people are building extensions to RSVP, they often want to define their own error messages 🧚 those help a ton with the first round of debugging, and with testing against older versions or other implementations 🔍

so this doc defines a brand-new RSVP object that lets user-defined errors get communicated 🎀 organizations can use these errors for their internal development 🏢 and the error values can also be shared with the wider community to help different implementations play nicely together 🫶 interop bestie 💜

PathErr and ResvErr messages both need an ERROR_SPEC object ([RFC2205]) 📨 and [RFC3473] defines the Notify message, which also needs an ERROR_SPEC object 🦋 here's the clever part: to avoid changing the mandatory contents of those messages, this doc defines a new error code value. that value says "hey, the new object is here and it carries a user-defined error code" ✨ no structural drama, just a flag 🙌

one more thing 👀 the ResvConf message from [RFC2205] also carries an ERROR_SPEC object, BUT that usage doesn't carry meaningful Error Codes or Error Values. so the extensions in this doc don't apply to that message 🙅‍♀️ not that one, sorry ResvConf 💅

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] 📖 these are the official requirement words, so read them carefully bestie 🤓

2. User-Defined Error 💖

a new Error Code is defined for use in an ERROR_SPEC object ✨ here's the code and its value:

Error Code = 33: User Error Spec

this error code signals that a USER_ERROR_SPEC is present 🦋 one Error Value is defined:

Error Value 0 = Further details in User Error Spec

future specs may define more error values 🔮

okay the big rule for this section: when sending this error code, a USER_ERROR_SPEC object MUST be included in the PathErr, ResvErr, or Notify message 🚨 no skipping it, periodt 💅

3. USER_ERROR_SPEC Class 👑

a new RSVP object class called USER_ERROR_SPEC is defined 🎀 for backwards compatibility, its class number lives in the range 192-247 🌈 as [RFC2205] explains, implementations that don't understand this kind of object will forward it unmodified 💜 so older implementations won't break, they just pass it along like a good friend 🫶

here's the object's layout. the class is 194 and the C-Type is 1 🦋

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                   ~
   |                                                               |
   +---------------+---------------+---------------+---------------+

let's break down each field 🔍

Enterprise Number 🏢 this is a unique ID for an organization, stored as a 32-bit integer 🔢 these are assigned by IANA and handed out on a first come first served basis through the IANA registry called "Enterprise Numbers" [RFC2578] 📋

Sub Org 🧩 this is also a unique org ID, but it's an 8-bit integer ✨ an organization MAY use this field to make independent Error Value spaces 🦋 that's meant to help teams doing parallel development work without stepping on each other 👯‍♀️ if independent spaces aren't needed, this field SHOULD be set to zero 💅

Err Desc Len 📏 this is the length of the error description in the Error Description field, counted in bytes and NOT including any padding 🙅‍♀️ zero is a totally valid length if no description is supplied 🌸

User Error Value 🔢 a 16-bit integer 💜 its meaning is set by the (sub-)organization shown in the Enterprise Number and Sub Org fields 🫶

Error Description 📝 this is 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] 🚨 non-negotiable, bestie 💅 it's also RECOMMENDED that implementations keep their generated strings to single-line printable US-ASCII [ASCII] whenever that's doable 🎀 that helps the recipient actually read it easily ✨

if Err Desc Len is zero, then zero bytes are supplied 🫧

heads up though: the content of this field is implementation-specific 🙈 it's usually printable, but not every implementation shows it to every user (thanks, character set choices) 😭 so the content SHOULD be limited to supplementary info and SHOULD NOT hold anything critical for running the network 🚫 the critical stuff lives in the User Error Value field 💖

User-Defined Subobjects 🧚 user-defined subobjects MAY be included ✨ the generic format of subobjects is in Section 3.1 📐 a subobject's semantics are shown by its Type field, but the semantics, format, and contents of its Value field are set by the (sub-)organization shown in the Enterprise Number and Sub Org fields of this object 🦋

3.1. Subobjects 🧩

each subobject is a TLV (Type, Length, Value) in this format 📦

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

Type 🏷️ this is an 8-bit number assigned by the (sub-)organization shown in the Enterprise Number and Sub Org fields of the USER_ERROR_SPEC object 💜

Length 📏 this is the total length of the subobject in bytes, counting the Type and Length fields too 🔢 the Length MUST be at least 4 🚨 and it MUST also be a multiple of 4 💅 no sneaky lengths allowed, bestie 🙅‍♀️

6. Security Considerations 🔐

Okay so bestie, this section is the one you really need to read carefully 🥺✨ This document makes no changes to the basic message exchanges of [RFC2205] and [RFC3473]. The protocol flow stays exactly the same, no plot twists 💅 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. So the only real difference is that some errors that used to vanish into the void will now get sent out, which is lowkey iconic 🦋

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. So it's basically a way to say "hey, something sketchy is happening" 🚨👀

Heads up, bestie: a character string that gets displayed or logged opens the door to certain security attacks through overruns or embedded control characters 😭💀 Implementations SHOULD take precautions against overruns. Especially where the full character set of [RFC5198] is not supported, implementations SHOULD use the procedures set out in [RFC5137] to handle unexpected or unknown control characters 🫶

7. Acknowledgments 🌸

The authors would like to thank Elisheva Halevy for motivating this document 💖 Thanks also to Tom Nadeau, Magnus Westerlund, Hannes Tschofenig, Bruce Davie, Jukka Manner, Francois Le Faucheur, Lars Eggert, and Tom Petch for their review and comments 🧚✨

8. References 📚

8.1. Normative References

  • [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.

8.2. Informative References

  • [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.

Authors' Addresses 💌

  • George Swallow, Cisco Systems, Inc., EMail: swallow@cisco.com
  • Adrian Farrel, Old Dog Consulting, EMail: adrian@olddog.co.uk

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 ietf-ipr@ietf.org.

📦 where this page comes from