INTERET-DRAFT M. Isom„ki Document: draft-isomaki-simple-list-man-sem-00.txt O. Ribera Expires: April 2003 I. Almar J. Costa Nokia October 2002 Semantic Description of SIMPLE List Manipulation Operations 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 The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract In SIMPLE based presence and messaging applications, it is necessary for the user to be able to configure a number of pieces of information. One of the most common types of information is a list of URIs. List management is useful outside the scope of SIMPLE as well, for instance in conferencing. There are many reasons why it would be beneficial to manage the lists in a similar fashion regardless of the application. Before the selection of the actual protocol(s) to manage the lists there is a need to describe their semantics on an abstract level. This document proposes the semantics for SIMPLE list manipulation protocol. Table of Contents 1 Introduction 2 Conventions used in this document 3 List Manipulation in the Overall Manipulation Framework 4 List Manipulation Requirements and Their Impacts on The Protocol 5 Abstract Description of the Protocol 6 Security Considerations 7 Acknowledgements 8 References 9 Author's Addresses 1 Introduction Presence and Instant Messaging applications typically have a number of features that users should be able to configure. These include adding and removing members on various lists, and defining authorization policies. In most cases the authorization policies also make use of configurable lists. SIP extensions for presence [1], presentity collections [2] and instant messaging [3], allow users to subscribe to each others presence and send instant messages to each other. However, the manipulation of the lists used for presentity collections or presence authorization policies has been left out of the scope of these specifications. In many cases the manipulation can be done e.g. via Web-pages, but sometimes tighter integration into the actual presence and IM application is desired. This is essential especially for devices with small display, such as mobile handsets. For these reasons, a standardized protocol for the manipulation purposes is needed. The SIMPLE working group has chartered a work item for defining protocols for presence list and presence authorization policy manipulation. The framework and requirements for these protocols have been described in [4]. Based on this, it has become evident that list manipulation is one of the key pieces of the solution. It seems clear that the best way is to meet all list manipulation needs by a single protocol. It is expected that this protocol should be useful also for other applications requiring list manipulation. For instance conferencing can use lists for defining authorization policies (similar to presence) and setting "mass-invitations". The aim of this draft is to define the semantics of the list manipulation protocol, and describe how it fits to the overall framework. First the list manipulation related requirements in [4] are evaluated one by one and based on them a set of requests and their parameters for the manipulation protocol is proposed. It is expected that once the semantics are agreed on this level, the next step is to make proposals to map them to concrete protocols. 2 Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [1]. 3 List Manipulation in the Overall Manipulation Framework This draft follows the data manipulation framework presented in [4]. The data manipulation client (from now on referred to as just the client) uses some protocol to interact with the data manipulation server. The data manipulation server (from now on referred to as just the server) manages a persistent storage of the data elements. This storage is accessible by the actual application whose features the data elements describe. An example for the presence service is provided in [4]. The actual data elements to be manipulated are dependent on the application. For instance a Presentity Collection Server requires a list of URIs, while Presence Agent requires an authorization policy description, and the lists associated with it. On the other hand a conferencing server might require a number of data elements, of which various lists are just one part. It is expected that the client can discover what data elements the server allows it to manipulate, and what addresses can be used for manipulating the elements related to a particular application instance. How this discovery happens is beyond the scope of this document, but at least two ways should be possible. The first is that the client knows the SIP URI related to an application instance (such as a presentity collection or a conference), and can based on that learn the related data element types and their manipulation URIs. The second is that the client creates the application instance, and by doing so it learns this information. OPEN ISSUE: The second case still leaves a problem how to discover the address/URI which can be used to create an application instance, such as a presentity collection or a conference. A list is basically just one type of data element. Based on [4] there are at least two models how lists are related to the applications - here defined as static or dynamic. Static relation means that the purpose and number of lists for a particular application type are known a priori. For instance in the case of presentity colletion, it is known that the application always requires exactly one list. Dynamic relation means that the number of lists used by a particular application instance can vary. Presence authorization according to [4] is a good example of the dynamic relation. The number of lists vary and they are referenced from a "script" defining the policy rules. The static relation is easy to handle. The "placeholders" for the lists can be allocated directly on the server when the application instance is created. The dynamic relation requires that the client needs to able to create and link new lists dynamically to an application instance. 4 List Manipulation Requirements and Their Impacts on The Protocol List manipulation requirements are expressed in [4] in relation to presentity collections (in Chapter 4 of [4]) and presence authorization policy management (in Chapter 5.1 of [4]). In this Chapter these requirements are analysed in order to see how they affect the design of the manipulation protocol. 4.1 Requirements for Relation of Applications and Lists Some requirements to the protocol are implied by the framework presented in Chapter 3 of [4]. Presentity collection basically includes a single list of URIs to manipulate. This is a static relation. There is a direct 1:1 mapping between a SIP URI of the presentity collection and the list of URIs. There is no need for separate list creation. Creating the presentity collection will create the "placeholder" for the list of URIs as well. Presence authorization policy uses lists in a dynamic and indirect manner. There is a direct 1:1 mapping between presentity's SIP URI and the script defining the authorization policy rules. However, the script may contain references to one or more lists, and the number of "active" lists varies based on the contents of the script. This implies that the client needs to be able to create and delete lists which can be referenced in the script, and maybe even lists not referenced by the current script need to be maintained by the server. 4.2 Requirements for Request and Response Types There are requirements, which imply what request and response types the protocol needs to have. They are presented below, with the explanations of the implied request and response types. The requirements are from Chapter 4 of [4]. REQ1: It MUST be possible for a client to create a presentity collection and associate it with a URI. REQ2: It MUST be possible for the user to specify the URI for the presentity collection when one is created. If the name cannot be allocated (because it already exists, for example), it MUST be possible to inform the client of the failure, and the reason for it. REQ3: It SHOULD be possible for the server to provide client a URI for the list when one is created, in the case where the client does not provide it. These requirements imply that the protocol needs to have a CREATE request from the client to the server. The transaction needs to include the negotiation of URI, so that the client can propose a URI (this is carried in the request), which server needs to verify, or if the client does not propose a URI, the server may issue one (this is carried in the response). There needs to be an error response for the case that the client proposes an invalid URI. REQ4: It MUST be possible to add an entry to the presentity collection. Each entry MUST consist of at least a URI, and MAY include a display name. It MUST be possible for the entry to be any URI that is meaningful in the context of a presentity collection. Examples would include a SIP URI or pres URI. This requirement implies that the protocol needs to have an ADDENTRY request for providing a new list entry from the client to the server. Display name can be provided as an additional parameter to the entry. The server needs to verify the validity of the entry, so there needs to be an error response for an invalid entry. OPEN ISSUE: Related to Chapter 4.4: Should this be just an operation within a larger UPDATEENTRIES request, which could contain several operations? REQ6: It MUST be possible to remove an entry from the presentity collection, by providing the URI for the specific entry to be removed. If the entry does not exist, it MUST be possible for the server to inform the client of this fact. This requirement implies that the protocol needs to have a REMOVEENTRY request, in which client provides the URI to be removed. There needs to be an error response for the case where the URI does not exist. OPEN ISSUE: Related to Chapter 4.4: Should this be just an operation within a larger UPDATEENTRIES request, which could contain several operations? REQ7: It SHOULD be possible to clear all the entries from a presentity collection. This requirement implies that the protocol needs to have (an optional) CLEARENTRIES request. REQ8: It MUST be possible to delete a presentity collection. In this context, deleted means that the name of the presentity collection is no longer defined, so that the subscriptions to the collection would fail. This requirement implies that the protocol needs to have a DELETE request. REQ9: It MUST be possible to query for the set of URIs in a particular presentity collection, by providing the URI for the presentity collection. This requirement implies that the protocol needs to have a GETENTRIES request. The response would contain all the entries currently stored in the list. REQ11: It MUST be possible for a client to store a cached copy of the list. This implies that it MUST be possible for the server to notify the client of the change in the list. It MUST be possible for the client to manipulate the local cached copy even when there is no connectivity to the server. It MUST be possible to synchronize with the master copy of the server, when connectivity is re-established. This requirement implies that the protocol needs to have a NOTIFY request from the server to the client. NOTIFY needs to contain at least the information that there is a change in the list. Indirectly the requirement also implies that there needs to be a SUBSCRIBE request from the client to the server, so that the server knows where to send the NOTIFYs. It is probably useful to design the notification so that it is not specific to any data element, such as a list. REQ20: It MUST be possible to modify an entry in the presentity collection. This requirement implies that the protocol needs to have a MODIFYENTRY request, in which the client provides the URI for the entry to be modified and the new content for the entry. There needs to be an error response for the case where the new content is invalid. Also, there needs to be an error response when the entry to be modified does not exist. OPEN ISSUE: Related to Chapter 4.4: Should this be just an operation within a larger UPDATEENTRIES request, which could contain several operations? The essentially same requirements are listed in [4] in Chapter 5.1 as REQ 7.1 - REQ 7.9 in the context of the lists used for presence authorization policies. Since the requirements are identical, they can also be met with the same set of request and response types. 4.3 Security Requirements There are requirements for the security of the protocol. These are from Chapter 4 of [4]. REQ 15: It MUST be possible for the server to authenticate the client. REQ 16: It MUST be possible for the client to authenticate the server. REQ 17: It MUST be possible for the message integrity to be insured between the client and the server. REQ 18: It MUST be possible for privacy to be insured between the client and the server. These imply that the protocol needs to support mutual authentication, integrity protection and encryption. There are various ways to implement these, and this version of the document does not propose a particular one. However, since the protocol is intended to be used in conjunction with SIP, it seems reasonable that the client identity could be same as for SIP, and that SIP authentication mechanisms would be usable, e.g. HTTP-Digest [5] and HTTP-Digest-AKA [6]. 4.4 Miscellaneous Requirements The rest of the list manipulation related requirements presented in Chapter 4 of [4] are analysed below with their implications. REQ 5: It MUST be possible for a presentity collection to contain entries which are themselves presentity collections. From the manipulation point of view this does not imply any additional mechanisms to the protocol. REQ 10: It MUST be possible for the presentity collection to be associated with a list of authorized users. Those authorized users are the only ones permitted to manipulate the presentity collection. It is not clear whether there is a requirement that the client should be able to manipulate the authorized user's list as well. Even in that case this would be just another list with a static relation to the presentity collection. REQ 12: It MUST be possible for there to be multiple clients with cached copies of the list. REQ 13: Manipulations of the presentity collection MUST exhibit the ACID property; that is, they MUST be atomic, be consistent, durable, and operate independently. Multi-client support is basically addressed by the notication and ACID property requirements. The ACID property can be assumed in the protocol design, since the request-response pairs identified in Chapter 4.2 are independent from each other, and each request accomplishes a particular task. REQ 14: It MAY be possible for the client to batch multiple operations (add a presentity, remove a presentity) into a single request that is processed atomically. This would be beneficial e.g. for wireless clients. In the terminology used in this document this would mean that ADDENTRY, REMOVEENTRY and MODIFYENTRY requests would be actually just operations within a MANIPULATEENTRIES request, which could contain several of them. OPEN ISSUE: Should this be supported? REQ 19: It MUST be possible for the protocol to operate through and intermediary, such as a proxy. This requirement does not imply anything new for the end-to-end protocol. Proxy support is important e.g. for firewall or Network Address Translator traversal. 5 Abstract Description of the Protocol This chapter aims to put together a proposal for a list manipulation protcol semantics. It is based on the erquirements analyzed in Chapter 4. The choise made in the proposal is to include ADDENTRY, REMOVEENTRY and MODIFYENTRY as operations within an UPDATEENTRY request that can contain multiple operations. In addition to the requests clearly needed according to the requirements, it is assumed that there may be a need for a client to set or at least read some attributes of the list. These can include e.g. the maximum number of etries allowed on the list, and other useful information. For that purpose a request to set and get such attributes has been included. Security issues are not specified to be solved by any particular solution in this version of the draft, so the security related parameters are only indicative. Sections 5.1 - 5.3 describe the common parts of the protocol, while Sections 5.4 - 5.12 define specific Requests and Responses. C->S indicates direction from the client to the server. S->C indicates direction from the server to the client. 5.1 Common Parameters in the Client-originated Requests All the requests originted by the client have a common set of parameters that consist of: ¸Transaction identifier ¸Client identifier ¸Client authentication information (Optional) ¸Client signature (Optional) ¸Resource identifier The transaction identifier is used by the client and the server to match requests and responses. Client identifier, client authentication information and client signature are used to solve the security requirements listed in Chapter 4.3. Their semantics are not expressed in this version of this draft. Resource identifier is used to identify the list the request applies to. 5.2 Common Parameters in the Server-originated Requests All the Requests originated by the server have a common set of parameters that consist of: ¸Transaction identifier ¸Server identifier ¸Server authentication information (Optional) ¸Server signature (Optional) The transaction identifier is used by the client and the server to match requests and responses. Server identifier, server authentication information and server signature are used to meet the security requirements listed in Chapter 4.3. Their semantics are not expressed in this version of this draft. 5.3 Common Parameters and Error Statuses in Responses The status contains the information of the execution of a request such as: ¸Status code ¸Specific informative text (Optional) If the request was successful, the response contains "OK" status. There is a set of error statuses common to all responses. The error codes themselves are not defined in this draft, however, the conceptual errors are: ¸Invalid Transaction identifier ¸Authentication failure ¸Request not allowed ¸Not Authorized ¸Resource non existent 5.4 CREATE C->S: CREATE Request S->C: CREATE Response The CREATE Request is always issued by the client for creating a list in the server. The server creates the list with the attributes, entries and URI suggested by the client if valid. If no URI is provided by the client, the server assigns one. In the request, the client could specify the list attributes and the initial list entries. CREATE Request may have a wider context than just creating a single list. It can be used to create a complete application instance, for example a presentity collection or a conference. This specification only takes into account the issues related to list creation. SPECIFIC REQUEST PARAMETERS: ¸List attributes (Optional) ¸List Entries (Optional) ¸Proposed List URI (Optional) OPEN ISSUE: Should it be possible to assign the entries in CREATE? OPEN ISSUE: Are there any feasible attributes that the client should be allowed to set? In the CREATE Response, the server confirms the operation and the final URI to be assigned to the list. SPECIFIC RESPONSE PARAMETERS: ¸Assigned List URI ¸URI where the future list manipulation operations should be addressed, if that is different from the assigned list URI SPECIFIC RESPONSE ERROR STATUSES: ¸Proposed List URI already exists or cannot be used ¸Invalid attributes ¸Invalid entries 5.5 DELETE C->S: DELETE Request S->C: DELETE Response The DELETE Request is always issued by the client for deleting a list from the server. DELETE Request may have a wider context than just deleting a single list. It can be used to delete a complete application instance, for example a presentity collection or a conference. This specification only takes into account the issues related to list deletion. SPECIFIC REQUEST PARAMETERS: No specific parameters. SPECIFIC RESPONSE PARAMETERS: No specific parameters. SPECIFIC RESPONSE ERROR STATUSES: No specific errors. 5.6 UPDATEENTRIES C->S MODIFYENTRY Request S->C MODIFYENTRY Response The UPDATEENTRIES Request is used by the client to add, delete or modify entries on the list. The same request can contain multiple add, modify and delete operations. NOTE: This operation MUST be atomic ,thus if the operation can not be successfully completed for all elements, all changes MUST be rolled back and client notified of the failure with the status parameter. SPECIFIC REQUEST PARAMETERS: ¸Operations (ADDENTRY, REMOVEENTRY, MODIFYENTRY) with each having own set of parameters: ¸ ADDENTRY: URI and (optional) display name of the entry ¸ REMOVEENTRY: URI of the entry ¸ MODIFYENTRY: URI of the entry to be modified and URI and (optional) display name of the new entry The UPDATEENTRIES Response informs the client of the success or failure of the operation. SPECIFIC RESPONSE PARAMETERS: No specific parameters. SPECIFIC RESPONSE ERRORS: ¸Entry does not exist ¸Invalid new entry OPEN ISSUE: It would be possible to also have separate ADDENTRY, REMOVEENTRY and MODIFYENTRY requests. 5.7 GETENTRIES C->S GETENTRIES Request S->C GETENTRIES Response The "Get Entries Request" is used by the client to obtain the entries of a list. SPECIFIC REQUEST PARAMETERS: No specific parameters. The "Get Entries Response" returns the entries of a list to the client. SPECIFIC RESPONSE PARAMETERS: ¸Entries of the list SPECIFIC RESPONSE ERROR STATUSES: No specific errors. 5.8 CLEARENTRIES C->S: CLEARENTRIES Request S->C: CLEARENTRIES Response The SETATTRIBUTES Request removes all the entries of a list. SPECIFIC REQUEST PARAMETERS: No specific parameters. The CLEARENTRIES Response informs of the success or failure of the operation. SPECIFIC RESPONSE PARAMETERS: No specific parameters. SPECIFIC RESPONSE ERROR STATUSES: No specific errors. 5.9 SETATTRIBUTES C->S: SETATTRIBUTES Request S->C: SETATTRIBUTES Response The SETATTRIBUTES Request changes the attributes of a list. SPECIFIC REQUEST PARAMETERS: ¸Attributes to modify The SETATTRIBUTES Response informs of the success or failure of the operation. SPECIFIC RESPONSE PARAMETERS: No specific parameters. SPECIFIC RESPONSE ERROR STATUSES: ¸Invalid List Attributes OPEN ISSUE: Are there any useful attributes that the client would need to set? 5.10 GETATTRIBUTES C->S: GETATTRIBUTES Request S->C: GETATTRIBUTES Response The GETATTRIBUTES Requests retrieves the attributes of a list. SPECIFIC REQUEST PARAMETERS: No specific parameters. The GETATTRIBUTES Response returns the attributes of the list or failure of the operation. SPECIFIC RESPONSE PARAMETERS: ¸Attributes SPECIFIC RESPONSE ERRORS: No specific errors. OPEN ISSUE: Are there any useful attributes that the client would need to get? 5.11 SUBSCRIBE C->S SUBSCRIBE Request S->C SUBSCRIBE Response The SUBSCRIBE Request is used by the client to request to the server that when certain lists change, a notification with change information is to be sent to the client. SPECIFIC REQUEST PARAMETERS: ¸Proposed Expiration time for the subscription ¸Address to receive the notifications SPECIFIC RESPONSE PARAMETERS: ¸Final Expiration time for the subscription SPECIFIC RESPONSE ERROR STATUSES: No specific errors. 5.12 NOTIFY S->C NOTIFY Request C->S NOTIFY Response The "List Change Notification" notifies to the client that a the list has changed an optionally includes the changes occurred. SPECIFIC REQUEST PARAMETERS: ¸Identifier for the changed resource ¸Details of the change (optional) SPECIFIC RESPONSE PARAMETERS: No specific parameters SPECIFIC RESPONSE ERROR STATUSES: ¸Subscription does not exist 6 Security Considerations The protocol described here will need to meet the requirements listed in Chapter 4.3. Otherwise it might be possible for a malicious party to manipulate the features of the services of some other party. That would for instance allow the malicious party to authorize himself to see that other party's presence information. 7 Acknowledgements The authors would like to thank Aki Niemi for his comments. 8 References [1] J. Rosenberg, "Session initiation protocol (SIP) extensions for presence," Internet Draft, Internet Engineering Task Force, May 2002. Work in progress. [2] J. Rosenberg and B. Campbell, "A SIP event package for list presence," Internet Draft, Internet Engineering Task Force, June 2002. Work in progress. [3] B. Campbell et al., "Session Initiation Protocol Extension for Instant Messaging", Internet Draft, Internet Engineering Task Force, September 2002. Work in progress. [4] J. Rosenberg and M. Isom„ki, "Requirements for Manipulation of Data Elements in SIMPLE Systems", Internet Draft, Internet Engineering Task Force, October 2002. Work in progress. [5] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A. and L. Stewart, "HTTP authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. [6] A. Niemi, J. Arkko, V. Torvinen, " Hypertext Transfer Protocol (HTTP) Digest Authentication Using Authentication and Key Agreement (AKA)", RFC 3310, September 2002. 9 Author's Addresses Markus Isom„ki Nokia It„merenkatu 11-13 00180 Helsinki Finland Tel: +358 50 522 5984 E-mail: markus.isomaki@nokia.com Oriol Ribera Nokia Parc De Negocis Mas Blau Edif. Prima Muntadas Porta B 08820 El Prat Del Llobregat Barcelona Spain Tel: +34 933 796 633 E-mail: oriol.ribera@nokia.com Ignacio Almar Nokia Parc De Negocis Mas Blau Edif. Prima Muntadas Porta B 08820 El Prat Del Llobregat Barcelona Spain Tel: +34 933 796 633 E-mail: ignacio.almar@nokia.com Jose Costa Nokia Valimotie 9 00380 Helsinki Finland Tel: +358 718 008 000 E-mail: jose.costa-requena@nokia.com INTERNET-DRAFT SIMPLE List Manipulation Operations October 2002 Isom„ki et al. Expires - April 2003 [Page 13] Isom„ki et al. Expires - April 2003 [Page 1]