idnits 2.17.1 draft-camarillo-sipping-transac-package-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 6, 2004) is 7378 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2141 (ref. '2') (Obsoleted by RFC 8141) ** Downref: Normative reference to an Informational RFC: RFC 2648 (ref. '3') ** Obsolete normative reference: RFC 3023 (ref. '4') (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 3265 (ref. '6') (Obsoleted by RFC 6665) == Outdated reference: A later version (-03) exists of draft-camarillo-sipping-exploders-01 == Outdated reference: A later version (-06) exists of draft-ietf-sipping-dialog-package-03 Summary: 5 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SIPPING Working Group G. Camarillo 3 Internet-Draft Ericsson 4 Expires: August 6, 2004 M. Garcia-Martin 5 Nokia 6 February 6, 2004 8 A Transaction Event Package for the Session Initiation Protocol (SIP) 9 draft-camarillo-sipping-transac-package-00.txt 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that other 18 groups may also distribute working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at http:// 26 www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on August 6, 2004. 33 Copyright Notice 35 Copyright (C) The Internet Society (2004). All Rights Reserved. 37 Abstract 39 SIP provides a SIP Events notification framework that is extensible 40 throught the addition of event packages. This document defines a 41 transaction event package for the SIP Events notification, along with 42 a data format used in notifications for this package. The transaction 43 package allows users to subscribe to a resource in an application 44 server and receive notifications about the changes in state of 45 transactions the application server initiates as part of a service. 46 Additionally, we define a new SIP Associated-Transactions-State 47 header field that allows a server to return a subscrible URI that 48 provides transactions notification information. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . 3 55 4. The Transaction Event Package . . . . . . . . . . . . . . . 4 56 4.1 Event Package Name . . . . . . . . . . . . . . . . . . . . . 4 57 4.2 Event Package Parameters . . . . . . . . . . . . . . . . . . 4 58 4.3 SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . . 4 59 4.4 Subscription Duration . . . . . . . . . . . . . . . . . . . 4 60 4.5 NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . . 4 61 4.6 Notifier Processing of SUBSCRIBE Requests . . . . . . . . . 4 62 4.7 Notifier Generation of NOTIFY Requests . . . . . . . . . . . 5 63 4.8 Subscriber Processing of NOTIFY Requests . . . . . . . . . . 5 64 4.9 Handling of Forked Requests . . . . . . . . . . . . . . . . 5 65 4.10 Rate of Notifications . . . . . . . . . . . . . . . . . . . 5 66 4.11 State Agents . . . . . . . . . . . . . . . . . . . . . . . . 5 67 5. Transaction Information Format . . . . . . . . . . . . . . . 5 68 5.1 Structure of the Transaction Information . . . . . . . . . . 6 69 5.1.1 Transaction Element . . . . . . . . . . . . . . . . . . . . 6 70 5.2 Constructing Coherent State . . . . . . . . . . . . . . . . 7 71 5.3 Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 5.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 6. The Associated-Transactions-State Header Field . . . . . . . 10 74 6.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 75 7. Security Considerations . . . . . . . . . . . . . . . . . . 11 76 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . 11 77 8.1 MIME Registration for application/transaction-info+xml . . . 11 78 8.2 URN Sub-Namespace Registration for 79 urn:ietf:params:xml:ns:transaction-info . . . . . . . . . . 12 80 8.3 Schema Registration . . . . . . . . . . . . . . . . . . . . 12 81 8.4 Associated-Transactions-State Header Field Registration . . 13 82 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 83 Normative References . . . . . . . . . . . . . . . . . . . . 13 84 Informational References . . . . . . . . . . . . . . . . . . 13 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 14 86 Intellectual Property and Copyright Statements . . . . . . . 15 88 1. Introduction 90 The SIP [5] Events framework [6] defines general mechanisms for 91 subscription to, and notification of, events within SIP networks. It 92 introduces the notion of a package, which is a specific 93 "instantiation" of the events mechanism for a well-defined set of 94 events. Here, we define an event package for transactions. 96 An example of an application using this package is a MESSAGE exploder 97 (SIP exploders are described in [8]) that sends MESSAGE requests to a 98 set of destinations on behalf of a user. The user subscribes to the 99 transaction state of the transactions generated by the application 100 server as part of the service. The subscriber receives one more 101 notifications containing the status of those transactions. This way, 102 the user is informed of which MESSAGE requests were delivered to 103 their destination and which ones failed. 105 The transaction state of the transactions generated by the 106 application server as part of the service is identified by a URI. The 107 user agent uses this URI to subscribe to this state. The user agent 108 may use different mechanisms to obtain such a URI. Section 6 defines 109 one of such mechanisms: the Associated-Transactions-State SIP header 110 field. 112 2. Terminology 114 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 115 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT 116 RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as 117 described in BCP 14, RFC 2119 [1] and indicate requirement levels for 118 compliant implementations. 120 3. Definitions 122 We define the following terms: 124 Triggering transaction: A SIP transaction that triggers a set of 125 actions in an application server. These actions usually include 126 the generation of one or more SIP associated transactions by the 127 application server. 129 Triggering request: The SIP request that is part of a triggering 130 transaction. 132 Associated transaction: A SIP transaction that is generated by an 133 application server on reception of a triggering request. 135 4. The Transaction Event Package 137 This section provides the details for defining a SIP Events package, 138 as specified by RFC 3265 [6]. 140 4.1 Event Package Name 142 The name of this event package is "transaction". This package name is 143 carried in the Event and Allow-Events header fields, as defined in 144 [6]. 146 4.2 Event Package Parameters 148 This package does not define any event package parameters. 150 4.3 SUBSCRIBE Bodies 152 This package does not define any SUBSCRIBE bodies. 154 4.4 Subscription Duration 156 The default subscription duration for this event package is 60 157 seconds. 159 4.5 NOTIFY Bodies 161 In this event package, the body of the notification contains a 162 transaction information document. This document describes the state 163 of one or more transactions associated with the subscribed resource. 164 All subscribers and notifiers MUST support the "application/ 165 transaction-info+xml" data format described in Section 5. The 166 subscribe request MAY contain an Accept header field. If no such 167 header field is present, it has a default value of "application/ 168 transaction-info+xml". If the header field is present, it MUST 169 include "application/transaction-info+xml", and MAY include any other 170 types capable of representing transaction state. 172 The notifications generated by the server MUST be in one of the 173 formats specified in the Accept header field in the SUBSCRIBE 174 request. 176 4.6 Notifier Processing of SUBSCRIBE Requests 178 The transaction information for a resource contains sensitive 179 information. So, all subscriptions SHOULD be authenticated. 180 Authorization policy is at the discretion of the administrator of the 181 notifier. 183 4.7 Notifier Generation of NOTIFY Requests 185 The notifier MUST generate a notification containing the state of all 186 the transactions associated with the subscribed resource as soon as 187 any of the following actions take place: a) all the transactions 188 complete; b) the subscription timer expires. 190 This behaviour guarantees that the subscriber gets at least one 191 notification as soon as the transactions are complete or, within 192 the subscription timer. 194 The notifier MAY send notifications more often (e.g., once every time 195 the state of a transaction changes) if there are filters applied to 196 the subscription. 198 4.8 Subscriber Processing of NOTIFY Requests 200 On reception of a valid NOTIFY request, the subscriber SHOULD 201 immediately render the transaction status to the end-user in an 202 implementation specific way. 204 4.9 Handling of Forked Requests 206 By their nature, the resources supported by this package are 207 centralized. So, SUBSCRIBE requests should not generally fork. Users 208 of this package MUST NOT install more than a single subscription as a 209 result of a single SUBSCRIBE request. 211 4.10 Rate of Notifications 213 For reasons of congestion control, it is important that the rate of 214 notifications not become excessive. As a result, it is RECOMMENDED 215 that the server not generate notifications for a single subscriber at 216 a rate faster than once every five seconds. 218 4.11 State Agents 220 Transaction state is ideally maintained in the element which 221 generates the transactions. Consequently, the elements that generate 222 the transactions are the ones best suited to handle subscriptions to 223 it. The usage of state agents is NOT RECOMMENDED for this package. 225 5. Transaction Information Format 227 Transaction information is an XML document that MUST be well-formed 228 and SHOULD be valid. Transaction information documents MUST be based 229 on XML 1.0 and MUST be encoded using UTF-8. This specification makes 230 use of XML namespaces for identifying Transaction information 231 documents. The namespace URI for elements defined by this 232 specification is a URN [2], using the namespace identifier 'ietf' 233 defined by RFC 2648 [3] and extended by [7]. This URN is: 235 urn:ietf:params:xml:ns:transaction-info 237 A Transaction information document begins with the root element tag 238 "transaction-info". 240 5.1 Structure of the Transaction Information 242 A transaction information document starts with a "transaction-info" 243 element. This element has three mandatory attributes: 245 version: allows the recipient of transaction information documents 246 to properly order them. Versions start at 0, and increment by one 247 for each new document sent to a subscriber. Versions are scoped 248 within a subscription. Versions MUST be representable using a 32 249 bit integer. 251 state: indicates whether the document contains the "full" 252 transaction information, or whether it contains only information 253 on those transactions which have changed since the previous 254 document ("partial"). 256 entity: contains a URI that identifies the resource whose 257 transaction information is reported in the remainder of the 258 document. 260 The "transaction-info" element has a series of zero or more 261 "transaction" sub-elements. 263 5.1.1 Transaction Element 265 The "transaction" element contains information on a particular 266 associated transaction. It has two mandatory attributes: "id" and 267 "r-uri". 269 id: provides a single string that can be used as an identifier for 270 this transaction. The "id" is created when the request that 271 initiates the transaction is sent and it MUST be unique amonst all 272 the transactions at the subscribed resource. 274 r-uri: provides the Request-URI of the request that initiated the 275 associated transaction. 277 The transaction element has a mandatory sub-element: the "state" 278 sub-element. 280 5.1.1.1 State Element 282 The "state" element indicates the state of the transaction. Its value 283 is an enumerated type describing one of the following two states: 284 "pending" or "complete". It has an optional "code" attribute that 285 contains a provisional response status code (in the pending state) or 286 a final response code (in the complete state). 288 The following is an example of a state element: 290 complete 292 5.2 Constructing Coherent State 294 The subscriber to the transaction information maintains a table for 295 the list of transactions. The table contains a row for each 296 transaction. Each row is indexed by an ID, present in the "id" 297 attribute of the "transaction" element. The contents of each row 298 contain the state of that transaction as conveyed in the document. 299 The table is also associated with a version number. The version 300 number MUST be initialized with the value of the "version" attribute 301 from the "transaction-info" element in the first document received. 302 Each time a new document is received, the value of the local version 303 number, and the "version" attribute in the new document, are 304 compared. If the value in the new document is one higher than the 305 local version number, the local version number is increased by one, 306 and the document is processed. If the value in the document is more 307 than one higher than the local version number, the local version 308 number is set to the value in the new document, and the document is 309 processed. If the document did not contain full state, the subscriber 310 SHOULD generate a refresh request to trigger a full state 311 notification. If the value in the document is less than the local 312 version, the document is discarded without processing. The 313 "transaction-info" element contains an "entity" attribute that 314 indicate the URI of the subscribed resource. 316 The processing of the transaction information document depends on 317 whether it contains full or partial state. If it contains full state, 318 indicated by the value of the "state" attribute in the 319 "transaction-info" element, the contents of the table are flushed. 320 They are repopulated from the document. A new row in the table is 321 created for each "transaction" element. If the document contains 322 partial state, as indicated by the value of the "state" attribute in 323 the "transaction-info" element, the document is used to update the 324 table. For each "transaction" element in the document, the subscriber 325 checks to see whether a row exists for that transaction. This check 326 is done by comparing the ID in the "id" attribute of the 327 "transaction" element with the ID associated with the row. If the 328 transaction does not exist in the table, a row is added, and its 329 state is set to the information from that "transaction" element. If 330 the transaction does exist, its state is updated to be the 331 information from that "transaction" element. If a row is updated or 332 created, such that its state is now terminated, that entry MAY be 333 removed from the table at any time. 335 5.3 Schema 337 The following is the schema for the application/transaction-info+xml 338 type: 340 341 346 347 349 350 351 352 354 356 357 359 360 361 362 363 364 365 366 367 369 370 371 372 373 374 375 376 378 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 400 5.4 Example 402 The following is an example of a application/transaction-info+xml 403 document: 405 406 410 411 complete 412 413 414 complete 415 416 417 pending 419 420 422 6. The Associated-Transactions-State Header Field 424 User agents may need to obtain a URI that identifies a set of 425 transactions at the application server in order to subscribe to the 426 state of those transactions. A user agent can use different means to 427 obtain such a URI. One of them consists of using the 428 Associated-Transactions-State SIP header field, which we define here. 430 The Associated-Transactions-State header field can be used when an 431 application server receives a SIP request that causes the application 432 server to initiate a set of transactions. We refer to this SIP 433 request as the triggering request and the set of transactions as the 434 associated transactions. 436 For example, an application server provides conferencing services. 437 When this application server receives an INVITE from a user who is 438 the first joining a particular conference, the application server 439 sends a MESSAGE to the rest of the participants to inform them 440 that there is already a user in the conference. In this case, the 441 triggering request is the INVITE, and the associated transactions 442 are the MESSAGE transactions. 444 Application servers MAY include a Associated-Transactions-State 445 header field in the responses to a triggering request. Clients can 446 use the URI in this header field to subscribe to the state of the 447 associated transactions. 449 In our example, the response to the INVITE request carries a 450 Associated-Transactions-State header field. The client subscribes 451 to the URI received in this header field to monitor the state of 452 the MESSAGE transactions. This way, the user knows who of the rest 453 of the participants receives the MESSAGE. 455 6.1 Syntax 457 The ABNF of the Associated-Transactions-State header field is: 459 Associated-Transactions-State = HCOLON transactions-state-uri 460 transactions-state-uri = SIP-URI / SIPS-URI 461 OPEN ISSUE: do we want to have transactions-state-uri = addr-spec, 462 which includes SIP-URI / SIPS-URI / absoluteURI ? Do we need non-SIP 463 URIs? 465 7. Security Considerations 467 TBD. 469 8. IANA Considerations 471 This document registers a new MIME type, application/ 472 transaction-info+xml, new XML namespace and a new SIP header field. 474 8.1 MIME Registration for application/transaction-info+xml 476 MIME media type name: application 478 MIME subtype name: transaction-info+xml 480 Mandatory parameters: none 482 Optional parameters: Same as charset parameter application/xml as 483 specified in RFC 3023 [4]. 485 Encoding considerations: Same as encoding considerations of 486 application/xml as specified in RFC 3023 [4]. 488 Security considerations: See Section 10 of RFC 3023 [4] and Section 7 489 of this specification. 491 Interoperability considerations: none. 493 Published specification: This document. 495 Applications which use this media type: This document type has been 496 used to support SIP applications such as MESSAGE exploders. 498 Additional Information: 500 Magic Number: None 502 File Extension: .tin or .xml 504 Macintosh file type code: "TEXT" 506 Personal and email address for further information: Gonzalo 507 Camarillo, 508 Intended usage: COMMON 510 Author/Change controller: The IETF. 512 8.2 URN Sub-Namespace Registration for 513 urn:ietf:params:xml:ns:transaction-info 515 This section registers a new XML namespace, as per the guidelines in 516 [7] 518 URI: The URI for this namespace is 519 urn:ietf:params:xml:ns:transaction-info. 521 Registrant Contact: IETF, SIPPING working group,, 522 Gonzalo Camarillo, 524 XML: 526 BEGIN 527 528 530 531 532 534 Transaction Information Namespace 535 536 537

Namespace for Transaction Information

538

application/transaction-info+xml

539

See RFCXXXX.

540 541 542 END 544 8.3 Schema Registration 546 This specification registers a schema, as per the guidelines in [7]. 548 URI: please assign. 550 Registrant Contact: IETF, SIPPING working group,, 551 Gonzalo Camarillo, 553 XML: The XML can be found in Section 5.3. 555 8.4 Associated-Transactions-State Header Field Registration 557 9. Acknowledgements 559 This document is partially based on the event package for INVITE 560 initiated dialogs [9]. 562 Normative References 564 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 565 Levels", BCP 14, RFC 2119, March 1997. 567 [2] Moats, R., "URN Syntax", RFC 2141, May 1997. 569 [3] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, 570 August 1999. 572 [4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC 573 3023, January 2001. 575 [5] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., 576 Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP: 577 Session Initiation Protocol", RFC 3261, June 2002. 579 [6] Roach, A., "Session Initiation Protocol (SIP)-Specific Event 580 Notification", RFC 3265, June 2002. 582 [7] Mealling, M., "The IETF XML Registry", 583 draft-mealling-iana-xmlns-registry-05 (work in progress), June 584 2003. 586 Informational References 588 [8] Camarillo, G., "Requirements for Session Initiation Protocol 589 (SIP) Exploder Invocation", draft-camarillo-sipping-exploders-01 590 (work in progress), November 2003. 592 [9] Rosenberg, J. and H. Schulzrinne, "An INVITE Inititiated Dialog 593 Event Package for the Session Initiation Protocol (SIP)", 594 draft-ietf-sipping-dialog-package-03 (work in progress), October 595 2003. 597 Authors' Addresses 599 Gonzalo Camarillo 600 Ericsson 601 Hirsalantie 11 602 Jorvas 02420 603 Finland 605 EMail: Gonzalo.Camarillo@ericsson.com 607 Miguel A. Garcia-Martin 608 Nokia 609 P.O.Box 407 610 NOKIA GROUP, FIN 00045 611 Finland 613 EMail: miguel.an.garcia@nokia.com 615 Intellectual Property Statement 617 The IETF takes no position regarding the validity or scope of any 618 intellectual property or other rights that might be claimed to 619 pertain to the implementation or use of the technology described in 620 this document or the extent to which any license under such rights 621 might or might not be available; neither does it represent that it 622 has made any effort to identify any such rights. Information on the 623 IETF's procedures with respect to rights in standards-track and 624 standards-related documentation can be found in BCP-11. Copies of 625 claims of rights made available for publication and any assurances of 626 licenses to be made available, or the result of an attempt made to 627 obtain a general license or permission for the use of such 628 proprietary rights by implementors or users of this specification can 629 be obtained from the IETF Secretariat. 631 The IETF invites any interested party to bring to its attention any 632 copyrights, patents or patent applications, or other proprietary 633 rights which may cover technology that may be required to practice 634 this standard. Please address the information to the IETF Executive 635 Director. 637 Full Copyright Statement 639 Copyright (C) The Internet Society (2004). All Rights Reserved. 641 This document and translations of it may be copied and furnished to 642 others, and derivative works that comment on or otherwise explain it 643 or assist in its implementation may be prepared, copied, published 644 and distributed, in whole or in part, without restriction of any 645 kind, provided that the above copyright notice and this paragraph are 646 included on all such copies and derivative works. However, this 647 document itself may not be modified in any way, such as by removing 648 the copyright notice or references to the Internet Society or other 649 Internet organizations, except as needed for the purpose of 650 developing Internet standards in which case the procedures for 651 copyrights defined in the Internet Standards process must be 652 followed, or as required to translate it into languages other than 653 English. 655 The limited permissions granted above are perpetual and will not be 656 revoked by the Internet Society or its successors or assignees. 658 This document and the information contained herein is provided on an 659 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 660 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 661 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 662 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 663 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 665 Acknowledgment 667 Funding for the RFC Editor function is currently provided by the 668 Internet Society.