Internet Engineering Task Force SIP WG Internet Draft H. Schulzrinne Columbia University D. Oran Cisco G. Camarillo Ericsson draft-schulzrinne-sip-reason-01.txt February 28, 2002 Expires: August 2002 The Reason Header Field for the Session Initiation Protocol STATUS OF THIS MEMO This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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 To view the list Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html. Abstract For creating services, it is often useful to know why a SIP request was issued. This document defines an optional informational header field, Reason, that provides this information. H. Schulzrinne et. al. [Page 1] Internet Draft SIP February 28, 2002 Table of Contents 1 Introduction ........................................ 3 1.1 Terminology ......................................... 3 2 The Reason Request Header Field ..................... 3 3 IANA Considerations ................................. 5 4 Security Considerations ............................. 5 5 Acknowledgments ..................................... 5 6 Authors' Addresses .................................. 5 7 Bibliography ........................................ 6 H. Schulzrinne et. al. [Page 2] Internet Draft SIP February 28, 2002 1 Introduction The same SIP [1] request can be issued for a variety of reasons. For example, a SIP CANCEL request can be issued if the call has completed on another branch or was abandoned before answer. While the protocol and system behavior is the same in both cases, namely, alerting will cease, the user interface may well differ. In the second case, the call may be logged as a missed call, while this would not be appropriate if the call was picked up elsewhere. Third party call controllers sometimes generate a SIP request upon reception of a SIP response from another dialog. Gateways generate SIP requests after receiving messages from a different protocol than SIP. In both cases the client may be interested in knowing what triggered the SIP request. SIP responses already have a means of informing the user of why a request failed. The simple mechanism in this draft accomplishes something roughly similar for requests. Initially, the request header field defined here appears to be most useful for BYE and CANCEL requests, but it can appear in any requests and in any response. Clients and servers are free to ignore this header. It has no impact on protocol processing. 1.1 Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [2] and indicate requirement levels for compliant SIP implementations. 2 The Reason Request Header Field The Reason header field can appear in any request or response. The syntax of the header field follows the standard SIP parameter syntax. Reason = "Reason" HCOLON reason-code *(SEMI reason-params) reason-code = 1*DIGIT reason-params = triggered-by | protocol-cause | reason-text | reason-extension triggered-by = "triggered" EQUAL quoted-string protocol-cause = "cause" EQUAL cause cause = 1*DIGIT H. Schulzrinne et. al. [Page 3] Internet Draft SIP February 28, 2002 reason-text = "text" EQUAL quoted-string reason-extension = generic-param Examples are: Reason: 1 ;text="Call completed elsewhere" Reason: 4 ;triggered="Q.850" ;cause=16 ;text="Terminated" Reason: 7 ;triggered="SIP/2.0" ;cause=600 ;text="Busy Everywhere" Reason: 8 ;triggered="SIP/2.0" ;cause=580 ;text="Precondition Failure" The following reason codes and text phrases have been defined: 1. (Call completed elsewhere): CANCEL request; another branch completed the call. 2. (Abandoned): CANCEL request; the call attempt was abandoned. 3. (Timed out): CANCEL request; the call attempt timed out. 4. (Terminated): BYE request; the caller or callee terminated the call. 5. (Transfer completed): BYE request; the call transfer was completed. 6. (No media): BYE request; the call was terminated since the other side did not receive media for an extended period of time. 7. (Interworking): BYE and CANCEL requests and any final response; the call was terminated because a gateway or a third party call controller received an error or a release message from the other side. This reason code SHOULD only be used if none of the other reason codes is applicable. 8. (Offer refused): BYE and CANCEL request; an offer that the client wanted to refuse was received in a response. The user agent client terminates the session. 9. (Update requested): 155 response; the Reason header field contains the status code of the final response that triggered the 155 response. H. Schulzrinne et. al. [Page 4] Internet Draft SIP February 28, 2002 The text phrase MAY be modified, e.g., translated into different languages or enhanced with additional call-specific information, for example, Reason: 2 ;text="Anrufer gab nach 30 Sekunden auf" The following values for the triggered parameter have been defined: SIP/2.0: The cause parameter contains a SIP status code. Q.850: The cause parameter contains an ITU-T Q.850 cause value in decimal representation. The default value is "SIP/2.0". Proxies generating a CANCEL request upon reception of a CANCEL from the previous hop that contains a Reason header field SHOULD copy it into the new CANCEL request. 3 IANA Considerations IANA registers new reason codes. All new reason codes MUST be defined in an RFC. IANA also registers new values for the triggered parameter. These values MUST refer to either an ITU-T Recommendation number, an IETF protocol name or the recognized protocol identifier from another standardization organization. 4 Security Considerations While spoofing or removing the Reason header field has no impact on protocol operation, the user interface may change and end systems may provide services based on this header field. Thus, it is RECOMMENDED that this field is protected by a suitable integrity mechanism. 5 Acknowledgments Jonathan Rosenberg provided helpful comments and suggestions. 6 Authors' Addresses Henning Schulzrinne Dept. of Computer Science Columbia University 1214 Amsterdam Avenue H. Schulzrinne et. al. [Page 5] Internet Draft SIP February 28, 2002 New York, NY 10027 USA electronic mail: schulzrinne@cs.columbia.edu David R. Oran Cisco Systems, Inc. Acton, MA USA electronic mail: oran@cisco.com Gonzalo Camarillo Ericsson Advanced Signalling Research Lab. FIN-02420 Jorvas Finland electronic mail: Gonzalo.Camarillo@ericsson.com 7 Bibliography [1] M. Handley, H. Schulzrinne, E. Schooler, and J. Rosenberg, "SIP: session initiation protocol," Request for Comments 2543, Internet Engineering Task Force, Mar. 1999. [2] S. Bradner, "Key words for use in RFCs to indicate requirement levels," Request for Comments 2119, Internet Engineering Task Force, Mar. 1997. Full Copyright Statement Copyright (c) The Internet Society (2002). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. H. Schulzrinne et. al. [Page 6] Internet Draft SIP February 28, 2002 This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS 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. H. Schulzrinne et. al. [Page 7]