RFC 6503
Centralized Conferencing Manipulation Protocol
Internet Engineering Task Force (IETF) M. Barnes Request for Comments: 6503 Polycom Category: Standards Track C. Boulton ISSN: 2070-1721 NS-Technologies S. Romano University of Napoli H. Schulzrinne Columbia University March 2012 Centralized Conferencing Manipulation ProtocolAbstract
The Centralized Conferencing Manipulation Protocol (CCMP) allows a Centralized Conferencing (XCON) system client to create, retrieve, change, and delete objects that describe a centralized conference. CCMP is a means to control basic and advanced conference features such as conference state and capabilities, participants, relative roles, and details. CCMP is a stateless, XML-based, client server protocol that carries, in its request and response messages, conference information in the form of XML documents and fragments conforming to the centralized conferencing data model schema. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc6503.
Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.Table of Contents
1. Introduction ....................................................4 2. Conventions and Terminology .....................................5 3. XCON Conference Control System Architecture .....................5 3.1. Conference Objects .........................................7 3.2. Conference Users ...........................................7 4. Protocol Overview ...............................................8 4.1. Protocol Operations ........................................9 4.2. Data Management ...........................................10 4.3. Data Model Compliance .....................................11 4.4. Implementation Approach ...................................12 5. CCMP Messages ..................................................13 5.1. CCMP Request Message Type .................................13 5.2. CCMP Response Message Type ................................15 5.3. Detailed Messages .........................................17 5.3.1. blueprintsRequest and blueprintsResponse ...........20 5.3.2. confsRequest and confsResponse .....................22 5.3.3. blueprintRequest and blueprintResponse .............24 5.3.4. confRequest and confResponse .......................26 5.3.5. usersRequest and usersResponse .....................30 5.3.6. userRequest and userResponse .......................32 5.3.7. sidebarsByValRequest and sidebarsByValResponse .....37 5.3.8. sidebarByValRequest and sidebarByValResponse .......39 5.3.9. sidebarsByRefRequest and sidebarsByRefResponse .....42 5.3.10. sidebarByRefRequest and sidebarByRefResponse ......44 5.3.11. extendedRequest and extendedResponse ..............47 5.3.12. optionsRequest and optionsResponse ................49 5.4. CCMP Response Codes .......................................53 6. A Complete Example of CCMP in Action ...........................57 6.1. Alice Retrieves the Available Blueprints ..................58 6.2. Alice Gets Detailed Information about a Specific Blueprint .................................................60
6.3. Alice Creates a New Conference through a Cloning
Operation .................................................62
6.4. Alice Updates Conference Information ......................65
6.5. Alice Inserts a List of Users into the Conference Object ..66
6.6. Alice Joins the Conference ................................68
6.7. Alice Adds a New User to the Conference ...................70
6.8. Alice Asks for the CCMP Server Capabilities ...............72
6.9. Alice Makes Use of a CCMP Server Extension ................75
7. Locating a Conference Server ...................................78
8. Managing Notifications .........................................79
9. HTTP Transport .................................................80
10. Security Considerations .......................................82
10.1. Assuring That the Proper Conference Server Has
Been Contacted ...........................................83
10.2. User Authentication and Authorization ....................84
10.3. Security and Privacy of Identity .........................85
10.4. Mitigating DoS Attacks ...................................86
11. XML Schema ....................................................87
12. IANA Considerations ..........................................105
12.1. URN Sub-Namespace Registration ..........................105
12.2. XML Schema Registration .................................106
12.3. MIME Media Type Registration for
'application/ccmp+xml' ..................................106
12.4. DNS Registrations .......................................107
12.4.1. Registration of a Conference Server
Application Service Tag ..........................108
12.4.2. Registration of a Conference Server
Application Protocol Tag for CCMP ................108
12.5. CCMP Protocol Registry ..................................108
12.5.1. CCMP Message Types ...............................109
12.5.2. CCMP Response Codes ..............................111
13. Acknowledgments ..............................................113
14. References ...................................................113
14.1. Normative References ....................................113
14.2. Informative References ..................................114
Appendix A. Evaluation of Other Protocol Models and
Transports Considered for CCMP ......................116
A.1. Using SOAP for CCMP ......................................117
A.2. A RESTful Approach for CCMP ..............................117
1. Introduction
"A Framework for Centralized Conferencing" [RFC5239] (XCON framework) defines a signaling-agnostic framework, naming conventions, and logical entities required for building advanced conferencing systems. The XCON framework introduces the conference object as a logical representation of a conference instance, representing the current state and capabilities of a conference. The Centralized Conferencing Manipulation Protocol (CCMP) defined in this document allows authenticated and authorized users to create, manipulate, and delete conference objects. Operations on conferences include adding and removing participants, changing their roles, as well as adding and removing media streams and associated endpoints. CCMP implements the client-server model within the XCON framework, with the conferencing client and conference server acting as client and server, respectively. CCMP uses HTTP [RFC2616] as the protocol to transfer requests and responses, which contain the domain-specific XML-encoded data objects defined in [RFC6501] "Conference Information Data Model for Centralized Conferencing (XCON)". Section 2 clarifies the conventions and terminology used in the document. Section 3 provides an overview of the conference control functionality of the XCON framework, together with a description of the main targets CCMP deals with, namely conference objects and conference users. A general description of the operations associated with protocol messages is given in Section 4 together with implementation details. Section 5 delves into the details of specific CCMP messages. A complete, non-normative, example of the operation of CCMP, describing a typical call flow associated with conference creation and manipulation, is provided in Section 6. A survey of the methods that can be used to locate a conference server is provided in Section 7, and Section 8 discusses potential approaches to notifications management. CCMP transport over HTTP is highlighted in Section 9. Security considerations are presented in Section 10. Finally, Section 11 provides the XML schema.
2. Conventions and Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. In addition to the terms defined in "A Framework for Centralized Conferencing" [RFC5239], this document uses the following terms and acronyms: XCON-aware client: An XCON conferencing system client that is able to issue CCMP requests. First-Party Request: A request issued by the client to manipulate its own conferencing data. Third-Party Request: A request issued by a client to manipulate the conference data of another client.3. XCON Conference Control System Architecture
CCMP supports the XCON framework. Figure 1 depicts a subset of the "Conferencing System Logical Decomposition" architecture from the XCON framework document. It illustrates the role that CCMP assumes within the overall centralized architecture.
........................................................ . Conferencing System . . . . +---------------------------------------+ . . | C O N F E R E N C E O B J E C T | . . +-+-------------------------------------+ | . . | C O N F E R E N C E O B J E C T | | . . +-+-------------------------------------+ | | . . | C O N F E R E N C E O B J E C T | | | . . | | |-+ . . | |-+ . . +---------------------------------------+ . . ^ . . | . . v . . +-------------------+ . . | Conference Control| . . | Server | . . +-------------------+ . . ^ . .........................|.............................. | |Centralized |Conferencing |Manipulation |Protocol | .........................|.............................. . V . . +----------------+ . . | Conference | . . | Control | . . | Client | . . +----------------+ . . . . Conferencing Client . ........................................................ Figure 1: Conferencing Client Interaction The Centralized Conferencing Manipulation Protocol (CCMP) allows the conference control client (conferencing client) to interface with the conference object maintained by the conferencing system, as depicted in Figure 1. Note that additional functionality of the conferencing client and conferencing system is discussed in the XCON framework and related documents.
This section provides details of the identifiers REQUIRED to address and manage the clients associated with a conferencing system using CCMP.3.1. Conference Objects
Conference objects feature a simple dynamic inheritance-and-override mechanism. Conference objects are linked into a tree known as a "cloning tree" (see Section 7.1 of [RFC5239]). Each cloning tree node inherits attributes from its parent node. The roots of these inheritance trees are conference templates also known as "blueprints". Nodes in the inheritance tree can be active conferences or simply descriptions that do not currently have any resources associated with them (i.e., conference reservations). An object can mark certain of its properties as unalterable, so that they cannot be overridden. Per the framework, a client may specify a parent object (a conference or blueprint) from which to inherit values when a conference is created using the conference control protocol. Conference objects are uniquely identified by the XCON-URI within the scope of the conferencing system. The XCON-URI is introduced in the XCON framework and defined in the XCON common data model. Conference objects are comprehensively represented through XML documents compliant with the XML schema defined in the XCON data model [RFC6501]. The root element of such documents, called <conference-info>, is of type "conference-type". It encompasses other XML elements describing different conference features and users as well. Using CCMP, conferencing clients can use these XML structures to express their preferences in creating or updating a conference. A conference server can convey conference information back to the clients using the XML elements.3.2. Conference Users
Each conference can have zero or more users. All conference participants are users, but some users may have only administrative functions and do not contribute or receive media. Users are added one user at a time to simplify error reporting. When a conference is cloned from a parent object, users are inherited as well, so that it is easy to set up a conference that has the same set of participants or a common administrator. The conference server creates individual users, assigning them a unique conference user identifier (XCON- USERID). The XCON-USERID as identifier of each conferencing system client is introduced in the XCON framework and defined in the XCON
common data model. Each CCMP request, with an exception pointed out in Section 5.3.6 representing the case of a user at his first entrance in the system as a conference participant, must carry the XCON-USERID of the requestor in the proper <confUserID> parameter. The XCON-USERID acts as a pointer to the user's profile as a conference actor, e.g., her signaling URI and other XCON protocol URIs in general, her role (moderator, participant, observer, etc.), her display text, her joining information, and so on. A variety of elements defined in the common <conference-info> element as specified in the XCON data model are used to describe the users related to a conference including the <users> element, as well as each <user> element included within it. For example, it is possible to determine how a specific user expects and is allowed to join a conference by looking at the <allowed-users-list> in <users>: each <target> element involved in such a list represents a user and shows a 'method' attribute defining how the user is expected to join the conference, i.e., "dial-in" for users that are allowed to dial, "dial-out" for users that the conference focus will be trying to reach (with "dial-in" being the default mode). If the conference is currently active, dial-out users are contacted immediately; otherwise, they are contacted at the start of the conference. CCMP, acting as the conference control protocol, provides a means to manipulate these and other kinds of user-related features. As a consequence of an explicit user registration to a specific XCON conferencing system, conferencing clients are usually provided (besides the XCON-USERID) with log-in credentials (i.e., username and password). Such credentials can be used to authenticate the XCON- aware client issuing CCMP requests. Thus, both username and password should be carried in a CCMP request as part of the "subject" parameter whenever a registered conferencing client wishes to contact a CCMP server. CCMP does not maintain a user's subscriptions at the conference server; hence, it does not provide any specific mechanism allowing clients to register their conferencing accounts. The "subject" parameter is just used for carrying authentication data associated with pre-registered clients, with the specific registration modality outside the scope of this document.4. Protocol Overview
CCMP is a client-server, XML-based protocol for user creation, retrieval, modification, and deletion of conference objects. CCMP is a stateless protocol, such that implementations can safely handle transactions independently from each other. CCMP messages are XML documents or XML document fragments compliant with the XCON data model representation [RFC6501].
Section 4.1 specifies the basic operations that can create, retrieve, modify, and delete conference-related information in a centralized conference. The core set of objects manipulated by CCMP includes conference blueprints, the conference object, users, and sidebars. Each operation in the protocol model, as summarized in Section 4.1, is atomic and either succeeds or fails as a whole. The conference server MUST ensure that the operations are atomic in that the operation invoked by a specific conferencing client completes prior to another client's operation on the same conference object. While the details for this data locking functionality are out of scope for the CCMP specification and are implementation specific for a conference server, some core functionality for ensuring the integrity of the data is provided by CCMP as described in Section 4.2. While the XML documents that are carried in CCMP need to comply with the XCON data model, there are situations in which the values for mandatory elements are unknown by the client. The mechanism for ensuring compliance with the data model in these cases is described in Section 4.3. CCMP is completely independent from underlying protocols, which means that there can be different ways to carry CCMP messages from a conferencing client to a conference server. The specification describes the use of HTTP as a transport solution, including CCMP requests in HTTP POST messages and CCMP responses in HTTP 200 OK replies. This implementation approach is further described in Section 4.4.4.1. Protocol Operations
The main operations provided by CCMP belong in four general categories: create: for the creation of a conference object, a conference user, a sidebar, or a blueprint. retrieve: to get information about the current state of either a conference object (be it an actual conference, a blueprint, or a sidebar) or a conference user. A retrieve operation can also be used to obtain the XCON-URIs of the current conferences (active or registered) handled by the conferencing server and/or the available blueprints. update: to modify the current features of a specified conference or conference user.
delete: to remove from the system a conference object or a
conference user.
Thus, the main targets of CCMP operations are as follows:
o conference objects associated with either active or registered
conferences,
o conference objects associated with blueprints,
o conference objects associated with sidebars, both embedded in the
main conference (i.e., <entry> elements in <sidebars-by-value>)
and external to it (i.e., whose XCON-URIs are included in the
<entry> elements of <sidebars-by-ref>),
o <user> elements associated with conference users, and
o the list of XCON-URIs related to conferences and blueprints
available at the server, for which only retrieval operations are
allowed.
4.2. Data Management
The XCON framework defines a model whereby the conference server
centralizes and maintains the conference information. Since multiple
clients can modify the same conference objects, a conferencing client
might not have the latest version of a specific conference object
when it initiates operations. To determine whether the client has
the most up-to-date conference information, CCMP defines a versioning
approach. Each conference object is associated with a version
number. All CCMP response messages containing a conference document
(or a fragment thereof) MUST contain a <version> parameter. When a
client sends an update message to the server, which includes
modifications to a conference object, if the modifications are all
successfully applied, the server MUST return a response, with a
<response-code> of "200", containing the version number of the
modified object. With this approach, a client working on version "X"
of a conference object that receives a response, with a <response-
code> of "200", with a version number that is "X+1" can be certain
that the version it manipulated was the most up to date. However, if
the response contains a version that is at least "X+2", the client
knows that the object modified by the server was more up to date than
the object the client was manipulating. In order to ensure that the
client always has the latest version of the modified object, the
client can send a request to the conference server to retrieve the
conference object. The client can then update the relevant data
elements in the conference object prior to invoking a specific
operation. Note that a client subscribed to the XCON event package
[RFC6502] notifications about conference object modifications, will receive the most up-to-date version of that object upon receipt of a notification. The "version" parameter is OPTIONAL for requests, since it is not needed by the server: as long as the required modifications can be applied to the target conference object without conflicts, the server does not care whether the client has stored an up-to-date view of the information. In addition, to ensure the integrity of the data, the conference server first checks all the parameters, before making any changes to the internal representation of the conference object. For example, it would be undesirable to change the <subject> of the conference, but then detect an invalid URI in one of the <service- uris> and abort the remaining updates.4.3. Data Model Compliance
The XCON data model [RFC6501] identifies some elements and attributes as mandatory. Since the XML documents carried in the body of the CCMP requests and responses need to be compliant with the XCON data model, there can be a problem in cases of client-initiated operations, such as the initial creation of conference objects and cases whereby a client updates a conference object adding new elements, such as a new user. In such cases, not all of the mandatory data can be known in advance by the client issuing a CCMP request. As an example, a client cannot know, at the time it issues a conference creation request, the XCON-URI that the server will assign to the yet-to-be-created conference; hence, it is not able to populate the mandatory 'entity' attribute of the conference document contained in the request with the correct value. To solve this issue, the CCMP client fills all mandatory data model fields, for which no value is available at the time the request is constructed, with placeholder values in the form of a wildcard string, AUTO_GENERATE_X (all uppercase), with X being a unique numeric index for each data model field for which the value is unknown. This form of wildcard string is chosen, rather than the use of random unique strings (e.g., FOO_BAR_LA) or non-numeric values for X, to simplify processing at the server. The values of AUTO_GENERATE_X are only unique within the context of the specific request. The placeholder AUTO_GENERATE_X values MUST be within the value part of an attribute or element (e.g., <userinfo entity="xcon-userid:AUTO_GENERATE_1@example.com">).
When the server receives requests containing values in the form of
AUTO_GENERATE_X, the server does the following:
(a) Generates the proper identifier for each instance of
AUTO_GENERATE_X in the document. If an instance of
AUTO_GENERATE_X is not within the value part of the attribute/
element, the server MUST send a <response-code> of "400 Bad
Request". In cases where AUTO_GENERATE_X appears only in the
user part of a URI (i.e., in the case of XCON-USERIDs or XCON-
URIs), the server needs to ensure that the domain name is one
that is within the server's domain of responsibility. If the
domain name is not within the server's domain of responsibility,
then the server MUST send a <response-code> of "427 Invalid
Domain Name". The server MUST replace each instance of a
specific wildcard field (e.g., AUTO_GENERATE_1) with the same
identifier. The identifiers MUST be unique for each instance of
AUTO_GENERATE_X within the same XML document received in the
request; for example, the value that replaces AUTO_GENERATE_1
MUST NOT be the same as the value that replaces AUTO_GENERATE_2.
Note that the values that replace the instances of
AUTO_GENERATE_X are not the same across all conference objects;
for example, different values can be used to replace
AUTO_GENERATE_1 in two different documents.
(b) Sends a response in which all values of AUTO_GENERATE_X received
in the request have been replaced by the newly created one(s).
With this approach, compatibility with the data model requirements is
maintained, while allowing for client-initiated manipulation of
conference objects at the server's side. Note that the use of this
mechanism could be avoided in come cases by using multiple
operations, such as creating a new user and then adding the new user
to an existing conference. However, the AUTO_GENERATE_X mechanism
allows a single operation to be used to effect the same change on the
conference object.
4.4. Implementation Approach
CCMP is implemented using HTTP, placing the CCMP request messages
into the body of an HTTP POST operation and placing the CCMP
responses into the body of the HTTP response messages. A non-
exhaustive summary of the other approaches that were considered and
the perceived advantages of the HTTP solution described in this
document are provided in Appendix A.
Most CCMP commands can pend indefinitely, thus increasing the
potential that pending requests can continue to increase when a
server is receiving more requests than it can process within a
specific time period. In this case, a server SHOULD return a <response-code> of "510" to the pending requests. In addition, to mitigate the situation, clients MUST NOT wait indefinitely for a response and MUST implement a timer such that when it expires, the client MUST close the connection. Thirty seconds is RECOMMENDED as the default value for this timer. Sixty seconds is considered a reasonable upper range. Note that there may be cases where a response message is lost and a request has been successful (e.g., user added to a conference); yet, the client will be unaware and close the connection. However, as described in Section 4.2, there is a versioning mechanism for the conference objects; thus, there is a mechanism for the conference object stored by the client to be brought up to date. CCMP messages have a MIME-type of "application/ccmp+xml", which appears inside the Content-Type and Accept header fields of HTTP requests and responses. The XML documents in the CCMP messages MUST be encoded in UTF-8. This specification follows the recommendations and conventions described in [RFC3023], including the naming convention of the type ('+xml' suffix) and the usage of the 'charset' parameter. The 'charset' parameter MUST be included with the XML document. Section 9 provides the complete requirements for an HTTP implementation to support CCMP.
(page 13 continued on part 2)
