Internet Engineering Task Force SIP WG
Internet Draft Schulzrinne/Oran/Camarillo
draft-schulzrinne-sip-reason-00.txt Columbia U./Cisco/Ericsson
December 17, 2001
Expires: May, 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.
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.
Schulzrinne/Oran/Camarillo [Page 1]
Internet Draft SIP December 17, 2001
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 methods, but it is defined that it can
appear in any method.
Clients 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 request header field can appear in any method.
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 protocol
protocol = quoted-string
protocol-cause = "cause" EQUAL cause
cause = 1*DIGIT
reason-text = "text" EQUAL text
text = *<TEXT-UTF8, excluding CR, CF>
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"
Schulzrinne/Oran/Camarillo [Page 2]
Internet Draft SIP December 17, 2001
The syntax of the header field follows the standard SIP parameter
syntax.
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; 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.
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 gibt nach 30 Sekunden auf"
The following values for the triggered parameter have been defined:
1. SIP/2.0: The cause parameter contains a SIP status code.
2. Q.850: It refers to the ITU-T Q.850 recommendation. The
cause parameter contains a Q.850 cause value (decimal
representation).
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.
Schulzrinne/Oran/Camarillo [Page 3]
Internet Draft SIP December 17, 2001
3 IANA Considerations
IANA registers new reason codes. All new reason codes MUST be defined
in an RFC.
IANA registers new values for the triggered parameter.
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
We wish to thank Jonathan Rosenberg for his comments and suggestions.
6 Authors' Addresses
Henning Schulzrinne
Dept. of Computer Science
Columbia University
1214 Amsterdam Avenue
New York, NY 10027
USA
electronic mail: schulzrinne@cs.columbia.edu
Dave Oran
Cisco
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.
Schulzrinne/Oran/Camarillo [Page 4]
Internet Draft SIP December 17, 2001
Full Copyright Statement
Copyright (c) The Internet Society (2001). 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.
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.
Schulzrinne/Oran/Camarillo [Page 5]