summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc3326.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc3326.txt')
-rw-r--r--doc/rfc/rfc3326.txt451
1 files changed, 451 insertions, 0 deletions
diff --git a/doc/rfc/rfc3326.txt b/doc/rfc/rfc3326.txt
new file mode 100644
index 0000000..322b516
--- /dev/null
+++ b/doc/rfc/rfc3326.txt
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+Network Working Group H. Schulzrinne
+Request for Comments: 3326 Columbia University
+Category: Standards Track D. Oran
+ Cisco
+ G. Camarillo
+ Ericsson
+ December 2002
+
+
+ The Reason Header Field for the Session Initiation Protocol (SIP)
+
+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.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+Abstract
+
+ For creating services, it is often useful to know why a Session
+ Initiation Protocol (SIP) request was issued. This document defines
+ a header field, Reason, that provides this information. The Reason
+ header field is also intended to be used to encapsulate a final
+ status code in a provisional response. This functionality is needed
+ to resolve the "Heterogeneous Error Response Forking Problem", or
+ HERFP.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Schulzrinne, et. al. Standards Track [Page 1]
+
+RFC 3326 The Reason Header Field for SIP December 2002
+
+
+Table of Contents
+
+ 1. Introduction ............................................... 2
+ 1.1. Terminology ................................................ 3
+ 2. The Reason Request Header Field ............................ 3
+ 3. Examples ................................................... 4
+ 3.1. Call Completed Elsewhere ................................... 4
+ 3.2. Refusing an Offer that Comes in a Response ................. 4
+ 3.3. Third Party Call Control ................................... 5
+ 3.4. ISUP interworking .......................................... 5
+ 4. IANA Considerations ........................................ 6
+ 5. Security Considerations .................................... 6
+ 6. Acknowledgments ............................................ 7
+ 7. Authors' Addresses ......................................... 7
+ 8. Normative References ....................................... 7
+ 9. Full Copyright Statement ................................... 8
+
+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 offer a means of informing the user of why a
+ request failed. The simple mechanism in this document accomplishes
+ something roughly similar for requests.
+
+ An INVITE can sometimes be rejected not because the session
+ initiation was declined, but because some aspect of the request was
+ not acceptable. If the INVITE forked and resulted in a rejection,
+ the error response may never be forwarded to the client unless all
+ the other branches also reject the request. This problem is known as
+ the "Heterogeneous Error Response Forking Problem", or HERFP. It is
+ foreseen that a solution to this problem may involve encapsulating
+ the final error response in a provisional response. The Reason header
+ field is a candidate to be used for such encapsulation.
+
+
+
+
+
+Schulzrinne, et. al. Standards Track [Page 2]
+
+RFC 3326 The Reason Header Field for SIP December 2002
+
+
+ Initially, the Reason header field defined here appears to be most
+ useful for BYE and CANCEL requests, but it can appear in any request
+ within a dialog, in any CANCEL request and in any response whose
+ status code explicitly allows the presence of this header field.
+
+ Note that the Reason header field is usually not needed in responses
+ because the status code and the reason phrase already provide
+ sufficient information.
+
+ Clients and servers are free to ignore this header field. 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 BCP 14, RFC 2119
+ [2] and indicate requirement levels for compliant SIP
+ implementations.
+
+2. The Reason Header Field
+
+ The Reason header field MAY appear in any request within a dialog, in
+ any CANCEL request and in any response whose status code explicitly
+ allows the presence of this header field. The syntax of the header
+ field follows the standard SIP parameter syntax.
+
+ Reason = "Reason" HCOLON reason-value *(COMMA reason-value)
+ reason-value = protocol *(SEMI reason-params)
+ protocol = "SIP" / "Q.850" / token
+ reason-params = protocol-cause / reason-text
+ / reason-extension
+ protocol-cause = "cause" EQUAL cause
+ cause = 1*DIGIT
+ reason-text = "text" EQUAL quoted-string
+ reason-extension = generic-param
+
+ The following values for the protocol field have been defined:
+
+ SIP: The cause parameter contains a SIP status code.
+
+ Q.850: The cause parameter contains an ITU-T Q.850 cause value
+ in decimal representation.
+
+
+
+
+
+
+
+
+Schulzrinne, et. al. Standards Track [Page 3]
+
+RFC 3326 The Reason Header Field for SIP December 2002
+
+
+ Examples are:
+
+ Reason: SIP ;cause=200 ;text="Call completed elsewhere"
+ Reason: Q.850 ;cause=16 ;text="Terminated"
+ Reason: SIP ;cause=600 ;text="Busy Everywhere"
+ Reason: SIP ;cause=580 ;text="Precondition Failure"
+
+ 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.
+
+ In normal SIP operation, a SIP status code in a response provides the
+ client with information about the request that triggered the
+ response, the session parameters, or the user. For example, a 405
+ (Method not allowed) response indicates that the request contained an
+ unsupported method. A 488 (Not Acceptable Here) indicates that the
+ session parameters are unacceptable and a 486 (Busy Here) provides
+ information about the status of the user.
+
+ Any SIP status code MAY appear in the Reason header field of a
+ request. However, status codes that provide information about the
+ user and about session parameters are typically useful for
+ implementing services whereas status codes intended to report errors
+ about a request are typically useful for debugging purposes.
+
+ A SIP message MAY contain more than one Reason value (i.e., multiple
+ Reason lines), but all of them MUST have different protocol values
+ (e.g., one SIP and another Q.850). An implementation is free to
+ ignore Reason values that it does not understand.
+
+3. Examples
+
+ This section contains a number of examples that illustrate the use of
+ the Reason header field.
+
+3.1 Call Completed Elsewhere
+
+ A proxy forks an INVITE request and one of the branches returns a 200
+ (OK). The forking proxy includes this status code in a Reason header
+ field in the CANCEL request that it sends to the rest of the
+ branches.
+
+3.2 Refusing an Offer that Comes in a Response
+
+ A client sends an empty INVITE and receives an unacceptable offer in
+ a 200 (OK) response. The client sends an ACK with a correctly
+ formatted answer and immediately sends a BYE to terminate the
+
+
+
+
+Schulzrinne, et. al. Standards Track [Page 4]
+
+RFC 3326 The Reason Header Field for SIP December 2002
+
+
+ session. The client includes a 488 (Not Acceptable Here) status code
+ in a Reason header field.
+
+3.3 Third Party Call Control
+
+ The third party call controller of figure 1 tries to establish a
+ session between A and B. However, user B is busy. The controller
+ sends a BYE with the status code 486 (Busy Here) in a Reason header
+ field.
+
+ A Controller B
+ | INV no SDP | |
+ |<------------------| |
+ | | |
+ | 200 SDP A1 | |
+ |-----------------> | |
+ | | |
+ | ACK SDP held | |
+ |<------------------| |
+ | | |
+ | | INV no SDP |
+ | |----------------->|
+ | | |
+ | | 486 Busy Here |
+ | |<-----------------|
+ | | |
+ | | ACK |
+ | |----------------->|
+ | BYE (486) | |
+ |<------------------| |
+ | | |
+ | 200 OK | |
+ |-----------------> | |
+ | | |
+
+ Figure 1: Third Party Call Control
+
+3.4 ISUP interworking
+
+ The PSTN gateway of figure 2 generates an INVITE that has to be
+ CANCELed when a REL (release) message is received from the ISUP side.
+ The CANCEL request contains the Q.850 cause value (16 Normal Call
+ Clearing) of the REL message.
+
+
+
+
+
+
+
+
+Schulzrinne, et. al. Standards Track [Page 5]
+
+RFC 3326 The Reason Header Field for SIP December 2002
+
+
+ A Gateway B
+ | IAM | |
+ |-----------------> | |
+ | | INVITE |
+ | |----------------->|
+ | | |
+ | | 100 Trying |
+ | |<-----------------|
+ | REL (16) | |
+ |-----------------> | |
+ | | CANCEL (Q.850 16)|
+ | |----------------->|
+ | | 200 OK |
+ | |<-----------------|
+
+ Figure 2: ISUP Interworking
+
+4. IANA Considerations
+
+ This document defines a new SIP header field, "Reason", according to
+ Section 27 of RFC 3261.
+
+ Protocol values (and their associated protocol cause) to be used with
+ this header field are registered by the IANA into a new sub-registry
+ under http://www.iana.org/assignments/sip-parameters, labeled "Reason
+ Protocols". Reason protocols MUST refer to either an ITU-T
+ Recommendation number, an IETF protocol name or the recognized
+ protocol identifier from another standardization organization.
+ Protocol cause describes the source of the 'cause' field in the
+ Reason header field.
+
+ The only entries in the registry for the time being are:
+
+ Protocol Value Protocol Cause Reference
+ -------------- --------------- -----------
+ SIP Status code RFC 3261
+ Q.850 Cause value in decimal ITU-T Q.850
+ representation
+
+5. Security Considerations
+
+ Spoofing or removing the Reason header field from a response in a
+ HERFP scenario can make it impossible for a client to update properly
+ its previous request, making therefore session establishment
+ impossible. Thus, it is RECOMMENDED that this header field is
+ protected by a suitable integrity mechanism.
+
+
+
+
+
+Schulzrinne, et. al. Standards Track [Page 6]
+
+RFC 3326 The Reason Header Field for SIP December 2002
+
+
+ properly its previous request, making therefore session establishment
+ impossible. Thus, it is RECOMMENDED that this header field is
+ protected by a suitable integrity mechanism.
+
+6. Acknowledgments
+
+ Jonathan Rosenberg, Rohan Mahy and Vijay K. Gurbani provided helpful
+ comments and suggestions.
+
+8. Normative References
+
+ [1] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
+ Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP:
+ Session Initiation Protocol", RFC 3261, June 2002.
+
+ [2] Bradner, S., "Key words for use in RFCs to indicate requirement
+ levels," BCP 14, RFC 2119, March 1997.
+
+7. Authors' Addresses
+
+ Henning Schulzrinne
+ Dept. of Computer Science
+ Columbia University
+ 1214 Amsterdam Avenue
+ New York, NY 10027
+ USA
+
+ EMail: schulzrinne@cs.columbia.edu
+
+
+ David R. Oran
+ Cisco Systems, Inc.
+ Acton, MA
+ USA
+
+ EMail: oran@cisco.com
+
+
+ Gonzalo Camarillo
+ Ericsson
+ Advanced Signalling Research Lab.
+ FIN-02420 Jorvas
+ Finland
+
+ EMail: Gonzalo.Camarillo@ericsson.com
+
+
+
+
+
+
+Schulzrinne, et. al. Standards Track [Page 7]
+
+RFC 3326 The Reason Header Field for SIP December 2002
+
+
+9. 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.
+
+ 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.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Schulzrinne, et. al. Standards Track [Page 8]
+