SIMPLE H. Khartabil Internet-Draft E. Leppanen Expires: August 2, 2004 M. Lonnfors J. Costa-Requena Nokia February 2, 2004 An Extensible Markup Language (XML) Based Format for Event Notification Filtering draft-ietf-simple-filter-format-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 August 2, 2004. Copyright Notice Copyright (C) The Internet Society (2004). 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. In order to enable this, a format is needed to enable the subscriber to choose when notifications are to be sent to it and what they are to contain. This document presents a solution in the form of an XML Khartabil, et al. Expires August 2, 2004 [Page 1] Internet-Draft XML Based Format for Filtering February 2004 document format. Table of Contents 1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 3. Structure of XML-Encoded Filter Criteria . . . . . . . . . 3 3.1 The Root Element . . . . . . . . . . . . . . 4 3.2 The Element . . . . . . . . . . . . . . . . . . . 4 3.3 The Element . . . . . . . . . . . . . . . . . . . . 5 3.3.1 The Element . . . . . . . . . . . . . . . . . . 5 3.3.1.1 The "type" Attribute . . . . . . . . . . . . . . . . . . . 6 3.3.2 The Element . . . . . . . . . . . . . . . . . . 6 3.4 The Element . . . . . . . . . . . . . . . . . . 7 3.4.1 The Element . . . . . . . . . . . . . . . . . . 7 3.4.1.1 The "changed-from" Attribute . . . . . . . . . . . . . . . 7 3.4.1.2 The "changed-to" Attribute . . . . . . . . . . . . . . . . 7 3.4.1.3 The "changed-by" Attribute . . . . . . . . . . . . . . . . 8 3.4.1.4 Combination of Attributes . . . . . . . . . . . . . . . . 8 3.4.2 The Element . . . . . . . . . . . . . . . . . . . 8 3.4.3 The Element . . . . . . . . . . . . . . . . . . 8 4. Syntax for Referencing XML Items and Making Logical Expressions . . . . . . . . . . . . . . . . . . . . . . . 8 5. IANA Considerations . . . . . . . . . . . . . . . . . . . 9 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 9 6.1 Filter Criteria Using Element . . . . . . . . . . . 9 6.2 Filter Criteria Using Element . . . . . . . . . 10 6.3 Filter Criteria Using and Elements . . . 10 6.4 Content Filter Using Namespaces . . . . . . . . . . . . . 11 6.5 Content Filter Using Only Elements . . . . . . . 11 6.6 Two Content Filters as Filter Criteria . . . . . . . . . . 12 7. XML Schema for Filter Criteria . . . . . . . . . . . . . . 12 8. Security Requirements . . . . . . . . . . . . . . . . . . 14 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 15 References . . . . . . . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 16 Intellectual Property and Copyright Statements . . . . . . 18 Khartabil, et al. Expires August 2, 2004 [Page 2] Internet-Draft XML Based Format for Filtering February 2004 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 Filtering is a mechanism for defining the preferred content to be delivered and for specifying the rules for when the content should be delivered. See requirements in [9] and [10]. 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. The SIP event notification framework [6] 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. The structure of the filter criteria is described using the XML Schema. The filter criteria is presented as an XML document. The XML document contains the user's preference when notifications are to be sent to it and what they are to contain. The scope of the "when" part is triggering. The triggering is defined as enabling a subscriber to specify triggering rules for notifications where the criteria are based on changes of the package specific state information, e.g., for the presence information document [5] the change in the value of the element. The functionality of the filtering regarding the SIP event notifications is specified in [11]. 3. Structure of XML-Encoded Filter Criteria The filter criteria is an XML document [16] that MUST be well-formed and MUST be valid. The filter criteria XML documents MUST have the XML declaration and it SHOULD contain an encoding declaration in the XML declaration, for example; "". This specification makes use of XML namespaces Khartabil, et al. Expires August 2, 2004 [Page 3] Internet-Draft XML Based Format for Filtering February 2004 for identifying the XML schema of the filter criteria instance documents and document fragments. The namespace identifier for elements defined by this specification is a URN [13], using the namespace identifier 'ietf' defined by [14] and extended by [12]. This urn is: urn:ietf:params:xml:ns:simple-filter+xml. This namespace declaration indicates the namespace on which the filter criteria are based on. 3.1 The Root Element The root element of the filter criteria is . The element MUST contain the namespace definition mentioned above. With the optional "package" attribute it is possible to define the package to which the filter criteria is applied. This might be especially useful in cases where the XML document containing the filter criteria is separated from the events that makes use of it or from the protocol that usually carries it. The element MUST contain one or more elements. 3.2 The Element The element is used to specify the content of an individual filter. The MUST have an 'id' attribute. The value of the 'id' attribute MUST be unique within the element. The MAY have an 'uri' attribute. The value of the 'uri' attribute is the URI of the resource which information is requested for. The URI of the resource is useful in cases where the 'event list' extension [7] is used with a package. Since a subscription to an event package may be addressed to an event list, the "uri" attribute allows the subscriber to define a filter specific to an individual resource within that list. That resource may be another list. The 'uri' attribute may, of course, carry the URI of the list itself. If the does not contain the 'uri' attribute, the filter applies to the resource indentified in the subscription request. The URI attribute MAY also carry a domain. In this case, the filter applies to resources in that domain. This can be used when a subscription is for a resource that is an event list with many resources from differing domains. Khartabil, et al. Expires August 2, 2004 [Page 4] The MAY have a 'remove' attribute which indicates together with the 'id' attribute the existing filter to be removed. The value of the 'remove' attribute is of the type "Boolean". The default value is 'false'. The element MAY contain a element and MAY contain one or more elements, but MUST contain either the element or the element. 3.3 The Element The element is used to specify the content to be delivered to the user. It does not specify the exact content but the rules that are used to construct that information. The element MAY contain one or more elements and one or more elements. However, the element MUST contain at least one element. When more than one element has been defined, the result is the union of all the elements. When more than one element has been defined, the result is the union of all the elements. 3.3.1 The Element The element is used to select the content to be delivered. Its value can identify XML elements, an attribute or a namespace of XML document to be filtered. This is indicated using the "type" attribute. The element, if identifying elements, MUST identify one element only, unless the conditional expression results in more than one element with the same name being identified. Note that the resulting XML document MUST be valid. Therefore, in addition to including the elements identified with the element, all other mandatory XML elements and/or attributes must be incorporated in the resulting XML document in order to make it valid. This, in practice, means that a subscriber defining a filter only needs to optional elements and/or attributes, but may mandatory elements and/or attributes as well. The following example selects the element defined in the PIDF XML document [2]. This results in the selection of all the ancenstors of . I.e. and . //tuple/status. When identifying XML elements, the value may consist of two parts (similar to XPath [17]): the XML element selector and the condition (comparison and logical expressions). The syntax is defined in section Section 4 (see the definition of "selection".) Khartabil, et al. Expires August 2, 2004 [Page 5] Internet-Draft XML Based Format for Filtering February 2004 3.3.1.1 The "type" Attribute The "type" attribute is used to describe the value of the element. The following values are pre-defined: 'xml-element' and 'namespace'. The "type" attribute is optional, and, if omitted, the default value is 'xml-element'. The syntax is defined in a way that follows XPath. The XML element selector appears first followed by the condition part in square brackets. In the XML element selector part the XML elements may be referenced by giving the full hierarchical path as: "/presence/tuple/ status/basic", or by denoting the selection to cover any hierarchical level by its name as: "//basic" or using the wildcard "*" denoting any value in a certain level as "/*/watcher". Example references are listed as follows: o Selection by using an XML element as a condition: * //*[status/basic="open"] * /presence/tuple[*/basic="open"] o Selection by using XML attributes as a condition : * //watcher[@duration-subscribed<500] * /*/watcher[@event="rejected"] o Selection by using two XML elements as a condition : * //tuple[status/basic="open" and type="device"] The "namespace" value is used when the element contains a value of a namespace. The value is the URI of the namespace. The resulting XML document is comprised of the elements defined within the namespace. 3.3.2 The Element The element is used to define exceptions to the set of XML elements and/or attributes selected by the elements. Thus, those XML elements (including their lower level "child" elements) and/or attributes defined by the element are not delivered. This is most useful when an element identifies a namespace. Khartabil, et al. Expires August 2, 2004 [Page 6] Internet-Draft XML Based Format for Filtering February 2004 The element has the optional "type" attribute (see the definition of the "type" in Section 3.3.1.1). The element MUST NOT be used if there are no element(s) in the same content filter. 3.4 The Element The element is used to identify the package specific changes that a resource has to encounter before the content is delivered to the subscriber. It can appear more than once in a filter document. Multiple appearances of this element denotes the "OR" operation. This means that updates to a resource that satisfy any of the elements criteria constitute the content to be delivered. The element MAY contain the element, the element or the , but MUST contain at least one of the three elements. Any combination of the 3 elements is possible. Multiple appearances of those element within a element denotes the "AND" operation. This means that updates to a resource that satisfy ALL of the , and elements' criteria within the element constitute the content to be delivered. 3.4.1 The Element The element is used to identify the XML element or attribute, from the package specific XML document, that must change, compared to the previous XML document, in order to activate the trigger and cause the content to be delivered. The XML element or attribute is identified using the syntax defined in Section 4 for the "reference". The element MUST identify only one XML element or attribute. The element MAY contain the "changed-from" attribute, "changed-to" attribute, "changed-by" attribute, or any combination of the three. 3.4.1.1 The "changed-from" Attribute A trigger is active when the XML element or attribute identified with the element has changed from the value indicated by this attribute to a different value. 3.4.1.2 The "changed-to" Attribute A trigger is active when the XML element or attribute identified with the element has changed to the value indicated by this Khartabil, et al. Expires August 2, 2004 [Page 7] Internet-Draft XML Based Format for Filtering February 2004 attribute from a different value. 3.4.1.3 The "changed-by" Attribute A trigger is active when the XML element or attribute identified with the element has changed by the value indicated by this attribute from a different value. 3.4.1.4 Combination of Attributes Any combination of the "changed-from", "changed-to", and "changed-by" attributes in the element is possible. For example, if the "changed-from" attribute was combined with the "changed-to" attribute it is interpreted as: the trigger is active when the XML element or attribute identified with the element has changed from the "changed-from" value to the "changed-to" value. Note that if the "changed-by" attribute is used in combination with the other attributes, the other attribute types MUST match the "changed-by" type of decimal. 3.4.2 The Element The element is used to trigger the content delivery when the XML element or attribute, identified in it, has been added to the new XML document in comparison to the previous XML document. It can be used, for example, to learn of new services and/or capabilities subscribed to by the user, or services and/or capabilities that the user has now allowed the subscriber to see. The XML element or attribute is indicated using the syntax defined in Section 4 for the "reference". Note that if a filter includes both the content filter () part and the element then the definitions of the part SHOULD cover also the added elements, or otherwise the content is delivered without the items defined in the element. 3.4.3 The Element The element is used to trigger the content to be delivered when the XML element or attribute, identified in it, has been removed from the new XML document in comparison to the previous XML document. The XML element or attribute is indicated using the syntax defined in Section 4 for the "reference". 4. Syntax for Referencing XML Items and Making Logical Expressions The ABNF [18] is used to describe the syntax for the expressions. The syntax is defined to be XPATH [17] compatible, but has only a Khartabil, et al. Expires August 2, 2004 [Page 8] Internet-Draft XML Based Format for Filtering February 2004 restricted set of capabilities of the XPATH. More information about the meaning of the items of the syntax can be found in [17]. The "abbreviated syntax" of the "node test" is used in the references ("reference"). The expression in the syntax relates to the predicate, comparision and logical expressions of the XPATH. selection = reference [expression] expression = "[" (elem-expr / attr-expr) 1*[oper (elem-expr / attr-expr)] "]" elem-expr = (elem-path / ".") compar value elem-path = (element / "*") 1*["/" / "*" / element] ["*" / element] attr-expr = [elem-path "/"] attribute compar value reference = elem-reference / attr-reference elem-reference = "/" 1*("/" / "/*" / ("/" element)) attr-reference = reference attribute oper = "and" / "or" compar = "=" / "<" / ">" element = [ns] string attribute = "@" [ns] string ns = string ":" string = value = 5. IANA Considerations A new content type "application/simple-filter+xml" is defined to represent an XML MIME for the filter criteria. This specification follows the guidelines of RFC3023 [15] OPEN ISSUE: IANA registration template must be added later. 6. Examples The XML Schema for the XML document examples is specified in the Section 7. 6.1 Filter Criteria Using Element A user wishes to get to know his friend's availability and willingness for messaging (SMS, IM and MMS) in order to know whether the friend is able to receive a message, the address to contact and the type of the message to be used. This example shows how to define a content filter. The whole content and upper level elements of the tuples of the presence information Khartabil, et al. Expires August 2, 2004 [Page 9] Internet-Draft XML Based Format for Filtering February 2004 are selected based on a condition defined by a logical expression. The condition is: select elements that have a value "MMS", "SMS" or "IM". The element is defined in [3] as an extension to PIDF [2]. The first filter definition includes optional elements while the second filter definition shows only the minimum set of definitions. The first filter definition: //pidf:tuple/pidf:status/pidf:basic[rpid:class="IM" or rpid:class="SMS" or rpid:class="MMS"] 6.2 Filter Criteria Using Element A user requires to get informed when his colleaque becomes available by some communication mean(s). The user gets the full presence state of the colleaque. The filter selects the content to be delivered to the subscriber when a certain PIDF [2] tuple changes its status from 'CLOSED' to 'OPEN'. /pidf:presence/pidf:tuple/pidf:status/pidf:basic 6.3 Filter Criteria Using and Elements A user wishes to get information about pending and waiting subscriptions in order to be able to authorise watchers to see his Khartabil, et al. Expires August 2, 2004 [Page 10] Internet-Draft XML Based Format for Filtering February 2004 presence information. The filter selects watcher information notifications [8] to be sent when a subscription status has changed to "pending" or "waiting". In the notification, only the watchers that have a status of "pending" or "waiting" are included. wi:watcher[@wi:status="pending" or @wi:status="waiting"] //wi:watcher/@wi:status@status //wi:watcher/@wi:status@status 6.4 Content Filter Using Namespaces A user turns her teminal on and the terminal automatically fetches general presence status and information about communication means from a certain pre-defined set of her buddies. The filter is defined to select XML elements belonging to the pidf namespace. urn:ietf:params:xml:ns:pidf 6.5 Content Filter Using Only Elements A user wants to know if a group of his friends are available for gaming. He orders notifications about the current status and future changes of the game specific presence information. Khartabil, et al. Expires August 2, 2004 [Page 11] This filter is defined to select the game specific tuple to be delivered. //pidf:tuple/pidf:status[game-ext:label="game-X"] 6.6 Two Content Filters as Filter Criteria The user is interested in getting up-to-date information about the communication means and contact addresses of his friends. The user wants to get also more information (e.g. location) about one of the friends in the list named Bob. The PIDF element is filtered out, i.e. excluded. The list was predefined as buddies@domain.com. //pidf:tuple/pidf:status/pidf:basic[rpid:type="service"] urn:ietf:params:xml:ns:pidf //pidf:tuple/pidf:note 7. XML Schema for Filter Criteria XML Schema Implementation (Normative) Khartabil, et al. Expires August 2, 2004 [Page 12] Internet-Draft XML Based Format for Filtering February 2004 XML Schema Definition for Filter Criteria. Khartabil, et al. Expires August 2, 2004 [Page 13] Internet-Draft XML Based Format for Filtering February 2004 8. Security Requirements The filters in the body in a SIP message has a significant effect on the ways in which the request is handled at a server. As a result, it is especially important that messages containing this extension be Khartabil, et al. Expires August 2, 2004 [Page 14] Internet-Draft XML Based Format for Filtering February 2004 authenticated and authorised. Processing of requests and looking up filter criteria requires a set of operations and searches, which can require some amount of computation. This enables a DoS attack whereby a user can send requests with substantial number of messages with large contents, in the hopes of overloading the server. To counter this, the server SHOULD only allow filters with no more than about 20 occurances of the , , and elements. Requests can reveal sensitive information about a UA's capabilities. If this information is sensitive, it SHOULD be encrypted using SIP S/ MIME capabilities. All filtering related security measures discussed in [6] MUST be followed along with package specific security. 9. Acknowledgements The authors would like to thank Jonathan Rosenberg, Henning Schulzrinne, Tim Moran, Jari Urpalainen, Sreenivas Addagatla and all the active SIMPLE mailing list contributors for their valuable input. References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [2] Sugano, H., "CPIM Presence Information Data Format", draft-ietf-impp-cpim-pidf-08.txt (work in progress), May 2003. [3] Schulzrinne, H., "RPID -- Rich Presence Information Data Format", draft-ietf-simple-rpid-00.txt (work in progress), July 2003. [4] Schulzrinne, H., "CIPID: Contact Information in Presence Information Data Format", draft-ietf-simple-cipid-00.txt (work in progress), August 2003. [5] Rosenberg, J., "Session Initiation Protocol (SIP) Extensions for Presence", draft-ietf-simple-presence-10.txt, January 2003. [6] Roach, A., "Session Initiation Protocol (SIP)-Specific Event Notification", RFC 3265, June 2002. [7] Roach, A., "A Session Initiation Protocol (SIP) Event Notification Extension for Resource Lists", Khartabil, et al. Expires August 2, 2004 [Page 15] Internet-Draft XML Based Format for Filtering February 2004 draft-ietf-simple-event-list-04.txt, June 2003. [8] Rosenberg, J., "An Extensible Markup Language (XML) Based Format for Watcher Information", draft-ietf-simple-winfo-format-04.txt, January 2003. [9] Khartabil, H., "Requirements for Presence Specific Event Notification Filtering", draft-ietf-simple-pres-filter-reqs-03.txt (work in progress), January 2004. [10] Kiss, K., "Requirements for Filtering of Watcher Information", draft-ietf-simple-winfo-filter-reqs-01.txt (work in progress), January 2004. [11] Khartabil, H., "Functional Description of Event Notification Filtering", draft-simple-filter-funct-00.txt (work in progress), February 2004. [12] Mealling, M., "The IETF XML Registry", draft-mealling-iana-xmlns-registry-04.txt, June 2002. [13] Moats, R., "The URN Syntax", RFC 2141, May 1997. [14] Moats, R., "The URN Namespace for IETF Documents", RFC 2648, August 1999. [15] Murata, M., "XML Media Types", RFC 3023, March 1997. [16] Bray, T., "Exensible Markup Language (XML) 1.0 (Second Edition)", W3C CR CR-xml11-20011006, October 2000. [17] Clark, J., "XML Path Language (XPath) Version 1.0", W3C REC REC-xpath-19991116, November 1999. [18] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. Khartabil, et al. Expires August 2, 2004 [Page 16] Internet-Draft XML Based Format for Filtering February 2004 Authors' Addresses Hisham Khartabil Nokia P.O. Box 321 Helsinki Finland Phone: +358 7180 76161 EMail: hisham.khartabil@nokia.com Eva Leppanen Nokia P.O BOX 785 Tampere Finland Phone: +358 7180 77066 EMail: eva-maria.leppanen@nokia.com Mikko Lonnfors Nokia Itamerenkatu 00180 Helsinki Finland Phone: + 358 50 4836402 EMail: mikko.lonnfors@nokia.com Jose Costa-Requena Nokia P.O. Box 321 FIN-00045 NOKIA GROUP FINLAND Phone: +358 71800 8000 EMail: jose.costa-requena@nokia.com Khartabil, et al. Expires August 2, 2004 [Page 17] Internet-Draft XML Based Format for Filtering February 2004 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Full Copyright Statement Copyright (C) The Internet Society (2004). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION Khartabil, et al. Expires August 2, 2004 [Page 18] Internet-Draft XML Based Format for Filtering February 2004 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Khartabil, et al. Expires August 2, 2004 [Page 19]