Network Working Group M. Mohali Internet-Draft B. Chatras Intended status: Standards Track France Telecom Orange Expires: August 28, 2011 February 24, 2011 Extending the Session Initiation Protocol (SIP) Reason Header for Applications draft-mohali-sipcore-reason-extension-application-01 Abstract This document defines a new protocol value "Application" for the Reason Header field and a new IANA Registry for registering application types. This new value enables signaling that a request or response has been issued as a result of a decision made by a particular type of application or that an initial request has been retargeted as a result of an application decision. Requirements Language 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 [RFC2119]. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. 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." This Internet-Draft will expire on August 28, 2011. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Mohali & Chatras Expires August 28, 2011 [Page 1] Internet-Draft Reason Header extension for Application February 2011 Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Reason header field extension . . . . . . . . . . . . . . . . 3 3. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. Reason header field in a SIP request . . . . . . . . . . . 5 3.2. header field in a SIP History-Info header field . . . . . 6 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 7.1. Normative References . . . . . . . . . . . . . . . . . . . 10 7.2. Informative References . . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 Mohali & Chatras Expires August 28, 2011 [Page 2] Internet-Draft Reason Header extension for Application February 2011 1. Introduction The Reason header field [RFC3326] provides a mechanism to signal the reason why a SIP request or response was issued or why an initial request was retargeted. This document requests IANA registration of a new protocol value "Application" for the Reason Header field and a new IANA Registry for registering application types. This extension enables signaling that a request or response has been issued as a result of a decision made by a particular type of application or that an initial request has been retargeted as a result of an application decision (e.g. Freephone number translation). 2. Reason header field extension The syntax of the Reason header field as defined in [RFC3326] is as follows: 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 This document adds a new protocol value "Application". This protocol value can be used anywhere the presence of a Reason Header field is allowed. When this protocol value is used, the protocol-cause and the reason- text fields shall be set to values registered in a new IANA Registry for registering application types. A unique cause value and reason-text is registered for each new reason-value added with protocol value "Application". For each new registered value, it has to be defined the following: Mohali & Chatras Expires August 28, 2011 [Page 3] Internet-Draft Reason Header extension for Application February 2011 Cause value: this is an identifier number corresponding to the cause value of the protocol-cause parameter in the Reason header field. Reason text: this is a unique string identifying the application name. The reason text is intended to give a short textual description of the application. Description: this is a description of the application and the conditions under which this reason-value is used. The description shall be sufficiently clear to differentiate the new reason from all other existing reasons. This document registers protocol causes for the following cases: Cause value: 1 Reason text: Universal Access Number Description: A Universal Access Number application has influenced processing of the call (e.g. by translating a dialed Universal Access number to a routable directory number). Cause value: 2 Reason text: Freephone Description: A Freephone application has influenced processing of the call (e.g. by translating a dialed Free Phone number to a routable directory number). Cause value: 3 Reason text: Premium Rate Description: A Premium Rate application has influenced processing of the call (e.g. by translating a dialed Premium Rate number to a routable directory number). Cause value: 4 Reason text: Directory Enquiry Description: A Directory Enquiry application has influenced processing of the call (e.g. completion of the call to the Directory Number responding to the enquiry). Cause value: 5 Reason text: VPN Description: A VPN application has influenced processing of the call (e.g. by translating a private number to a routable Directory Number). Cause value: 6 Reason text: Credit Card Calling Mohali & Chatras Expires August 28, 2011 [Page 4] Internet-Draft Reason Header extension for Application February 2011 Description: A Credit Card Calling application has influenced processing of the call (e.g. it has completed the call to a directory number dialed in-band by the calling user). Cause value: 7 Reason text: Voice Activated Dialing Description: A Voice-Activated Dialing application has influenced processing of the call (e.g. it has retargeted the call to a directory number determined by speech recognition). Cause value: 8 Reason text: Customized Call Routing Description: An Customized Call Routing application has influenced processing of the call (e.g. by translating a dialed number into a routable directory number based on customized criteria such as time of day or caller's location). Cause value: 9 Reason text: Prepaid Description: A Prepaid application has influenced processing of the call (e.g. it has requested that the call be released due to exhaustion of credit available on the user account). 3. Use Cases The following text provides two examples illustrating when this new class of Reason values could be used. The first example describes a use in a SIP request and the second example describes a situation when the Reason header is used in a SIP request as a parameter of the History-Info header [RFC4244]. 3.1. Reason header field in a SIP request This section presents the case where an application inserts the Reason header in a BYE request to signal that a call is cleared due to a failure caused by this particular application: A served user having a prepaid calling card wants to call a friend. First, the served user joins the Prepaid application where it gets authenticated. Then, the user dials a number corresponding to an international destination. Unfortunately, the user has not enough credits left on his card and at some point in time the Prepaid application ends the call by sending a BYE method with a Reason header set as follows: Reason: application ;cause=9 ;text="Prepaid", Mohali & Chatras Expires August 28, 2011 [Page 5] Internet-Draft Reason Header extension for Application February 2011 SIP ;cause=402; text="Payment Required" Note: [RFC3326] states that a SIP message MAY contain more than one Reason value (i.e., multiple Reason lines), but all of them MUST have different protocol values and an implementation is free to ignore Reason values that it does not understand. 3.2. header field in a SIP History-Info header field [RFC4244] defines a SIP header field, History-Info, to provide a standard mechanism for capturing requests history information. The History-Info header field allows receiving applications to determine hints about how and why the call arrived at the application/user. The History-Info header field can contain optional reason information by including the Reason header field[RFC3326] as a SIP or SIPs URI component in the hi-targeted-to-uri parameter. The History-Info header field can be added by proxies and other SIP intermediaries when requests are retargeted. Retargeting could be due to a failure or redirection responses but also to normal forwarding of requests. When the call is retargeted as a result of receiving a SIP response (e.g. 3XX response), the Reason Header contains the received SIP status code. When the call is retargeted as a result of an application decision (e.g. Freephone service), the extension of the Reason header defined in this document allows to convey the identification of this application in the signaling. This might help other applications invoked downstream to take appropriate decisions to avoid undesired service interactions. The following example illustrates this last case where the Reason header is set due to retargeting by a Freephone service running in a SIP Application Server. Reason: application ;cause=2 ;text="Freephone" More specifically, in such a case, the Reason header would appear in a History-Info header as described in [RFC4244] and illustrated below: Alice calls the Company dialing a Freephone service number. Mohali & Chatras Expires August 28, 2011 [Page 6] Internet-Draft Reason Header extension for Application February 2011 Alice Free Phone Service Company | | | | INVITE F1 | | |--------------->| INVITE F2 | | |---------------->| | | | | | | F1: INVITE Alice -> proxy.example.com INVITE sip:+89955510044@example.com;user=phone SIP/2.0 Via: SIP/2.0/TCP proxy.example.com:5060;branch=z9hG4bK-klj79f From: Alice ; tag=1234567 To: Company Supported: histinfo Max-Forwards: 70 Call-Id: 12345600@example.com Record-Route: CSeq: 1 INVITE Contact: Alice Content-Type: application/sdp Content-Length: F2: INVITE proxy.example.com -> Company INVITE sip:+12125551212@phone2net.com SIP/2.0 Via: SIP/2.0/TCP as.example.com:5060;branch=z9hG4bK-vlk25e Via: SIP/2.0/TCP proxy.example.com:5060;branch=z9hG4bK-klj79f From: Alice ; tag=1234567 To: sip:+12125551212@phone2net.com;user=phone Supported: histinfo Max-Forwards: 69 Call-Id: 12345600@example.com Record-Route: History-Info: ;index=1 ;index=1.1;mp=1 CSeq: 1 INVITE Contact: Alice Content-Type: application/sdp Content-Length: Mohali & Chatras Expires August 28, 2011 [Page 7] Internet-Draft Reason Header extension for Application February 2011 4. IANA Considerations This document adds to one existing IANA Registry and creates one new namespace Registry according to Section 27 of [RFC3261]. The existing IANA Registry for the SIP Reason Header is as follows: Protocol Value Protocol Cause Reference -------------- -------------- --------- SIP Status code RFC 3261 Q.850 Cause value in decimal ITU-T Q.850 Preemption Cause value in decimal* RFC 4411 This document adds to that Registry with the following entry: Protocol Value Protocol Cause Reference -------------- -------------- --------- Application Cause value in decimal [RFCXXXX] Below is a new IANA Registry for initial values of reason-params fields (protocol-cause and reason-text) associated with the protocol value "Application". Per [RFC3326], the reason-text string is a quoted default string with only human understandability meant. These strings can be changed by local policy. The following cause values and associated reason text are defined: Reason- Protocol param Reason-text Reference -------- ------- ------------ --------- Application Cause=1 Universal Access Number [RFCXXXX] Application Cause=2 Freephone [RFCXXXX] Application Cause=3 Premium Rate [RFCXXXX] Application Cause=4 Directory Enquiry [RFCXXXX] Application Cause=5 VPN [RFCXXXX] Application Cause=6 Credit Card Calling [RFCXXXX] Application Cause=7 Voice Activated Dialing [RFCXXXX] Application Cause=8 Customized Call Routing [RFCXXXX] Application Cause=9 Prepaid [RFCXXXX] Note to the RFC-Editor: RFCXXXX should be replaced by this RFC reference when available. The cause values created by the Application Protocol namespace in Mohali & Chatras Expires August 28, 2011 [Page 8] Internet-Draft Reason Header extension for Application February 2011 this document are described in Section 2. Each cause value has a reason-text string and a detailed description of what the cause value is for. Section 3 provides an example for the above cause codes with a message flow diagram. The above cause values are included in this Application namespace registry. Note: The cause number MAY either be requested by the requester or, if not requested, assigned by IANA. Public and Private values: o The process for registering a public reason is deemed to be "specification required" as per [RFC5226]. Each new public reason value will be compared against existing work to see that it does not duplicate existing values. o The process for registering a private reason is deemed to be "First Come First Served" as per [RFC5226]. A specification is not required but is encouraged. Cause values range: o Public cause values MUST be given in the range 0x0001-0x7fff. o Private cause values MUST be given in the range 0x8000-0xffff. o Cause value 0 is reserved. 5. Security Considerations This specification does not add any security constraint beyond the security considerations for the Reason header field described in [RFC3326] apply. 6. Acknowledgements The editor would like to acknowledge the feedback and support provided by Mary Barnes, Roland Jesske, Paul Kyzivat and Adam Roach. 7. References Mohali & Chatras Expires August 28, 2011 [Page 9] Internet-Draft Reason Header extension for Application February 2011 7.1. Normative References [RFC2119] "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [RFC3261] "SIP: Session Initiation Protocol", RFC 3261, June 2002. [RFC3326] "The Reason Header Field for the Session Initiation Protocol (SIP)", December 2002. [RFC4244] "An Extension to the Session Initiation Protocol (SIP) for Request History Information", RFC 4244, November 2005. 7.2. Informative References [RFC5226] "Guidelines for Writing an IANA Considerations Section in RFCs", May 2008. Authors' Addresses Marianne Mohali France Telecom Orange 38-40 rue du General Leclerc Issy-Les-Moulineaux Cedex 9 92794 France Phone: +33 1 45 29 45 14 Email: marianne.mohali@orange-ftgroup.com Bruno Chatras France Telecom Orange 38-40 rue du General Leclerc Issy-Les-Moulineaux Cedex 9 92794 France Phone: +33 1 45 29 41 48 Email: bruno.chatras@orange-ftgroup.com Mohali & Chatras Expires August 28, 2011 [Page 10]