idnits 2.17.1 draft-boulton-sip-control-framework-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 20. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1623. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1634. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1641. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1647. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 5 instances of too long lines in the document, the longest one being 12 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: It is reasonable to expect this document to be used in various network architectures. This will include a wide range of deployments where the clients could be co-located in a secured, private domain or spread across disparate domains that require traversal of devices such as Network Address Translators (NAT) and Firewalls (which is covered in Section 11). It is important, therefore, that this document provides a 'keep-alive' mechanism that enables the control channel being created to firstly be kept active during times of inactivity (most Firewalls have a timeout period after which connections are closed) and also provide the ability for application level failure detection. It should be noted at this point that the following procedures apply explicitly to the control channel being created and for details relating to a SIP keep-alive mechanism implementers should seek guidance from SIP Outbound [11]. The following 'keep-alive' procedures SHOULD be implemented by all entities but MAY NOT be implemented if it can be guaranteed that deployments will only occur with entities in a co-located domain. It should be noted that choosing to not implement the 'keep-alive' mechanism in this section, even when in a co-located architecture, will reduce the ability to detect application level errors -especially during long periods of in-activity. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: During the SIP dialog negotiation the clients will also negotiate a timeout period for the control channel 'keep-alive' mechanism. The following rules MUST be obeyed in conjunction with COMEDIA[6]: o If the Client initiating the SIP INVITE request has a COMEDIA 'setup' attribute equal to 'active', the 'k-alive' 'Control-Packages' SIP header parameter MUST be included. The value of the 'k-alive' header parameter SHOULD be in the range of 95 and 120 seconds (this is consistent with SIP Outbound[11]). The client generating the subsequent answer ('passive' client) MUST copy the 'k-alive' 'Control-Packages' header parameter into the response with the same value. o If the Client initiating the SIP INVITE request has a COMEDIA 'setup' attribute equal to 'passive', the 'k-alive' Control-Packages SIP header parameter MUST NOT be included. The client generating the subsequent answer ('active' client) MUST include the 'k-alive' header parameter. The value of the 'k-alive' header parameter SHOULD be in the range of 95 and 120 seconds. o If the Client initiating the SIP INVITE request has a COMEDIA 'setup' attribute equal to 'actpass', the 'k-alive' 'Control-Packages' header parameter MUST be included. The value of the 'k-alive' header parameter SHOULD be in the range of 95 to 120 seconds. If the client generating the subsequent answer places a value of 'active' in the COMEDIA 'setup' attribute, It MUST include a 'k-alive' header parameter and MAY choose a value that is different from that received in the request. The value SHOULD be in the range 95 to 120 seconds. If the client generating the subsequent answer places a value of 'passive' in the COMDEDIA 'setup' attribute, it MUST copy the 'k-alive' header and value from the request into the 'k-alive' 'Control-Packages' SIP header parameter. o The 'Control-Packages' 'k-alive' header parameter MUST not be included when the COMEDIA 'setup' attribute is equal to 'holdconn'. o Following the previous steps ensures that the entity initiating the control channel connection is always the one specifying the keep-alive timeout period. It will always be the initiator of the connection who generates the 'K-ALIVE' Control Framework level messages. The following section describes in more detail how to generate the Control Framework 'K-ALIVE' message. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 7, 2007) is 6288 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) -- Obsolete informational reference (is this intentional?): RFC 3525 (ref. '7') (Obsoleted by RFC 5125) == Outdated reference: A later version (-20) exists of draft-ietf-sip-outbound-07 -- Obsolete informational reference (is this intentional?): RFC 2234 (ref. '17') (Obsoleted by RFC 4234) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Boulton 3 Internet-Draft Ubiquity Software Corporation 4 Expires: August 11, 2007 T. Melanchuk 5 BlankSpace 6 S. McGlashan 7 Hewlett-Packard 8 A. Shiratzky 9 Radvision 10 February 7, 2007 12 A Control Framework for the Session Initiation Protocol (SIP) 13 draft-boulton-sip-control-framework-05 15 Status of this Memo 17 By submitting this Internet-Draft, each author represents that any 18 applicable patent or other IPR claims of which he or she is aware 19 have been or will be disclosed, and any of which he or she becomes 20 aware will be disclosed, in accordance with Section 6 of BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF), its areas, and its working groups. Note that 24 other groups may also distribute working documents as Internet- 25 Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt. 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 This Internet-Draft will expire on August 11, 2007. 40 Copyright Notice 42 Copyright (C) The IETF Trust (2007). 44 Abstract 46 This document describes a Framework and protocol for application 47 deployment where the application logic and processing are 48 distributed. The framework uses the Session Initiation Protocol 49 (SIP) to establish an application-level control mechanism between 50 application servers and associated external servers such as media 51 servers. 53 The motivation for the creation of this Framework is to provide an 54 interface suitable to meet the requirements of a distributed, 55 centralized conference system, as defined by the XCON work group of 56 the IETF. It is not, however, limited to this scope and it is 57 envisioned that this generic Framework will be used for a wide 58 variety of de-coupled control architectures between network entities. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 4 64 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 4. Locating External Server Resources . . . . . . . . . . . . . . 10 66 5. Control Client SIP UAC Behavior - Control Channel Setup . . . 10 67 5.1. Control Client SIP UAC Behavior - Media Dialogs . . . . . 12 68 6. Control Server SIP UAS Behavior - Control Channel Setup . . . 12 69 7. Control Channel Keep-Alive . . . . . . . . . . . . . . . . . . 14 70 7.1. Timeout Negotiation . . . . . . . . . . . . . . . . . . . 14 71 7.2. Generating Keep-Alive Messages . . . . . . . . . . . . . . 15 72 8. Control Framework Interactions . . . . . . . . . . . . . . . . 16 73 8.1. Constructing Requests . . . . . . . . . . . . . . . . . . 17 74 8.1.1. Sending CONTROL . . . . . . . . . . . . . . . . . . . 18 75 8.1.2. Sending REPORT . . . . . . . . . . . . . . . . . . . . 18 76 8.2. Constructing Responses . . . . . . . . . . . . . . . . . . 20 77 9. Response Code Descriptions . . . . . . . . . . . . . . . . . . 21 78 9.1. 200 Response Code . . . . . . . . . . . . . . . . . . . . 21 79 9.2. 202 Response Code . . . . . . . . . . . . . . . . . . . . 21 80 9.3. 400 Response Code . . . . . . . . . . . . . . . . . . . . 21 81 9.4. 403 Response Code . . . . . . . . . . . . . . . . . . . . 21 82 9.5. 481 Response Code . . . . . . . . . . . . . . . . . . . . 21 83 9.6. 500 Response Code . . . . . . . . . . . . . . . . . . . . 22 84 10. Control Packages . . . . . . . . . . . . . . . . . . . . . . . 22 85 10.1. Control Package Name . . . . . . . . . . . . . . . . . . . 22 86 10.2. Framework Message Usage . . . . . . . . . . . . . . . . . 22 87 10.3. Common XML Support . . . . . . . . . . . . . . . . . . . . 23 88 10.4. CONTROL Message Bodies . . . . . . . . . . . . . . . . . . 23 89 10.5. REPORT Message Bodies . . . . . . . . . . . . . . . . . . 23 90 10.5.1. Events . . . . . . . . . . . . . . . . . . . . . . . . 23 91 10.6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 24 92 11. Network Address Translation (NAT) . . . . . . . . . . . . . . 24 93 12. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 24 94 12.1. SIP Formal Syntax . . . . . . . . . . . . . . . . . . . . 24 95 12.2. Control Framework Formal Syntax . . . . . . . . . . . . . 24 97 13. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 98 14. Security Considerations . . . . . . . . . . . . . . . . . . . 32 99 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32 100 15.1. IANA Registration of the 'escs' Option Tag . . . . . . . . 32 101 15.2. Control Package Registration Information . . . . . . . . . 32 102 15.2.1. Control Package Registration Template . . . . . . . . 32 103 15.3. SDP Transport Protocol . . . . . . . . . . . . . . . . . . 32 104 15.3.1. TCP/ESCS . . . . . . . . . . . . . . . . . . . . . . . 32 105 15.3.2. TCP/TLS/ESCS . . . . . . . . . . . . . . . . . . . . . 32 106 15.4. SDP Attribute Names . . . . . . . . . . . . . . . . . . . 32 107 15.5. SIP Response Codes . . . . . . . . . . . . . . . . . . . . 32 108 16. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 32 109 17. Appendix A . . . . . . . . . . . . . . . . . . . . . . . . . . 32 110 17.1. Common Dialog/Multiparty Reference Schema . . . . . . . . 32 111 18. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 112 18.1. Normative References . . . . . . . . . . . . . . . . . . . 34 113 18.2. Informative References . . . . . . . . . . . . . . . . . . 34 114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 36 115 Intellectual Property and Copyright Statements . . . . . . . . . . 37 117 1. Introduction 119 Applications are often developed using an architecture where the 120 application logic and processing activities are distributed. 121 Commonly, the application logic runs on "application servers" whilst 122 the processing runs on external servers, such as "media servers". 123 This document focuses on the framework and protocol between the 124 application server and external processing server. The motivation 125 for this framework comes from a set of requirements for Media Server 126 Control, which can be found in the 'Media Control Protocol Framework' 127 document[8]. While the Framework is not media server control 128 specific, it is the primary driver and use case for this work. It is 129 intended that the framework contained in this document will be used 130 for a plethora of appropriate device control scenarios. 132 This document does not define a SIP based extension that can be used 133 directly for the control of external components. The framework 134 mechanism must be extended by other documents that are known as 135 "Control Packages". A comprehensive set of guidelines for creating 136 "Control Packages" is described in Section 10. 138 Current IETF transport device control protocols, such as megaco [7], 139 while excellent for controlling media gateways that bridge separate 140 networks, are troublesome for supporting media-rich applications in 141 SIP networks, because they duplicate many of the functions inherent 142 in SIP. Rather than relying on single protocol session 143 establishment, application developers need to translate between two 144 separate mechanisms. 146 Application servers traditionally use SIP third party call control 147 RFC 3725 [12] to establish media sessions from SIP user agents to a 148 media server. SIP, as defined in RFC 3261 [2], also provides the 149 ideal rendezvous mechanism for establishing and maintaining control 150 connections to external server components. The control connections 151 can then be used to exchange explicit command/response interactions 152 that allow for media control and associated command response results. 154 2. Conventions and Terminology 156 In this document, BCP 14/RFC 2119 [1] defines the key words "MUST", 157 "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", 158 "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL". In 159 addition, BCP 15 indicates requirement levels for compliant 160 implementations. 162 The following additional terms are defined for use in this document: 164 B2BUA: A B2BUA is a Back-to-Back SIP User Agent. 165 Control Server: A Control Server is an entity that performs a 166 service, such as media processing, on behalf of a Control Client. 167 For example, a media server offers mixing, announcement, tone 168 detection and generation, and play and record services. The 169 Control Server in this case, has a direct RTP [15] relationship 170 with the source or sink of the media flow. In this document, we 171 often refer to the Control Server simply as "the Server". 172 Control Client: A Control Client is an entity that requests 173 processing from a Control Server. Note that the Control Client 174 may not have any processing capabilities whatsoever. For example, 175 the Control Client may be an Application Server (B2BUA) or other 176 endpoint requesting manipulation of a third-party's media stream, 177 that terminates on a media server acting in the role of a Control 178 Server. In this document, we often refer to the Control Client 179 simply as "the Client". 180 Control Channel: A Control Channel is a reliable connection between 181 a Client and Server that is used to exchange Framework messages. 182 The term "Connection" is used synonymously within this document. 183 Framework Message: A Framework Message is a message on a Control 184 Channel that has a type corresponding to one of the Methods 185 defined in this document. A Framework message is often referred 186 to by its method, such as a "CONTROL message". 187 Method: A Method is the type of a framework message. Three Methods 188 are defined in this document: SYNCH, CONTROL, REPORT, and K-ALIVE. 189 Control Command: A Control Command is an application level request 190 from a Client to a Server. Control Commands are carried in the 191 body of CONTROL messages. Control Commands are defined in 192 separate specifications known as "Control Packages". 193 framework transaction: A framework transaction is defined as a 194 sequence composed of a control framework message originated by 195 either a Control Client or Control Server and responded to with a 196 control Framework response code message. Note that the control 197 framework has no "provisional" responses. A control framework 198 transaction MUST complete within Transaction-Timeout time. 199 extended framework transaction: An extended framework transaction is 200 used to extend the lifetime of a CONTROL method transaction when 201 the Control Command it carries cannot be completed within Command- 202 Timeout milliseconds. A Server extends the lifetime of a CONTROL 203 method transaction by sending a 202 response code followed by one 204 or more REPORT transactions as specified in Section 8.1.2. 205 Extended framework transactions allow command failures to be 206 discovered at the transaction layer. 207 Transaction-Timeout: the maximum allowed time between a control 208 Client or Server issuing a framework message and receiving a 209 corresponding response. The value for the timeout should be based 210 on a multiple of the network RTT plus Command-Timeout milliseconds 211 to allow for message parsing and processing. 213 3. Overview 215 This document details mechanisms for establishing, using, and 216 terminating a reliable channel using SIP for the purpose of 217 controlling an external server. The following text provides a non- 218 normative overview of the mechanisms used. Detailed, normative 219 guidelines are provided later in the document. 221 Control channels are negotiated using standard SIP mechanisms that 222 would be used in a similar manner to creating a SIP voice session. 223 Figure 1 illustrates a simplified view of the proposed mechanism. It 224 highlights a separation of the SIP signaling traffic and the 225 associated control channel that is established as a result of the SIP 226 interactions. 228 The use of SIP for the specified mechanism provides many inherent 229 capabilities which include:- 230 o Service location - Use SIP Proxies or Back-to-Back User Agents for 231 discovering Control Servers. 232 o Security mechanisms - Leverage established security mechanisms 233 such as Transport Layer Security (TLS) and Client Authentication. 234 o Connection maintenance - The ability to re-negotiate a connection, 235 ensure it is active, audit parameters, and so forth. 236 o Agnostic - Generic protocol allows for easy extension. 238 As mentioned in the previous list, one of the main benefits of using 239 SIP as the session control protocol is the "Service Location" 240 facilities provided. This applies at both a routing level, where RFC 241 3263 [4] provides the physical location of devices, and at the 242 Service level, using Caller Preferences[13] and Callee 243 Capabilities[14]. The ability to select a Control Server based on 244 Service level capabilities is extremely powerful when considering a 245 distributed, clustered architecture containing varying services (for 246 example Voice, Video, IM). More detail on locating Control Server 247 resources using these techniques is outlined in Section 5 of this 248 document. 250 +--------------SIP Traffic--------------+ 251 | | 252 v v 253 +-----+ +--+--+ 254 | SIP | | SIP | 255 |Stack| |Stack| 256 +---+-----+---+ +---+-----+---+ 257 | Control | | Control | 258 | Client |<----Control Channel---->| Server | 259 +-------------+ +-------------+ 260 Figure 1: Basic Architecture 262 The example from Figure 1 conveys a 1:1 connection between the 263 Control Client and the Control Server. It is possible, if required, 264 for multiple control channels using separate SIP dialogs to be 265 established between the Control Client and the Control Server 266 entities. Any of the connections created between the two entities 267 can then be used for Server control interactions. The control 268 connections are agnostic to any media sessions. Specific media 269 session information can be incorporated in control interaction 270 commands (which themselves are defined in external packages) using 271 the XML schema defined in Section 17. The ability to have multiple 272 control channels allows for stronger redundancy and the ability to 273 manage high volumes of traffic in busy systems. 275 [Editors Note: Still under discussion. How does an app server know, 276 when there are multiple external servers, which specific server has 277 any given media session? Next version of the draft will discuss the 278 correlation procedures. The App server needs a control channel with 279 the media server and needs to know which channel to use once the 280 media session has been established. Sounds like a GRUU usage?] 282 Consider the following simple example for session establishment 283 between a Client and a Server (Note: Some lines in the examples are 284 removed for clarity and brevity). Note that the roles discussed are 285 logical and can change during a session, if the Control Package 286 allows. 288 The Client constructs and sends a SIP INVITE request to the external 289 Server. The request contains the SIP option tag "escs" in a SIP 290 "Require" header for the purpose of forcing the use of the mechanism 291 described in this document. The SDP payload includes the required 292 information for control channel negotiation. The COMEDIA [6] 293 specification for setting up and maintaining reliable connections is 294 used (more detail available in later sections). 296 The client MUST include details of control packages that are 297 supported and, more specifically, that will be used within the 298 control channel created. This is achieved through the inclusion of a 299 SIP "Control-Packages" header. The "Control-Packages" header is 300 defined and described later in this document. 302 Client Sends to External Server: 304 INVITE sip:External-Server@example.com SIP/2.0 305 To: 306 From: ;tag=64823746 307 Require: escs 308 Control-Packages: 309 Call-ID: 7823987HJHG6 310 Content-Type: application/sdp 312 v=0 313 o=originator 2890844526 2890842808 IN IP4 controller.example,com 314 s=- 315 c=IN IP4 controller.example.com 316 m=application 7575 TCP/ESCS 317 a=setup:active 318 a=connection:new 320 On receiving the INVITE request, the external Server supporting this 321 mechanism generates a 200 OK response containing appropriate SDP. 323 External Server Sends to Client: 325 SIP/2.0 200 OK 326 To: ;tag=28943879 327 From: ;tag=64823746 328 Call-ID: 7823987HJHG6 329 Content-Type: application/sdp 331 v=0 332 o=originator 2890844526 2890842808 IN IP4 controller.example,com 333 s=- 334 c=IN IP4 mserver.example.com 335 m=application 7563 TCP/ESCS 336 a=setup:passive 337 a=connection:new 339 The Control Client receives the SIP 200 OK response and extracts the 340 relevant information (also sending a SIP ACK). It creates an 341 outgoing (as specified by the SDP 'setup:' attribute) TCP connection 342 to the Control Server. The connection address (taken from 'c=') and 343 port (taken from 'm=')are used to identify the remote part in the new 344 connection. 346 Once established, the newly created connection can be used to 347 exchange control language requests and responses. If required, after 348 the control channel has been setup, media sessions can be established 349 using standard SIP third party call control. 351 [Editors Note: See previous note:this is where we may need to mention 352 how an App Server knows which external Server is responsible for any 353 given media session.] 355 Figure 4 provides a simplified example where the proposed framework 356 is used to control a User Agent's RTP session. (1) in brackets 357 represents the SIP dialog and dedicated control channel previously 358 described in this overview section. 360 +--------Control SIP Dialog(1)---------+ 361 | | 362 v v 363 +-----+ +--+--+ 364 +------(2)------>| SIP |---------------(2)------------->| SIP | 365 | |Stack| |Stack| 366 | +---+-----+---+ +---+-----+---+ 367 | | | | | 368 | | Control |<--Control Channel(1)-->| | 369 | | Client | | Control | 370 | +-------------+ | Server | 371 +--+--+ | | 372 |User | | | 373 |Agent|<=====================RTP(2)===================>| | 374 +-----+ +-------------+ 376 Figure 4: Participant Architecture 378 (2) from Figure 4 represents the User Agent SIP dialog interactions 379 and associated media flow. A User Agent would create a SIP dialog 380 with the Control Client entity. The Control Client entity will also 381 create a related dialog to the Control Server (B2BUA type 382 functionality). Using the interaction illustrated by (2), the User 383 Agent is able to negotiate media capabilities with the Control Server 384 using standard SIP mechanisms as defined in RFC 3261 [2] and RFC 3264 385 [5]. 387 If not present in the SDP received by the Control Client from the 388 User Agent(2), a media label SDP attribute, which is defined in [10], 389 should be inserted for every media description (identified as m= line 390 as defined in [9]). This provides flexibility for the Control 391 Client, because it can generate control messages that specify a 392 particular Media stream (between User Agent and Control Server) 393 within a SIP media dialog. If a Media label is not included in the 394 control message, it applies to all media associated with the dialog. 396 A non 2xx class SIP response received for the INVITE request 397 indicates that no SIP dialog has been created and is treated as 398 specified RFC 3261 [2]. One exception to this is the "496" (TODO: 399 need to pick an appropriate response code) response code whose 400 operation is defined in Section 6. 402 4. Locating External Server Resources 404 Section will describe mechanisms for locating an external Server. 406 5. Control Client SIP UAC Behavior - Control Channel Setup 408 On creating a new SIP INVITE request, a UAC can insist on using the 409 mechanisms defined in this document. This is achieved by inserting a 410 SIP Require header containing the option tag 'escs'. A SIP Require 411 header with the value 'escs' MUST NOT be present in any other SIP 412 request type. 414 If on creating a new SIP INVITE request, a UAC does not want to 415 insist on the usage of the mechanisms defined in this document but 416 merely that it supports them, a SIP Supported header MUST be included 417 in the request with the option tag 'escs'. 419 The SIP INVITE MUST include a SIP "Control-Packages" header which 420 MUST contain at least one valid entry and can contain multiple 421 control packages if required. 423 If a reliable response is received (as defined RFC 3261 [2] and RFC 424 3262 [3]) that contains a SIP Require header containing the option 425 tag 'escs', the mechanisms defined in this document are applicable to 426 the newly created dialog. 428 Before the UAC can send a request, it MUST include a valid session 429 description using the Session Description Protocol defined in [9]. 430 The following information defines the composition of some specific 431 elements of the SDP payload that MUST be adhered to for compliancy to 432 this specification. 434 The Connection Data line in the SDP payload is constructed as 435 specified in [9]: 437 c= 439 The first sub-field, , MUST equal the value "IN". The 440 second sub-field, , MUST equal either "IP4" or "IP6". The 441 third sub-field for Connection Data is . This 442 supplies a representation of the SDP originators address, for example 443 dns/IP representation. The address will be the network address used 444 for connections in this specification. 446 Example: 448 c=IN IP4 controller.example.com 450 The SDP MUST contain a corresponding Media Description entry for 451 compliance to this specification: 453 m= 455 The first "sub-field" MUST equal the value "application". 456 The second sub-field, , MUST represent a port on which the 457 constructing client can receive an incoming connection if required. 458 The port is used in combination with the address specified in the 459 'Connection Data line defined previously to supply connection 460 details. If the constructing client can't receive incoming 461 connections it MUST still enter a valid port range entry. The use of 462 the port value '0' has the same meaning as defined in the SDP 463 specification[9]. The third sub-field, , MUST equal the value 464 "TCP/ESCS" as defined in Section 15.3.2 of this document. 466 [Editors note: Need to cover other protocols so not TCP specific] 468 The SDP MUST also contain a number of SDP media attributes(a=) that 469 are specifically defined in the COMEDIA specification. The 470 attributes provide connection negotiation and maintenance parameters. 471 A client conforming to this specification SHOULD support all the 472 possible values defined for media attributes from the COMEDIA [6] 473 specification but MAY choose not to support values if it can 474 definitely determine they will never be used (for example will only 475 ever initiate outgoing connections). It is RECOMMENDED that a 476 Controlling UAC initiate a connection to an external Server but that 477 an external Server MAY negotiate and initiate a connection using 478 COMEDIA, if network topology prohibits initiating connections in a 479 certain direction. An example of the attributes is: 481 a=setup:active 482 a=connection:new 484 This example demonstrates a new connection that will be initiated 485 from the owner of the SDP payload. The connection details are 486 contained in the SDP answer received from the UAS. A full example of 487 an SDP payload compliant to this specification can be viewed in 488 Section 3. Once the SDP has been constructed along with the 489 remainder of the SIP INVITE request (as defined in RFC 3261 [2]), it 490 can be sent to the appropriate location. The SIP dialog and 491 appropriate control connection is then established. 493 5.1. Control Client SIP UAC Behavior - Media Dialogs 495 It is intended that the Control framework will be used within a 496 variety of architectures for a wide range of functions. One of the 497 primary functions will be the use of the control channel to apply 498 specific Control package commands to co-existing SIP dialogs that 499 have been established with the same remote server, for example the 500 manipulation of audio dialogs connected to a media server. 502 Such co-existing dialogs will pass through the Control Client (see 503 Figure 4) entity and may contain more than one Media Description (as 504 defined by "m=" in the SDP). The Control Client SHOULD include a 505 media label attribute (B2BUA functionality), as defined in [10], for 506 each "m=" definition. A Control Client constructing the SDP MAY 507 choose not to include the media label SDP attribute if it does not 508 require direct control on a per media stream basis. 510 This framework identifies the common re-use of referencing media 511 dialogs and has specified a connection reference attribute that can 512 optionally be imported into any Control Package. It is intended that 513 this will reduce repetitive specifying of dialog reference language. 514 The schema can be found in Section 17.1 in Appendix A. 516 Similarly, the ability to identify and apply commands to a group of 517 media dialogs is also identified as a common structure that could be 518 defined and re-used (for example playing a prompt to all participants 519 in a Conference). The schema for such operations can also be found 520 in Section 17.1 in Appendix A. 522 Support for both the common attributes described here is specified as 523 part of each Control Package definition, as detailed in Section 10. 525 6. Control Server SIP UAS Behavior - Control Channel Setup 527 On receiving a SIP INVITE request, an external Server(UAS) inspects 528 the message for indications of support for the mechanisms defined in 529 this specification. This is achieved through the presence of the SIP 530 Supported and Require headers containing the option tag 'escs'. If 531 the external Server wishes to construct a reliable response that 532 conveys support for the extension, it should follow the mechanisms 533 defined in RFC 3261 [2] for responding to SIP supported and Require 534 headers. If support is conveyed in a reliable SIP provisional 535 response, the mechanisms in RFC 3262 [3] MUST also be used. 537 When constructing a SIP success response, the SDP payload MUST be 538 constructed using the semantics(Connection, Media and attribute) 539 defined in Section 5 using valid local settings and also with full 540 compliance to the COMEDIA[6] specification. For example, the SDP 541 attributes included in the answer constructed for the example offer 542 provided in Section 5 would look as illustrated below: 544 a=setup:passive 545 a=connection:new 547 Once the SIP success response has been constructed, it is sent using 548 standard SIP mechanisms. Depending on the contents of the SDP 549 payloads that were negotiated using the Offer/Answer exchange, a 550 reliable connection will be established between the Controlling UAC 551 and external Server UAS entities. The connection is now available to 552 exchange commands, as defined in "Control Packages" and described in 553 Section 10. The state of the SIP Dialog and the associated Control 554 channel are now explicitly linked. If either party wishes to 555 terminate a Control channel is simply issues a SIP termination 556 request (SIP BYE request). The Control Channel therefore lives for 557 the duration of the SIP dialog. 559 If the UAS does not support the extension contained in a SIP 560 Supported or Require header it MUST respond as detailed in RFC 3261 561 [2]. If the UAS does support the SIP extension contained in a SIP 562 Require or Supported header but does not support one or more of the 563 Control packages, as represented in the "Control-Packages" SIP 564 header, it MUST respond with a SIP "496 Unknown Control Package" 565 response code. The error response MUST conform to RFC 3261 [2] and 566 MUST also include a "Control-Packages" SIP header which lists the 567 control packages from the request that the UAS does not support. 568 This provides the Controlling UAC with an explicit reason for failure 569 and allows for re-submission of the request without the un-supported 570 control package. 572 A SIP entity receiving a SIP OPTIONS request MUST respond 573 appropriately as defined in RFC 3261 [2]. This involves providing 574 information relating to supported SIP extensions in the 'Supported' 575 message header. For this extension a value of 'escs' MUST be 576 included. Additionally, a SIP entity MUST include all the additional 577 control packages that are associated with the Control channel. This 578 is achieved by including a 'Control-Packages' SIP message header 579 listing all relevant supported Control package tokens. 581 7. Control Channel Keep-Alive 583 It is reasonable to expect this document to be used in various 584 network architectures. This will include a wide range of deployments 585 where the clients could be co-located in a secured, private domain or 586 spread across disparate domains that require traversal of devices 587 such as Network Address Translators (NAT) and Firewalls (which is 588 covered in Section 11). It is important, therefore, that this 589 document provides a 'keep-alive' mechanism that enables the control 590 channel being created to firstly be kept active during times of 591 inactivity (most Firewalls have a timeout period after which 592 connections are closed) and also provide the ability for application 593 level failure detection. It should be noted at this point that the 594 following procedures apply explicitly to the control channel being 595 created and for details relating to a SIP keep-alive mechanism 596 implementers should seek guidance from SIP Outbound [11]. The 597 following 'keep-alive' procedures SHOULD be implemented by all 598 entities but MAY NOT be implemented if it can be guaranteed that 599 deployments will only occur with entities in a co-located domain. It 600 should be noted that choosing to not implement the 'keep-alive' 601 mechanism in this section, even when in a co-located architecture, 602 will reduce the ability to detect application level errors - 603 especially during long periods of in-activity. 605 7.1. Timeout Negotiation 607 During the SIP dialog negotiation the clients will also negotiate a 608 timeout period for the control channel 'keep-alive' mechanism. The 609 following rules MUST be obeyed in conjunction with COMEDIA[6]: 610 o If the Client initiating the SIP INVITE request has a COMEDIA 611 'setup' attribute equal to 'active', the 'k-alive' 'Control- 612 Packages' SIP header parameter MUST be included. The value of the 613 'k-alive' header parameter SHOULD be in the range of 95 and 120 614 seconds (this is consistent with SIP Outbound[11]). The client 615 generating the subsequent answer ('passive' client) MUST copy the 616 'k-alive' 'Control-Packages' header parameter into the response 617 with the same value. 618 o If the Client initiating the SIP INVITE request has a COMEDIA 619 'setup' attribute equal to 'passive', the 'k-alive' Control- 620 Packages SIP header parameter MUST NOT be included. The client 621 generating the subsequent answer ('active' client) MUST include 622 the 'k-alive' header parameter. The value of the 'k-alive' header 623 parameter SHOULD be in the range of 95 and 120 seconds. 624 o If the Client initiating the SIP INVITE request has a COMEDIA 625 'setup' attribute equal to 'actpass', the 'k-alive' 'Control- 626 Packages' header parameter MUST be included. The value of the 627 'k-alive' header parameter SHOULD be in the range of 95 to 120 628 seconds. If the client generating the subsequent answer places a 629 value of 'active' in the COMEDIA 'setup' attribute, It MUST 630 include a 'k-alive' header parameter and MAY choose a value that 631 is different from that received in the request. The value SHOULD 632 be in the range 95 to 120 seconds. If the client generating the 633 subsequent answer places a value of 'passive' in the COMDEDIA 634 'setup' attribute, it MUST copy the 'k-alive' header and value 635 from the request into the 'k-alive' 'Control-Packages' SIP header 636 parameter. 637 o The 'Control-Packages' 'k-alive' header parameter MUST not be 638 included when the COMEDIA 'setup' attribute is equal to 639 'holdconn'. 640 o Following the previous steps ensures that the entity initiating 641 the control channel connection is always the one specifying the 642 keep-alive timeout period. It will always be the initiator of the 643 connection who generates the 'K-ALIVE' Control Framework level 644 messages. The following section describes in more detail how to 645 generate the Control Framework 'K-ALIVE' message. 647 7.2. Generating Keep-Alive Messages 649 Once the SIP dialog has been established using the offer answer 650 mechanism and the control channel has been established (including the 651 initial identity handshake using SYNCH as discussed in section 652 Section 8), both the 'active' and 'passive' (as defined in 653 COMEDIA[6]) clients MUST start a keep-alive timer equal to the value 654 negotiated during the offer/answer exchange (from the 'k-alive' 655 'Control-Packages' SIP header parameter). 657 When acting as an 'active' client, a 'K-ALIVE' Control Framework 658 message MUST be generated before the local 'keep-alive' timer fires. 659 An active client is free to send the K-ALIVE Control Framework 660 message when ever it chooses. A guideline of 80% of the local 'keep- 661 alive' timer is suggested. The 'passive' client MUST generate a 200 662 OK Control Framework response to the K-ALIVE message and reset the 663 local 'keep-alive' timer. No other Control Framework response is 664 valid. On receiving the 200 OK Control Framework message, the 665 'active' client MUST reset the local 'keep-alive' timer. If no 200 666 OK response is received to the K-ALIVE Control Framework message, 667 before the local 'keep-alive' timer fires, the 'active' client SHOULD 668 tear down the SIP dialog and recover the associated control channel 669 resources. The 'active' client MAY choose to try and recover the 670 connection by renegotiation using COMEDIA. 672 When acting as a 'passive' client, a 'K-ALIVE' Control Framework 673 message MUST be received before the local 'keep-alive' timer fires. 674 The 'passive' client MUST generate a 200 OK control framework 675 response to the K-ALIVE Control Framework message. On sending the 676 200 OK response, the 'passive' client MUST reset the local 'keep- 677 alive' timer. If no K-ALIVE message is received before the local 678 'keep-alive' timer fires, the 'passive' client SHOULD tear down the 679 SIP dialog and recover the associated control channel resources. The 680 'active' client MAY try to and recover the connection by 681 renegotiating using COMEDIA. 683 8. Control Framework Interactions 685 The use of the COMEDIA specification in this document allows for a 686 Control Channel to be set up in either direction as a result of the 687 SIP INVITE transaction. While providing a flexible negotiation 688 mechanism, it does provide certain correlation problems between the 689 channel and the overlying SIP dialog. Remember that the two are 690 implicitly linked and so need a robust correlation mechanism. A 691 Control Client receiving an incoming connection (whether it be acting 692 in the role of UAC or UAS) has no way of identifying the associated 693 SIP dialog as it could be simply listening for all incoming 694 connections on a specific port. As a consequence, some rules are 695 applied to allow a connecting (defined as 'active' role in COMEDIA) 696 client to identify the associated SIP dialog that triggered the 697 connection. The following steps provide an identification mechanism 698 that MUST be carried out before any other signaling is carried out on 699 the newly created Control channel. 700 o Once connected, the client initiating the connection (as 701 determined by COMEDIA) MUST immediately send a Control Framework 702 SYNCH request. The SYNCH request will be constructed as defined 703 in Section 12.2 and MUST only contain one message header, 704 'dialog-id', which contains the SIP dialog information. 705 o The 'dialog-id' message header is constructed by concatenating the 706 Local-tag, Call-ID and Remote-tag (as defined in Section 12.2) 707 from the SIP dialog and separating with a '~'. See syntax defined 708 in Section 17.1 in Appendix A and examples in Section 10.6. For 709 example, if the SIP dialog had values of 'Local-tag=HKJDH', 710 'Remote-tag=JJSUSHJ' and 'Call-ID=8shKUHSUKHW@example.com' - the 711 'dialog-id' header would look like this: 712 'dialog-id=HKJDH~8shKUHSUKHW@example.com~JJSUSHJ'. 713 o The client who initiated the connection MUST then send the SYNCH 714 request. It should then wait for a period of 5 seconds to receive 715 a response. It MAY choose a longer time to wait but it should not 716 be shorter than 5 seconds. 717 o If no response is received for the SYNCH control message, a 718 timeout occurs and the control channel is terminated along with 719 the associated SIP dialog (issue a BYE request). 720 o If the client who initiated a connection receives a 481 response, 721 this implies that the SYNCH request was received but no associated 722 SIP dialog exists. This also results in the control channel being 723 terminated along with the associated SIP dialog (issue a BYE 724 request). 725 o All other error responses received for the SYNCH request are 726 treated as detailed in this specification and also result in the 727 termination of the control channel and the associated SIP dialog 728 (issue a BYE request). 729 o The receipt of a 200 response to a SYNCH message implies that the 730 SIP dialog and control connection have been successfully 731 correlated. The control channel can now be used for further 732 interactions. 734 Once a successful control channel has been established, as defined in 735 Section 5 and Section 6 (and the connection has been correlated, as 736 described in previous paragraph), the two entities are now in a 737 position to exchange relevant control framework messages. The 738 remainder of this section provides details of the core set of methods 739 and responses that MUST be supported for the core control framework. 740 Future extensions to this document MAY define new methods and 741 responses. 743 8.1. Constructing Requests 745 An entity acting as a Control Client is now able to construct and 746 send new requests on a control channel and MUST adhere to the syntax 747 defined in Section 12. Control Commands MUST also adhere to the 748 syntax defined by the Control Packages negotiated in Section 5 and 749 Section 6 of this document. A Control Client MUST create a unique 750 transaction and associated identifier per request transaction. The 751 transaction identifier is then included in the first line of a 752 control framework message along with the method type (as defined in 753 the ABNF in Section 12). The first line starts with the SCFW token 754 for the purpose of easily extracting the transaction identifier. The 755 transaction identifier MUST be globally unique over space and time. 756 All required mandatory and optional control framework headers are 757 then inserted into the control message with appropriate values (see 758 relevant individual header information for explicit detail). A 759 "Control-Package" header MUST also be inserted with the value 760 indicating the Control Package to which this specific request applies 761 (Multiple packages can be negotiated per control channel). 763 Any framework message that contains an associated payload MUST also 764 include a 'Content-Length' message header which represents the size 765 of the message body in decimal number of octets. If no associated 766 payload is to be added to the message, a 'Content-Length' header with 767 a value of '0' MUST be included. 769 When all of the headers have been included in the framework message, 770 it is sent down the control channel established in Section 5. 772 It is a requirement that a Server receiving such a request respond 773 quickkly with an appropriate response (as defined in Section 8.2). A 774 Control Client entity needs to wait for Transaction-Time time for a 775 response before considering the transaction a failure. 777 8.1.1. Sending CONTROL 779 A 'CONTROL' message is used by Control Client to invoke control 780 commands on a Control Server. The message is constructed in the same 781 way as any standard Control Framework message, as discussed 782 previously in Section 8.1 and defined in Section 12. A CONTROL 783 message MAY contain a message body. The explicit control command(s) 784 of the message payload contained in a CONTROL message are specified 785 in separate Control Package specifications. These specifications 786 MUST conform to the format defined in Section 10.4. 788 8.1.2. Sending REPORT 790 A 'REPORT' message is used by a Control Server in two situations. 791 The first situation occurs when processing of a Control Command 792 extends beyond a Command-Timeout. In this case a 202 response is 793 returned. Status updates and the final results of the command are 794 then returned in subsequent REPORT messages. The second situation 795 allows REPORT to be used as an event notification mechanism where 796 events are correlated with the original CONTROL message. In this 797 case, REPORT messages may be sent after the original transaction or 798 extended transaction has completed. 800 All REPORT messages MUST contain the same transaction ID in the 801 request start line that was present in the original CONTROL 802 transaction. This allows both extended transactions and event 803 notifications to be correlated with the original CONTROL transaction. 805 8.1.2.1. Reporting the Status of Extended Transactions 807 On receiving a CONTROL message, a Control Server MUST respond within 808 Command-Timeout with a status code for the request, as specified in 809 Section 8.2. If the command completed within that time, a 200 810 response code would have been sent. If the command did not complete 811 within that time, the response code 202 would have been sent 812 indicating that the requested command is still being processed and 813 the CONTROL transaction is being extended. The REPORT method is used 814 to update the status of the extended transaction. 816 A Control Server issuing a 202 response MUST immediately issue a 817 REPORT message. The initial REPORT message MUST contain a 'Seq' 818 (Sequence) message header with a value equal to '1' (It should be 819 noted that the 'Seq' numbers at both Control Client Control Server 820 for framework messages are independent). The initial REPORT message 821 MUST also contain a 'Status' message header with a value of 822 'pending'. This initial REPORT message MUST NOT contain a message 823 body and is primarily used to establish a subsequent message 824 transaction based on the initial CONTROL message. 826 All REPORT messages for an extended CONTROL transaction MUST contain 827 a 'Timeout' message header. This header will contain a value in 828 delta seconds that represents the amount of time the recipient of the 829 REPORT message must wait before assuming that there has been a 830 problem and terminating the extended transaction and associated 831 state. On receiving a REPORT message with a 'Status' header of 832 'pending' or 'update', the Control Client MUST reset the counter for 833 the associated extended CONTROL transaction to the indicated timeout 834 period. If the timeout period approaches with no intended REPORT 835 messages being generated, the entity acting as a Control Framework 836 UAS for the interaction MUST generate a REPORT message containing, as 837 defined in this paragraph, a 'Status' header of 'pending'. Such a 838 message acts as a timeout refresh and in no way impacts the extended 839 transaction, because no message body or semantics are permitted. It 840 is RECOMMENDED that a minimum value of 10 and a maximum of ?? is used 841 for the value of the 'Timeout' message header. It is also 842 RECOMMENDED that a Control Server refresh the timeout period of the 843 CONTROL transaction at an interval that is not too close to the 844 expiry time. A value of 80% of the timeout period could be used, for 845 example a timeout period of 10 seconds would be refreshed after 8 846 seconds. 848 Subsequent REPORT messages that provide additional information 849 relating to the extended CONTROL transaction MUST also include and 850 increment by 1 the 'Seq' header value. They MUST also include a 851 'Status' header with a value of 'update'. These REPORT messages sent 852 to update the extended CONTROL transaction status MAY contain a 853 message body, as defined by individual Control Packages and specified 854 in Section 9.5. A REPORT message sent updating the extended 855 transaction also acts as a timeout refresh, as described earlier in 856 this section. This will result in a transaction timeout period at 857 the initiator of the request being reset to the interval contained in 858 the 'Timeout' message header. 860 When all processing for an extended CONTROL transaction has taken 861 place, the entity acting as a Control Server MUST send a terminating 862 REPORT message. The terminating REPORT message MUST increment the 863 value in the 'Seq' message header by the value of '1' from the 864 previous REPORT message. It MUST also include a 'Status' header with 865 a value of 'terminate' and MAY contain a message body. A Control 866 Framework UAC can then clean up any pending state associated with the 867 original control transaction. 869 8.1.2.2. Reporting Asynchronous Events 871 Commands that are carried in CONTROL messages can request that the 872 Server notify the Client about events that occur sometime in the 873 future. It is not desirable to use extended Control transactions for 874 these types of commands for two reasons. First, an event never 875 occurring is often correct behavior. Second, events may occur long 876 after the original request for their notification. 878 REPORT messages can be used to notify events. REPORT messages that 879 notify events MUST contain a 'Status' header of 'Notify'. They MUST 880 NOT contain either a 'Timeout' or 'Seq' header and any such headers 881 MUST be ignored when the REPORT message has a 'Status' of 'notify'. 882 The REPORT message MAY contain a message body. 884 8.2. Constructing Responses 886 A Control Client or Server, on receiving a request, MUST generate a 887 response within Command-Time time. The response MUST conform to the 888 ABNF defined in Section 12. The first line of the response MUST 889 contain the transaction identifier used in first line of the request, 890 as defined in Section 8.1. Responses MUST NOT include the 'Status' 891 or 'Timeout' message headers - if they are included they have no 892 meaning or semantics. 894 A Control Client or Server MUST then include a status code in the 895 first line of the constructed response. A CONTROL request that has 896 been understood, and either the relevant actions for the control 897 command have completed or a control command error is detected, uses 898 the 200 status code as defined in Section 9.1. A 200 response MAY 899 include message bodies. If a 200 response does contain a payload it 900 MUST include a Content-Length header. A 200 is the only response 901 defined in this specification that allows a message body to be 902 included. A client receiving a 200 class response then considers the 903 control command completed. A CONTROL request that is received and 904 understood but requires processing that extends beyond Command-Time 905 time will return a 202 status code in the response. This will be 906 followed immediately by an initial REPORT message as defined in 907 Section 8.1.2. A Control Package SHOULD explicitly define the 908 circumstances under which either 200 or 202 with subsequent 909 processing takes place. 911 If a Control Client or Server encounters problems with either a 912 REPORT or CONTROL request, an appropriate error code should be used 913 in the response, as listed in Section 9. The generation of a non 2xx 914 class response code to either a CONTROL or REPORT message will result 915 in failure of the transaction, and all associated state and resources 916 should be terminated. The response code may provide an explicit 917 indication of why the transaction failed, which might result in a re- 918 submission of the request. 920 [timm]: how can an error response provide an explicit indication of 921 the reason for the transaction failure when only a 200 response 922 allows message bodies? 924 9. Response Code Descriptions 926 The following response codes are defined for transaction responses to 927 methods defined in Section 8.1. All response codes in this section 928 MUST be supported and can be used in response to both CONTROL and 929 REPORT messages except that a 202 MUST NOT be generated in response 930 to a REPORT message. 932 Note that these response codes apply to framework transactions only. 933 Success or error indications for control commands MUST be treated as 934 the result of a control command and returned in either a 200 response 935 or REPORT message. 937 9.1. 200 Response Code 939 The 200 code indicates the completion of a successful transaction. 941 9.2. 202 Response Code 943 The 202 response code indicates the completion of a successful 944 transaction with additional information to be provided at a later 945 time through the REPORT mechanism defined in Section 8.1.2. 947 9.3. 400 Response Code 949 The 400 response indicates that the request was syntactically 950 incorrect. 952 9.4. 403 Response Code 954 The 400 response indicates that the requested operation is illegal. 956 9.5. 481 Response Code 958 The 481 response indicates that the intended target of the request 959 does not exist. 961 9.6. 500 Response Code 963 The 500 response indicates that the recipient does not understand the 964 request 966 10. Control Packages 968 "Control Packages" are intended to specify behavior that extends the 969 the capability defined in this document. "Control Packages" are not 970 allowed to weaken "MUST" and "SHOULD" strength statements that are 971 detailed in this document. A "Control Package" may strengthen 972 "SHOULD" to "MUST" if justified by the specific usage of the 973 framework. 975 In addition to normal sections expected in a standards-track RFC and 976 SIP extension documents, authors of "Control Packages" need to 977 address each of the issues detailed in the following subsections. 978 The following sections MUST be used as a template and included 979 appropriately in all Control-Packages. 981 10.1. Control Package Name 983 This section MUST be present in all extensions to this document and 984 provides a token name for the Control Package. The section MUST 985 include information that appears in the IANA registration of the 986 token. Information on registering control package event tokens is 987 contained in Section 15. The package name MUST also register a 988 version number for the package. This enables updates to the package 989 to be registered where appropriate. An initial version of a package 990 MUST start with the value '1.0'. Subsequent versions MUST increment 991 this number if the same package name is to be used. The exact 992 increment is left to the discretion of the package author. 994 10.2. Framework Message Usage 996 The Control Framework defines a number of message primitives that can 997 be used to exchange commands and information. There are no 998 limitations restricting the directionality of messages passed down a 999 control channel. This section of a Control package document should 1000 explicitly detail the control messages that can be used as well as 1001 provide an indication of directionality between entities. This will 1002 include which role type is allowed to initiate a request type. 1004 [Editors Note: Need to examine text.] 1006 10.3. Common XML Support 1008 This optional section is only included in a Control Package if the 1009 attributes for media dialog or Conference reference are required. 1010 The Control Package will make strong statements (MUST strength) if 1011 the XML schema defined in Section 17.1 in Appendix A is to be 1012 supported. If only part of the schema is required (for example just 1013 'connection-id' or just conf-id), the Control Package will make 1014 equally strong (MUST strength) statements. 1016 10.4. CONTROL Message Bodies 1018 This mandatory section of a Control Package defines the control body 1019 that can be contained within a CONTROL command request, as defined in 1020 Section 8 (or that no control package body is required). This 1021 section should indicate the location of detailed syntax definitions 1022 and semantics for the appropriate body types. 1024 10.5. REPORT Message Bodies 1026 This mandatory section of a Control Package defines the REPORT body 1027 that can be contained within a REPORT command request, as defined in 1028 Section 8 (or that no report package body is required). This section 1029 should indicate the location of detailed syntax definitions and 1030 semantics for the appropriate body types. It should be noted that 1031 the Control Framework specification does allow for payloads to exist 1032 in 200 responses to CONTROL messages (as defined in this document). 1033 An entity that is prepared to receive a payload type in a REPORT 1034 message MUST also be prepared to receive the same payload in a 200 1035 response to a CONTROL message. 1037 10.5.1. Events 1039 A Control Package can optionally include one or more subscriptions 1040 that allow a controlling client to receive specific event updates in 1041 REPORT message bodies. The mechanisms that installs/un-installs 1042 subscriptions is not specified in document and is considered out of 1043 scope. Event notifications are always carried in REPORT messages 1044 MUST conform to the rules detailed in Section 8.1.2.2. This section 1045 of a Control Package definition MUST specify details of the payload 1046 expected to be received from subscriptions that have been installed. 1048 [Editors Note: Ongoing discussions relating to a generic 1049 subscription/event mechanism across all packages.] 1051 10.6. Examples 1053 It is strongly RECOMMENDED that Control Packages provide a range of 1054 message flows that represent common flows using the package and this 1055 framework document. 1057 11. Network Address Translation (NAT) 1059 [Editors Note: This section will look at geographically distributed 1060 systems where NAT traversal might be an issue. It will look at both 1061 the SIP media dialog traversal and the control channel traversal.] 1063 12. Formal Syntax 1065 12.1. SIP Formal Syntax 1067 The ABNF for the "Control-Packages" SIP header is as follows: 1069 Control-Packages = "Control-Packages" HCOLON control-package-value 1070 *(COMMA control-package-value) *( SEMI package-params ) 1071 control-package-value = control-package-name "/" control-package-version 1072 control-package-name = token 1073 control-package-version = 1*DIGIT "." 1*DIGIT 1074 package-params = k-alive-param *(SEMI extension-param) 1075 k-alive-param = "keep-alive" EQUAL delta-seconds 1076 delta-seconds = 1*DIGIT 1077 extension-param = generic-param 1079 12.2. Control Framework Formal Syntax 1081 The Control Framework interactions use the UTF-8 transformation 1082 format as defined in RFC3629 [16]. The syntax in this section uses 1083 the Augmented Backus-Naur Form (ABNF) as defined in RFC2234 [17]. 1085 control-req-or-resp = control-request / control-response 1086 control-request = control-req-start headers [control-content] 1087 control-response = control-resp-start headers 1088 control-req-start = pSCFW SP transact-id SP method CRLF 1089 control-resp-start = pSCFW SP transact-id SP status-code [SP comment] CRLF 1090 comment = utf8text 1092 pSCFW = %x53.43.46.57; SCFW in caps 1093 transact-id = alpha-num-token 1094 method = mCONTROL / mREPORT / mSYNCH / mK-ALIVE / other-method 1095 mCONTROL = %x43.4F.4E.54.52.4F.4C; CONTROL in caps 1096 mREPORT = %x52.45.50.4F.52.54; REPORT in caps 1097 mSYNCH = %x53.59.4E.43.48; SYNCH in caps 1098 mK-ALIVE = %x4B.2D.41.4C.49.56.45;K-ALIVE in caps 1100 other-method = 1*UPALPHA 1101 status-code = 3DIGIT ; any code defined in this and other documents 1103 headers = Content-Length 1104 /Control-Package 1105 /Status 1106 /Seq 1107 /Timeout 1108 /Dialog-id 1109 /ext-header 1111 Content-Length = "Content-Length:" SP 1*DIGIT 1112 Control-Package = "Control-Package:" SP 1*alpha-num-token 1113 Status = "Status:" SP ("pending" / "update" / "terminate" ) 1114 Timeout = "Timeout:" SP 1*DIGIT 1115 Seq = "Seq:" SP 1*DIGIT 1116 Dialog-id = "Dialog-id:" SP dialog-id-string 1118 dialog-id-string = alpha-num-token "~" alpha-num-token ["~" alpha-num-token] 1120 alpha-num-token = alphanum 3*31alpha-num-tokent-char 1121 alpha-num-tokent-char = alphanum / "." / "-" / "+" / "%" / "=" 1123 control-content = Content-Type 2CRLF data CRLF 1125 Content-Type = "Content-Type:" SP media-type 1126 media-type = type "/" subtype *( ";" gen-param ) 1127 type = token 1128 subtype = token 1130 gen-param = pname [ "=" pval ] 1131 pname = token 1132 pval = token / quoted-string 1134 token = 1*(%x21 / %x23-27 / %x2A-2B / %x2D-2E 1135 / %x30-39 / %x41-5A / %x5E-7E) 1136 ; token is compared case-insensitive 1138 quoted-string = DQUOTE *(qdtext / qd-esc) DQUOTE 1139 qdtext = SP / HTAB / %x21 / %x23-5B / %x5D-7E 1140 / UTF8-NONASCII 1141 qd-esc = (BACKSLASH BACKSLASH) / (BACKSLASH DQUOTE) 1142 BACKSLASH = "\" 1143 UPALPHA = %x41-5A 1144 ALPHANUM = ALPHA / DIGIT 1146 data = *OCTET 1147 ext-header = hname ":" SP hval CRLF 1149 hname = ALPHA *token 1150 hval = utf8text 1152 utf8text = *(HTAB / %x20-7E / UTF8-NONASCII) 1154 UTF8-NONASCII = %xC0-DF 1UTF8-CONT 1155 / %xE0-EF 2UTF8-CONT 1156 / %xF0-F7 3UTF8-CONT 1157 / %xF8-Fb 4UTF8-CONT 1158 / %xFC-FD 5UTF8-CONT 1159 UTF8-CONT = %x80-BF 1161 The following table details a summary of the headers that can be 1162 contained in Control Framework interactions. The "where" columns 1163 details where headers can be used: 1165 R: header field may only appear in requests; 1167 r: header field may only appear in responses; 1169 2xx, 4xx, etc.: A numerical value or range indicates response 1170 codes with which the header field can be used; 1172 An empty entry in the "where" column indicates that the header 1173 field may be present in all requests and responses. 1175 The remaining columns list the specified methods and the presence of 1176 a specific header: 1178 m: The header field is mandatory. 1179 o: The header field is optional. 1181 Header field Where CONTROL REPORT SYNCH 1182 ___________________________________________________ 1183 Content-Length o o - 1184 Control-Package R m - - 1185 Seq - m - 1186 Status R - m - 1187 Timeout R - m - 1188 Dialog-id R - - m 1190 Figure 11: Table 1 1192 13. Examples 1194 The following examples provide an abstracted flow of Control Channel 1195 establishment and Control Framework message exchange. The SIP 1196 signaling is prefixed with the token 'SIP'. All other messages are 1197 Control Framework interactions defined in this document. 1199 Control Client Control Server 1200 | | 1201 | (1) SIP INVITE | 1202 | ----------------------------------------> | 1203 | | 1204 | (2) SIP 200 | 1205 | <--------------------------------------- | 1206 | | 1207 | (3) SIP ACK | 1208 | ----------------------------------------> | 1209 | | 1210 |==>=======================================>==| 1211 | Control Channel Established | 1212 |==>=======================================>==| 1213 | | 1214 | (4) SYNCH | 1215 | ----------------------------------------> | 1216 | | 1217 | (5) 200 | 1218 | <--------------------------------------- | 1219 | | 1220 | (6) CONTROL | 1221 | ----------------------------------------> | 1222 | | 1223 | (7) 202 | 1224 | <--------------------------------------- | 1225 | | 1226 | (8) REPORT (pending) | 1227 | <---------------------------------------- | 1228 | | 1229 | (9) 200 | 1230 | ----------------------------------------> | 1231 | | 1232 | (10) REPORT (update) | 1233 | <---------------------------------------- | 1234 | | 1235 | (11) 200 | 1236 | ----------------------------------------> | 1237 | | 1238 | (12) REPORT (terminate) | 1239 | <---------------------------------------- | 1240 | | 1241 | (13) 200 | 1242 | ----------------------------------------> | 1243 | | 1244 | (14) SIP BYE | 1245 | ----------------------------------------> | 1246 | | 1247 | (15) SIP 200 | 1248 | <--------------------------------------- | 1249 |=============================================| 1250 | Control Channel Terminated | 1251 |=============================================| 1252 | | 1254 1. Control Client->Control Server (SIP): INVITE 1255 sip:control-server@example.com 1257 INVITE sip:control-server@example.com SIP/2.0 1258 To: 1259 From: ;tag=8937498 1260 Via: SIP/2.0/UDP control-client.example.com;branch=z9hG412345678 1261 CSeq: 1 INVITE 1262 Require: escs 1263 Control-Packages: 1264 Call-ID: 893jhoeihjr8392@example.com 1265 Contact: 1266 Content-Type: application/sdp 1268 v=0 1269 o=originator 2890844526 2890842808 IN IP4 controller.example,com 1270 s=- 1271 c=IN IP4 control-client.example.com 1272 m=application 7575 TCP/ESCS 1273 a=setup:active 1274 a=connection:new 1276 2. Control Server->Control Client (SIP): 200 OK 1278 SIP/2.0 200 OK 1279 To: ;tag=023983774 1280 From: ;tag=8937498 1281 Via: SIP/2.0/UDP control-client.example.com;branch=z9hG412345678 1282 CSeq: 1 INVITE 1283 Require: escs 1284 Control-Packages: 1285 Call-ID: 893jhoeihjr8392@example.com 1286 Contact: 1287 Content-Type: application/sdp 1289 v=0 1290 o=originator 2890844526 2890842808 IN IP4 controller.example,com 1291 s=- 1292 c=IN IP4 control-server.example.com 1293 m=application 7575 TCP/ESCS 1294 a=setup:passive 1295 a=connection:new 1297 3. Control Client->Control Server (SIP): ACK 1298 4. Control Client opens a TCP connection to the Control Server. 1299 The connection can now be used to exchange control framework 1300 messages. Control Client-->Control Server (Control Framework 1301 Message): SYNCH. 1303 SCFW 8djae7khauj SYNCH 1304 Dialog-id: 8937498~893jhoeihjr8392@example.com~023983774 1306 5. Control Server-->Control Client (Control Framework Message): 1307 200. 1309 SCFW 8djae7khauj 200 1311 6. Control Client opens a TCP connection to the Control Server. 1312 The connection can now be used to exchange control framework 1313 messages. Control Client-->Control Server (Control Framework 1314 Message): CONTROL. 1316 SCFW i387yeiqyiq CONTROL 1317 Control-Package: 1318 Content-Length: 11 1320 1322 7. Control Server-->Control Client (Control Framework Message): 1323 202. 1325 SCFW i387yeiqyiq 202 1327 8. Control Server-->Control Client (Control Framework Message): 1328 REPORT. 1330 SCFW i387yeiqyiq REPORT 1331 Seq: 1 1332 Status: pending 1333 Timeout: 10 1335 9. Control Client-->Control Server (Control Framework Message): 1336 200. 1338 SCFW i387yeiqyiq 200 1339 Seq: 1 1341 10. Control Server-->Control Client (Control Framework Message): 1342 REPORT. 1344 SCFW i387yeiqyiq REPORT 1345 Seq: 2 1346 Status: update 1347 Timeout: 10 1349 1350 11. Control Client-->Control Server (Control Framework Message): 1351 200. 1353 SCFW i387yeiqyiq 200 1354 Seq: 2 1356 12. Control Server-->Control Client (Control Framework Message): 1357 REPORT. 1359 SCFW i387yeiqyiq REPORT 1360 Seq: 3 1361 Status: terminate 1362 Timeout: 10 1364 1366 13. Control Client-->Control Server (Control Framework Message): 1367 200. 1369 SCFW i387yeiqyiq 200 1370 Seq: 3 1372 14. Control Client->Control Server (SIP): BYE 1374 BYE sip:control-client@pc2.example.com SIP/2.0 1375 To: 1376 From: ;tag=8937498 1377 Via: SIP/2.0/UDP control-client.example.com;branch=z9hG423456789 1378 CSeq: 2 BYE 1379 Require: escs 1380 Control-Packages: 1381 Call-ID: 893jhoeihjr8392@example.com 1383 15. Control Server->Control Client (SIP): 200 OK 1385 SIP/2.0 200 OK 1386 To: ;tag=023983774 1387 From: ;tag=8937498 1388 Via: SIP/2.0/UDP control-client.example.com;branch=z9hG423456789 1389 CSeq: 2 BYE 1390 Require: escs 1391 Control-Packages: 1392 Call-ID: 893jhoeihjr8392@example.com 1394 14. Security Considerations 1396 Security Considerations to be included in later versions of this 1397 document. 1399 15. IANA Considerations 1401 15.1. IANA Registration of the 'escs' Option Tag 1403 15.2. Control Package Registration Information 1405 15.2.1. Control Package Registration Template 1407 15.3. SDP Transport Protocol 1409 15.3.1. TCP/ESCS 1411 15.3.2. TCP/TLS/ESCS 1413 15.4. SDP Attribute Names 1415 15.5. SIP Response Codes 1417 16. Acknowledgments 1419 The authors would like to thank Ian Evans and Michael Bardzinski of 1420 Ubiquity Software, Adnan Saleem of Convedia, and Dave Morgan for 1421 useful review and input to this work. Eric Burger contributed to the 1422 early phases of this work. 1424 17. Appendix A 1426 During the creation of the Control Framework it has become clear that 1427 there are number of components that are common across multiple 1428 packages. It has become apparent that it would be useful to collect 1429 such re-usable components in a central location. In the short term 1430 this appendix provides the place holder for the utilities and it is 1431 the intention that this section will eventually form the basis of an 1432 initial 'Utilities Document' that can be used by Control Packages. 1434 17.1. Common Dialog/Multiparty Reference Schema 1436 The following schema provides some common attributes for allowing 1437 Control Packages to apply specific commands to a particular SIP media 1438 dialog (also referred to as Connection) or conference. If used 1439 within a Control Package the Connection and multiparty attributes 1440 will be imported and used appropriately to specifically identify 1441 either a SIP dialog or a conference instance. If used within a 1442 package, the value contained in the 'connection-id' attribute MUST be 1443 constructed by concatenating the 'Local' and 'Remote' SIP dialog 1444 identifier tags as defined in RFC3261 [2]. They MUST then be 1445 separated using the '~' character. So the format would be: 1447 'Local Dialog tag' + '~' + 'Remote Dialog tag' 1449 As an example, for an entity that has a SIP Local dialog identifier 1450 of '7HDY839' and a Remote dialog identifier of 'HJKSkyHS', the 1451 'connection-id' attribute for a Control Framework command would be: 1453 7HDY839~HJKSkyHS 1455 If a session description has more than one media description (as 1456 identified by 'm=' in [9]) it is possible to explicitly reference 1457 them individually. When constructing the 'connection-id' attribute 1458 for a command that applies to a specific media ('m=') in an SDP 1459 description, an optional third component can be concatenated to the 1460 Connection reference key. It is again separated using the '~' 1461 character and uses the 'label' attribute as specified in [10]. So 1462 the format would be: 1464 'Local Dialog tag' + '~' + 'Remote Dialog tag' + '~' + 'Label Attribute' 1466 As an example, for an entity that has a SIP Local dialog identifier 1467 of '7HDY839', a Remote dialog identifier of 'HJKSkyHS' and an SDP 1468 label attribute of 'HUwkuh7ns', the 'connection-id' attribute for a 1469 Control Framework command would be: 1471 7HDY839~HJKSkyHS~HUwkuh7ns 1473 It should be noted that Control Framework requests initiated in 1474 conjunction with a SIP dialog will produce a different 1475 'connection-id' value depending on the directionality of the request, 1476 for example Local and Remote tags are locally identifiable. 1478 As with the Connection attribute previously defined, it is also 1479 useful to have the ability to apply specific control framework 1480 commands to a number of related dialogs, such as a multiparty call. 1481 This typically consists of a number of media dialogs that are 1482 logically bound by a single identifier. The following schema allows 1483 for control framework commands to explicitly reference such a 1484 grouping through a 'conf' XML container. If used by a Control 1485 Package, any control XML referenced by the attribute applies to all 1486 related media dialogs. Unlike the dialog attribute, the 'conf-id' 1487 attribute does not need to be constructed based on the overlying SIP 1488 dialog. The 'conf-id' attribute value is system specific and should 1489 be selected with relevant context and uniqueness. 1491 The full schema follows: 1493 1494 1498 1500 1501 1502 SIP Connection and Conf Identifiers 1503 1505 1506 1508 1509 1511 18. References 1513 18.1. Normative References 1515 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 1516 Levels", BCP 14, RFC 2119, March 1997. 1518 18.2. Informative References 1520 [2] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 1521 Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: 1522 Session Initiation Protocol", RFC 3261, June 2002. 1524 [3] Rosenberg, J. and H. Schulzrinne, "Reliability of Provisional 1525 Responses in Session Initiation Protocol (SIP)", RFC 3262, 1526 June 2002. 1528 [4] Rosenberg, J. and H. Schulzrinne, "Session Initiation Protocol 1529 (SIP): Locating SIP Servers", RFC 3263, June 2002. 1531 [5] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model with 1532 Session Description Protocol (SDP)", RFC 3264, June 2002. 1534 [6] Yon, D. and G. Camarillo, "TCP-Based Media Transport in the 1535 Session Description Protocol (SDP)", RFC 4145, September 2005. 1537 [7] Groves, C., Pantaleo, M., Anderson, T., and T. Taylor, "Gateway 1538 Control Protocol Version 1", RFC 3525, June 2003. 1540 [8] Dolly, M., "Media Control Protocol Requirements", 1541 draft-dolly-xcon-mediacntrlframe-02 (work in progress), 1542 September 2006. 1544 [9] Handley, M., "SDP: Session Description Protocol", 1545 draft-ietf-mmusic-sdp-new-26 (work in progress), January 2006. 1547 [10] Levin, O. and G. Camarillo, "The SDP (Session Description 1548 Protocol) Label Attribute", 1549 draft-ietf-mmusic-sdp-media-label-01 (work in progress), 1550 January 2005. 1552 [11] Jennings, C. and R. Mahy, "Managing Client Initiated 1553 Connections in the Session Initiation Protocol (SIP)", 1554 draft-ietf-sip-outbound-07 (work in progress), January 2007. 1556 [12] Rosenberg, J., Peterson, J., Schulzrinne, H., and G. Camarillo, 1557 "Best Current Practices for Third Party Call Control (3pcc) in 1558 the Session Initiation Protocol (SIP)", BCP 85, RFC 3725, 1559 April 2004. 1561 [13] Rosenberg, J., Schulzrinne, H., and P. Kyzivat, "Indicating 1562 User Agent Capabilities in the Session Initiation Protocol 1563 (SIP)", RFC 3840, August 2004. 1565 [14] Rosenberg, J., Schulzrinne, H., and P. Kyzivat, "Caller 1566 Preferences for the Session Initiation Protocol (SIP)", 1567 RFC 3841, August 2004. 1569 [15] Schulzrinne, H., Casner, S., Frederick, R., and V. Jacobson, 1570 "RTP: A Transport Protocol for Real-Time Applications", STD 64, 1571 RFC 3550, July 2003. 1573 [16] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 1574 STD 63, RFC 3629, November 2003. 1576 [17] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1577 Specifications: ABNF", RFC 2234, November 1997. 1579 Authors' Addresses 1581 Chris Boulton 1582 Ubiquity Software Corporation 1583 Building 3 1584 Wern Fawr Lane 1585 St Mellons 1586 Cardiff, South Wales CF3 5EA 1588 Email: cboulton@ubiquitysoftware.com 1590 Tim Melanchuk 1591 BlankSpace 1593 Email: tim.melanchuk@gmail.com 1595 Scott McGlashan 1596 Hewlett-Packard 1597 Gustav III:s boulevard 36 1598 SE-16985 Stockholm, Sweden 1600 Email: scott.mcglashan@hp.com 1602 Asher Shiratzky 1603 Radvision 1604 24 Raoul Wallenberg st 1605 Tel-Aviv, Israel 1607 Email: ashers@radvision.com 1609 Full Copyright Statement 1611 Copyright (C) The IETF Trust (2007). 1613 This document is subject to the rights, licenses and restrictions 1614 contained in BCP 78, and except as set forth therein, the authors 1615 retain all their rights. 1617 This document and the information contained herein are provided on an 1618 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1619 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1620 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1621 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1622 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1623 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1625 Intellectual Property 1627 The IETF takes no position regarding the validity or scope of any 1628 Intellectual Property Rights or other rights that might be claimed to 1629 pertain to the implementation or use of the technology described in 1630 this document or the extent to which any license under such rights 1631 might or might not be available; nor does it represent that it has 1632 made any independent effort to identify any such rights. Information 1633 on the procedures with respect to rights in RFC documents can be 1634 found in BCP 78 and BCP 79. 1636 Copies of IPR disclosures made to the IETF Secretariat and any 1637 assurances of licenses to be made available, or the result of an 1638 attempt made to obtain a general license or permission for the use of 1639 such proprietary rights by implementers or users of this 1640 specification can be obtained from the IETF on-line IPR repository at 1641 http://www.ietf.org/ipr. 1643 The IETF invites any interested party to bring to its attention any 1644 copyrights, patents or patent applications, or other proprietary 1645 rights that may cover technology that may be required to implement 1646 this standard. Please address the information to the IETF at 1647 ietf-ipr@ietf.org. 1649 Acknowledgment 1651 Funding for the RFC Editor function is provided by the IETF 1652 Administrative Support Activity (IASA).