idnits 2.17.1 draft-yusef-splices-invoke-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 10, 2011) is 4704 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'RFC2119' on line 96 looks like a reference -- Missing reference section? 'RFC3261' on line 361 looks like a reference -- Missing reference section? 'RFC3265' on line 376 looks like a reference -- Missing reference section? 'RFC3515' on line 413 looks like a reference -- Missing reference section? 'RFC3406' on line 190 looks like a reference -- Missing reference section? 'RFC3880' on line 277 looks like a reference -- Missing reference section? 'RFC4538' on line 352 looks like a reference -- Missing reference section? 'RFC5226' on line 554 looks like a reference Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT R. Shekh-Yusef 3 Intended Status: Standards Track Avaya 4 Expires: December 12, 2011 C. Jennings 5 Cisco Systems 6 A. Johnston 7 Avaya 8 F. Audet 9 Skype 10 June 10, 2011 12 The Session Initiation Protocol (SIP) INVOKE Method 13 draft-yusef-splices-invoke-01 15 Abstract 17 This document defines the SIP INVOKE method, which describes a 18 mechanism by which a UA can invoke a well-defined action on a remote 19 UA. These actions are represented by well-defined URNs that must be 20 registered with IANA. 22 This document also defines a new event package 'invoke', and the 23 Action and Action-Progress request headers. 25 Status of this Memo 27 This Internet-Draft is submitted to IETF in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF), its areas, and its working groups. Note that 32 other groups may also distribute working documents as 33 Internet-Drafts. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 The list of current Internet-Drafts can be accessed at 41 http://www.ietf.org/1id-abstracts.html 43 The list of Internet-Draft Shadow Directories can be accessed at 44 http://www.ietf.org/shadow.html 46 Copyright and License Notice 48 Copyright (c) 2011 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3. The INVOKE Method . . . . . . . . . . . . . . . . . . . . . . 7 66 3.1. The Action Header Field . . . . . . . . . . . . . . . . . 7 67 3.2. URN Structure . . . . . . . . . . . . . . . . . . . . . . 7 68 3.3. URN Categories . . . . . . . . . . . . . . . . . . . . . . 8 69 3.4. URN Actions . . . . . . . . . . . . . . . . . . . . . . . 8 70 3.5. URN Action Parameters . . . . . . . . . . . . . . . . . . 8 71 3.6. Message Body Inclusion . . . . . . . . . . . . . . . . . . 9 72 4. Event Package . . . . . . . . . . . . . . . . . . . . . . . . 10 73 4.1. Subscription . . . . . . . . . . . . . . . . . . . . . . . 10 74 4.2. Progress Indication . . . . . . . . . . . . . . . . . . . 10 75 4.3. Subscription Termination . . . . . . . . . . . . . . . . . 10 76 4.4. The Body of the NOTIFY . . . . . . . . . . . . . . . . . . 10 77 5. User Agent Behavior . . . . . . . . . . . . . . . . . . . . . 11 78 5.1. Forming an INVOKE request . . . . . . . . . . . . . . . . 11 79 5.2. Processing an INVOKE request . . . . . . . . . . . . . . . 11 80 5.3. Request Authorization . . . . . . . . . . . . . . . . . . 11 81 5.4. Action Progress Indication . . . . . . . . . . . . . . . . 11 82 6. Control Channel . . . . . . . . . . . . . . . . . . . . . . . 12 83 7. Capabilities Indications . . . . . . . . . . . . . . . . . . . 12 84 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 85 9. Example Flows . . . . . . . . . . . . . . . . . . . . . . . . 13 86 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 87 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 88 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 89 13. Author's Addresses . . . . . . . . . . . . . . . . . . . . . . 17 91 1. Terminology 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 95 document are to be interpreted as described in RFC 2119 [RFC2119]. 97 To simplify discussions of the INVOKE method and its extensions, the 98 two terms below are being used throughout the document: 100 o INVOKE-Issuer: the UA issuing the INVOKE request 102 o INVOKE-Recipient: the UA receiving the INVOKE request 104 2. Background 106 The Session Initiation Protocol (SIP) [RFC3261] provides users with 107 the ability to initiate, manage and terminate multimedia sessions. 108 Many deployments have SIP applications in the SIP signaling path that 109 get involved in the setup and management of these multimedia 110 sessions. 112 A SIP application is a program running on a SIP network element that 113 provides some value-added function to a user. Some of these 114 applications need mechanisms to monitor or/and control a SIP User 115 Agent (UA). 117 SIP already provides an extensible framework, SIP-Specific Event 118 Notification [RFC3265], by which SIP UAs can monitor remote UAs and 119 get indications that certain events have occurred. For example, the 120 following are widely used event packages: 122 o Dialog package - call states 124 o Registration package - phone status 126 o Conference package - conference status 128 SIP also provides a method for requesting UAs to perform certain 129 task, i.e., REFER [RFC3515]. The REFER method has many limitations 130 that prevents it from being the ideal method for application level 131 interaction: 133 o The REFER method is overloaded with five distinct meanings as 134 described in [draft-worley-sip-many-refers-00.txt] 136 o The body of the NOTIFY is always message/sipfrag and any 137 application data must be delivered in the body of the sipfrag 138 message. 140 o The referral progress indication is inside the body of the NOTIFY 141 method, instead of headers in the NOTIFY method. 143 o Progress indications for accessing non-SIP resources are not 144 clearly defined and use SIP progress indications. 146 o Implicit subscription is used, but explicit subscription is not 147 allowed 149 o There is no way for the REFER-Issuer to ask the REFER-Recipient 150 to keep the dialog alive after the referral. 152 This document defines the INVOKE method, which describes a mechanism 153 by which a UA can invoke a well-defined action on a remote UA. These 154 actions are represented by well-defined URNs that must be registered 155 with IANA. It also provides a mechanism that allows the INVOKE 156 issuer to be notified of the outcome of the invoked action. 157 Furthermore, It allows the INVOKE issuer to keep the dialog 158 established with the INVOKE recipient open, to allow both sides to 159 exchange application specific information. 161 This document also defines the 'invoke' event package and the Action, 162 Subscribe-Type and Action-Progress request headers. 164 3. The INVOKE Method 166 INVOKE is a SIP method as defined by [RFC3261]. The INVOKE method 167 indicates that the INVOKE-Recipient should invoke the action 168 specified in the request. 170 An INVOKE request MAY be placed inside or outside the scope of a 171 dialog created with a SUBSCRIBE request. 173 3.1. The Action Header Field 175 The Action header is a request header field as defined by [RFC3261]. 176 It only appears in an INVOKE request or a SUBSCRIBE request. 178 The INVOKE method uses the Action header to hold a URN that 179 represents the action to be invoked by the INVOKE-Recipient, e.g. 180 urn:invoke:call:answer. 182 The SUBSCRIBE method uses the Action header to hold a URN that 183 represents the action or category of actions to be monitored by the 184 INVOKE-Recipient. 186 3.2. URN Structure 188 The Namespace Identifier (NID) of the URN is intended to be in the 189 formal space and assigned by IANA, as per the procedures of 190 [RFC3406]. This document defines the 'invoke' namespace. 192 The Namespace Specific String (NSS) of the URN includes the action 193 name, and may be followed by a semi-colon and additional action- 194 specific parameters. 196 The action identifier has a hierarchical structure of categories 197 separated by colon, and the right-most label is the action name. 199 The reason behind the above structure is to avoid the creation of a 200 namespace with a very long list of unrelated actions. 202 3.3. URN Categories 204 This document defines the following categories as part of the NSS of 205 the URN: 207 o call: to allow access to call actions available on a SIP UA, 208 e.g. answer a call, decline a call, ... 210 o conference: to allow access to conference actions available on a 211 SIP UA, e.g. add, remove, ... 213 3.4. URN Actions 215 This document defines the following actions: 217 o Answer call - urn:invoke:call:answer 218 o Terminate call - urn:invoke:call:terminate 219 o Decline call - urn:invoke:call:decline 220 o Ignore call - urn:invoke:call:ignore 221 o Send call to VM - urn:invoke:call:sendvm 222 o Hold call - urn:invoke:call:hold 223 o Unhold call - urn:invoke:call:unhold 224 o Mute call - urn:invoke:call:mute 225 o Unmute call - urn:invoke:call:unmute 226 o Conference - urn:invoke:conference:add 227 - urn:invoke:conference:remove 229 Note that the very important "Make call" CTI primitive does not 230 require a action URN since it is accomplished by sending a REFER with 231 a URI identifying the resource (e.g., a sip, sips or tel URI). 233 3.5. URN Action Parameters 235 An action can be followed by a semi-colon and additional action- 236 specific parameters. 238 For example: 240 urn:invoke:call:answer;media=audio;transducer=speaker|headset 242 This action indicates to the UA to answer the call and provide an 243 audio answer and use either the speaker or headset for the incoming 244 media. 246 The following is a list of example action parameters: 248 o media=audio|video|audvid 249 o transducer=speaker|headset 250 o target= 251 o direction=recvonly|sendonly|sendrecv 252 o abort 254 3.6. Message Body Inclusion 256 An INVOKE method MAY contain a body. This specification assigns no 257 meaning to such a body. A receiving agent may choose to process the 258 body according to its Content-Type or based on the action that the 259 request invokes. 261 OPEN ISSUE: Header vs. Body? 263 There has been some discussion on the list on the question of header 264 field vs message body. This is not the real issue, as either could 265 conceivably be used. Instead, the main issue is what is being 266 invoked: is it a named feature/action/event, or is it a script. The 267 authors strongly believe that the invocation of a script by the 268 method would be a mistake. This would introduce all kinds of 269 security issues and vulnerabilities. This mechanism is purposely 270 defined using URNs - invoking a named feature/action/event. While 271 this might seem to limit the flexibility, it allows a UA to 272 understand exactly what operation is being requested, and apply 273 appropriate policy. If a given feature, action, or event can not be 274 carried out simply by referencing its name and perhaps a few 275 parameters, then this means that it is not suitable for this 276 mechanism. If a true script execution is needed, existing scripting 277 approaches such as CPL (Call Processing Language) [RFC3880] should be 278 considered. 280 Since the invocation is a simple named feature and not a generic 281 script, the question of whether a header field of message body is 282 appropriate. Since it is just a name with at most a few parameters, 283 the authors feel that a header field is sufficient to carry this, and 284 a body is overkill and inefficient. 286 4. Event Package 288 This specification defines the new event package 'invoke', which 289 enables one UA to monitor another UA for the invocation of a specific 290 URN. 292 4.1. Subscription 294 The UA issuing the subscribe request can monitor either a specific 295 action or a category of actions as specified in the Action header 296 field. For example, a subscription to urn:invoke:call:answer would 297 result in NOTIFYs being sent when this specific URN is invoked, while 298 a subscription to urn:invoke:call would result in NOTIFYs being sent 299 when any URN in this category has been invoked. 301 4.2. Progress Indication 303 The Action-Progress header is used to allow the INVOKE-Recipient to 304 report on the progress of the invoked action. The Action-Progress 305 header MUST be added to the NOTIFY requests sent to the INVOKE- 306 Issuer. 308 OPEN ISSUE: Some of these actions are not SIP actions. Should a new list 309 of generic response codes be defined for this purpose? 311 4.3. Subscription Termination 313 Either side can terminate the subscription using the normal [RFC3265] 314 procedures. The SUBSCRIBE-Issuer, by sending a SUBSCRIBE request with 315 expires 0, when it is no longer interested in receiving notification 316 about a specific action or category of actions. The SUBSCRIBE- 317 Recipient, by sending a NOTIFY with Subscription-Status: terminated, 318 when it no longer wants to allow the SUBSCRIBE-Issuer to monitor a 319 specific action or a category of actions. 321 4.4. The Body of the NOTIFY 323 A NOTIFY method MAY contain a body that is specific to the action 324 invoked by the INVOKE request. A receiving agent MAY choose to 325 process the body according to its Content-Type or based on the 326 invoked action. 328 5. User Agent Behavior 330 5.1. Forming an INVOKE request 332 INVOKE is a SIP request and is constructed as defined in [RFC3261]. 333 An INVOKE request MUST contain exactly one Action header field value. 334 It MAY contain Target-Dialog header [RFC4538] to associate the action 335 with an existing dialog. 337 5.2. Processing an INVOKE request 339 A UA accepting a well-formed INVOKE request MUST invoke the action 340 identified by the URN in the Action header field value. 342 An agent responding to an INVOKE method MUST return a 400 (Bad 343 Request) if the request contained zero or more than one Action header 344 field values. 346 5.3. Request Authorization 348 When a UA receives a request to invoke an action, it needs to 349 authorize that request. Some requests can be authorized based on the 350 identity of the sender, the request method, local policy, etc. 352 The Target-Dialog mechanism [RFC4538] MAY be used when a user agent 353 authorization depends on whether the sender of the request is 354 currently in a dialog with that user agent, or whether the sender of 355 the request is aware of a dialog the user agent has with another 356 entity. 358 In most cases, the same user will be logged in to the different 359 devices using the same credentials provided in the REGISTER requests. 360 In this case, all INVOKE requests MUST be challenged using the digest 361 authentication mechanism described by [RFC3261]. 363 5.4. Action Progress Indication 365 The NOTIFY mechanism defined in [RFC3265] MUST be used to inform the 366 INVOKE-Issuer of the status of the action. 368 Each NOTIFY MUST contain an Event header field with a value of 369 'invoke'. Each NOTIFY MUST contain an Action-Progress header field. 370 The Action-Progress header allows the INVOKE-Recipient to report on 371 the progress of the invoked action. 373 6. Control Channel 375 The INVOKE-Issuer MAY establish a Control Channel with the INVOKE- 376 Recipient, using the subscription mechanism defined in [RFC3265], to 377 allow both sides to exchange application specific information related 378 to the invoked action. 380 The INVOKE-Issuer MAY use INVOKE in the context of the Control 381 Channel dialog to send application specific updates to the INVOKE- 382 Recipient. 384 The INVOKE-Recipient MUST use NOTIFY to send application specific 385 updates to the INVOKE-Issuer. 387 7. Capabilities Indications 389 A UA compliant to this specification MUST indicate its support by 390 including the option tag 'invoke' in the Supported header of all 391 requests it sends. 393 A new feature tag is defined to allow a User Agent to indicate which 394 categories it supports. The new feature tag is described below: 396 Feature tag name: invoke 398 Each value of the invoke tag indicates a URN category supported by a 399 SIP UA. The values for this tag equal the URN category names that 400 are supported by the UA. 402 For example, a UA that supports the 'call' and 'conference' 403 categories would look as follows: 405 invoke="call,conference" 407 8. Security Considerations 409 The functionality described in this document allows an authorized 410 party to manipulate SIP sessions and dialogs in arbitrary ways. Any 411 user agent that accepts these types of requests needs to be very 412 careful in who it authorizes to send these types of requests. The 413 same security considerations as [RFC3515] apply. 415 9. Example Flows 417 INVOKE 419 Alice Bob 420 | | 421 | | 422 |-F1 INVOKE------------->| 423 | | 424 |<-------------F2 200 OK-| 425 | | 426 | |-------> 427 | | (whatever) 428 | |<------ 429 | | 431 SUBSCRIBE and INVOKE 433 Alice Bob 434 | | 435 | | 436 |-F1 SUBSCRIBE---------->| 437 | | 438 |<-------------F2 200 OK-| 439 | | 440 |<-------------F3 NOTIFY-| 441 | | 442 |-F4 200 OK------------->| 443 | | 444 | |<--- INVITE 445 | | 446 | |---> 180 447 | | 448 |-F5 INVOKE------------->| 449 | | 450 |<-------------F6 200 OK-| 451 | | 452 | |---> 200 OK 453 | | 454 | |<--- ACK 455 | | 456 |<-------------F7 NOTIFY-| 457 | | 458 |-F8 200 OK------------->| 459 | | 461 F1 SUBSCRIBE sip:bob@example.com SIP/2.0 462 Via: SIP/2.0/UDP host.example.com;branch=z9hG4bKnashds7 463 To: 464 From: ;tag=12341234 465 Call-ID: 12345678@host.example.com 466 CSeq: 1 SUBSCRIBE 467 Max-Forwards: 70 468 Expires: whatever 469 Event: invoke 470 Action: urn:invoke:call 471 Contact: sip:alice@host.example.com 472 Content-Length: 0 474 F2 SIP/2.0 200 OK 475 Via: SIP/2.0/UDP host.example.com;branch=z9hG4bKnashds7 476 To: ;tag=abcd1234 477 From: ;tag=12341234 478 Call-ID: 12345678@host.example.com 479 CSeq: 1 SUBSCRIBE 480 Contact: sip:bob@host.example.com 481 Expires: whatever 482 Content-Length: 0 484 F3 NOTIFY sip:alice@host.example.com SIP/2.0 485 Via: SIP/2.0/UDP host.example.com;branch=z9hG4bK8sdf2 486 To: ;tag=12341234 487 From: ;tag=abcd1234 488 Call-ID: 12345678@host.example.com 489 CSeq: 1 NOTIFY 490 Max-Forwards: 70 491 Event: invoke 492 Action: urn:invoke:call 493 Action-Progress: 100 Trying 494 Subscription-State: active; expires=whatever 495 Contact: sip:bob@host.example.com 496 Content-Length: 0 498 F4 SIP/2.0 200 OK 499 Via: SIP/2.0/UDP host.example.com;branch=z9hG4bK8sdf2 500 To: ;tag=12341234 501 From: ;tag=abcd1234 502 Call-ID: 12345678@host.example.com 503 CSeq: 1 NOTIFY 505 F5 INVOKE sip:bob@example.com SIP/2.0 506 Via: SIP/2.0/UDP host.example.com;branch=z9hG4bKnashds8 507 To: ;tag=abcd1234 508 From: ;tag=12341234 509 Call-ID: 12345678@host.example.com 510 CSeq: 1 INVOKE 511 Max-Forwards: 70 512 Action: urn:invoke:call:answer 513 Contact: sip:alice@host.example.com 514 Content-Length: 0 516 F6 SIP/2.0 200 OK 517 Via: SIP/2.0/UDP host.example.com;branch=z9hG4bKnashds8 518 To: ;tag=abcd1234 519 From: ;tag=12341234 520 Call-ID: 12345678@host.example.com 521 CSeq: 1 INVOKE 522 Contact: sip:bob@host.example.com 523 Content-Length: 0 525 F7 NOTIFY sip:alice@host.example.com SIP/2.0 526 Via: SIP/2.0/UDP host.example.com;branch=z9hG4bK4cd42a 527 To: ;tag=12341234 528 From: ;tag=abcd1234 529 Call-ID: 12345678@host.example.com 530 CSeq: 2 NOTIFY 531 Max-Forwards: 70 532 Event: invoke 533 Action: urn:invoke:call:answer 534 Action-Progress: 200 OK 535 Subscription-State: active; expires=whatever 536 Contact: sip:bob@host.example.com 537 Content-Length: 0 539 F8 SIP/2.0 200 OK 540 Via: SIP/2.0/UDP host.example.com;branch=z9hG4bK4cd42a 541 To: ;tag=12341234 542 From: ;tag=abcd1234 543 Call-ID: 12345678@host.example.com 544 CSeq: 2 NOTIFY 545 Content-Length: 0 547 10. IANA Considerations 549 This specification defines the list of actions in section 3.4 as an 550 initial set of URNs, to be registered with IETF, for use with this 551 specification. 553 In order to add any new action URN to the list above, it must go 554 through the "IETF review" process as defined in [RFC5226]. 556 11. Acknowledgments 558 TO-DO 560 12. References 562 [RFC2119]Bradner, S., "Key words for use in RFCs to Indicate 563 Requirement Levels", BCP 14, RFC 2119, March 1997. 565 [RFC3261]Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 566 Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session 567 Initiation Protocol", RFC 3261, June 2002. 569 [RFC3265]Roach, A., "Session Initiation Protocol (SIP)-Specific Event 570 Notification", RFC 3265, June 2002. 572 [RFC3515]Sparks, R., "The Session Initiation Protocol (SIP) Refer 573 Method", RFC 3515, April 2003. 575 [RFC3406]Daigle, L., van Gulik, D., Iannella, R., and P. Faltstrom, 576 "Uniform Resource Names (URN) Namespace Definition Mechanisms", 577 BCP 66, RFC 3406, October 2002. 579 [RFC5226]Narten, T. and H. Alvestrand, "Guidelines for Writing an 580 IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. 582 [RFC3880]Lennox, J., Wu, X., and H. Schulzrinne, "Call Processing 583 Language (CPL): A Language for User Control of Internet Telephony 584 Services", RFC 3880, October 2004. 586 [RFC4538]Rosenberg, J., "Request Authorization through Dialog 587 Identification in the Session Initiation Protocol (SIP)", RFC 4538, 588 June 2006. 590 13. Author's Addresses 592 Rifaat Shekh-Yusef 593 Avaya 594 250 Sidney Street 595 Belleville, Ontario K8N 5B7 596 Canada 598 Phone: +1-613-967-5267 599 Email: rifatyu@avaya.com 601 Cullen Jennings 602 Cisco Systems 603 170 West Tasman Drive 604 Mailstop SJC-21/2 605 San Jose, CA 95134 606 USA 608 Phone: +1-408-902-3341 609 Email: fluffy@cisco.com 611 Alan Johnston 612 Avaya 613 St. Louis, MO 63124 614 USA 616 Email: alan.b.johnston@gmail.com 618 Francois Audet 619 Skype 620 USA 622 Email: francois.audet@skype.net