INTERNET-DRAFT R. Shekh-Yusef Intended Status: Standards Track Avaya Expires: November 18, 2011 C. Jennings Cisco Systems A. Johnston Avaya F. Audet Skype May 17, 2011 The Session Initiation Protocol (SIP) INVOKE Method draft-yusef-splices-invoke-00 Abstract This document defines the INVOKE method, which describes a mechanism by which a UA can invoke a well-defined action on a remote UA. These actions are represented by well-defined URNs that must be registered with IANA. It also provides a mechanism that allows the INVOKE issuer to be notified of the outcome of the invoked action. Furthermore, It allows the INVOKE issuer to keep the dialog established with the INVOKE recipient open, to allow both sides to exchange application specific information. This document also defines the 'invoke' event package and the Action, Subscribe-Type and Action-Progress request headers. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. 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/1id-abstracts.html Shekh-Yusef, et al. Expires November 18, 2011 [Page 1] INTERNET DRAFT The SIP INVOKE method May 17, 2011 The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html Copyright and License 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 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. Shekh-Yusef, et al. Expires November 18, 2011 [Page 2] INTERNET DRAFT The SIP INVOKE method May 17, 2011 Table of Contents 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. The INVOKE Method . . . . . . . . . . . . . . . . . . . . . . 7 3.1. The Action Header Field . . . . . . . . . . . . . . . . . 7 3.1.1. URN Structure . . . . . . . . . . . . . . . . . . . . 7 3.1.2. URN Categories . . . . . . . . . . . . . . . . . . . . 8 3.2. The Subscribe-Type Header Field . . . . . . . . . . . . . 9 3.3. Message Body Inclusion . . . . . . . . . . . . . . . . . . 9 4. Event Package . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1. Subscription Types . . . . . . . . . . . . . . . . . . . . 10 4.2. The Action-Progress Header Field . . . . . . . . . . . . . 11 4.3. Example Flows . . . . . . . . . . . . . . . . . . . . . . 11 5. User Agent Behavior . . . . . . . . . . . . . . . . . . . . . 16 5.1. Forming an INVOKE request . . . . . . . . . . . . . . . . 16 5.2. Processing an INVOKE request . . . . . . . . . . . . . . . 16 5.3. Action Progress Indication . . . . . . . . . . . . . . . . 16 5.4. The Body of the NOTIFY . . . . . . . . . . . . . . . . . . 17 5.5. Multiple INVOKE Requests in a Dialog . . . . . . . . . . . 17 5.6. Request Authorization . . . . . . . . . . . . . . . . . . 17 6. Control Channel . . . . . . . . . . . . . . . . . . . . . . . 18 7. Capabilities Indications . . . . . . . . . . . . . . . . . . . 18 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 12. Author's Addresses . . . . . . . . . . . . . . . . . . . . . . 20 Shekh-Yusef, et al. Expires November 18, 2011 [Page 3] INTERNET DRAFT The SIP INVOKE method May 17, 2011 1. Terminology 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]. To simplify discussions of the INVOKE method and its extensions, the two terms below are being used throughout the document: o INVOKE-Issuer: the UA issuing the INVOKE request o INVOKE-Recipient: the UA receiving the INVOKE request Shekh-Yusef, et al. Expires November 18, 2011 [Page 4] INTERNET DRAFT The SIP INVOKE method May 17, 2011 2. Background The Session Initiation Protocol (SIP) [RFC3261] provides users with the ability to initiate, manage and terminate multimedia sessions. Many deployments have SIP applications in the SIP signaling path that get involved in the setup and management of these multimedia sessions. A SIP application is a program running on a SIP network element that provides some value-added function to a user. Some of these applications need mechanisms to monitor or/and control a SIP User Agent (UA). SIP already provides an extensible framework, (SIP)-Specific Event Notification [RFC 3265], by which SIP UAs can monitor remote UAs and get indications that certain events have occurred. For example, the following are widely used event packages: o Dialog package - call states o Registration package - phone status o Conference package - conference status SIP also provides a method for requesting UAs to perform certain task, i.e., REFER [RFC3515]. The REFER method has many limitations that prevents it from being the ideal method for application level interaction: o The REFER method is overloaded with five distinct meanings as described in [draft-worley-sip-many-refers-00.txt] o The body of the NOTIFY is always message/sipfrag and any application data must be delivered in the body of the sipfrag message. o The referral progress indication is inside the body of the NOTIFY method, instead of headers in the NOTIFY method. o Progress indications for accessing non-SIP resources are not clearly defined and use SIP progress indications. o Implicit subscription is used, but explicit subscription is not allowed Shekh-Yusef, et al. Expires November 18, 2011 [Page 5] INTERNET DRAFT The SIP INVOKE method May 17, 2011 o There is not way for the REFER-Issuer to ask the REFER-Recipient to keep the dialog alive after the referral. This document defines the INVOKE method, which describes a mechanism by which a UA can invoke a well-defined action on a remote UA. These actions are represented by well-defined URNs that must be registered with IANA. It also provides a mechanism that allows the INVOKE issuer to be notified of the outcome of the invoked action. Furthermore, It allows the INVOKE issuer to keep the dialog established with the INVOKE recipient open, to allow both sides to exchange application specific information. This document also defines the 'invoke' event package and the Action, Subscribe-Type and Action-Progress request headers. Shekh-Yusef, et al. Expires November 18, 2011 [Page 6] INTERNET DRAFT The SIP INVOKE method May 17, 2011 3. The INVOKE Method INVOKE is a SIP method as defined by [RFC3261]. The INVOKE method indicates that the INVOKE-Recipient should invoke the action specified in the request. An INVOKE request implicitly establishes a subscription to the 'invoke' event. Event subscriptions are defined in [RFC3265]. An INVOKE request MAY be placed outside the scope of a dialog created with an INVITE. INVOKE creates a dialog, and MAY be Record-Routed, hence MUST contain a single Contact header field value. INVOKEs occurring inside an existing dialog MUST follow the Route/Record- Route logic of that dialog. 3.1. The Action Header Field The Action header is a request header field as defined by [RFC3261]. It only appears in an INVOKE request. The INVOKE method uses the Action header to hold a URN that represents the action to be invoked by the INVOKE-Recipient, e.g. urn:invoke:call:answer. OPEN ISSUE: Should a separate header be defined for action parameters? 3.1.1. URN Structure The Namespace Identifier (NID) of the URN is intended to be in the formal space and assigned by IANA, as per the procedures of [RFC3406]. This document defines the 'invoke' namespace. The Namespace Specific String (NSS) of the URN includes the action name, and may be followed by a semi-colon and additional action- specific parameters. The action identifier has a hierarchical structure of categories separated by colon, and the right-most label is the action name. The reason behind the above structure is to avoid the creation of a namespace with a very long list of unrelated actions. Shekh-Yusef, et al. Expires November 18, 2011 [Page 7] INTERNET DRAFT The SIP INVOKE method May 17, 2011 3.1.2. URN Categories This document defines the following categories as part of the NSS of the URN: o call: to allow access to call actions available on a SIP UA, e.g. answer a call, decline a call, ... o conference: to allow access to conference actions available on a SIP UA, e.g. add, remove, ... This document defines the following actions: o Answer call - urn:invoke:call:answer o Terminate call - urn:invoke:call:terminate o Decline call - urn:invoke:call:decline o Ignore call - urn:invoke:call:ignore o Send call to VM - urn:invoke:call:sendvm o Hold call - urn:invoke:call:hold o Unhold call - urn:invoke:call:unhold o Mute call - urn:invoke:call:mute o Unmute call - urn:invoke:call:unmute o Conference - urn:invoke:conference:add - urn:invoke:conference:remove Note that the very important "Make call" CTI primitive does not require a action URN since it is accomplished by sending a REFER with a URI identifying the resource (e.g., a sip, sips or tel URI). This specification defines the above list as an initial set of URNs, to be registered with IETF, for use with this specification. In order to add any new action URN to the list above, it must go through the "IETF review" process as defined in RFC 5226. Shekh-Yusef, et al. Expires November 18, 2011 [Page 8] INTERNET DRAFT The SIP INVOKE method May 17, 2011 3.2. The Subscribe-Type Header Field The Subscribe-Type header is a request header field as defined by [RFC3261]. It only appears in an INVOKE request. The INVOKE method uses the Subscribe-Type header to indicate the type of implicit subscription that this INVOKE method will create. The Subscribe-Type header field MAY have one of the values 'fetch', 'execute' or 'monitor', as described in section 4. 3.3. Message Body Inclusion An INVOKE method MAY contain a body. This specification assigns no meaning to such a body. A receiving agent may choose to process the body according to its Content-Type or based on the action that the request invokes. Shekh-Yusef, et al. Expires November 18, 2011 [Page 9] INTERNET DRAFT The SIP INVOKE method May 17, 2011 4. Event Package This specification defines the new event package 'invoke'. This specification also allows for an implicit and explicit subscription to the 'invoke' event package. Implicit subscription is off by default, which results in no subscription to the invoke event package, and no NOTIFYs being sent back to the INVOKE-Issuer. 4.1. Subscription Types To subscribe to the 'invoke' event package, whether using implicit or explicit subscription, the UA issuing the subscribe request MUST include a Subscribe-Type header in the INVOKE request or the SUBSCRIBE request with one of the following options: fetch: This option results in one NOTIFY being sent back to the INVOKE-Issuer, but no action will be invoked. The single NOTIFY will terminate the dialog. execute: This option results in one NOTIFY being sent back to the INVOKE-Issuer before the action invocation and one NOTIFY being sent back after the action invocation. The last NOTIFY will terminate the dialog. monitor: This option results in one NOTIFY being sent back to the INVOKE-Issuer before the action invocation and multiple NOTIFYs being sent back after the action invocation. Either side can terminate the dialog: the INVOKE-Issuer by sending SUBSCRIBE with expires 0, and the INVOKE-Recipient by sending a NOTIFY with Subscription-State: terminated. Explicit subscription to the 'invoke' event package enables one UA to monitor another UA for the invocation of a specific URN. The UA issuing the subscribe request, whether using implicit or explicit subscription, can monitor either a specific action or a category of actions. For example, a subscription to urn:invoke:call:answer would result in NOTIFYs being sent when this specific URN is invoked, while a subscription to urn:invoke:call would result in NOTIFYs being sent when any URN in this category has been invoked. Shekh-Yusef, et al. Expires November 18, 2011 [Page 10] INTERNET DRAFT The SIP INVOKE method May 17, 2011 4.2. The Action-Progress Header Field The Action-Progress header is used to allow the INVOKE-Recipient to report on the progress of the invoked action. The Action-Progress header MUST be added to the NOTIFY requests sent to the INVOKE- Issuer. OPEN ISSUE: Some of these actions are not SIP actions. Should a new list of generic response codes be defined for this purpose? 4.3. Example Flows INVOKE Alice Bob | | | F1 INVOKE | |----------------------->| | F2 200 OK | |<-----------------------| | | | |-------> | | (whatever) | |<------ | | INVOKE with Subscribe-Type: fetch Alice Bob | | | F1 INVOKE | |----------------------->| | F2 202 Accepted | |<-----------------------| | F3 NOTIFY Subscription-State: terminated |<-----------------------| | F4 200 OK | |----------------------->| | | | | | | | | | | Shekh-Yusef, et al. Expires November 18, 2011 [Page 11] INTERNET DRAFT The SIP INVOKE method May 17, 2011 INVOKE with Subscribe-Type: execute Alice Bob | | | F1 INVOKE | |----------------------->| | F2 202 Accepted | |<-----------------------| | F3 NOTIFY Subscription-State: active;expires=xxx |<-----------------------| | F4 200 OK | |----------------------->| | | | | | |-------> | | (whatever) | |<------ | | | F5 NOTIFY Subscription-State: terminated |<-----------------------| | F6 200 OK | |----------------------->| | | | | Shekh-Yusef, et al. Expires November 18, 2011 [Page 12] INTERNET DRAFT The SIP INVOKE method May 17, 2011 INVOKE with Subscribe-Type: monitor Alice Bob | | | F1 INVOKE | |----------------------->| | F2 202 Accepted | |<-----------------------| | F3 NOTIFY Subscription-State: active;expires=xxx |<-----------------------| | F4 200 OK | |----------------------->| | | | | | |-------> | | (whatever) | |<------ | | | F5 NOTIFY Subscription-State: active;expires=xxx |<-----------------------| | F6 200 OK | |----------------------->| | . | | . | | . | | F7 NOTIFY Subscription-State: active;expires=xxx |<-----------------------| | F8 200 OK | |----------------------->| | | Either side can terminate the dialog, Alice by sending a SUBSCRIBE request with expires equals to 0, and Bob by sending a NOTIFY with Subscription-State: terminated. Shekh-Yusef, et al. Expires November 18, 2011 [Page 13] INTERNET DRAFT The SIP INVOKE method May 17, 2011 Here are examples of what the messages between Alice and Bob might look like for an INVOKE request with a subscribe type of 'execute': Message One (F1) INVOKE sip:bob@example.com SIP/2.0 Via: SIP/2.0/UDP agenta.example.com;branch=z9hG4bK1234567890-A To: From: ;tag=123456789 Call-ID: 123456789@agenta.example.com CSeq: 12345678 INVOKE Max-Forwards: 70 Action: whatever URN Subscribe-Type: execute Contact: sip:alice@example.com Content-Type: application specific Content-Length: whatever Message Two (F2) SIP/2.0 202 Accepted Via: SIP/2.0/UDP agenta.example.com;branch=z9hG4bK1234567890-A To: ;tag=1234567810 From: ;tag=123456789 Call-ID: 123456789@agenta.example.com CSeq: 12345678 INVOKE Contact: sip:bob@example.com Content-Length: 0 Message Three (F3) NOTIFY sip:alice@example.com SIP/2.0 Via: SIP/2.0/UDP agentb.example.com;branch=z9hG4bK1234567890-B To: ;tag=123456789 From: ;tag=1234567810 Call-ID: 123456789@agenta.example.com CSeq: 12345679 NOTIFY Max-Forwards: 70 Event: invoke Action-Progress: 100 Trying Subscription-State: active;expires=(depends on Action URN) Contact: sip:bob@example.com Content-Type: application specific Content-Length: whatever Shekh-Yusef, et al. Expires November 18, 2011 [Page 14] INTERNET DRAFT The SIP INVOKE method May 17, 2011 Message Four (F4) SIP/2.0 200 OK Via: SIP/2.0/UDP agentb.example.com;branch=z9hG4bK1234567890-B To: ;tag=123456789 From: ;tag=1234567810 Call-ID: 123456789@agenta.example.com CSeq: 12345679 NOTIFY Contact: sip:alice@example.com Content-Length: 0 Message Five (F5) NOTIFY sip:a@example.com SIP/2.0 Via: SIP/2.0/UDP agentb.example.com;branch=z9hG4bK1234567890-C To: ;tag=123456789 From: ;tag=1234567810 Call-ID: 123456789@agenta.example.com CSeq: 123456710 NOTIFY Max-Forwards: 70 Event: invoke Action-Progress: 200 OK Subscription-State: terminated Contact: sip:bob@example.com Content-Type: application specific Content-Length: whatever Message Six (F6) SIP/2.0 200 OK Via: SIP/2.0/UDP agentb.example.com;branch=z9hG4bK1234567890-C To: ;tag=123456789 From: ;tag=1234567810 Call-ID: 123456789@agenta.example.com CSeq: 123456710 NOTIFY Contact: sip:alice@example.com Content-Length: 0 Shekh-Yusef, et al. Expires November 18, 2011 [Page 15] INTERNET DRAFT The SIP INVOKE method May 17, 2011 5. User Agent Behavior 5.1. Forming an INVOKE request INVOKE is a SIP request and is constructed as defined in [RFC3261]. An INVOKE request MUST contain exactly one Action header field value. It MAY contain Target-Dialog header to associate the action with an existing dialog. 5.2. Processing an INVOKE request A UA accepting a well-formed INVOKE request SHOULD request approval from the user to proceed (this request could be satisfied with an interactive query or through accessing configured policy). If approval is granted, the UA MUST invoke the action identified by the URN in the Action header field value. If the approval sought above for a well-formed INVOKE request is immediately denied, the UA MUST decline the request. An agent responding to an INVOKE method MUST return a 400 (Bad Request) if the request contained zero or more than one Action header field values. An agent (including proxies generating local responses) MAY return a 100 (Trying) or any appropriate 4xx-6xx class response as prescribed by [RFC3261]. If no final response has been generated according to the rules above, the UA MUST return a 202 Accepted response before the INVOKE transaction expires. If an INVOKE request is accepted (that is, a 2xx class response is returned), the recipient MAY create a subscription and send notifications of the status of the invoke as described in Section 5.3. 5.3. Action Progress Indication The NOTIFY mechanism defined in [RFC3265] MUST be used to inform the INVOKE-Issuer of the status of the action. The dialog identifiers (To, From, and Call-ID) of each NOTIFY must match those of the INVOKE as they would if the INVOKE had been a SUBSCRIBE request. Each NOTIFY MUST contain an Event header field with a value of 'invoke'. Shekh-Yusef, et al. Expires November 18, 2011 [Page 16] INTERNET DRAFT The SIP INVOKE method May 17, 2011 Each NOTIFY MUST contain an Action-Progress header field. The Action- Progress header allows the INVOKE-Recipient to report on the progress of the invoked action. 5.4. The Body of the NOTIFY A NOTIFY method MAY contain a body that is specific to the action invoked by the INVOKE request. A receiving agent MAY choose to process the body according to its Content-Type or based on the invoked action. 5.5. Multiple INVOKE Requests in a Dialog When an INVOKE-Recipient receives a dialog-creating INVOKE request in the context of an existing INVOKE dialog, it MUST respond with 403 Forbidden. 5.6. Request Authorization When a UA receives a request to invoke an action, it needs to authorize that request. Some requests can be authorized based on the identity of the sender, the request method, local policy, etc. The Target-Dialog mechanism MAY be used when a user agent authorization depends on whether the sender of the request is currently in a dialog with that user agent, or whether the sender of the request is aware of a dialog the user agent has with another entity. In most cases, the same user will be logged in to the different devices using the same credentials provided in the REGISTER requests. In this case, all INVOKE requests MUST be challenged using the digest authentication mechanism described by [RFC 3261]. Shekh-Yusef, et al. Expires November 18, 2011 [Page 17] INTERNET DRAFT The SIP INVOKE method May 17, 2011 6. Control Channel The INVOKE-Issuer MAY establish a Control Channel with the INVOKE- Recipient, using the subscription type 'monitor', to allow both sides to exchange application specific information related to the invoked action. The INVOKE-Issuer MAY use PUBLISH in the context of the Control Channel dialog with the 'invoke' event package to send application specific updates to the INVOKE-Recipient. The INVOKE-Recipient MUST use NOTIFY to send application specific updates to the INVOKE-Issuer. 7. Capabilities Indications A UA compliant to this specification MUST indicate its support by including the option tag 'invoke' in the Supported header of all requests it sends. A new feature tag is defined to allow a User Agent to indicate which categories it supports. The new feature tag is described below: Feature tag name: invoke Each value of the invoke tag indicates a URN category supported by a SIP UA. The values for this tag equal the URN category names that are supported by the UA. For example, a UA that supports the 'call' and 'conference' categories would look as follows: invoke="call,conference" 8. Security Considerations The functionality described in this document allows an authorized party to manipulate SIP sessions and dialogs in arbitrary ways. Any user agent that accepts these types of requests needs to be very careful in who it authorizes to send these types of requests. The same security considerations as [RFC3515] apply. Shekh-Yusef, et al. Expires November 18, 2011 [Page 18] INTERNET DRAFT The SIP INVOKE method May 17, 2011 9. IANA Considerations TO-DO 10. Acknowledgments TO-DO 11. References TO-DO [RFC2119]Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Shekh-Yusef, et al. Expires November 18, 2011 [Page 19] INTERNET DRAFT The SIP INVOKE method May 17, 2011 12. Author's Addresses Rifaat Shekh-Yusef Avaya 250 Sidney Street Belleville, Ontario K8P 5B7 Canada Phone: +1-613-967-5267 Email: rifatyu@avaya.com Cullen Jennings Cisco Systems 170 West Tasman Drive Mailstop SJC-21/2 San Jose, CA 95134 USA Phone: +1-408-902-3341 Email: fluffy@cisco.com Alan Johnston Avaya St. Louis, MO 63124 USA Email: alan.b.johnston@gmail.com Francois Audet Skype USA Email: francois.audet@skype.net Shekh-Yusef, et al. Expires November 18, 2011 [Page 20]