idnits 2.17.1 draft-ietf-sip-xcapevent-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 707 has weird spacing: '... Change in...' -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 9, 2009) is 5402 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'XXX' is mentioned on line 1198, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 649, but not defined == Outdated reference: A later version (-14) exists of draft-ietf-simple-xcap-diff-13 == Outdated reference: A later version (-04) exists of draft-ietf-sipcore-subnot-etags-02 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3265 (Obsoleted by RFC 6665) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SIP J. Urpalainen 3 Internet-Draft Nokia 4 Intended status: Standards Track D. Willis, Ed. 5 Expires: January 10, 2010 Softarmor Systems LLC 6 July 9, 2009 8 An Extensible Markup Language (XML) Configuration Access Protocol (XCAP) 9 Diff Event Package 10 draft-ietf-sip-xcapevent-08 12 Status of this Memo 14 This Internet-Draft is submitted to IETF in full conformance with the 15 provisions of BCP 78 and BCP 79. This document may contain material 16 from IETF Documents or IETF Contributions published or made publicly 17 available before November 10, 2008. The person(s) controlling the 18 copyright in some of this material may not have granted the IETF 19 Trust the right to allow modifications of such material outside the 20 IETF Standards Process. Without obtaining an adequate license from 21 the person(s) controlling the copyright in such materials, this 22 document may not be modified outside the IETF Standards Process, and 23 derivative works of it may not be created outside the IETF Standards 24 Process, except to format it for publication as an RFC or to 25 translate it into languages other than English. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF), its areas, and its working groups. Note that 29 other groups may also distribute working documents as Internet- 30 Drafts. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 The list of current Internet-Drafts can be accessed at 38 http://www.ietf.org/ietf/1id-abstracts.txt. 40 The list of Internet-Draft Shadow Directories can be accessed at 41 http://www.ietf.org/shadow.html. 43 This Internet-Draft will expire on January 10, 2010. 45 Copyright Notice 47 Copyright (c) 2009 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents in effect on the date of 52 publication of this document (http://trustee.ietf.org/license-info). 53 Please review these documents carefully, as they describe your rights 54 and restrictions with respect to this document. 56 Abstract 58 This document describes an "xcap-diff" SIP (Session Initiation 59 Protocol) event package for the SIP Event Notification Framework, 60 which clients can use to receive notifications of changes to 61 Extensible Markup Language (XML) Configuration Access Protocol (XCAP) 62 resources. The initial synchronization information exchange and 63 document updates are based on the XCAP Diff format. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 69 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 70 4. XCAP-Diff Event Package . . . . . . . . . . . . . . . . . . . 4 71 4.1. Overview of Operation With Basic Requirements . . . . . . 4 72 4.2. Event Package Name . . . . . . . . . . . . . . . . . . . . 5 73 4.3. 'diff-processing' Event Package Parameter . . . . . . . . 5 74 4.4. SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 6 75 4.5. Subscription Duration . . . . . . . . . . . . . . . . . . 8 76 4.6. NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 8 77 4.7. Notifier Generation of NOTIFY Requests . . . . . . . . . . 8 78 4.8. Subscriber Processing of NOTIFY Requests . . . . . . . . . 11 79 4.9. Handling of Forked Requests . . . . . . . . . . . . . . . 13 80 4.10. Rate of Notifications . . . . . . . . . . . . . . . . . . 13 81 4.11. State Agents . . . . . . . . . . . . . . . . . . . . . . . 13 82 5. An Initial Example NOTIFY document . . . . . . . . . . . . . . 13 83 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 84 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 85 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 15 86 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 87 9.1. Normative References . . . . . . . . . . . . . . . . . . . 16 88 9.2. Informative References . . . . . . . . . . . . . . . . . . 17 89 Appendix A. Informative Examples . . . . . . . . . . . . . . . . 17 90 A.1. Initial documents on an XCAP server . . . . . . . . . . . 17 91 A.2. An Initial Subscription . . . . . . . . . . . . . . . . . 18 92 A.3. A Document Addition Into a Collection . . . . . . . . . . 19 93 A.4. A Series of XCAP Component Modifications . . . . . . . . . 20 94 A.5. An XCAP Component Subscription . . . . . . . . . . . . . . 24 95 A.6. A Conditional Subscription . . . . . . . . . . . . . . . . 27 96 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 98 1. Introduction 100 The SIP Events framework [RFC3265] describes subscription and 101 notification conventions for the Session Initiation Protocol (SIP) 102 [RFC3261]. The Extensible Markup Language (XML) 103 [W3C.REC-xml-20060816] Configuration Access Protocol (XCAP) [RFC4825] 104 allows a client to read, write and modify XML-formatted application 105 usage data stored on an XCAP server. 107 While XCAP allows authorized users or devices to modify the same XML 108 document, XCAP does not provide an effective mechanism (beyond 109 polling) to keep resources synchronized between a server and a 110 client. This memo defines an "xcap-diff" event package that, 111 together with the SIP event notification framework [RFC3265] and the 112 XCAP diff format [I-D.ietf-simple-xcap-diff], allows a user to 113 subscribe to changes in an XML document, and to receive notifications 114 whenever the XML document changes. 116 There are three basic features that this event package enables: 118 First, a client can subscribe to a list of XCAP documents' URLs in a 119 collection located on an XCAP server. This allows a subscriber to 120 compare server resources with its local resources using the URLs and 121 the strong entity tag (ETag) values of XCAP documents, which are 122 shown in the XCAP Diff format, and to synchronize them. 124 Second, this event package can signal a change in those documents in 125 one of three ways. The first mode only indicates the event type and 126 does not include document contents, so the subscriber uses HTTP 127 [RFC2616] to retrieve the updated document. The second mode includes 128 document content changes in notification messages, using the XML- 129 Patch-Ops [RFC5261] format with minimal notification size. The third 130 mode also includes document content changes in notification messages 131 with the same XML-Patch-Ops format, but is more verbose, and shows 132 the full HTTP version-history. 134 Third, the client can subscribe to specific XML elements or 135 attributes (XCAP components) showing their existing contents in the 136 resulting XCAP Diff format notification messages. If the requested 137 component does not exist but is later created, the notifier sends a 138 notification with the component's content. The notifier also sends 139 notifications when the subscribed XCAP components are removed, for 140 example after a successful HTTP DELETE request. 142 2. Terminology 144 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 145 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 146 document are to be interpreted as described in RFC 2119, BCP 14 147 [RFC2119] and indicate requirement levels for compliant 148 implementations. 150 3. Definitions 152 The following terms are used in this document: 154 XCAP Component: An XML element or an attribute, which can be 155 updated, removed, or retrieved with XCAP. 157 Aggregating: An XCAP client can update only a single XCAP Component 158 at a time using HTTP. However, a notifier may be able to 159 aggregate a series of these modifications into a single 160 notification using XML-Patch-Ops semantics encoded in the XCAP- 161 Diff format. 163 This document reuses terminology mostly defined in XCAP [RFC4825] and 164 some in WebDAV [RFC4918]. 166 4. XCAP-Diff Event Package 168 4.1. Overview of Operation With Basic Requirements 170 To receive "xcap-diff" event package features, the subscriber 171 indicates its interest in certain resources by including a URI list 172 in the subscription body to the notifier. Each URL in this list MUST 173 be a HTTP URL that identifies a collection, an XCAP document, or an 174 XCAP component. Collection URLs MUST have a trailing forward slash 175 "/", following the conventions of WebDAV [RFC4918]. A collection 176 selection includes all documents in that collection and recursively 177 all documents in sub-collections. The URL of an XCAP component 178 consists of the document URL with the XCAP Node Selector added. 179 Although the XCAP Node Selector allows requesting all in-scope 180 namespaces of an element, the client MUST NOT subscribe to 181 namespaces. 183 The notifier MUST support XCAP component subscriptions. The notifier 184 sends the first notification in response to the subscription, and 185 this first notification MUST contain the URLs of the documents and 186 XCAP component contents that are part of the subscription. The 187 subsequent notifications MAY contain patches to these documents. The 188 subscriber can specify how the notifier will signal the changes of 189 documents by using the 'diff-processing' event package parameter, 190 covered in the Section 4.3. Note that the existence of the "diff- 191 processing" parameter or its value has no influence on XCAP component 192 subscriptions. 194 4.2. Event Package Name 196 The name of this event package is "xcap-diff". As specified in 197 [RFC3265], this value appears in the Event header field present in 198 SUBSCRIBE and NOTIFY requests. 200 4.3. 'diff-processing' Event Package Parameter 202 With the aid of the optional "diff-processing" Event header field 203 parameter, the subscriber indicates a preference as to how the 204 notifier SHOULD indicate change notifications of documents. The 205 possible values are "no-patching", "xcap-patching", and "aggregate". 206 All three modes provide information that allows the subscriber to 207 synchronize its local cache, but only the "xcap-patching" mode 208 provides intermediate states of the version history. The notifier 209 SHOULD use the indicated mode if it understands it (as such optimizes 210 network traffic within the capabilities of the receiver). 212 The "no-patching" value means that the notifier indicates only the 213 document and the event type (creation, modification, and removal) 214 in the notification. The notification does not necessarily 215 indicate the full HTTP ETag change history. Notifiers MUST 216 support the "no-patching" mode as a base-line for 217 interoperability. The other, more complex modes are optional. 219 The "xcap-patching" value means that the notifier includes all 220 updated XCAP component contents and entity tag (ETag) changes made 221 by XCAP clients (via HTTP). The client receives the full (HTTP) 222 ETag change history of a document. 224 The "aggregate" value means that the notifier MAY aggregate 225 several individual XCAP component updates into a single XCAP Diff 226 element. The policy for determining whether or not to 227 apply aggregation or to determine how many updates to aggregate is 228 locally determined. 230 The notifier SHOULD support the "xcap-patching" and "aggregate" 231 modes, and thus implement XML-Patch-Ops ( [RFC5261]) diff- 232 generation, because this can greatly reduce the required number of 233 notifications and overall transmissions. 235 If the subscription does not contain the "diff-processing" header 236 field parameter, the notifier MUST default to the "no-patching" mode. 238 Note: To see the difference between "xcap-patching" and 239 "aggregate" modes, consider a document that has versions "a", "b" 240 and "c" with corresponding ETag values "1", "2" and "3". The 241 "xcap-patching" mode will include first the change from version 242 "a" to "b" with the versions' corresponding "1" and "2" ETags and 243 then the change from version "b" to "c" with their "2" and "3" 244 ETags. The "aggregate" mode optimizes the change and indicates 245 only a single aggregated change from "a" to "c" with the old "1" 246 and new "3" ETags. If these changes are closely related, that is, 247 the same element has been updated many times, the bandwidth 248 savings are larger. 250 This "diff-processing" parameter is a subscriber hint to the 251 notifier. The notifier may respond using a simpler mode, but not a 252 more complex one. Notifier selection of a mode is covered in 253 Section 4.7. During re-subscriptions, the subscriber MAY change the 254 diff-processing parameter. 256 The formal grammar [RFC5234] of the "diff-processing" parameter: 258 diff-processing = "diff-processing" EQUAL ( 259 "no-patching" / 260 "xcap-patching" / 261 "aggregate" / 262 token ) 264 where EQUAL and token are defined in RFC 3261 [RFC3261]. 266 4.4. SUBSCRIBE Bodies 268 The URI list is described by the XCAP resource list format [RFC4826], 269 and is included as a body of the initial SUBSCRIBE request. Only a 270 simple subset of that format is required, a flat list of XCAP R-URIs. 271 The "uri" attribute of the element contains these URI values. 272 The subscriber MUST NOT use hierarchical lists or 273 references, etc., (though in the future, semantics may be expanded 274 thanks to the functionality in the resource list format). In 275 subsequent SUBSCRIBE requests, such as those used for refreshing the 276 expiration timer, the subscribed URI list MAY change, in which case 277 the notifier MUST use the new list. 279 The SUBSCRIBE request MAY contain an Accept header field. If no such 280 header field is present, it has a default value of "application/ 281 xcap-diff+xml". If the header field is present, it MUST include 282 "application/xcap-diff+xml", and MAY include any other types. 284 The SUBSCRIBE request MAY contain the Suppress-If-Match header field 286 [I-D.ietf-sipcore-subnot-etags], which directs the notifier to 287 suppress either the body of a subsequent notification, or the entire 288 notification if the ETag value matches. 290 If the SUBSCRIBE body contains elements or attributes that the 291 notifier doesn't understand, the notifier MUST ignore them. 293 Subscribers need to appropriately populate the Request-URI of the 294 SUBSCRIBE request, typically set to the URI of the notifier. This 295 document does not constrain that URI. It is assumed that the 296 subscriber is provisioned with or has learned the URI of the notifier 297 of this event package. 299 The XCAP server will usually be co-located with the SIP notifier, so 300 the subscriber MAY use relative XCAP Request-URIs. Because relative 301 Request-URIs are allowed, the notifier MUST know how to resolve these 302 against the correct XCAP Root URI value. 304 Figure 1 shows a SUBSCRIBE request and body covering several XCAP 305 resources: a "resource-list" document, a specific element (XCAP 306 component) in a "rls-services" document, and a collection in "pidf- 307 manipulation" application usage. The "Content-Type" header of this 308 SUBSCRIBE request is "application/resource-lists+xml". 310 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 311 ... 312 Accept: application/xcap-diff+xml 313 Event: xcap-diff; diff-processing=aggregate 314 Content-Type: application/resource-lists+xml 315 Content-Length: [XXX] 316 Expires: 4200 318 319 320 321 322 324 325 326 328 Figure 1: Example subscription body 330 When subscribing to XCAP components, namespace prefixes of XCAP Node 331 Selectors MUST be properly resolved to namespace URIs. Section 6.4. 332 of RFC 4825 [RFC4825] describes the conventions when using prefixes 333 in XCAP Node Selectors. If only XCAP Default Document Namespace is 334 used, just like in the previous example ( element), the 335 query component of the "uri" value is not required. 337 4.5. Subscription Duration 339 The default expiration time for subscriptions within this package is 340 3600 seconds. As per RFC 3265 [RFC3265], the subscriber MAY specify 341 an alternative expiration timer in the Expires header field. 343 4.6. NOTIFY Bodies 345 The format of the NOTIFY message body is either the default of 346 "application/xcap-diff+xml" or is a format listed in the Accept 347 header field of the SUBSCRIBE. 349 In this event package, notification messages contain an XCAP Diff 350 document [I-D.ietf-simple-xcap-diff]. 352 The XCAP Diff format [I-D.ietf-simple-xcap-diff] can include the 353 subscribed XCAP component contents. For documents, the format can 354 also include corresponding URIs, ETag values, and patching 355 instructions from version "a" to "b". Removal events (of documents, 356 elements, or attributes) can be identified too. Except for 357 collection selections, the "sel" selector values of the XCAP-Diff 358 format MUST be octet-by-octet equivalent to the relevant "uri" 359 parameter values of the element of the "resource-list" 360 document. 362 With XCAP component subscriptions, XCAP Node Selectors can contain 363 namespace prefixes. A notifier MUST then resolve these prefixes to 364 namespace URIs according to RFC 4825 [RFC4825] conventions. In other 365 words, notifiers MUST be aware of XCAP Default Document Namespaces 366 for Application Usages when they locate unprefixed qualified XCAP 367 elements. Note that the namespace resolving rules of Patch operation 368 elements: , and are described in Section 369 4.2.1 of [RFC5261]. 371 4.7. Notifier Generation of NOTIFY Requests 373 During the initial subscription, or if the URI list changes in 374 SUBSCRIBE refresh requests, the notifier MUST resolve the requested 375 XCAP resources and their privileges. If there are superfluous 376 resource selections in the requested URI list, the notifier SHOULD 377 NOT provide overlapping similar responses for these resources. A 378 resource for which an authenticated user does not have a read 379 privilege MUST NOT be included in the XCAP-Diff format. Note that an 380 XCAP component that could not be located with XCAP semantics does not 381 produce an error. Instead, the request remains in a "pending" state, 382 that is, waiting for this resource to be created (or read access 383 granted if XCAP Application Usages utilize dynamic access control 384 lists). Subscriptions to collections have a similar property: once a 385 new document is created into the subscribed collection, the creation 386 of a new resource is signaled with the next NOTIFY request. 388 After the notifier knows the list of authorized XCAP resources, it 389 generates the first NOTIFY, which contains URI references to all 390 subscribed, existing documents for which the subscriber has read 391 privileges, and typically XCAP component(s) of existing content. 393 After sending the initial notification, the notifier selects a diff- 394 processing mode for reporting changes. If the subscriber suggested a 395 mode in the "diff-processing" parameter of the SUBSCRIBE, the 396 notifier MAY use that requested mode or MAY fall back to a simpler 397 operational mode, but the notifier MUST NOT use a more complex mode 398 than the one chosen by the subscriber. From least to most complex, 399 the order of the modes is the following: "no-patching", "xcap- 400 patching", "aggregate". Thus, the notifier may respond to an 401 "aggregate" request using any mode, but cannot reply to an "xcap- 402 patching" subscription using the "aggregate" mode. Naturally, the 403 notifier MUST handle a "no-patching" request with the "no-patching" 404 mode. 406 In all modes, the notifier MUST maintain the chronological order of 407 XCAP changes. If several changes to a given resource are presented 408 in a single notification, the chronological update order MUST be 409 preserved in the XML document order of the notification body. 410 Chronological order is preserved to simplify the required subscriber 411 implementation logic. 413 While the "aggregate" mode uses bandwidth most efficiently, it 414 introduces other challenges. The initial synchronization might fail 415 with rapidly changing resources, because the "aggregate" mode 416 messages might not include the full version-history of a document and 417 the base XCAP protocol does not support version-history retrievals of 418 documents. When new documents are created in subscribed collections 419 and the notifier is aggregating patches, the same issue can occur. 420 In a corner case, the notifier may not be able to provide patches 421 with the XML-Patch-Ops [RFC5261] semantics. 423 If the notifier has to temporarily disable diff generation and send 424 only the URI references of some changed documents to the subscriber, 425 it MUST continue with the "xcap-patching" mode afterwards for these 426 resources, if the initial subscription also started with the "xcap- 427 patching" mode. 429 Note: The diff-generation may be disabled when the NOTIFY body 430 becomes impractically large or an intermediate error has happened. 431 As the subscriber loses then track of the patching operations, it 432 must refresh to a "known good" state by downloading current 433 documents. Once it has done so, it can re-subscribe for example 434 with the "aggregate" mode. 436 In the "aggregate" mode, the notifier chooses how long to wait for 437 multiple patches to combine and how this combination is done. 439 In the "xcap-patching" mode, the notifier MAY try to optimize the 440 diff-generation, for example by eliminating redundant information 441 since some XCAP clients will probably not have completely optimized 442 their HTTP PUT request. 444 Note: It is straightforward to change the XCAP client's change 445 requests: PUT and DELETE (sent via HTTP) to use XML-Patch-Ops 446 semantics. While XCAP does not support patching of all XML node 447 types - for example, namespace declarations can not be added 448 separately - efficient utilization of XML-Patch-Ops can sometimes 449 significantly reduce the bandwidth requirements at the expense of 450 extra processing. 452 After the notifier has reported the existence of an XCAP component, 453 it MUST also report its removal consistently. For example, the 454 removal of the parent element of the subscribed element requires the 455 same signalling since the subscribed element ceases to exist. To 456 signal the removal of an XCAP component, the notifier sets the 457 Boolean "exist" attribute value of the or 458 elements to false. Even with rapidly changing resources the notifier 459 MUST signal only the latest state: e.g. whether the XCAP component 460 exists or not. 462 When the notifier receives a re-subscription, it MUST re-send the 463 current full XML-Diff content unless the subscriber has requested a 464 conditional subscription [I-D.ietf-sipcore-subnot-etags] by using the 465 header field Suppress-If-Match: [ETag value]. With a conditional re- 466 subscription, the notifier MUST also inspect the subscription body 467 when determining the current subscription state. Since the 468 subscription is based on a list of XCAP R-URIs, it is RECOMMENDED 469 that the notifier does not consider the order of these URIs when 470 determining the equivalence to "stored" previous states. If a match 471 to the previous state is not found, the NOTIFY message MUST contain 472 the full XML-Diff state (similar to the initial notification). The 473 notifiers SHOULD implement the conditional subscription handling with 474 this event package. 476 During re-subscriptions, the subscriber may change the value of the 477 diff-processing parameter. The value change influences only 478 subsequent notifications, not the notification (if generated) 479 followed immediately after the (re-)SUBSCRIBE request. 481 Event packages like this require reliable transfer of NOTIFY 482 messages. This means that all messages MUST successfully be 483 transferred or the document will become out of sync, and then patches 484 will most likely fail (or worse, have unintended consequences). This 485 "xcap-diff" event package requires, similar to Partial-PIDF-Notify 486 RFC 5263 [RFC5263], that a notifier MUST NOT send a new NOTIFY 487 request to the same dialog unless a successful 200-response has been 488 received for the last sent NOTIFY request. If the NOTIFY request 489 fails due to a timeout, the notifier MUST remove the subscription. 491 Note: This requirement ensures that out-of-order events will not 492 happen or that the dialog will terminate after non-resolvable 493 NOTIFY request failures. In addition, some of the probable NOTIFY 494 error responses (for example, 401, 407, 413) can possibly be 495 handled gracefully without tearing down the dialog. 497 If, for example, the subscriber has selected too many elements to 498 which to subscribe, such that the notification body would be 499 impractically large (that is, an intermediate NOTIFY failure), the 500 notifier MAY discard the element content. The existence of 501 elements is then indicated with an empty element, and the 502 content is not shown for those resources. In other words, the 503 element does not not have a child element which would show 504 the subscribed "full" element content. 506 4.8. Subscriber Processing of NOTIFY Requests 508 The first NOTIFY request will usually contain references to HTTP 509 resources including their strong ETag values. If the subscriber does 510 not have similar locally cached versions, it will typically start an 511 unconditional HTTP GET request for those resources. During this HTTP 512 retrieval time, the subscriber MAY also receive patches to these 513 documents (if it has requested them) and if the documents are 514 changing rapidly. It can happen that the version retrieved by HTTP 515 is not the same than what is indicated in the initial notification. 516 A subscriber can then chain the modification list for each document, 517 and locate the position where the previous ETag value is equal to 518 that retrieved via HTTP. If an ETag match is not found from the 519 first change, a subscriber MUST omit all changes up to the point 520 where it is the same. From that change onwards, the subscriber 521 applies all reported patches. If the version received via HTTP is 522 newer than any received via the notifications, the subscriber may not 523 find an equivalent match of an ETag value from the chain of patches. 525 This can happen since notifications are reported after HTTP changes 526 and preferably at some minimum intervals. Also document removals can 527 be reported in notifications and/or HTTP retrievals may fail because 528 of unexisting resources (rapidly changing). In any case, the 529 subscriber can re-fetch the possible out-of-sync document, wait for 530 subsequent notifications or refresh the subscription (with "xcap- 531 patching") and repeat the described "sync" algorithm until a "full" 532 sync is achieved. 534 If the notifier aggregates patches, the previous modification list 535 may not contain the ETag value retrieved by HTTP simply because of 536 aggregation optimizations. A similar out-of-sync cycle can happen 537 when new (subscribed) documents are created which change rapidly. To 538 avoid such difficulties, the subscriber MAY start the subscription 539 with the "xcap-patching" mode, and then refresh the subscription with 540 the "aggregate" mode after the initial sync is achieved. Naturally, 541 the subscriber can revert back to the "xcap-patching" mode from 542 "aggregate" at anytime and vice versa. 544 If the subscriber has received a "full" sync and it has detected that 545 some of the resources are being served with the "xcap-patching" mode 546 while others are in the "aggregate" mode, it SHOULD refresh the 547 subscription to the "aggregate" mode. 549 The notifier MAY at any time temporarily use the "no-patching" mode 550 for some resources so that the subscriber receives only URI 551 references of modifications. When the notifier is acting in this 552 mode, several cycles MAY be needed before an initial "full" sync is 553 achieved. As the notifier MAY change modes in the middle of a 554 dialog, the subscriber is always responsible for taking appropriate 555 actions. Also, as the last resort, the subscriber MAY always disable 556 the usage of diff-processing by setting the "diff-processing" 557 parameter to "no-patching". 559 If a diff format cannot be applied due to patch processing and/or 560 programming errors (for a list, see Section 5.1 of [RFC5261]), the 561 subscriber SHOULD refresh the subscription and disable patching by 562 setting the "diff-processing" parameter to "no-patching". The 563 subscriber SHOULD NOT reply with a non-200 response since the 564 notifier cannot make corrections. 566 During unconditional re-subscriptions, the subscriber MUST stamp the 567 received state of all previous resources as stale. However, if a 568 conditional [I-D.ietf-sipcore-subnot-etags] re-subscription is 569 successful, the subscriber MUST preserve the current state of 570 resources unless the subscribed URI list has changed. That is, the 571 subscriber MUST fetch the resource's state, for example, from some 572 local cache. 574 4.9. Handling of Forked Requests 576 This specification allows only a single dialog to be constructed from 577 an initial SUBSCRIBE request. If the subscriber receives forked 578 responses to a SUBSCRIBE, the subscriber MUST apply the procedures in 579 Section 4.4.9 of RFC 3265 [RFC3265] for handling non-allowed forked 580 requests. 582 4.10. Rate of Notifications 584 Notifiers of "xcap-diff" event package SHOULD NOT generate 585 notifications for a single subscription at a rate of more than once 586 every five seconds. 588 4.11. State Agents 590 State agents play no role in this package. 592 5. An Initial Example NOTIFY document 594 Figure 2 shows an example initial XCAP Diff format document provided 595 by the first NOTIFY request to the SUBSCRIBE example in Figure 1. 596 The following is an example Event header field for this SUBSCRIBE 597 request: 599 Event: xcap-diff; diff-processing=aggregate 601 The subscriber requests that the notifier "aggregate" XCAP component 602 updates and anticipates that the subsequent notifications will 603 contain aggregated patches to these documents. 605 606 610 613 616 620 621 622 623 624 625 presence 626 627 629 631 Figure 2: An example initial XCAP Diff format document 633 Note that the resource-list "index" document included only the new 634 ETag value, as the document existed during the subscription time. In 635 the "pidf-manipulation" collection, there is only a single document 636 for which the user has read privilege. The element exists 637 within the rls-services "index" document and its content is shown. 638 Note also that the element was located using the Default 639 Document Namespace (no prefix in XCAP Node Selector value) although 640 it has an "s" prefix in the source document. 642 6. IANA Considerations 644 This specification instructs IANA to add a new event package to the 645 SIP Event Types Namespace registry. The new data to be added is: 647 Package Name Type Contact Reference 648 ------------- -------- ------- --------- 649 xcap-diff package IETF SIP Working Group [RFCXXXX] 650 652 7. Security Considerations 654 This document defines a new SIP event package for the SIP event 655 notification framework specified in RFC 3265 [RFC3265]. As such, all 656 the security considerations of RFC 3265 apply. The configuration 657 data can contain sensitive information, and both the client and the 658 server need to authenticate each other. The notifiers MUST 659 authenticate the "xcap-diff" event package subscriber using the 660 normal SIP authentication mechanisms, for example Digest as defined 661 in Section 22 of RFC 3261 [RFC3261]. The notifiers MUST be aware of 662 XCAP User identities (XUI) and how to map the authenticated SIP 663 identities unambiguously with XUIs. 665 Since XCAP [RFC4825] provides a basic authorization policy for 666 resources and since notifications contain content similar to XCAP 667 resources, the security considerations of XCAP also apply. The 668 notifiers MUST obey the XCAP authorization rules when signalling 669 resource changes. In practice, this means following the read 670 privilege rules of XCAP resources. 672 Denial-of-Service attacks against notifiers deserve special mention. 673 The following can cause denial of service due to intensive 674 processing: subscriptions to a long list of URIs, "pending" 675 subscriptions to non-existent documents or XCAP components, and diff- 676 generation algorithms that try to optimize the required bandwidth 677 usage to extremes. 679 The mechanism used for conveying xcap-diff event information MUST 680 ensure integrity and SHOULD ensure confidentially of the information. 681 An end-to-end SIP encryption mechanism, such as S/MIME described in 682 Section 26.2.4 of RFC 3261 [RFC3261], SHOULD be used. If that is not 683 available, it is RECOMMENDED that TLS [RFC5246] be used between 684 elements to provide hop-by-hop authentication and encryption 685 mechanisms described in Section 26.2.2 "SIPS URI Scheme" and Section 686 26.3.2.2 "Interdomain Requests" of RFC 3261 [RFC3261]. 688 8. Acknowledgments 690 The author would like to thank Jonathan Rosenberg for his valuable 691 comments and providing the initial event package, and Aki Niemi, 692 Pekka Pessi, Miguel Garcia, Pavel Dostal, Krisztian Kiss, Anders 693 Lindgren, Sofie Lassborn, Keith Drage, Stephen Hinton, Byron Campen, 694 Avshalom Houri, Ben Campbell, Paul Kyzivat, Spencer Dawkins, Pasi 695 Eronen and Chris Newman for their valuable comments. Lisa Dusseault 696 critiqued the document during IESG review, raising numerous issues 697 that resulted in improved document quality. Further, technical 698 writer A. Jean Mahoney devoted countless hours to integrating Lisa's 699 comments and cleaning up the technical English usage. 701 9. References 703 9.1. Normative References 705 [I-D.ietf-simple-xcap-diff] 706 Rosenberg, J. and J. Urpalainen, "An Extensible Markup 707 Language (XML) Document Format for Indicating A Change in 708 XML Configuration Access Protocol (XCAP) Resources", 709 draft-ietf-simple-xcap-diff-13 (work in progress), 710 June 2009. 712 [I-D.ietf-sipcore-subnot-etags] 713 Niemi, A., "An Extension to Session Initiation Protocol 714 (SIP) Events for Conditional Event Notification", 715 draft-ietf-sipcore-subnot-etags-02 (work in progress), 716 April 2009. 718 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 719 Requirement Levels", BCP 14, RFC 2119, March 1997. 721 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 722 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 723 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 725 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 726 A., Peterson, J., Sparks, R., Handley, M., and E. 727 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 728 June 2002. 730 [RFC3265] Roach, A., "Session Initiation Protocol (SIP)-Specific 731 Event Notification", RFC 3265, June 2002. 733 [RFC4825] Rosenberg, J., "The Extensible Markup Language (XML) 734 Configuration Access Protocol (XCAP)", RFC 4825, May 2007. 736 [RFC4826] Rosenberg, J., "Extensible Markup Language (XML) Formats 737 for Representing Resource Lists", RFC 4826, May 2007. 739 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 740 Specifications: ABNF", STD 68, RFC 5234, January 2008. 742 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 743 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 745 [RFC5261] Urpalainen, J., "An Extensible Markup Language (XML) Patch 746 Operations Framework Utilizing XML Path Language (XPath) 747 Selectors", RFC 5261, September 2008. 749 9.2. Informative References 751 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 752 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 754 [RFC5263] Lonnfors, M., Costa-Requena, J., Leppanen, E., and H. 755 Khartabil, "Session Initiation Protocol (SIP) Extension 756 for Partial Notification of Presence Information", 757 RFC 5263, September 2008. 759 [W3C.REC-xml-20060816] 760 Maler, E., Paoli, J., Bray, T., Yergeau, F., and C. 761 Sperberg-McQueen, "Extensible Markup Language (XML) 1.0 762 (Fourth Edition)", World Wide Web Consortium 763 Recommendation REC-xml-20060816, August 2006, 764 . 766 Appendix A. Informative Examples 768 These examples illustrate the basic features of the xcap-diff event 769 package. Only the relevant header fields are shown. Note also that 770 the SIP R-URIs of these examples don't correspond to reality. 772 A.1. Initial documents on an XCAP server 774 The following documents exist on an XCAP server (xcap.example.com) 775 with an imaginary "tests" application usage (there's no default 776 document namespace defined in this imaginary application usage). 778 http://xcap.example.com/tests/users/sip:joe@example.com/index: 780 781 782 This is a sample document 783 785 and then 787 http://xcap.example.com/tests/users/sip:john@example.com/index: 789 790 791 This is another sample document 792 794 A.2. An Initial Subscription 796 The following demonstrates the listing of a collection contents and 797 it shows only resources where the user has read privilege. The user 798 Joe, whose XUI is "sip:joe@example.com", sends an initial 799 subscription: 801 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 802 ... 803 Accept: application/xcap-diff+xml 804 Event: xcap-diff; diff-processing=aggregate 805 Content-Type: application/resource-lists+xml 806 Content-Length: [XXX] 808 809 810 811 812 813 815 In addition to the 200 (OK) response, the notifier sends the first 816 NOTIFY: 818 NOTIFY sip:joe@userhost.example.com SIP/2.0 819 ... 820 Event: xcap-diff 821 Content-Type: application/xcap-diff+xml 822 Content-Length: [XXX] 824 825 828 831 833 The subscriber learns that the document on this "tests" application 834 usage is equivalent to its locally cached version, so it does not 835 act. If the local version had been different, the subscriber would 836 most likely re-fetch the document. 838 If the subscriber had requested the "tests/users/" collection, the 839 notification body would have been the same since Joe has no read 840 privilege to John's resources (XCAP default behavior). 842 If the Expires header field had a value "0", the request would be 843 similar to the PROPFIND method of WebDAV. The syntax and responses 844 differ, however. 846 A.3. A Document Addition Into a Collection 848 Let's say that Joe adds a new document to his collection, using 849 either the same client or another client running on a different 850 device. He does an HTTP PUT to his application usage collection: 852 PUT /tests/users/sip:joe@example.com/another_document HTTP/1.1 853 Host: xcap.example.com 854 .... 855 Content-Type: application/xml 856 Content-Length: [XXX] 858 859 860 This is another sample document 861 863 This HTTP PUT request results in the XCAP client receiving a strong 864 HTTP ETag "terteer" for this new document. 866 Then the subscriber receives a notification afterwards: 868 NOTIFY sip:joe@userhost.example.com SIP/2.0 869 ... 870 Event: xcap-diff 871 Content-Type: application/xcap-diff+xml 872 Content-Length: [XXX] 874 875 878 881 883 Note that the result is "additive"; it doesn't indicate the already 884 indicated "index" document. Only the initial (or refreshed) 885 notification contains all document URI references. 887 If Joe's client both modifies the documents and refreshes the 888 subscriptions, it would typically ignore this notification, since its 889 modifications had caused the notification. If the client that 890 received this NOTIFY hadn't submitted the document change, it would 891 probably fetch this new document. 893 If Joe's client refreshes the subscription with the same request body 894 as in the initial subscription, the result will include these two 895 documents: "index" and "another_document" with their ETags. 897 A.4. A Series of XCAP Component Modifications 899 Now Joe's client uses its XCAP patching capability by doing the 900 following: 902 PUT /tests/users/sip:joe@example.com/index/~~/doc/foo HTTP/1.1 903 Host: xcap.example.com 904 .... 905 Content-Type: application/xcap-el+xml 906 Content-Length: [XXX] 908 this is a new element 910 Since the insertion of the element is successful, Joe's client 911 receives the new HTTP ETag "fgherhryt3" of the updated "index" 912 document. 914 Immediately thereafter, Joe's client issues another HTTP request 915 (this request could even be pipe-lined): 917 PUT /tests/users/sip:joe@example.com/index/~~/doc/bar HTTP/1.1 918 Host: xcap.example.com 919 .... 920 Content-Type: application/xcap-el+xml 921 Content-Length: [XXX] 923 this is a bar element 924 926 The reported new HTTP ETag of "index" is now "dgdgdfgrrr". 928 And Joe's client issues yet another HTTP request: 930 PUT /tests/users/sip:joe@example.com/index/~~/doc/foobar HTTP/1.1 931 Host: xcap.example.com 932 .... 933 Content-Type: application/xcap-el+xml 934 Content-Length: [XXX] 936 this is a foobar element 938 The reported new ETag of "index" is now "63hjjsll". 940 After awhile, Joe's client receives a notification with an embedded 941 patch since it has requested "aggregate" diff-processing and the 942 notifier is capable of producing them: 944 NOTIFY sip:joe@userhost.example.com SIP/2.0 945 ... 946 Event: xcap-diff 947 Content-Type: application/xcap-diff+xml 948 Content-Length: [XXX] 950 951 954 957 this is a new elementthis is a bar element 959 this is a foobar element 960 962 964 Joe's client applies this patch to the locally cached "index" 965 document, detects the ETag update, and stores the last ETag value. 966 Note how several XCAP component modifications were aggregated. 968 Note also that, if Joe's client did not have a locally cached version 969 of the reference document, it would have needed to do a HTTP GET 970 request after the initial notification. If the ETag of the received 971 resource by HTTP did not match either the previous or new ETag of 972 this aggregated patch, an out-of-sync condition would be probable. 973 This issue is not typical, but it can happen. To resolve the issue, 974 the client could re-fetch the "index" document and/or wait for 975 subsequent notifications to detect a match. A better and simpler way 976 to avoid the issue is to refresh the subscription with the "xcap- 977 patching" mode and later refresh with the "aggregate" mode. 979 Alternatively, if the notifier's operational mode been "xcap- 980 patching", the NOTIFY could have been the following: 982 NOTIFY sip:joe@userhost.example.com SIP/2.0 983 ... 984 Event: xcap-diff 985 Content-Type: application/xcap-diff+xml 986 Content-Length: [XXX] 988 989 992 995 this is a new element 998 1001 this is a bar element 1003 1005 1008 this is a foobar element 1011 1013 If the client had to re-fetch the "index" document after the initial 1014 notification, it could have skipped some or all of these patches, 1015 depending on whether the HTTP ETag matched some of these ETags in the 1016 chain of patches. If the HTTP ETag did not match and the received 1017 HTTP version is a newer version indicated in later notification(s) 1018 then the sync may then be achieved since the notifier provided the 1019 full change history in the "xcap-patching" mode. 1021 Lastly, the notifier could (temporarily) fall back to the "no- 1022 patching" mode, which allows the notifier to keep the dialog alive 1023 when there are too many updates: 1025 NOTIFY sip:joe@userhost.example.com SIP/2.0 1026 ... 1027 Event: xcap-diff 1028 Content-Type: application/xcap-diff+xml 1029 Content-Length: [XXX] 1031 1032 1035 1039 1041 At any time, the notifier may fall back to the "no-patching" mode for 1042 some or all of the subscribed documents. 1044 A.5. An XCAP Component Subscription 1046 The user Joe sends an initial subscription for the "id" affribute of 1047 a element. The "index" document exists, but the root 1048 element does not contain the "id" attribute at the time of the 1049 subscription. 1051 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 1052 ... 1053 Accept: application/xcap-diff+xml 1054 Event: xcap-diff 1055 Content-Type: application/resource-lists+xml 1056 Content-Length: [XXX] 1058 1059 1060 1061 1062 1063 1065 The first NOTIFY looks like the following since there is nothing to 1066 indicate: 1068 NOTIFY sip:joe@userhost.example.com SIP/2.0 1069 ... 1070 Event: xcap-diff 1071 Content-Type: application/xcap-diff+xml 1072 Content-Length: [XXX] 1074 1075 1078 Note that if the "index" document hadn't existed, the first NOTIFY 1079 request would have been the same. The XCAP Diff document format 1080 doesn't indicate reasons for non-existing resources. 1082 Afterwards Joe's client updates the whole document root element 1083 including the attribute "id" (not a typical XCAP operation nor a 1084 preferred one, just an illustration here): 1086 PUT /tests/users/sip:joe@example.com/index/~~/doc HTTP/1.1 1087 Host: xcap.example.com 1088 .... 1089 Content-Type: application/xcap-el+xml 1090 Content-Length: [XXX] 1092 This is a new root element 1094 The new HTTP ETag of the "index" document is now "dwawrrtyy". 1096 Then Joe's client gets a notification: 1098 NOTIFY sip:joe@userhost.example.com SIP/2.0 1099 ... 1100 Event: xcap-diff 1101 Content-Type: application/xcap-diff+xml 1102 Content-Length: [XXX] 1104 1105 1108 bar 1111 1113 Note that the HTTP ETag value of the new document is not shown as it 1114 is irrelevant for this use-case. 1116 Then Joe's client removes the "id" attribute: 1118 DELETE /tests/users/sip:joe@example.com/index/~~/doc/@id HTTP/1.1 1119 Host: xcap.example.com 1120 .... 1121 Content-Length: 0 1123 And the subscriber gets a notification: 1125 NOTIFY sip:joe@userhost.example.com SIP/2.0 1126 ... 1127 Event: xcap-diff 1128 Content-Type: application/xcap-diff+xml 1129 Content-Length: [XXX] 1131 1132 1135 1138 1139 The notification indicates that the subscribed attribute was removed 1140 from the document. Naturally attributes are "removed" if the element 1141 where they belong is removed, for example by an HTTP DELETE request. 1142 The component selections indicate only the existence of attributes or 1143 elements. 1145 A.6. A Conditional Subscription 1147 The last example is a conditional subscription where a full refresh 1148 can be avoided when there are no changes in resources. Joe's client 1149 sends an initial subscription: 1151 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 1152 ... 1153 Accept: application/xcap-diff+xml 1154 Event: xcap-diff; diff-processing=xcap-patching 1155 Content-Type: application/resource-lists+xml 1156 Content-Length: [XXX] 1158 1159 1160 1161 1162 1163 1165 Since there are now two documents in the repository, the first NOTIFY 1166 looks like the following: 1168 NOTIFY sip:joe@userhost.example.com SIP/2.0 1169 ... 1170 Event: xcap-diff 1171 SIP-ETag: xggfefe54 1172 Content-Type: application/xcap-diff+xml 1173 Content-Length: [XXX] 1175 1176 1179 1182 1185 1187 Note that the NOTIFY request contains the SIP-ETag "xggfefe54". This 1188 SIP-ETag is placed in the Suppress-If-Match header field of the 1189 conditional subscription. The "diff-processing" mode also is changed 1190 (or is requested to change): 1192 SUBSCRIBE sip:tests@xcap.example.com SIP/2.0 1193 ... 1194 Suppress-If-Match: xggfefe54 1195 Accept: application/xcap-diff+xml 1196 Event: xcap-diff; diff-processing=aggregate 1197 Content-Type: application/resource-lists+xml 1198 Content-Length: [XXX] 1200 1201 1202 1203 1204 1205 1207 If the notifier finds a match to the previous stored state when it 1208 evaluates this request, it responds with 204 (No Notification). If 1209 there are no reportable changes as per 1210 [I-D.ietf-sipcore-subnot-etags], NOTIFY request generation is 1211 suppressed. When the notifier can aggregate several modifications, 1212 this re-subscription enables the processing of that mode thereafter. 1213 Indeed, the re-subscription may be quite process-intensive, 1214 especially when there are a large number of relevant reported 1215 resources. 1217 Authors' Addresses 1219 Jari Urpalainen 1220 Nokia 1221 Itamerenkatu 11-13 1222 Helsinki 00180 1223 Finland 1225 Phone: +358 7180 37686 1226 Email: jari.urpalainen@nokia.com 1228 Dean Willis (editor) 1229 Softarmor Systems LLC 1230 3100 Independence Pk #311-164 1231 Plano, TX 75075 1232 USA 1234 Phone: +1 214 504 19876 1235 Email: dean.willis@softarmor.com