SIMPLE H. Khartabil Internet-Draft M. Lonnfors Expires: November 18, 2003 J. Costa-Requena E. Leppanen Nokia May 20, 2003 Functional Description of Event Notification Filtering draft-khartabil-simple-filter-funct-00 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. This Internet-Draft will expire on November 18, 2003. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract The SIP event notification framework describes the usage of the Session Initiation Protocol (SIP) for subscriptions and notifications of changes to a state of a resource. The document does not describe a mechanism of how filtering of event notification information can be achieved. This document describes the operations a subscriber performs in order to define filtering rules, how to handle responses to subscriptions carrying filtering rules, and how to handle notifications with filtering rules applied to them. The document also describes how the Khartabil, et al. Expires November 18, 2003 [Page 1] Internet-Draft Functional Description of Filtering May 2003 notifier behaves when receiving such filtering rules and how a notification is constructed. The format of the filter is outside the scope of this document. Table of Contents 1. Conventions . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Client Operation . . . . . . . . . . . . . . . . . . . . . . 4 3.1 Transport Mechanism . . . . . . . . . . . . . . . . . . . . 4 3.2 SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . . 4 3.3 Subscriber Generating SUBSCRIBE Requests . . . . . . . . . . 4 3.3.1 Structure of Filter Criteria . . . . . . . . . . . . . . . . 4 3.3.2 Request-URI vs. Filter Criteria URI . . . . . . . . . . . . 5 3.3.3 Changing Filter Criteria within a Dialog . . . . . . . . . . 5 3.3.4 Subscriber Interpreting SIP responses . . . . . . . . . . . 5 3.4 Subscriber Processing of NOTIFY Requests . . . . . . . . . . 6 4. Resource List Server Behaviour . . . . . . . . . . . . . . . 6 4.1 Request-URI vs. Filter Criteria URI . . . . . . . . . . . . 6 5. Server Operation . . . . . . . . . . . . . . . . . . . . . . 7 5.1 NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . . 7 5.2 Notifier Processing SUBSCRIBE Requests . . . . . . . . . . . 7 5.2.1 Request-URI vs. Filter Criteria URI . . . . . . . . . . . . 7 5.3 Notifier Generating NOTIFY Requests . . . . . . . . . . . . 8 5.3.1 Generation of NOTIFY Contents . . . . . . . . . . . . . . . 8 5.3.2 Handling of Notification Triggering Rules . . . . . . . . . 9 5.4 Handling Abnormal Cases . . . . . . . . . . . . . . . . . . 9 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . 10 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 10 7.1 Presence Specific Examples . . . . . . . . . . . . . . . . . 10 7.1.1 Subscriber Requests Messaging Related Information . . . . . 11 7.1.2 Subscriber Fetches Information about "Open" Communication Means . . . . . . . . . . . . . . . . . . . . 12 7.1.3 Subscriber Requests Notifications when Presentity's Status Changes . . . . . . . . . . . . . . . . . . . . . . . 14 7.2 Watcher Information Specific Examples . . . . . . . . . . . 16 7.2.1 Watcher Subscriber Makes Subscription to Get All the Information about Active Watchers . . . . . . . . . . . . . 17 7.2.2 Watcher Subscriber Requests History Information of Watchers . . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.2.3 Watcher Subscriber Requests Specific Watcher Info On Specific Triggers . . . . . . . . . . . . . . . . . . . . . 20 8. Security Considerations . . . . . . . . . . . . . . . . . . 22 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 References . . . . . . . . . . . . . . . . . . . . . . . . . 22 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 23 Intellectual Property and Copyright Statements . . . . . . . 25 Khartabil, et al. Expires November 18, 2003 [Page 2] Internet-Draft Functional Description of Filtering May 2003 1. Conventions 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 [1] and indicate requirement levels for compliant implementations. 2. Introduction SIP event notification is described in [5]. 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. Filtering is a mechanism for controlling the content of event notifications. Additionally the subscriber may specify the rules for when a notification should be sent to it. Requirements for such mechanisms are defined in [10] and [11]. 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 [5] that the notifier may send a NOTIFY at any time, but typically it is sent when the state of the resource changes. It also states that the notifications would contain the complete and current state of the resource authorized for a certain subscriber to see. The format of such resource state information is package specific. In this memo, we assume that the NOTIFY for any package contains an XML document. There is a separate approach for the rate limiting of SIP event notifications, namely the throttling mechanism [12]. This throttling mechanism allows the subscriber to specify a maximum rate at which event notifications are generated by a single notifier. The solution for such requirements is out of scope for this document. This document presents a mechanism for filtering whereby a subscriber describes its preference when notifications are to be sent to it and what they are to contain. It also describes how the notifier functions when generating notifications by taking into account filters and default functionality of the package/service. The XML format for defining the filter criteria is described in [9]. Khartabil, et al. Expires November 18, 2003 [Page 3] Internet-Draft Functional Description of Filtering May 2003 3. Client Operation 3.1 Transport Mechanism Transportation of the filter criteria to the server is achieved by inserting the XML document, as defined in [9], in the body of the SUBSCRIBE request. Alternatively, the XML document can be uploaded to the server using means outside the scope of this document. 3.2 SUBSCRIBE Bodies SIP entities compliant with this specification MUST support the content type 'application/simple-filter+xml'. 3.3 Subscriber Generating SUBSCRIBE Requests This section presents additional functionality required from the subscriber when filters are used in the bodies of the SUBSCRIBE requests. Normal operations of services, e.g., as defined in [4], [8] and [6] are otherwise followed. As defined in [5], the SUBSCRIBE message MAY contain a body. This body would serve the purpose of carrying filtering information. Honouring those filters is at the discretion of the notifier and might depend on local policies. No content in the body of a SUBSCRIBE indicates to the notifier that no filter is being requested so that the notifier is instructed to send all the NOTIFY requests using the notifier's own or service specific policy. Note that e.g. in the list case [6] the filter criteria might have been uploaded to the server beforehand (by means outside the scope of this document). If the body of the SUBSCRIBE includes the filter criteria, the body MUST be of the MIME-Type 'application/simple-filter+xml'. 3.3.1 Structure of Filter Criteria Multiple filter criteria MAY be included in one SUBSCRIBE. This is achieved by including multiple elements in the filter criteria [9]. Each element may include a URI attribute. A SUBSCRIBE request destined to a list URI [6] MAY include multiple criteria specific to individual resources. This is achieved by including multiple elements with different URIs of resources in each of those elements. This resource specific filter criteria overrides any list specific filter criteria, if any. The list specific filter criteria may or may not include a URI. Khartabil, et al. Expires November 18, 2003 [Page 4] Internet-Draft Functional Description of Filtering May 2003 3.3.2 Request-URI vs. Filter Criteria URI The URI in the filter criteria defines the target resource, e.g. in the Presence service case; it is the presentity's presence information to which the filter criteria is applied. The subscriber MAY choose to leave the URI in the filter criteria undefined. If the URI is not defined within the filter criteria, the filter criteria apply to the resource identified in the Request-URI. Similarly, the subscriber MAY define a filter criteria URI. If the Request-URI is a list URI [6], the filter criteria URI MUST be the list URI, a sub-list URI or resource who's URI is one of the URIs that result from a lookup, by an RLS, on the Request-URI. If not, the filter criteria may be ignored or may be rejected. 3.3.3 Changing 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 filter definitions are replaced. A SUBSCRIBE within the exiting dialog that does not contain a filter criteria is assumed to remove all existing filter criteria. In case of a list, a client may override the existing filter criteria for an individual resource, that is part of the list subscribed to earlier, by issuing a new SUBSCRIBE within the existing dialog. The new filter criteria MAY, e.g., include two elements: one for that resource who's filter criteria need to be changed and another for the rest of the resources of the list (to avoid the replacement of the original filter criteria). 3.3.4 Subscriber Interpreting SIP responses The SUBSCRIBE request will be confirmed with a final response. 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 and the filter criteria 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 acceptance of the filter criteria MAY arrive in a subsequent NOTIFY. A 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 [3] and [5]. Khartabil, et al. Expires November 18, 2003 [Page 5] Specifically, a "415" response indicates that the MIME type 'application/simple-filter+xml' is not understood by the notifier. A "488" response indicates that the content type (filter) is understood but some aspects of it were either not understood or not accepted. 3.4 Subscriber Processing of NOTIFY Requests If the 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 criteria have been applied. If the NOTIFY indicates that a subscription has been terminated [5], the subscription is assumed to be terminated. Behaviour in such events is also described in [5]. If the subscription is indicated as active, NOTIFY requests are handled as described in package specific documents and [5]. 4. Resource List Server Behaviour The Resource List Server is defined in [6]. This section describes how such entity behaves in the presence of a filter criteria in a subscription to a list. 4.1 Request-URI vs. Filter Criteria URI If the URI is not defined within the filter criteria, the filter criteria apply to the resource identified in the Request-URI. If no URI is indicated by the filter criteria, the filter criteria apply to all the notifications that the RLS issues. If the URI indicated by the filter criteria is a list URI, the filter criteria apply to all the notifications that the RLS issues. If the URI indicated by the filter criteria is for one resource who's URI is one of the URIs that result from a lookup, by the RLS, on the Request-URI, the filter criteria for that particular resource are extracted and propagated in the SUBSCRIBE request sent to that resource. (it is possible to have more than one filter criteria in a SUBSCRIBE body, and therefore a filter criteria specific to a resource must be extracted and only that is propagated. For example, if the Request-URI in a SUBSCRIBE has the value "sip:mybuddies@mydomain.com" where "bob@otherdomain.com" is a resource belonging to that list, and the URI in a filter criteria is "sip:bob@otherdomain.com", the filter criteria specific for Bob are extracted and placed in the body of the SUBSCRIBE sent to "bob@otherdomain.com". If the URI indicated by the filter criteria is for one resource who's URI is NOT one of the URIs that result from a lookup, by the RLS, on Khartabil, et al. Expires November 18, 2003 [Page 6] Internet-Draft Functional Description of Filtering May 2003 the Request-URI, the filter criteria are propagated to all the fanned out subscriptions. This is to accommodate the scenario where the subscriber knows that there are sub-lists in the list that the original subscription was sent to, and the subscriber wishes to set a filter criteria for a resource in that sub-list. 5. Server Operation 5.1 NOTIFY Bodies SIP entities compliant with this specification MUST support content-type 'application/simple-filter+xml'. 5.2 Notifier Processing SUBSCRIBE Requests This section present addition functionality required from the notifier when filters are used in the bodies of the SUBSCRIBE requests. Normal package specific functionality are otherwise followed. The notifier will examine the content type header and will return a 415 response if it does not understand the content type 'application/ simple-filter+xml'. If the notifier accepts the content type, it MAY send a "202" response. It then starts parsing the body [14]. Procedures described in section Section 5.4 are followed if an error is encountered. A 200-class responses indicate that the subscription has been accepted, and the NOTIFY will be sent immediately. A "200" response indicates that the subscription has been accepted, the user is authorized and the filter is accepted. A "202" response merely indicates that the subscription has been understood, but the authorization may or may not have been granted. A "202" response also indicates that the filter criteria have not been accepted yet. The acceptance of the filter criteria MAY arrive in a subsequent NOTIFY. 5.2.1 Request-URI vs. Filter Criteria URI The subscriber may have chosen to leave the URI in the filter criteria undefined. If the URI is not defined within the filter criteria, the filter criteria apply to the resource identified in the Request-URI. Similarly, the subscriber may have chosen to include a URI in the filter criteria. In this case, the filter criteria apply to all notifications send for this subscription. If the Request-URI and the URI in the filter criteria mismatch, the filter criteria may be Khartabil, et al. Expires November 18, 2003 [Page 7] Internet-Draft Functional Description of Filtering May 2003 ignored or may be rejected. 5.3 Notifier Generating NOTIFY Requests Upon receiving the SUBSCRIBE with the filter criteria, the notifier SHOULD retain the filter criteria as long as the subscription persists. The filter MAY be incorporated within an existing subscription (in an active dialog) by sending a re-SUBSCRIBE that includes the filter criteria in the body. If the response sent to the SUBSCRIBE was the 202 and the 202 was chosen because the filter could not be accepted that time, the NOTIFY MAY be used to terminate the subscription if the filter was found unacceptable. As described in [5], the NOTIFY message MAY contain a body that describes the state of the resource. This body is in one of the formats listed in the Accept header of the SUBSCRIBE, or the package specific default if the Accept header is omitted. 5.3.1 Generation of NOTIFY Contents If the NOTIFY being sent is the immediate one sent after a 2xx response to the original SUBSCRIBE, its contents may be populated according to the filter criteria. If applying the filter criteria results in not sending a NOTIFY, the NOTIFY must be with empty contents. A notifier may also choose not to obey the filter criteria in the first NOTIFY and instead send the configured value authorised for that subscriber set by the notifier using means outside the scope of this document). The input to the content filter is a package specific XML document, e.g. [2] and [7] derived according to the package specific specifications, ([4] and [8]). The content is filtered according to the XPath expression [15] in the element of the filter criteria. The XPath expression indicates the delivered XML elements and/or attributes. Prefixes of the namespaces of the items of the XML document to be filtered must be expanded before applying the filter to the items. The XPath expression directly states the XML elements and attributes to be delivered in the NOTIFY, along with their values. In addition to the selected contents also the namespaces of all the selected items are included in the NOTIFY. The XML elements and/or attributes indicated by the XPath expression in the element must be items that the subscriber is authorised to see. If not, the notifier policy dictates the behaviour of the notifier (notifier can either ignore Khartabil, et al. Expires November 18, 2003 [Page 8] Internet-Draft Functional Description of Filtering May 2003 the filter, parts of the filter, or reject the filter completely). Implementers need to carefully consider such an implementation decision; the subscriber may not be aware of the authorised contents and therefore most likely will include in the filter a criteria requesting unauthorised contents. It is therefore RECOMMENDED that notifiers just ignores the parts of the filter criteria where it is requesting authorised info. I.e. The filter criteria in the element where the unauthorised contents are requested is ignored. If polite blocking is used by the notifier, the notifier may choose not to ignore the filter, but choose to deliver notifications containing bogus information in the unauthorised elements or attributes. The resultant XML document MUST be well formed and valid according to the XML schema. This means that all mandatory elements and attributes along with their values MUST be included in the XML document regardless of the XPath expression. In other words, if the results of applying a filter criteria on an XML document results in a non-valid XML document, the notifier MUST copy elements and attributes, along with their values, from the original XML document into the newly formulated one in order for it to be a valid one. 5.3.2 Handling of Notification Triggering Rules There can be several elements inside one element. If the criteria for any of the elements are satisfied, a NOTIFY SHOULD be generated. The items (XML elements and/or attributes) indicated by the XPath expression in the element, element or element must be items that the subscriber is authorised to access. If not, the notifier policy dictates the behaviour of the notifier (notifier can either ignore the filter, parts of the filter, or reject the filter completely). 5.4 Handling Abnormal Cases In case of an invalid filter criteria definition the XML document of the filter criteria is not aligned with the XML schema of the filter criteria [9]. The notifier rejects the SUBSCRIBE request with a "488" response. A warning header in the response may give better indication why the filters were not accepted. If the subscription was accepted with a "202" response but the invalid filter criteria was discovered after that, a NOTIFY with a subscription-state of value 'terminated' is sent. An event-reason-value "badfilter", introduced here, of subexp-params [5] MAY be included. In case of an erroneous XPath clause in the filter definition the Khartabil, et al. Expires November 18, 2003 [Page 9] Internet-Draft Functional Description of Filtering May 2003 notifier either ignores the filter definition or terminates the subscription. If a or element is empty, the notifier proceeds as if the element did not exist. 6. IANA Considerations A new event-reason-value "badfilter" is defined to represent the event where the filter criteria is not well formed and/or not accepted. OPEN ISSUE: IANA registration template must be added later. [13] 7. Examples The following chapters include filtering examples for Presence and Watcher Information. The format of filter criteria is according to [9]. 7.1 Presence Specific Examples This chapter describes three use cases where the presence information filtering solution is utilised [4]. In the first use case the watcher is interested in getting messaging specific information of a certain presentity. In the second use case the watcher is interested in getting information about the communication means and contact addresses the presentity is currently available for communication on. The third case shows how a presentity can request triggers to receive notifications Below is the Presentity's presence information in PIDF [2]. It includes two tuples: one for the instant messaging and another for the voice related information. Khartabil, et al. Expires November 18, 2003 [Page 10] Internet-Draft Functional Description of Filtering May 2003 closed im im:presentity@domain.com open voice tel:2224055555@domain.com 7.1.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 parallel level PIDF XML elements that match the criteria (this means the tuple and its root element). That criteria are: