SIP Hisham Khartabil Internet Draft Mikko Lonnfors Expires: July, 2003 Jose Costa-Requena Eva Leppanen Nokia January, 2002 Event Notification Filtering for Presence draft-khartabil-simple-presence-filter-00.txt 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 a 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. This Internet Draft will expire on xxxx, 2003. Copyright Notice Copyright (C) The Internet Society (2002). All Rights Reserved. Abstract The Presence event package for the SIP events framework describes the usage of the Session Initiation Protocol (SIP) for subscriptions and notifications of user presence. The document details how watchers can subscribe for notifications of all authorised and available presence information about the presentity. The document does not describe a mechanism of how filtering of presence information can be achieved. This document defines a presence filter package for the Event Notification Filtering Architecture. The package provides the mechanism whereby a watcher can specify the presence event filtering Khartabil, et. al. [Page 1] Internet Draft Congestion Safety and C-I July 2002 rules, using XML, for the presence agent (PA) and how that PA is to behave when receiving such filter. Table of Contents 1.0 Terminology.......................................................3 2.0 Introduction......................................................3 2.1 Motivation For Using XML..........................................4 3.0 Presence Package Specific Filters.................................4 3.1 Package ID........................................................4 3.3 Transport mechanism...............................................5 3.4 Structure of XML-Encoded Presence Filter Criteria.................5 3.4.1 The Root Element................................5 3.4.2 The Element.........................................5 3.4.3 The Element..............................................6 5.0 Client and server operation.......................................6 5.1 Client Operation..................................................6 5.1.1 SUBSCRIBE Bodies................................................6 5.1.2 Subscriber Generating SUBSCRIBE requests........................7 5.1.2.1 To-Header vs. Filter URI......................................7 5.1.2.2 Changing The Filter Criteria Within A Dialog..................8 5.1.2.3 Subscriber Interpreting SIP responses.........................8 5.1.3 Subscriber processing of NOTIFY requests........................9 5.2 Server Operation..................................................9 5.2.1 NOTIFY Bodies...................................................9 5.2.2 Notifier processing of SUBSCRIBE Requests.......................9 5.2.2 Notifier Generation of NOTIFY requests.........................10 5.2.2.1 Generating NOTIFY Contents...................................10 6.0 IANA Considerations..............................................11 7.0 Examples.........................................................11 7.1 Subscriber requests messaging related information................12 7.2 Subscriber fetches information about "open" communication means..13 8.0 Presence Package Specific Filters XML Schema.....................15 9.0 Security Requirements............................................16 10.0 Acknowledgements................................................17 11.0 References......................................................17 AuthorsÆ Addresses...................................................18 Full Copyright Statement.............................................19 Acknowledgement......................................................19 Khartabil, et. al. [Page 2] Internet Draft Congestion Safety and C-I July 2002 1.0 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 [12]. The document uses the terms as defined in [1], [2] and [3]. 2.0 Introduction User presence is defined as the ability to express willingness and ability of a user to communicate with other users on the network [2]. SIP event notification is described in [4]. It defines a general framework for sending subscriptions and receiving notifications in SIP based systems. It introduces the concept of event packages, which are concrete applications of the general event framework to a specific usage of events. An event package for user presence is defined in [2]. Filtering is a mechanism for controlling the content of event notifications [5]. Additionally the subscriber may specify the rules for when a notification should be sent to it. The filtering mechanism is expected to be particularly valuable to users of mobile wireless access devices. The characteristics of the devices typically include high latency, low bandwidth, low data processing capabilities, small display, and limited battery power. Such devices can benefit from the ability to filter the amount of information generated at the source of the event notification. It is stated in [2] that the notifier (Presence Agent) may send a NOTIFY at any time, but typically it is sent when the state of the presentity changes. It also states that the notifications would contain the complete and current presence state of the presentity authorized for a certain subscriber to see. The format of such presence information is named Presence Information Data Format (PIDF), as defined in [3]. This document presents a mechanism for the filtering of the PIDF based presence information. The document specifically describes how the subscriber is able to both limit the content and indicate more specifically the prefered content of the notifications using XML and Xpath [15] technologies. It also describes how the presence agent (PA) functions when generating notifications by taking into account filters, authorisation rules and default functionality of the presence service. The presence specific filtering solution presented here is compatible with the Presence Event Package [2]. Khartabil, et. al. [Page 3] Internet Draft Congestion Safety and C-I July 2002 Requirements for the Presence filter criteria can be found from two drafts: The 3GPP Presence requirements document [14] sets the following requirement: "It must be possible for a watcher to select certain elements from the presence information that he wants (or does not want) to receive in notifications for." The filter requirements draft [5] presents the following case: "A watcher wishes to get to know presentity's availability and willingness for messaging (e.g. IM and MMS)." Events Notification RFC [4] and the SIMPLE working group both identify filtering work as potential work. 2.1 Motivation For Using XML When trying to select the schema and protocol for defining the filter criteria, it can be found that there are several alternatives available. The best practice is to modularise the problem and work on smaller modules (the protocol and the filter information schema). The selection of the schema for defining the filter criteria requires a readable syntax with enough flexibility to define the semantics. Among the multiple possibilities (i.e. XML, Perl, TCL, etc), XML provides a generic framework where a schema for the filter logic including a namespace allowing the definition of the filter criteria. Thus, an XML schema provides an extensible mechanism where the logic required for the filtering functionality can be built. XML provides extensibility based on "namespaces" associated with a globally unique URI. The XML also enables the use of Xpath [15] for referencing items in an XML document (which is in the case of Presence in the format of the PIDF). In addition, by using XML the need for reliance on the transport protocol in order to interpret the filter criteria can be eliminated. 3.0 Presence Package Specific Filters This section describes the technologies and information needed to provide a filter specification relevant to presence filtering. 3.1 Package ID The package ID is æpresenceÆ or ôpresence.listö. This ID is carried in the event-header of the SUBSCRIBE as well as within the XML document carrying filter criteria. Khartabil, et. al. [Page 4] Internet Draft Congestion Safety and C-I July 2002 3.3 Transport mechanism Transportation of the filter criteria to the server is achieved by inserting the filter XML document in the body of a SIP SUBSCRIBE request. Alternatively, the document can be uploaded to the server using a transport specific for data manipulation. 3.4 Structure of XML-Encoded Presence Filter Criteria Presence Filter Criteria is an XML document [7] that MUST be well- formed and SHOULD be valid. Presence Filter Criteria XML documents MUST have the XML declaration and it SHOULD contain an encoding declaration in the XML declaration e.g. "". This specification makes use of XML namespaces for identifying the XML schema of the Presence Filter Criteria documents and document fragments. The namespace identifier for elements defined by this specification is a URN [8], using the namespace identifier 'ietf' defined by [9] and extended by [10]. This urn is: urn:ietf:params:xml:ns:simple-pres-filter+xml. This namespace declaration indicates the namespace on which the filter criteria are based on. 3.4.1 The Root Element The root element of the filter criteria is . The MAY have a 'pkgdef' attribute that defines the 'Presence' or 'presence.list' as package for the filter criteria. The root element MUST contain the namespace mentioned above. This element MUST contain one or more elements. 3.4.2 The Element The element is used to specify the content of an individual filter. MUST have an 'id' attribute. The value of the 'id' attribute MUST be unique within the root element. MUST have an 'uri' attribute. The value of the 'uri' attribute is the URI of the PRESENTITY or URI of the set of presentities from whom presence information is requested. The URI of the PRESENTITY is useful in cases where the ælistÆ template package [6] is used with æpresenceÆ package and different filter criteria are defined for one or more members of the presence.list. Khartabil, et. al. [Page 5] Internet Draft Congestion Safety and C-I July 2002 The element MUST contain a element. OPEN ISSUE: The solution for defining conditions when notifications are triggered is defined in future versions of this document. 3.4.3 The Element The element is used to specify the content to be delivered to the WATCHER. It does not specify the exact content but rules that are used to construct that information. The element MUST contain the 'report' attribute. The value of the 'report' is either 'default' or 'list-selected'. The 'default' value means that also all the values of the selected PIDF XML attributes and elements are delivered. The 'list-selected' means that only the selected items are delivered. Note that all the namespace definitions related to the delivered content are always delivered. 3.4.3.1 Defining the delivered content It must be possible in the filter criteria to be able to select presence attributes and/or tuples of the default presence information format [3]. It must also be possible to reference presence information of any extensions as the PIDF allows extensions to be defined as own namespaces. A general way to reference any items (PIDF XML elements and attributes) of the presence information is to be specified. The referencing mechanism should support hierarchy of the items since there may be several nested PIDF XML elements and attributes in the presence information. The preferred presence information is indicated using the capabilities of XPath [15]. The XPath clause is stated in the value of the element. The items addressed with the XPath are indicated with the expanded name which means that the URI of the presence information namespace is included in addition to the reference to the presence information item. 5.0 Client and server operation 5.1 Client Operation 5.1.1 SUBSCRIBE Bodies SIP entities compliant with this specification MUST support content- type æapplication/simple-pres-filter+xmlÆ. Khartabil, et. al. [Page 6] Internet Draft Congestion Safety and C-I July 2002 5.1.2 Subscriber Generating SUBSCRIBE requests This section presents additional functionalities required from the subscriber when filters are used in SUBSCRIBE requests bodies. Normal operations as defined in [2] are then followed. As defined in [2], a SUBSCRIBE for presence MAY contain a body. This body, as defined in this document, would serve the purpose of filtering. Honouring of these filters is at the policy discretion of the PA. No content in the body of a SUBSCRIBE indicates to the PA that no filter is being requested; so that the PA is instructed to send all NOTIFY requests including presence states that its own policy allows. If present, the body MUST be of MIME-Type æapplication/simple-pres- filter+xmlÆ. 5.1.2.1 To-Header vs. Filter URI The Event package "presence" in Event-header of the SUBSCRIBE request specifies that the filter rules apply to the presence information of the URI indicated in filter, or the URI present in the To-header if no URI is indicated in the filter. If the template package ôlistö is used with ôpresenceö in the SUBSCRIBE, and no presentity URI is indicated by the filter, the filter rules apply to all the URIs that result from a lookup, by the Presence Agent, on the URI present in the To-header if no presentity URI is indicated in the filter. If the template package ôlistö is used with ôpresenceö in the SUBSCRIBE, and the URI indicated by the filter in a presence list URI, the filter rules apply to all the URIs that result from a lookup, by the Presence Agent, on the URI in the filter. If the template package ôlistö is used with ôpresenceö in the SUBSCRIBE, and the presentity URI indicated by the filter in for one presentity whoÆs URI is one of the URIs that result from a lookup, by the PA, on the URI in the To-header, the filter rules apply to that particular presentity. All other presence documents sent to the rest of the presentities are not affected by the filter. For example, if the To-header in a SUBSCRIBE has the URI sip:mybuddies@mydomain.com, and the URI in the filter is sip:bob@otherdomain.com, the filter only applied to bob@otherdomain.com. If the template package ôlistö is used with ôpresenceö in the SUBSCRIBE, and the presentity URI indicated by the filter in for one presentity whoÆs URI is NOT one of the URIs that result from a lookup, by the PA, on the URI in the To-header, the filter rules do not apply to that any particular presentity and are ignored. All Khartabil, et. al. [Page 7] Internet Draft Congestion Safety and C-I July 2002 presence documents sent to the presentities are not affected by the filter. Multiple filter criteria MAY be included in one SUBSCRIBE. This is achieved by including multiple elements. A SUBSCRIBE request destined to a presence list MAY include multiple filter criteria specific to individual presentities in that presence list. This is achieved by including multiple elements with differing URIs for presentities in each of those elements. This presentity specific filter overrides any presence list specific filter, if any. Presence list specific filter may or may not include a URI. 5.1.2.2 Changing The Filter Criteria Within A Dialog The client MAY reset or change the filter criteria by re-issuing a new SUBSCRIBE request within the existing dialog. The SUBSCRIBE provides the "replace" semantics. This means that all filters are replaced. A SUBSCRIBE within the exiting dialogs that does not contain a filter is assumed to be removing all filter criteria. As mentioend earlier, If the template package ôlistö is used with ôpresenceö in the SUBSCRIBE, the rules apply to all the URIs that result from a lookup, by the Presence Agent, on the URI in the filter criteria. A watcher may override a filter for an individual presentity, that is part of the presence list subscribed to earlier, by issuing a new SUBSCRIBE within the existing dialog. The new filter includes 2 elemets, one for that presentity who filter criteria needs changing, and the other for the presence list (to avoid the replacement of the original filter criteria). 5.1.2.3 Subscriber Interpreting SIP responses The SUBSCRIBE request will be confirmed with a final response. 200- class responses indicate that the subscription has been accepted, and that a NOTIFY will be sent immediately. A 200 response indicates that the subscription has been accepted, the user is authorized to subscribe to presence and that the filter is accepted. A 202 response merely indicates that the subscription has been understood, the content type has been accepted, and that authorization may or may not have been granted. A 202 response also indicates that the filter has not been accepted yet. The acceptation of the filter MAY arrive in a subsequent NOTIFY. Non-200 class final responses indicate that no subscription or dialog has been created, and no subsequent NOTIFY message will be sent. All non-200 class responses have the same meanings and handling as described in RFC 3261 [11] and RFC 3265[4]. Khartabil, et. al. [Page 8] Internet Draft Congestion Safety and C-I July 2002 Specifically, a 415 response indicates that the MIME-type æapplication/simple-pres-filter+xmlÆ is not understood by the server. A 488 response indicates that the content (filter) is understood but some aspects of it were either not understood or not accepted. 5.1.3 Subscriber processing of NOTIFY requests If a 2xx response was returned for the SUBSCRIBE, the NOTIFY that follows MAY contain a body that describes the presence state of the resource after the filter has been applied. If the NOTIFY indicates that a subscription has been terminated [4], the subscription is assumed to be terminated. Behaviour in such events is also described in [4]. If the subscription is indicated as active, NOTIFY requests are handled as described in [2] and [4]. 5.2 Server Operation 5.2.1 NOTIFY Bodies SIP entities compliant with this specification MUST support content- type æapplication/simple-pres-filter+xmlÆ. 5.2.2 Notifier processing of SUBSCRIBE Requests This section present addition functionalities required from the notifier when filters are used in SUBSCRIBE requests bodies. Normal operations as defined in [2] are then followed. If 2 elements address the same presentity, 488 error response is returned. The presence agent will examine the content-type header and will return a 415 response if it does not understand content-type æapplication/simple-pres-filter+xmlÆ. If the presence agent accepts the content-type, it then starts parsing the body. It returns a 488 response if the body is understood but some aspects of the contents (filter) were not understood and accepted. A warning header in the response may give a better indication why the filters are not supported. A 200-class responses indicate that the subscription has been accepted, and that a NOTIFY will be sent immediately. A 200 response indicates that the subscription has been accepted, the user is authorized to subscribe to presence and that the filter is accepted. A 202 response merely indicates that the subscription has been understood, and that authorization may or may not have been granted. Khartabil, et. al. [Page 9] Internet Draft Congestion Safety and C-I July 2002 A 202 response also indicates that the filter has not been accepted yet. The acceptation of the filter MAY arrive in a subsequent NOTIFY. 5.2.2 Notifier Generation of NOTIFY requests Upon receiving the SUBSCRIBE with the filtering rules, the Presence Agent SHOULD retain the filter as long as the subscription persists. The filter SHOULD persist as long as the subscription is active. The filter MAY be incorporated within an existing subscription (an active dialog) by sending a re-SUBSCRIBE that includes the filter in the body. If the response sent to the SUBSCRIBE was a 202, and the 202 was chosen because the filter could not be accepted in time, the NOTIFY MAY be used to terminate the subscription if the filter was not found acceptable. As described in [2], the NOTIFY message MAY contain a body that describes the presence state of the resource. This body is in a format listed in the Accept header of the SUBSCRIBE, or the presence specific default æapplication/cpim-pidf+xmlÆ if the Accept header is omitted. 5.2.2.1 Generating NOTIFY Contents The input to the filter is a PIDF document [3] derived according to the normal functionality defined in [2]. The content is filtered according to the XPath expression. The XPath expression indicates the delivered PIDF XML elements and/or attributes. Prefixes of the namespaces of the items of the PIDF XML document to be filtered must be expanded before applying the filter to the items. The 'report' attribute indicates whether the values of the selected items are delivered or not. If the value of the æreportÆ is "only- selected" the XPath expression directly states the delivered content. In case the value of the 'report' is "default" all the values and attributes of the selected elements are delivered. In addition to the selected contents also the namespaces of all the selected presence information items are conveyed. 5.2.3 Handling of abnormal cases In case of an unvalid filter definition û the filter XML document is not aligned with the filter XML schema, the presence agent rejects the SUBSCRIBE request with a 488. If the subscription was accepted with a 202 response and the filter is being evaluated after that, a NOTIFY with a subscription-state of terminated is sent. An event- reason-value of ôbadfilterö MAY be included. Khartabil, et. al. [Page 10] Internet Draft Congestion Safety and C-I July 2002 The above paragraph introduces an extension to the event-reason- value of subexp-params. The value, as shown above, is ôbadfilterö. In case of an errorneous XPath clause in the filter definition the presence agent either ignores the filter definition or terminates the subscription. In case of indication of empty content by the XPath clause the presence agent functions according to the normal procedure for the content filtering described in this document. 6.0 IANA Considerations A new content type "application/simple-pres-filter+xml" is defined to represent an XML MIME for the filter criteria of Presence. A new event-reason-value ôbadfilterö is defined to represent a the event where a filter is not well formed and not accpeted. This specification follows the guidelines of RFC3023 [12]. OPEN ISSUE: IANA registration template must be added later. (Note/Reminder: We must add IANA registration template for this) 7.0 Examples This chapter describes two use cases where the presence information filtering solution is utilised. In the first use case the watcher is intrested in getting messaging specific information of a certain presentity. In the second use case the watcher is intrested in getting information about the communication means and contact addresses the presentity is currently available for communication on. Below is the Presentity's presence information in PIDF. It includes two tuples: one for the instant messaging and another for the voice related information. closed message IM Khartabil, et. al. [Page 11] Internet Draft Congestion Safety and C-I July 2002 im:presentity@domain.com open voice tel:2224055555@domain.com 7.1 Subscriber requests messaging related information The subscriber initiates a subscription to the presentity's messaging (MMS, IM and SMS) related presence information. The subscription includes the content limiting filter. The filtered content is indicated with the Xpath expression. This Xpath expression selects all the upper, lower and paraller level PIDF XML elements that match the criteria. That criteria are: Description elements whoÆs value begins with "MMS", "SMS" or "IM". The 'default' value of the report attribute states that also the PIDF XML attributes related to the selected PIDF XML elements and values of the selected PIDF XML elements are requested to be included. In this case, the notification includes the contents of the tuple that has the value "IM" in its callerprefs element's description sub-element. SUBSCRIBE request from the subscriber including filtering: SUBSCRIBE sip:presentity@domain.com Via: SIP/2.0/TCP 10.0.0.1:5060;branch=xjfdsjfk To: From: ;tag:12341111 Call-ID: 121212@10.0.0.1 Cseq: 1 SUBSCRIBE Expires: 3600 Event: Presence Contact: Content-Type: application/simple-pres-filter+xml Content-Length: à Khartabil, et. al. [Page 12] Internet Draft Congestion Safety and C-I July 2002 //*[starts-with(urn:example-com:pidf- prefscaps/Description,"IM") or starts-with(urn:example-com:pidf- prefscaps/Description,"SMS") or starts-with(urn:example-com:pidf- prefscaps/Description,"MMS")]/descendant-or-self::*/ancestor-or- self::* Notification to the subscriber: NOTIFY sip:presentity@domain.com SIP/2.0 Via: SIP/2.0/TCP presence.domain.com:5060;branch=xjfder To: ;tag:12341111 From: ;tag:232321 Call-ID: 121212@10.0.0.1 Cseq: 1 NOTIFY Event: Presence Subscription-State: active; expires=3599 Content-Type: application/cpim-pidf+xml Content-Length: à closed message IM im:presentity@domain.com 7.2 Subscriber fetches information about "open" communication means The subscriber makes a subscription to the presentity's available communication means. The subscription includes the content limiting filter. The filtered content is indicated with the Xpath expression. This Xpath expression selects all the upper, lower and paraller level PIDF XML elements that match the criteria. That criteria are: the element's value is "Open". There is also need to indicate that only the tuples which have contact address information are selected. The 'default' value of the report attribute states that Khartabil, et. al. [Page 13] Internet Draft Congestion Safety and C-I July 2002 also the PIDF XML attributes related to the selected PIDF XML elements and values of the selected PIDF XML elements are requested to be included. In this case the notification returns the contents of the tuple that has value is "open" û the voice related information in its status element's basic sub-element. SUBSCRIBE request from the subscriber including filtering: SUBSCRIBE sip:presentity@domain.com SIP/2.0 Via: SIP/2.0/TCP 10.0.0.1:5060;branch=xjfdsjfk To: From: ;tag:12341111 Call-ID: 121212@10.0.0.1 Cseq: 1 SUBSCRIBE Expires: 3600 Event: Presence Contact: Content-Type: application/simple-pres-filter+xml Content-Length: à //*[urn:ietf:params:xml:ns:cpim-pidf/basic="Open" and urn:ietf:params:xml:ns:cpim-pidf/contact]/descendant-or- self::*/ancestor-or-self::* Notification to the subscriber: NOTIFY sip:presentity@domain.com SIP/2.0 Via: SIP/2.0/TCP presence.domain.com:5060;branch=xjfder To: ;tag:12341111 From: ;tag:232321 Call-ID: 121212@10.0.0.1 Cseq: 1 NOTIFY Event: Presence Subscription-State: active; expires=3599 Content-Type: application/cpim-pidf+xml Content-Length: à Khartabil, et. al. [Page 14] Internet Draft Congestion Safety and C-I July 2002 open voice tel:2224055555@domain.com 8.0 Presence Package Specific Filters XML Schema ******************* XML Schema Implementation (Normative) XML Schema Definition for SIP Event Filtering for Presence. Copyright 2002. Nokia. All rights reserved.