Internet Engineering Task Force SIPPING WG Internet Draft J. Rosenberg dynamicsoft H. Schulzrinne Columbia U. draft-ietf-sipping-conference-package-00.txt June 24, 2002 Expires: December 2002 A Session Initiation Protocol (SIP) Event Package for Conference State STATUS OF THIS MEMO This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress". The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt To view the list Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html. Abstract This document defines a conference event package for the SIP Events architecture, along with a data format used in notifications for this package. The conference package allows users to subscribe to a SIP URI that is associated with a conference. Notifications are sent about changes in the membership of this conference, changes in active speaker, and media mixing information. J. Rosenberg et. al. [Page 1] Internet Draft Conference Package June 24, 2002 Table of Contents 1 Introduction ........................................ 4 2 Terminology ......................................... 4 3 Conference Event Package ............................ 4 3.1 Event Package Name .................................. 5 3.2 Event Package Parameters ............................ 5 3.3 SUBSCRIBE Bodies .................................... 5 3.4 Subscription Duration ............................... 6 3.5 NOTIFY Bodies ....................................... 6 3.6 Notifier Processing of SUBSCRIBE Requests ........... 6 3.7 Notifier Generation of NOTIFY Requests .............. 6 3.8 Subscriber Processing of NOTIFY Requests ............ 6 3.9 Handling of Forked Requests ......................... 7 3.10 Rate of Notifications ............................... 7 3.11 State Agents ........................................ 7 4 Conference Data Format .............................. 7 4.1 Structute of the Format ............................. 8 4.1.1 User Element ........................................ 8 4.1.2 Status .............................................. 9 4.1.3 Dialog .............................................. 9 4.1.4 Media Status ........................................ 9 4.2 Constructing Coherent State ......................... 9 4.3 Schema .............................................. 10 4.4 Example ............................................. 13 5 Security Considerations ............................. 13 6 IANA Considerations ................................. 13 6.1 application/conference-info+xml MIME Registration ................................................................ 13 6.2 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:conference-info ......................... 14 7 Acknowledgements .................................... 15 8 Authors Addresses ................................... 15 9 Normative References ................................ 15 10 Informative References .............................. 16 J. Rosenberg et. al. [Page 2] Internet Draft Conference Package June 24, 2002 1 Introduction The SIP Events framework [1] defines general mechanisms for subscription to, and notification of, events within SIP networks. It introduces the notion of a package, which is a specific "instantiation" of the events mechanism for a well-defined set of events. Packages have been defined for user presence [9], watcher information [10], and message waiting indicators [11], amongst others. Here, we define an event package for SIP conferences. This package will work for any conference in which there is a central signaling element [12]. The conferencing package allows a subscriber to learn about the identities of participants and their status in the conference, the dialogs that are used by each user, the media makeup of the conference, and the mixing matrix (i.e., who is receiving whose audio). This information is vital to building conferencing applications using SIP. 2 Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [2] and indicate requirement levels for compliant implementations. 3 Conference Event Package The conference event package allows a user to subscribe to a conference. In SIP, conferences are represented by URIs. These URIs route to a SIP user agent that is responsible for ensuring that all users in the conference can communicate with each other. Detailed information on conferencing models can be found in [12]. This package can work with any of the tightly-coupled models described in that specification. However, the conference server may not have complete information on the media makeup of the conference. This is the case for multicast-based conferences, where the server cannot know the mixing matrix for the conference. In this case, that information would simply not be reported through this package. The specific information conveyed in notifications in this package is: o The SIP URI identifying the user. o The dialog state associated with that users attachment to the conference. J. Rosenberg et. al. [Page 4] Internet Draft Conference Package June 24, 2002 o Their status in the conference (active, declined, departed). o Their status in terms of receiving media in the conference. This section provides the details for defining a SIP Events package, as specified by [1]. 3.1 Event Package Name The name of this event package is "conference". This package name is carried in the Event and Allow-Events header, as defined in [1]. 3.2 Event Package Parameters A single parameter, "recurse" is defined for this package. When present, it informs the server that it should check whether any participants in the conference are themselves conferences, and if so, generate a subscription to their conference state with the "recurse" attribute. The users reported in notifications from this recursed subscription are reported to the original subscriber. The result is that the list of users reported to the subscriber represents the complete user list even when cascaded conferences are used. Example: Event: conference;recurse 3.3 SUBSCRIBE Bodies A SUBSCRIBE for a dialog package MAY contain a body. This body defines a filter to apply to the subscription. A SUBSCRIBE for a conference package MAY be sent without a body. This implies the default subscription filtering policy. The default policy is: o Notifications are generated every time there is any change in the set of users participating in the conference, or a change their state (dialog state, media mixing state, etc.) o Notifications do not normally contain full state; rather, they only indicate the state of the participant whose state has changed. The exception is a NOTIFY sent in response to a SUBSCRIBE. These NOTIFYs contain the complete view of conference state. J. Rosenberg et. al. [Page 5] Internet Draft Conference Package June 24, 2002 o For a given user, the notifications contain the identity information and status. 3.4 Subscription Duration The default expiration time for a subscription to a conference is one hour. Of course, once the conference ends, all subscriptions to that particular conference are terminated, with a reason of "noresource" [1]. 3.5 NOTIFY Bodies The body of the notification contains a conference information document. All implementations MUST support the type "application/conference-info+xml", defined in Section 4. Other formats MAY be supported. When a client generates a SUBSCRIBE request, and that request contains an Accept header, the "application/conference-info+xml" format MUST be included in the header. Other formats MAY be listed. The default value for the Accept header when it is not present in a request is "application/conference-info+xml". Of course, the notifications generated by the server MUST be in one of the formats specified in the Accept header in the SUBSCRIBE request. 3.6 Notifier Processing of SUBSCRIBE Requests The conference information contains very sensitive information. Therefore, all subscriptions SHOULD be authenticated and then authorized before approval. Authorization policy is at the discretion of the administrator, as always. However, a few recommendations can be made. It is RECOMMENDED that all users in the conference be allowed to subscribe to the conference. 3.7 Notifier Generation of NOTIFY Requests Notifications SHOULD be generated for the conference whenever a new participant joins, a participant leaves, and a dial-out attempt succeeds or fails. Notifications MAY be generated for the conference whenever the media mixing status of a user changes. 3.8 Subscriber Processing of NOTIFY Requests The SIP Events framework expects packages to specify how a subscriber J. Rosenberg et. al. [Page 6] Internet Draft Conference Package June 24, 2002 processes NOTIFY requests in any package specific ways, and in particular, how it uses the NOTIFY requests to contruct a coherent view of the state of the subscribed resource. Typically, the NOTIFY for the conference package will only contain information about those users whose state in the conference has changed. To construct a coherent view of the total state of all users, a subscriber to the dialog package will need to combine NOTIFYs received over time. Notifications within this package can convey partial information; that is, they can indicate information about a subset of the state associated with the subscription. This means that an explicit algorithm needs to be defined in order to construct coherent and consistent state. The details of this mechanism are specific to the particular document type. See Section 4.2 for information on constructing coherent information from an application/conference- info+xml document. 3.9 Handling of Forked Requests By their nature, the conferences supported by this package are centralized. Therefore, SUBSCRIBE requests for a conference should not generally fork. Users of this package MUST NOT install more than a single subscription as a result of a single SUBSCRIBE request. 3.10 Rate of Notifications For reasons of congestion control, it is important that the rate of notifications not become excessive. As a result, it is RECOMMENDED that the server not generate notifications for a single subscriber at a rate faster than once every 5 seconds. 3.11 State Agents Conference state is ideally maintained in the element in which the conference resides. Therefore, the elements that maintain the conference are the ones best suited to handle subscriptions to it. Therefore, the usage of state agents is NOT RECOMMENDED for this package. 4 Conference Data Format Conference information is an XML document [3] that MUST be well- formed and SHOULD be valid. Dialog information documents MUST be based on XML 1.0 and MUST be encoded using UTF-8. This specification makes use of XML namespaces for identifying dialog information documents and document fragments. The namespace URI for elements J. Rosenberg et. al. [Page 7] Internet Draft Conference Package June 24, 2002 defined by this specification is a URN [4], using the namespace identifier 'ietf' defined by [5] and extended by [6]. This URN is: urn:ietf:params:xml:ns:conference-info A conference information document begins with the root element tag "conference-info". 4.1 Structute of the Format Conference information begins with the top level element "conference-info". This element has three mandatory attributes: version: This attribute allows the recipient of conference information documents to properly order them. Versions start at 0, and increment by one for each new document sent to a subscriber. Versions are scoped within a subscription. Versions MUST be representable using a 32 bit integer. state: This attribute indicates whether the document contains the full conference information, or whether it contains only information on those users whose state have changed since the previous document (partial). entity: This attribute contains a URI that identifies the conference whose information is reported in the remainder of the document. The "conference-info" element has zero or more "user" sub-elements which contain information on the users in the conference. 4.1.1 User Element Each user element has zero or one "status" elements, indicating their status in the conference, zero or one "dialog" elements, indicating their dialog information, and zero or one "media-state" elements, indicating their media reception information. The user element has one mandatory attribute, "uri" that indicates the URI for the user in the conference. This is a logical identifier, not a machine specific one (i.e., its taken from the To/From, not the Contact). The optional attribute "display-name" contains a display name for the user. The standard "xml:lang" language attribute can also be present to indicate the language of the display name. J. Rosenberg et. al. [Page 8] Internet Draft Conference Package June 24, 2002 4.1.2 Status The status element contains the status of the user in the conference. The following statuses are defined: active: The user is in an active dialog with the conference host. departed: The user sent a BYE, thus leaving the conference. booted: The user was sent a BYE by the conference host, booting them out of the conference. failed: The server tried to bring the user into the conference, but its attempt to contact the specific user resulted in a non-200 class final response. 4.1.3 Dialog The dialog element is defined in [7]. 4.1.4 Media Status The "media-status" element indicates the types of media that the user is currently receiving in the conference. It consists of a series of "media-stream" sub-elements, each of one describes a particular media stream. Each "media-stream" element has a mandatory "media-type" attribute that indicates the MIME media type for the stream. There is also an optional "send-status" and "recv-status" attribute which attribute which indicates the status of the media to/from that user. If the "send-status" is "received-by-all", it means that the media for that stream that is being generated by the user is being mixed by the server and sent to all recipients. "muted" means that no one is receiving their media. If it is "unknown", the server does not know the status, perhaps because the media is being distributed via multicast or multi-unicast. If the "recv-status" is "receiving-all" it means that the user is hearing all other participants. If it is "anchor-only", the user is hearing media from just a single participant. If it is "unknown", the server does not know the status, perhaps because the media is being distributed via multicast or multi-unicast. 4.2 Constructing Coherent State The conference information subscriber maintains a table for the list of users in the conference. The table contains a row for each user. J. Rosenberg et. al. [Page 9] Internet Draft Conference Package June 24, 2002 Each row is indexed by a URI, present in the "uri" attribute of the "user" element. The contents of each row contain the state of that user as conveyed in the document. The table is also associated with a version number. The version number MUST be initialized with the value of the "version" attribute from the "conference-info" element in the first document received. Each time a new document is received, the value of the local version number, and the "version" attribute in the new document, are compared. If the value in the new document is one higher than the local version number, the local version number is increased by one, and the document is processed. If the value in the document is more than one higher than the local version number, the local version number is set to the value in the new document, the document is processed, and the subscriber SHOULD generate a refresh request to trigger a full state notification. If the value in the document is less than the local version, the document is discarded without processing. The processing of the conference information document depends on whether it contains full or partial state. If it contains full state, indicated by the value of the "state" attribute in the "conference- info" element, the contents of the table are flushed. They are repopulated from the document. A new row in the table is created for each "user" element. If the document contains partial state, as indicated by the value of the "state" attribute in the "conference- info" element, the document is used to update the table. For each "user" element in the document, the subscriber checks to see whether a row exists for that user. This check is done by comparing the URI in the "uri" attribute of the "user" element with the URI associated with the row. If the user doesn't exist in the table, a row is added, and its state is set to the information from that "user" element. If the user does exist, its state is updated to be the information from that "user" element. If a row is updated or created, such that its state is now booted, failed or departed, that entry MAY be removed from the table at any time. 4.3 Schema The following is the schema for the application/conference-info+xml type: J. Rosenberg et. al. [Page 10] Internet Draft Conference Package June 24, 2002 J. Rosenberg et. al. [Page 11] Internet Draft Conference Package June 24, 2002 OPEN ISSUE: We need to register the schema for the dialog info package in order to have a stable reference for it in the conference info schema above. J. Rosenberg et. al. [Page 12] Internet Draft Conference Package June 24, 2002 4.4 Example The following is an example conference information document: active active This document describes a conference with two users, both of which are active. 5 Security Considerations Subscriptions to conference state can reveal very sensitive information. For this reason, the document recommends authentication and authorization, and provides guidelines on sensible authorization policies. Since the data in notifications is sensitive as well, end-to-end SIP encryption mechanisms using S/MIME SHOULD be used to protect it. 6 IANA Considerations This document registers a new MIME type, application/conference- info+xml and registers a new XML namespace. 6.1 application/conference-info+xml MIME Registration MIME media type name: application MIME subtype name: conference-info+xml Mandatory parameters: none Optional parameters: Same as charset parameter application/xml as specified in RFC 3023 [8]. J. Rosenberg et. al. [Page 13] Internet Draft Conference Package June 24, 2002 Encoding considerations: Same as encoding considerations of application/xml as specified in RFC 3023 [8]. Security considerations: See Section 10 of RFC 3023 [8] and Section 5 of this specification. Interoperability considerations: none. Published specification: This document. Applications which use this media type: This document type has been used to support SIP conferencing applications. Additional Information: Magic Number: None File Extension: .cif or .xml Macintosh file type code: "TEXT" Personal and email address for further information: Jonathan Rosenberg, Intended usage: COMMON Author/Change controller: The IETF. 6.2 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:conference-info This section registers a new XML namespace, as per the guidelines in [6]. URI: The URI for this namespace is urn:ietf:params:xml:ns:conference-info. Registrant Contact: IETF, SIMPLE working group, , Jonathan Rosenberg . XML: BEGIN J. Rosenberg et. al. [Page 14] Internet Draft Conference Package June 24, 2002 Dialog Information Namespace

Namespace for Dialog Information

application/conference-info+xml

See RFCXXXX.

END 7 Acknowledgements The authors would like to thank Dan Petrie ans Sean Olson for their comments. 8 Authors Addresses Jonathan Rosenberg dynamicsoft 72 Eagle Rock Avenue First Floor East Hanover, NJ 07936 email: jdrosen@dynamicsoft.com Henning Schulzrinne Columbia University M/S 0401 1214 Amsterdam Ave. New York, NY 10027-7003 email: schulzrinne@cs.columbia.edu 9 Normative References [1] A. Roach, "SIP-specific event notification," Internet Draft, Internet Engineering Task Force, Mar. 2002. Work in progress. [2] S. Bradner, "Key words for use in RFCs to indicate requirement levels," RFC 2119, Internet Engineering Task Force, Mar. 1997. [3] W. W. W. C. (W3C), "Extensible markup language (xml) 1.0." The J. Rosenberg et. al. [Page 15] Internet Draft Conference Package June 24, 2002 XML 1.0 spec can be found at http://www.w3.org/TR/1998/REC-xml- 19980210. [4] R. Moats, "URN syntax," RFC 2141, Internet Engineering Task Force, May 1997. [5] R. Moats, "A URN namespace for IETF documents," RFC 2648, Internet Engineering Task Force, Aug. 1999. [6] M. Mealling, "The IANA XML registry," Internet Draft, Internet Engineering Task Force, Nov. 2001. Work in progress. [7] J. Rosenberg and H. Schulzrinne, "A session initiation protocol (SIP) event package for dialog state," Internet Draft, Internet Engineering Task Force, June 2002. Work in progress. [8] M. Murata, S. S. Laurent, and D. Kohn, "XML media types," RFC 3023, Internet Engineering Task Force, Jan. 2001. 10 Informative References [9] J. Rosenberg, "Session initiation protocol (SIP) extensions for presence," Internet Draft, Internet Engineering Task Force, May 2002. Work in progress. [10] J. Rosenberg, "A session initiation protocol (SIP)event template-package for watcher information," Internet Draft, Internet Engineering Task Force, May 2002. Work in progress. [11] R. Mahy, "A message summary and message waiting indication event package for the session initiation protocol (SIP)," Internet Draft, Internet Engineering Task Force, June 2002. Work in progress. [12] J. Rosenberg and H. Schulzrinne, "Models for multi party conferencing in SIP," Internet Draft, Internet Engineering Task Force, Nov. 2001. Work in progress. Full Copyright Statement Copyright (c) The Internet Society (2002). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this J. Rosenberg et. al. [Page 16] Internet Draft Conference Package June 24, 2002 document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. J. Rosenberg et. al. [Page 17]