idnits 2.17.1 draft-ietf-sip-events-01.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: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts -- however, there's a paragraph with a matching beginning. Boilerplate error? Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 286: '...individual event packages, and MUST be...' RFC 2119 keyword, line 386: '... requests MUST be echoed back in t...' RFC 2119 keyword, line 388: '... MUST be stored locally and MUST b...' RFC 2119 keyword, line 398: '... dialog MUST include themselves in...' RFC 2119 keyword, line 419: '...lity, both SUBSCRIBE and NOTIFY MAY be...' (73 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 261 has weird spacing: '... where proxy...' == Line 472 has weird spacing: '...e-using dialo...' == Line 857 has weird spacing: '... single token...' == Line 906 has weird spacing: '...ader is usefu...' == Line 972 has weird spacing: '... header is...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: NOTIFY requests SHOULD contain an "Subscription-Expires" header which indicates the remaining duration of the subscription (such a header is useful in case the SUBSCRIBE request forks, since the response to a forked subscribe -- which contains the "Expire" header that specifies the agreed-upon expiration time -- may not be received by the subscriber). The notifier SHOULD use this header to adjust the time remaining on the subscription; however, this mechanism MUST not be used to lengthen a subscription, only to shorten it. The notifier may inform a subscriber that a subscription has been removed by sending a NOTIFY message with an "Subscription-Expires" value of "0." -- 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 (May 2002) is 8017 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) -- Looks like a reference, but probably isn't: 'Roach' on line 1378 ** Obsolete normative reference: RFC 2543 (ref. '1') (Obsoleted by RFC 3261, RFC 3262, RFC 3263, RFC 3264, RFC 3265) -- Possible downref: Non-RFC (?) normative reference: ref. '2' -- Possible downref: Non-RFC (?) normative reference: ref. '4' ** Obsolete normative reference: RFC 2068 (ref. '5') (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 2223 (ref. '6') (Obsoleted by RFC 7322) -- Possible downref: Non-RFC (?) normative reference: ref. '7' -- Possible downref: Non-RFC (?) normative reference: ref. '8' Summary: 8 errors (**), 0 flaws (~~), 7 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Engineering Task Force Adam Roach 2 Internet Draft Ericsson Inc. 3 Category: Standards Track November 2001 4 Expires May 2002 5 7 SIP-Specific Event Notification 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance 12 with all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as 17 Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other 21 documents at any time. It is inappropriate to use Internet-Drafts 22 as reference material or cite them other than as "work in 23 progress". 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/lid-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html 31 This document is an individual submission to the IETF. Comments 32 should be directed to the authors. 34 Abstract 36 This document describes an extension to the Session Initiation 37 Protocol (SIP). The purpose of this extension is to provide an 38 extensible framework by which SIP nodes can request notification 39 from remote nodes indicating that certain events have occurred. 41 Concrete uses of the mechanism described in this document may be 42 standardized in the future. 44 Note that the event notification mechanisms defined herein are 45 NOT intended to be a general-purpose infrastructure for all 46 classes of event subscription and notification. 48 1. Table of Contents 50 1. Table of Contents...................................... 1 51 2. Introduction........................................... 3 52 2.1. Overview of Operation.................................. 4 53 3. Syntax................................................. 4 54 3.1. New Methods............................................ 4 55 3.1.1. SUBSCRIBE method....................................... 5 56 3.1.2. NOTIFY method.......................................... 6 57 3.2. New Headers............................................ 6 58 3.2.1. "Event" header......................................... 6 59 3.2.2. "Allow-Events" Header.................................. 7 60 3.2.3. "Subscription-Expires" Header.......................... 7 61 3.3. New Response Codes..................................... 7 62 3.3.1. "202 Accepted" Response Code........................... 8 63 3.3.2. "489 Bad Event" Response Code.......................... 8 64 4. Node Behavior.......................................... 8 65 4.1. General................................................ 8 66 4.1.1. Route Handling......................................... 8 67 4.1.2. Detecting support for SUBSCRIBE and NOTIFY............. 9 68 4.1.3. CANCEL requests........................................ 9 69 4.1.4. State Agents and Notifier Migration.................... 9 70 4.2. Description of SUBSCRIBE Behavior...................... 10 71 4.2.1. Correlation to dialogs, calls, and terminals........... 10 72 4.2.2. Subscription duration.................................. 11 73 4.2.3. Identification of Subscribed Events and Event Classes.. 11 74 4.2.4. Additional SUBSCRIBE Header Values..................... 12 75 4.2.5. Subscriber SUBSCRIBE Behavior.......................... 12 76 4.2.6. Proxy SUBSCRIBE Behavior............................... 14 77 4.2.7. Notifier SUBSCRIBE Behavior............................ 14 78 4.3. Description of NOTIFY Behavior......................... 17 79 4.3.1. Correlation............................................ 17 80 4.3.2. Identification of reported events, event classes, and c 18 81 4.3.3. Notifier NOTIFY Behavior............................... 18 82 4.3.4. Proxy NOTIFY Behavior.................................. 20 83 4.3.5. Subscriber NOTIFY Behavior............................. 20 84 4.4. Polling Resource State................................. 21 85 4.5. Allow-Events header usage.............................. 21 86 5. Event Packages......................................... 21 87 5.1. Appropriateness of Usage............................... 22 88 5.2. Sub-packages........................................... 22 89 5.3. Amount of State to be Conveyed......................... 23 90 5.3.1. Complete State Information............................. 23 91 5.3.2. State Deltas........................................... 23 92 5.4. Event Package Responsibilities......................... 24 93 5.4.1. Event Package Name..................................... 24 94 5.4.2. Event Package Parameters............................... 24 95 5.4.3. SUBSCRIBE Bodies....................................... 24 96 5.4.4. Subscription Duration.................................. 25 97 5.4.5. NOTIFY Bodies.......................................... 25 98 5.4.6. Notifier processing of SUBSCRIBE requests.............. 25 99 5.4.7. Notifier generation of NOTIFY requests................. 25 100 5.4.8. Subscriber processing of NOTIFY requests............... 25 101 5.4.9. Handling of forked requests............................ 26 102 5.4.10. Rate of notifications.................................. 26 103 5.4.11. State Agents........................................... 26 104 5.4.12. Examples............................................... 26 105 6. Security Considerations................................ 27 106 6.1. Access Control......................................... 27 107 6.2. Release of Sensitive Policy Information................ 27 108 6.3. Denial-of-Service attacks.............................. 27 109 7. IANA Considerations.................................... 27 110 7.1. Registration Template.................................. 28 111 8. Open Issues............................................ 29 112 8.1. CANCEL Handling........................................ 29 113 8.2. Version of SIP to reference............................ 29 114 8.3. Immediate NOTIFYs...................................... 30 115 9. Changes................................................ 30 116 9.1. Changes from draft-ietf-...-00......................... 30 117 9.2. Changes from draft-roach-...-03........................ 31 118 9.3. Changes from draft-roach-...-02........................ 33 119 9.4. Changes from draft-roach-...-01........................ 35 120 10. References............................................. 35 121 11. Acknowledgements....................................... 36 122 12. Author's Address....................................... 36 124 2. Introduction 126 The ability to request asynchronous notification of events proves 127 useful in many types of services for which cooperation between 128 end-nodes is required. Examples of such services include 129 automatic callback services (based on terminal state events), 130 buddy lists (based on user presence events), message waiting 131 indications (based on mailbox state change events), and PINT 132 status (based on call state events). 134 The methods described in this document allow a framework by which 135 notification of these events can be ordered. 137 The event notification mechanisms defined herein are NOT intended 138 to be a general-purpose infrastructure for all classes of event 139 subscription and notification. Meeting requirements for the 140 general problem set of subscription and notification is far too 141 complex for a single protocol. Our goal is to provide a 142 SIP-specific framework for event notification which is not so 143 complex as to be unusable for simple features, but which is still 144 flexible enough to provide powerful services. Note, however, that 145 event packages based on this framework may define arbitrarily 146 complex rules which govern the subscription and notification for 147 the events or classes of events they describe. 149 This draft does not describe an extension which may be used 150 directly; it must be extended by other drafts (herein referred to 151 as "event packages.") In object-oriented design terminology, it 152 may be thought of as an abstract base class which must be derived 153 into an instantiatable class by further extensions. Guidelines 154 for creating these extensions are described in section 5. 156 2.1. Overview of Operation 158 The general concept is that entities in the network can subscribe 159 to resource or call state for various resources or calls in the 160 network, and those entities (or entities acting on their behalf) 161 can send notifications when those states change. 163 A typical flow of messages would be: 165 Subscriber Notifier 166 |-----SUBSCRIBE---->| Request state subscription 167 |<-------200--------| Acknowledge subscription 168 |<------NOTIFY----- | Return current state information 169 |--------200------->| 170 |<------NOTIFY----- | Return current state information 171 |--------200------->| 173 The subscriber and notifier entities need not necessarily be UAs, 174 but often will be. 176 Subscriptions are expired and must be refreshed in exactly the 177 same manner as registrations (see RFC 2543 [1] ). 179 3. Syntax 181 This section describes the syntax extensions required for event 182 notification in SIP. Semantics are described in section 4. 184 3.1. New Methods 186 This document describes two new SIP methods: "SUBSCRIBE" and 187 "NOTIFY." 189 This table expands on tables 4 and 5 in RFC 2543 [1] . 191 Header Where SUB NOT 192 ------ ----- --- --- 193 Accept R o o 194 Accept-Encoding R o o 195 Accept-Language R o o 196 Allow 200 - - 197 Allow 405 o o 198 Authorization R o o 199 Call-ID gc m m 200 Contact R m m 201 Contact 1xx o o 202 Contact 2xx m o 203 Contact 3xx m m 204 Contact 485 o o 205 Content-Encoding e o o 206 Content-Length e o o 207 Content-Type e * * 208 CSeq gc m m 209 Date g o o 210 Encryption g o o 211 Expires g o - 212 From gc m m 213 Hide R o o 214 Max-Forwards R o o 215 Organization g o o 216 Priority R o o 217 Proxy-Authenticate 407 o o 218 Proxy-Authorization R o o 219 Proxy-Require R o o 220 Require R o o 221 Retry-After R - - 222 Retry-After 404,480,486 o o 223 Retry-After 503 o o 224 Retry-After 600,603 o o 225 Response-Key R o o 226 Record-Route R o o 227 Record-Route 2xx o o 228 Route R o o 229 Server r o o 230 Subject R o o 231 Timestamp g o o 232 To gc(1) m m 233 Unsupported 420 o o 234 User-Agent g o o 235 Via gc(2) m m 236 Warning r o o 237 WWW-Authenticate 401 o o 239 3.1.1. SUBSCRIBE method 240 "SUBSCRIBE" is added to the definition of the element "Method" in 241 the SIP message grammar. 243 Like all SIP method names, the SUBSCRIBE method name is case 244 sensitive. The SUBSCRIBE method is used to request asynchronous 245 notification of an event or set of events at a later time. 247 3.1.2. NOTIFY method 249 "NOTIFY" is added to the definition of the element "Method" in 250 the SIP message grammar. 252 The NOTIFY method is used to notify a SIP node that an event 253 which has been requested by an earlier SUBSCRIBE method has 254 occurred. It may also provide further details about the event. 256 3.2. New Headers 258 This table expands on tables 4 and 5 in RFC 2543 [1] , as amended 259 by the changes described in section 3.1. 261 Header field where proxy ACK BYE CAN INV OPT REG SUB NOT 262 ----------------------------------------------------------------- 263 Allow-Events g o o o o o o o o 264 Allow-Events 489 - - - - - - m m 265 Event R - - - - - - m m 266 Subscription-Expires R - - - - - - - o 268 3.2.1. "Event" header 270 The following header is defined for the purposes of this 271 specification. 273 Event = ( "Event" | "o" ) ":" event-type 274 *(( ";" parameter-name 275 ["=" ( token | quoted-string ) ] ) 276 event-type = event-package *( "." event-subpackage ) 277 event-package = token-nodot 278 event-subpackage = token-nodot 279 token-nodot = 1*( alphanum | "-" | "!" | "%" | "*" 280 | "_" | "+" | "`" | "'" | "~" ) 282 Event is added to the definition of the element "request-header" 283 in the SIP message grammar. 285 This document does not define values for event-types. These 286 values will be defined by individual event packages, and MUST be 287 registered with the IANA. 289 There must be exactly one event type listed per event header. 290 Multiple events per message are disallowed. 292 For the curious, the "o" short form is chosen to represent 293 "occurrence." 295 3.2.2. "Allow-Events" Header 297 The following header is defined for the purposes of this 298 specification. 300 Allow-Events = ( "Allow-Events" | "u" ) ":" 1#event-type 302 Allow-Events is added to the definition of the element 303 "general-header" in the SIP message grammar. 305 For the curious, the "u" short form is chosen to represent 306 "understands." 308 3.2.3. "Subscription-Expires" Header 310 The following header is defined for the purposes of this 311 specification. 313 Subscription-Expires = "Subscription-Expires" ":" 314 ( SIP-date | delta-seconds ) 315 *( ";" subexp-params ) 317 subexp-params = "reason" "=" reason-code 318 | generic-param 320 reason-code = "migration" 321 | "maint" 322 | "refused" 323 | "timeout" 324 | reason-extension 326 reason-extension = token 328 Subscription-Expires is added to the definition of the element 329 "request-header" in the SIP message grammar. 331 3.3. New Response Codes 332 3.3.1. "202 Accepted" Response Code 334 The 202 response is added to the "Success" header field 335 definition: 337 Success = "200" ; OK 338 | "202" ; Accepted 340 "202 Accepted" has the same meaning as that defined in HTTP/1.1 341 [5] . 343 3.3.2. "489 Bad Event" Response Code 345 The 489 event response is added to the "Client-Error" header 346 field definition: 348 Client-Error = "400" ; Bad Request 349 ... 350 | "489" ; Bad Event 352 "489 Bad Event" is used to indicate that the server did not 353 understand the event package specified in a "Event" header field. 355 4. Node Behavior 357 4.1. General 359 Unless noted otherwise, SUBSCRIBE and NOTIFY requests follow the 360 same protocol rules governing the usage of tags, Route handling, 361 Record-Route handling, Via handling, and Contact handling as 362 INVITE; retransmission, reliability, CSeq handling and 363 provisional responses are the same as those defined for BYE. 365 For the purposes of this document, a "dialog" is defined as all 366 messages sharing the tuple of "To" (including tag), "From" 367 (including tag), and "Call-Id." As in INVITE-initiated dialogs, 368 requests containg no "To" tag are also considered to be part of 369 the same dialog as messages which contain a "To" tag but 370 otherwise match. 372 4.1.1. Route Handling 374 Route and Record-Route handling for SUBSCRIBE and NOTIFY dialogs 375 is generally the same as for INVITE and its subsequent responses. 376 The exact method for echoing Record-Route headers in responses 377 and using them to form Route headers in subsequent requests is 378 described in RFC2543 [1] . For the purposes of the following 379 discussion, the "Contact" header is considered part of the 380 "Record-Route" set. 382 From a subscriber perspective, the "Record-Route" headers 383 received in a SUBSCRIBE response are stored locally and placed in 384 the "Route" headers for SUBSCRIBE refreshes. To support forking 385 of SUBSCRIBE requests, "Record-Route" headers received in NOTIFY 386 requests MUST be echoed back in the NOTIFY responses; if no route 387 for the dialog has been established, these "Record-Route" headers 388 MUST be stored locally and MUST be placed in the "Route" headers 389 for SUBSCRIBE refreshes. 391 From a notifier perspective, SUBSCRIBE request "Record-Route" 392 headers are echoed back in the SUBSCRIBE response and stored 393 locally. The locally stored copy of the "Record-Route" headers is 394 placed in the "Route" headers when generating NOTIFY requests. 396 The result of the forgoing rules is that proxies wishing to 397 remain on the signalling path for subsequent requests in the 398 dialog MUST include themselves in a "Record-Route" for all 399 requests, not just the initial SUBSCRIBE. 401 4.1.2. Detecting support for SUBSCRIBE and NOTIFY 403 Neither SUBSCRIBE nor NOTIFY necessitate the use of "Require" or 404 "Proxy-Require" headers; similarly, there is no token defined for 405 "Supported" headers. If necessary, clients may probe for the 406 support of SUBSCRIBE and NOTIFY using the OPTIONS request defined 407 in RFC2543 [1] . 409 The presence of the "Allow-Events" header in a message is 410 sufficient to indicate support for SUBSCRIBE and NOTIFY. 412 The "methods" parameter for Contact may also be used to 413 specifically announce support for SUBSCRIBE and NOTIFY messages 414 when registering. (See reference [8] for details on the "methods" 415 parameter). 417 4.1.3. CANCEL requests 419 For the purposes of generality, both SUBSCRIBE and NOTIFY MAY be 420 canceled; however, doing so is not recommended. Successfully 421 cancelled SUBSCRIBE and NOTIFY requests MUST be completed with a 422 "487 Request Cancelled" response; the server acts as if the 423 request were never received. In general, since neither SUBSCRIBE 424 nor NOTIFY are allowed to have protracted transactions, attempts 425 to cancel them are expected to fail. 427 4.1.4. State Agents and Notifier Migration 428 When state agents (see section 5.4.11. ) are used, it is often 429 useful to allow migration of subscriptions between state agents 430 and the nodes for which they are providing state aggregation (or 431 even among various state agents). Such migration may be effected 432 by sending a "NOTIFY" with an "Subscription-Expires" header of 433 "0," and a reason parameter of "migration." This NOTIFY request 434 is otherwise normal, and is formed as described in section 4.3.3. 436 Upon receipt of this NOTIFY message, the subscriber SHOULD 437 attempt to re-subscribe (as described in the following sections). 438 The resulting SUBSCRIBE message can then be proxied or redirected 439 to the node to which notification responsibility is passing. 441 4.2. Description of SUBSCRIBE Behavior 443 The SUBSCRIBE method is used to request current state and state 444 updates from a remote node. 446 4.2.1. Correlation to dialogs, calls, and terminals 448 A subscription is uniquely identified by the combination of the 449 To, From, and Call-ID fields in the SUBSCRIBE request. Refreshes 450 of subscriptions SHOULD reuse the same Call-ID if possible, since 451 subscriptions are uniquely identified at presence servers using 452 the Call-ID. Two subscriptions from the same user, for the same 453 user, but with different Call-IDs, are considered different 454 subscriptions. Note this is exactly the same as usage of Call-ID 455 in registrations. 457 Initial SUBSCRIBE requests MUST contain a "tag" parameter (as 458 defined in RFC 2543 [1] ) in the "From" header, and MUST NOT 459 contain a "tag" parameter in the "To" header. Responses to 460 SUBSCRIBE requests MUST contain a "tag" parameter in the "To" 461 header. 463 The "tag" in the "To" header allows the subscriber to 464 differentiate between NOTIFY requests from different clients in 465 the case that the SUBSCRIBE request was forked. SUBSCRIBE 466 requests for re-subscription MUST contain "tag" parameters in 467 both the "To" and "From" headers (matching those previously 468 established for the dialog). 470 The relationship between subscriptions and (INVITE-initiated) 471 sessions sharing the same dialog correlation information is 472 undefined. Re-using dialog correlation information for 473 subscriptions is allowed, but sharing of such information does 474 not change the semantics of the INVITE session or the SUBSCRIBE 475 dialog. 477 Similarly, the relationship between a subscription in one 478 direction (e.g. from node A to node B) and a subscription in the 479 opposite direction (from B to A) with the same dialog correlation 480 information is undefined. While re-using such information is 481 allowed, the sharing of such information does not change the 482 semantics of either SUBSCRIBE dialog. 484 4.2.2. Subscription duration 486 SUBSCRIBE requests SHOULD contain an "Expires" header. This 487 expires value indicates the duration of the subscription. The 488 formatting of these is described in RFC 2543. In order to keep 489 subscriptions effective beyond the duration communicated in the 490 "Expires" header, subscribers need to refresh subscriptions on a 491 periodic basis. This refreshing is performed in the same way as 492 REGISTER refreshes: the To, From, and Call-ID match those in the 493 SUBSCRIBE being refreshed, while the CSeq number is incremented. 495 If no "Expires" header is present in a SUBSCRIBE request, the 496 implied default is defined by the event package being used. 498 200-class responses to SUBSCRIBE requests also MUST contain an 499 "Expires" header. The period of time in the response MAY be 500 shorter or longer than specified in the request. The period of 501 time in the response is the one which defines the duration of the 502 subscription. 504 Similar to REGISTER requests, SUBSCRIBE requests may be renewed 505 at any time to prevent them from expiring at the end of the 506 "Expires" period. These renewals will contain a the same "To," 507 "From," and "Call-ID" as the original request, and an incremented 508 "CSeq" number. 510 Also similar to REGISTER requests, a natural consequence of this 511 scheme is that a SUBSCRIBE with an "Expires" of 0 constitutes a 512 request to unsubscribe from an event. 514 Notifiers may also wish to cancel subscriptions to events; this 515 is useful, for example, when the resource to which a subscription 516 refers is no longer available. Further details on this mechanism 517 are discussed in section 4.3.3. 519 4.2.3. Identification of Subscribed Events and Event Classes 521 Identification of events is provided by three pieces of 522 information: Request URI, Event Type, and (optionally) message 523 body. 525 The Request URI of a SUBSCRIBE request, most importantly, 526 contains enough information to route the request to the 527 appropriate entity. It also contains enough information to 528 identify the resource for which event notification is desired, 529 but not necessarily enough information to uniquely identify the 530 nature of the event (e.g. "sip:adam.roach@ericsson.com" would be 531 an appropriate URI to subscribe to for my presence state; it 532 would also be an appropriate URI to subscribe to the state of my 533 voice mailbox). 535 Subscribers MUST include exactly one "Event" header in SUBSCRIBE 536 requests, indicating to which event or class of events they are 537 subscribing. The "Event" header will contain a token which 538 indicates the type of state for which a subscription is being 539 requested. This token will be registered with the IANA and will 540 correspond to an event package which further describes the 541 semantics of the event or event class. 543 The "Event" header is considered mandatory for the purposes of 544 this document. However, to maintain compatibility with PINT (see 545 [3] ), servers MAY interpret a SUBSCRIBE request with no "Event" 546 header as requesting a subscription to PINT events. If the 547 servers do not support PINT, they SHOULD return "489 Bad Event" 548 to any SUBSCRIBE messages without an EVENT header. 550 If the event package to which the event token corresponds defines 551 behavior associated with the body of its SUBSCRIBE requests, 552 those semantics apply. 554 4.2.4. Additional SUBSCRIBE Header Values 556 Each SUBSCRIBE request MUST have exactly one "Contact:" header, 557 to be used as part of route handling, as described in section 558 4.1.1. 560 SUBSCRIBE requests MAY contain an "Accept" header. This header, 561 if present, indicates the body formats allowed in subsequent 562 NOTIFY requests. Event packages MUST define the behavior for 563 SUBSCRIBE requests without "Accept" headers; usually, this will 564 connote a single, default body type. 566 Header values not described in this document are to be 567 interpreted as described in RFC 2543 [1] . 569 4.2.5. Subscriber SUBSCRIBE Behavior 571 4.2.5.1. Requesting a Subscription 573 When a subscriber wishes to subscribe to a particular state for a 574 resource, it forms a SUBSCRIBE message. 576 The dialog correlation information is formed as if for an 577 original INVITE: the Call-ID is a new call ID with the syntax 578 described in RFC 2543; the To: field indicates the subscribed 579 resource's persistent address (which will generally match the 580 Request URI used to form the message); and the From: field will 581 indicate the subscriber's persistent address (typically 582 sip:user@domain). 584 This SUBSCRIBE request will be confirmed with a final response. 585 200-class responses indicate that the subscription has been 586 accepted, and that a NOTIFY will be sent immediately. A 200 587 response indicates that the subscription has been accepted and 588 that the user is authorized to subscribe to the requested 589 resource. A 202 response merely indicates that the subscription 590 has been understood, and that authorization may or may not have 591 been granted. 593 The "Expires" header in a 200-class response to SUBSCRIBE 594 indicates the actual duration for which the subscription will 595 remain active (unless refreshed). 597 Non-200 class final responses indicate that the subscription has 598 not been created, and no subsequent NOTIFY message will be sent. 599 All non-200 class responses (with the exception of "489," 600 described herein) have the same meanings and handling as 601 described in RFC 2543 [1] . 603 4.2.5.2. Refreshing of Subscriptions 605 At any time before a subscription expires, the subscriber may 606 refresh the timer on such a subscription by re-sending a 607 SUBSCRIBE request. The handling for such a request is the same as 608 for the initial creation of a subscription except as described 609 below. 611 Subscription renewals will contain a "To" field matching the 612 "From" field in the first NOTIFY request for the dialog 613 containing the subscription to be refreshed. They will contain 614 the same "From" and "Call-ID" fields as the original SUBSCRIBE 615 request, and an incremented "CSeq" number from the original 616 SUBSCRIBE request. Route handling is as discussed in section 617 4.1.1. 619 If a SUBSCRIBE request to refresh a subscription receives a "481" 620 response, this indicates that the subscription has been 621 terminated and that the subscriber did not receive notification 622 of this fact. In this case, the subscriber should consider the 623 subscription invalid. If the subscriber wishes to re-subscribe to 624 the state, he does so by composing an unrelated initial SUBSCRIBE 625 request with a freshly-generated Call-ID and a new, unique "From" 626 tag (see section 4.2.5.1. ) 627 If a SUBSCRIBE request to refresh a subscription fails, the 628 original subscription is still considered valid for the duration 629 of the most recently known "Expires" value as negotiated by 630 SUBSCRIBE and its response, or as communicated by NOTIFY in 631 "Subscription-Expires," except as described above. 633 4.2.5.3. Unsubscribing 635 Unsubscribing is handled in the same way as refreshing of a 636 subscription, with the "Expires" header set to "0." Note that a 637 successful unsubscription will also trigger a final "NOTIFY". 639 4.2.5.4. Confirmation of Subscription Creation 641 The subscriber can expect to receive a NOTIFY message from each 642 node which has registered a successful subscription or 643 subscription refresh. Until the first NOTIFY message arrives, the 644 subscriber should consider the state of the subscribed resource 645 to be in a neutral state. Event packages which define new event 646 packages MUST define this "neutral state" in such a way that 647 makes sense for their application (see section 5.4.7. ). 649 Due to the potential for both out-of-order messages and forking, 650 the subscriber MUST be prepared to receive NOTIFY messages before 651 the SUBSCRIBE transaction has completed. 653 Except as noted above, processing of this NOTIFY is the same as 654 in section 4.3.5. 656 4.2.6. Proxy SUBSCRIBE Behavior 658 Proxies need no additional behavior beyond that described in RFC 659 2543 [1] to support SUBSCRIBE. If a proxy wishes to see all of 660 the SUBSCRIBE and NOTIFY requests for a given dialog, it MUST 661 record-route all SUBSCRIBE and NOTIFY requests. 663 4.2.7. Notifier SUBSCRIBE Behavior 665 4.2.7.1. SUBSCRIBE Transaction Processing 667 In no case should a SUBSCRIBE transaction extend for any longer 668 than the time necessary for automated processing. In particular, 669 notifiers MUST NOT wait for a user response before returning a 670 final response to a SUBSCRIBE request. 672 The notifier SHOULD check that the event package specified in the 673 "Event" header is understood. If not, the notifier SHOULD return 674 a "489 Bad Event" response to indicate that the specified 675 event/event class is not understood. 677 The notifier SHOULD also perform any necessary authentication and 678 authorization per its local policy. See section 4.2.7.3. 680 If the SUBSCRIBE request contains a tag parameter in the "To" 681 field, but the notifier has no record of the indicated dialog, 682 the notifier has two options. If the notifier is able and willing 683 to reconstruct subscription state, he may accept the subscription 684 as an initial subscription. If the notifier cannot or is not 685 willing to reconstitute such state, it should respond with a "481 686 Subscription does not exist." 688 If the notifier is able to immediately determine that it 689 understands the event package, that the authenticated subscriber 690 is authorized to subscribe, and that there are no other barriers 691 to creating the subscription, it creates the subscription and 692 returns a "200 OK" response, unless doing so would reveal 693 authorization policy in an undesirable fashion (see section 6.2. 694 ). 696 If the notifier cannot immediately create the subscription (e.g. 697 it needs to wait for user input for authorization, or is acting 698 for another node which is not currently reachable), or wishes to 699 mask authorization policy, it will return a "202 Accepted" 700 response. This response indicates that the request has been 701 received and understood, but does not necessarily imply that the 702 subscription has been created yet. 704 The "Expires" values present in SUBSCRIBE 200-class responses 705 behave in the same way as they do in REGISTER responses: the 706 server MAY shorten or lengthen the interval. 708 200-class responses to SUBSCRIBE requests will not generally 709 contain any useful information beyond subscription duration; 710 their primary purpose is to serve as a reliability mechanism. 711 State information will be communicated via a subsequent NOTIFY 712 request from the notifier. 714 The other response codes defined in RFC 2543 may be used in 715 response to SUBSCRIBE requests, as appropriate. 717 4.2.7.2. Confirmation of Subscription Creation/Refreshing 719 Upon successfully accepting or refreshing of a subscription, 720 notifiers MUST send a NOTIFY message immediately to communicate 721 the current resource state to the subscriber. If the resource has 722 no meaningful state at the time that the SUBSCRIBE message is 723 processed, this NOTIFY message MAY contain an empty or neutral 724 body. See section 4.3.3. for further details on NOTIFY message 725 generation. 727 Note that a NOTIFY message is always sent immediately after any 728 200-class response to a SUBSCRIBE request, regardless of whether 729 the subscription has already been authorized. 731 4.2.7.3. Authentication/Authorization of SUBSCRIBE requests 733 Privacy concerns may require that notifiers either use access 734 lists or ask the notifier owner, on a per-subscription basis, 735 whether a particular remote node is authorized to subscribe to a 736 certain set of events. In general, authorization of users prior 737 to authentication is not particularly useful. 739 SIP authentication mechanisms are discussed in RFC2543 [1] . Note 740 that, even if the notifier node typically acts as a proxy, 741 authentication for SUBSCRIBE requests will always be performed 742 via a "401" response, not a "407;" notifiers always act as a user 743 agents when accepting subscriptions and sending notifications. 745 If authorization fails based on an access list or some other 746 automated mechanism (i.e. it can be automatically authoritatively 747 determined that the subscriber is not authorized to subscribe), 748 the notifier SHOULD reply to the request with a "403 Forbidden" 749 or "603 Decline" response, unless doing so might reveal 750 information that should stay private; see section 6.2. 752 If the notifier owner is interactively queried to determine 753 whether a subscription is allowed, a "202 Accept" response is 754 returned immediately. Note that a NOTIFY message is still formed 755 and sent under these circumstances, as described in the previous 756 section. 758 If subscription authorization was delayed and the notifier wishes 759 to convey that such authorization has been declined, it may do so 760 by sending a NOTIFY message containting a "Subscription-Expires" 761 header with a value of "0" and a reason parameter of "refused." 763 4.2.7.4. Refreshing of Subscriptions 765 When a notifier receives a subscription refresh, assuming that 766 the subscriber is still authorized, the notifier updates the 767 expiration time for subscription. As with the initial 768 subscription, the server MAY shorten or increase the amount of 769 time until expiration. The final expiration time is placed in the 770 "Expires" header in the response. 772 If no refresh for a notification address is received before its 773 expiration time, the subscription is removed. When removing a 774 subscription, the notifier MAY send a NOTIFY message with a 775 "Subscription-Expires" value of "0" to inform it that the 776 subscription is being removed. If such a message is sent, the 777 "Subscription-Expires" header SHOULD contain a "reason=timeout" 778 parameter. 780 4.3. Description of NOTIFY Behavior 782 NOTIFY messages are sent to inform subscribers of changes in 783 state to which the subscriber has a subscription. Subscriptions 784 are typically put in place using the SUBSCRIBE method; however, 785 it is possible that other means have been used. 787 If any non-SUBSCRIBE mechanisms are defined to create 788 subscriptions, it is the responsibility of the parties defining 789 those mechanisms to ensure that correlation of a NOTIFY message 790 to the corresponding subscription is possible. Designers of such 791 mechanisms are also warned to make a distinction between sending 792 a NOTIFY message to a subscriber who is aware of the 793 subscription, and sending a NOTIFY message to an unsuspecting 794 node. The latter behavior is invalid, and MUST receive a "481 795 Subscription does not exist" response (unless some other 400- or 796 500-class error code is more applicable), as described in section 797 4.3.5. In other words, knowlege of a subscription must exist in 798 both the subscriber and the notifier to be valid, even if 799 installed via a non-SUBSCRIBE mechanism. 801 A NOTIFY does not cancel its corresponding subscription; in other 802 words, a single SUBSCRIBE request may trigger several NOTIFY 803 requests. 805 4.3.1. Correlation 807 NOTIFY requests MUST contain the same Call-ID as the SUBSCRIBE 808 request which ordered them; the "To" field MUST match the "From" 809 field in the SUBSCRIBE that ordered them, and the "From" field 810 MUST match the "To" field that was sent in the 200-class response 811 to the SUBSCRIBE. In other words, NOTIFY requests MUST be in the 812 same dialog as the SUBSCRIBE that ordered them. 814 The From field of a NOTIFY request, like the "To" field of a 815 SUBSCRIBE response, MUST contain a tag; this allows for the 816 subscriber to differentiate between events from different 817 notifiers. 819 Successful SUBSCRIBE requests will receive only one 200-class 820 response; however, due to forking, the subscription may have been 821 accepted by multiple nodes. The subscriber MUST therefore be 822 prepared to receive NOTIFY requests with "From:" tags which 823 differ from the "To:" tag received in the SUBSCRIBE 200-class 824 response. 826 If multiple NOTIFY messages are received in response to a single 827 SUBSCRIBE message, they represent different destinations to which 828 the SUBSCRIBE request was forked. Unless the event package 829 specifies otherwise, the subscriber may either accept all such 830 notifications as representing different dialogs (which are then 831 refreshed separately), or send a 481 response to any NOTIFYs on 832 dialogs that it does not want to keep alive. 834 As expected, CSeq spaces are unique for each node; in other 835 words, the notifier uses a different CSeq space than the 836 subscriber and any other notifiers. 838 4.3.2. Identification of reported events, event classes, and current 839 state 841 Identification of events being reported in a notification is very 842 similar to that described for subscription to events (see section 843 4.2.3. ). 845 The Request URI of a NOTIFY request contains enough information 846 to route the request to the party which is subscribed to receive 847 notifications. It is derived from the "Contact" header present in 848 the corresponding SUBSCRIBE request. 850 If the same events for different resources are being subscribed 851 to, implementors are expected to use different dialogs in order 852 to be able to differentiate between notifications for them, 853 unless the body for the event contains enough information for 854 this correlation. 856 As in SUBSCRIBE requests, NOTIFY "Event" headers will contain a 857 single token which identifies the event or class of events for 858 which a notification is being generated. 860 If the event package to which the event token corresponds defines 861 behavior associated with the body of its NOTIFY requests, those 862 semantics apply. This information is expected to provide 863 additional details about the nature of the event which has 864 occurred and the resultant resource state. 866 When present, the body of the NOTIFY request MUST be formatted 867 into one of the body formats specified in the "Accept" header of 868 the corresponding SUBSCRIBE request. 870 4.3.3. Notifier NOTIFY Behavior 872 When a SUBSCRIBE request is successfully processed or a relevant 873 change in the subscribed state occurs, the notifier will 874 immediately construct and send a NOTIFY request to the 875 subscriber(s), per standard Route/Record-Route handling, as 876 described in section 4.1.1. 878 If the notifier is able, through any means, to determine that the 879 subscriber is no longer available to receive notifications, it 880 MAY elect to not send a notification. An example of a method by 881 which such information may be known is the "SIP for Presence" 882 event set (see [4] ). 884 A NOTIFY request is considered failed if the response times out, 885 or a non-200 class response code is received which has no 886 "Retry-After" header and no implied further action which can be 887 taken to retry the request (e.g. "401 Authorization Required.") 889 If the NOTIFY request fails (as defined above) due to a timeout 890 condition, and the subscription was installed using a soft-state 891 mechanism (such as SIP signalling), the notifier SHOULD remove 892 the subscription. 894 If the NOTIFY request fails (as defined above) due to an error 895 response, and the subscription was installed using a soft-state 896 mechanism, the notifier MUST remove the corresponding 897 subscription. 899 If a NOTIFY request receives a 481 response, the notifier MUST 900 remove the corresponding subscription even if such subscription 901 was installed by non-SUBSCRIBE means (such as an administrative 902 interface). 904 NOTIFY requests SHOULD contain an "Subscription-Expires" header 905 which indicates the remaining duration of the subscription (such 906 a header is useful in case the SUBSCRIBE request forks, since 907 the response to a forked subscribe -- which contains the "Expire" 908 header that specifies the agreed-upon expiration time -- may not 909 be received by the subscriber). The notifier SHOULD use this 910 header to adjust the time remaining on the subscription; however, 911 this mechanism MUST not be used to lengthen a subscription, only 912 to shorten it. The notifier may inform a subscriber that a 913 subscription has been removed by sending a NOTIFY message with an 914 "Subscription-Expires" value of "0." 916 If the duration of a subscription has been shortened or 917 terminated by the "Subscription-Expires" header as compared to 918 the most recent 200-class SUBSCRIBE response sent, that header 919 SHOULD include a "reason" parameter indicating the reason that 920 such action was taken. Currently, four such values are defined: 921 "migration" indicates that the node acting as notifier is 922 transferring responsibility for maintaing such state information 923 to another node; this only makes sense when subscriptions are 924 terminated, not when they are shortened. "Maint" indicates that 925 the subscription is being truncated or terminated due to server 926 maintainance, and "refused" indicates that the subscription has 927 been removed or shortened administratively (e.g. by a change in 928 ACL policy). Finally, if the notifier elects to send a NOTIFY 929 upon timeout of the subscription, they SHOULD include a 930 "Subscription-Expires" header with a value of "0" and a reason 931 parameter of "timeout." 933 4.3.4. Proxy NOTIFY Behavior 935 Proxies need no additional behavior beyond that described in RFC 936 2543 [1] to support NOTIFY. If a proxy wishes to see all of the 937 SUBSCRIBE and NOTIFY requests for a given dialog, it MUST 938 record-route all SUBSCRIBE and NOTIFY requests. 940 4.3.5. Subscriber NOTIFY Behavior 942 Upon receiving a NOTIFY request, the subscriber should check that 943 it matches at least one of its outstanding subscriptions; if not, 944 it MUST return a "481 Subscription does not exist" response 945 unless another 400- or 500-class response is more appropriate. 947 If, for some reason, the event package designated in the "Event" 948 header of the NOTIFY request is not supported, the subscriber 949 will respond with a "489 Bad Event" response. 951 To prevent spoofing of events, NOTIFY requests MAY be 952 authenticated, using any defined SIP authentication mechanism. 954 NOTIFY requests SHOULD contain "Subscription-Expires" headers 955 which indicate the time remaining on the subscription. If this 956 header is present, the subscriber SHOULD take it as the 957 authoritative duration and adjust accordingly. If an expires 958 value of "0" is present, the subscriber should consider the 959 subscription terminated. 961 When the subscription is terminated or shortened using the 962 "Subscription-Expires" mechanism, there SHOULD be a reason 963 parameter present. If it is present and the subscriber is still 964 interested in receiving updates to the state information, the 965 subscriber SHOULD attempt re-subscribe upon expiration if it is 966 set to "migration," "timeout," is not present, or is set to an 967 unknown value. Such a resubscription will be completely 968 independant of the original subscription, and will not share a 969 dialog with it; it will be generated as described in section 970 4.2.5.1. 972 If the "reason" parameter on a "Subscription-Expires" header is 973 set to either "maint" or "refused," the subscriber SHOULD NOT 974 attempt re-subscription. 976 Once the notification is deemed acceptable to the subscriber, the 977 subscriber SHOULD return a 200 response. In general, it is not 978 expected that NOTIFY responses will contain bodies; however, they 979 MAY, if the NOTIFY request contained an "Accept" header. 981 Other responses defined in RFC 2543 [1] may also be returned, as 982 appropriate. 984 4.4. Polling Resource State 986 A natural consequence of the behavior described in the preceding 987 sections is that an immediate fetch without a persistent 988 subscription may be effected by sending an appropriate SUBSCRIBE 989 with an "Expires" of 0. 991 Of course, an immediate fetch while a subscription is active may 992 be effected by sending an appropriate SUBSCRIBE with an "Expires" 993 greater than 0. 995 Upon receipt of this SUBSCRIBE request, the notifier (or 996 notifiers, if the SUBSCRIBE request was forked) will send a 997 NOTIFY request containing resource state to the address in the 998 SUBSCRIBE "Contact" field. Note that normal Route and 999 Record-Route handle still applies; see section 4.1.1. 1001 4.5. Allow-Events header usage 1003 The "Allow-Events" header, if present, includes a list of tokens 1004 which indicates the event packages supported by the client (if 1005 sent in a request) or server (if sent in a response). In other 1006 words, a node sending an "Allow-Events" header is advertising 1007 that it can process SUBSCRIBE requests and generate NOTIFY 1008 requests for all of the event packages listed in that header. 1010 Any node implementing one or more event packages SHOULD include 1011 an appropriate "Allow-Events" header indicating all supported 1012 events in INVITE requests and responses, OPTIONS responses, and 1013 REGISTER requests. "Allow-Events" headers MAY be included in any 1014 other type of request or response. 1016 This information is very useful, for example, in allowing user 1017 agents to render particular interface elements appropriately 1018 according to whether the events required to implement the 1019 features they represent are supported by the appropriate nodes. 1021 Note that "Allow-Events" headers MUST NOT be inserted by proxies. 1023 5. Event Packages 1025 This section covers several issues which should be taken into 1026 consideration when event packages based on SUBSCRIBE and NOTIFY 1027 are proposed. 1029 5.1. Appropriateness of Usage 1031 When designing an event package using the methods described in 1032 this draft for event notification, it is important to consider: 1033 is SIP an appropriate mechanism for the problem set? Is SIP being 1034 selected because of some unique feature provided by the protocol 1035 (e.g. user mobility), or merely because "it can be done?" If you 1036 find yourself defining event packages for notifications related 1037 to, for example, network management or the temperature inside 1038 your car's engine, you may want to reconsider your selection of 1039 protocols. 1041 Those interested in extending the mechanism defined in this 1042 document are urged to read "Guidelines for Authors of SIP 1043 Extensions" [2] for further guidance regarding appropriate uses 1044 of SIP. 1046 Further, it is expected that this mechanism is not to be used in 1047 applications where the frequency of reportable events is 1048 excessively rapid (e.g. more than about once per second). A SIP 1049 network is generally going to be provisioned for a reasonable 1050 signalling volume; sending a notification every time a user's GPS 1051 position changes by one hundreth of a second could easily 1052 overload such a network. 1054 5.2. Sub-packages 1056 Normal event packages define a set of state applied to a specific 1057 type of resource, such as user presence, call state, and 1058 messaging mailbox state. 1060 Sub-packages are a special type of package which define a set of 1061 state applied to other packages, such as statistics, access 1062 policy, and subscriber lists. Sub-packages may even be applied to 1063 other sub-packages. 1065 To extend the object-oriented analogy made earlier, sub-packages 1066 can be thought of as templatized C++ packages which must be 1067 applied to other packages to be useful. 1069 The name of a sub-package as applied to a package is formed by 1070 appending a period followed by the sub-package name to the end of 1071 the package. For example, if a subpackage called "watcherinfo" 1072 were being applied to a package called "presence," the event 1073 token used in "Event" and "Allow-Events" would be 1074 "presence.watcherinfo". 1076 Sub-packages must be defined so that they can be applied to any 1077 arbitrary package. In other words, sub-packages cannot be 1078 specifically tied to one or a few "parent" packages in such a way 1079 that they will not work with other packages. 1081 5.3. Amount of State to be Conveyed 1083 When designing event packages, it is important to consider the 1084 type of information which will be conveyed during a notification. 1086 A natural temptation is to convey merely the event (e.g. "a new 1087 voice message just arrived") without accompanying state (e.g. "7 1088 total voice messages"). This complicates implementation of 1089 subscribing entities (since they have to maintain complete state 1090 for the entity to which they have subscribed), and also is 1091 particularly susceptible to synchronization problems. 1093 There are two possible solutions to this problem that event 1094 packages may choose to implement. 1096 5.3.1. Complete State Information 1098 For packages which typically convey state information that is 1099 reasonably small (on the order of 1 kb or so), it is suggested 1100 that event packages are designed so as to send complete state 1101 information when an event occurs. 1103 In the circumstances that state may not be sufficient for a 1104 particular class of events, the event packages should include 1105 complete state information along with the event that occurred. 1106 For example, "no customer service representatives available" may 1107 not be as useful "no customer service representatives available; 1108 representative sip:46@cs.xyz.int just logged off". 1110 5.3.2. State Deltas 1112 In the case that the state information to be conveyed is large, 1113 the event package may choose to detail a scheme by which NOTIFY 1114 messages contain state deltas instead of complete state. 1116 Such a scheme would work as follows: any NOTIFY sent in immediate 1117 response to a SUBSCRIBE contains full state information. NOTIFY 1118 messages sent because of a state change will contain only the 1119 state information that has changed; the subscriber will then 1120 merge this information into its current knowledge about the state 1121 of the resource. 1123 Any event package that supports delta changes to states MUST use 1124 a payload which contains a version number that increases by 1125 exactly one for each NOTIFY message. Note that the state version 1126 number appears in the body of the message, not in a SIP header. 1128 If a NOTIFY arrives that has a version number that is incremented 1129 by more than one, the subscriber knows that a state delta has 1130 been missed; it ignores the NOTIFY message containing the state 1131 delta (except for the version number, which it retains to detect 1132 message loss), and re-sends a SUBSCRIBE to force a NOTIFY 1133 containing a complete state snapshot. 1135 5.4. Event Package Responsibilities 1137 Event packages are not required to re-iterate any of the behavior 1138 described in this document, although they may choose to do so for 1139 clarity or emphasis. In general, though, such packages are 1140 expected to describe only the behavior that extends or modifies 1141 the behavior described in this document. 1143 Note that any behavior designated with "SHOULD" or "MUST" in this 1144 document is not allowed to be changed by extension documents; 1145 however, such documents may elect to strengthen "SHOULD" 1146 requirements to "MUST" strength if required by their application. 1148 In addition to the normal sections expected by "Instructions to 1149 RFC Authors" [6] and "Guidelines for Authors of SIP Extensions" 1150 [2] , authors of event packages MUST address each of the issues 1151 detailed in the following subsections, whenever applicable. 1153 5.4.1. Event Package Name 1155 This mandatory section of an event package defines the token name 1156 to be used to designate the event package. It MUST include the 1157 information which appears in the IANA registration of the token. 1158 For information on registering such types, see section 7. 1160 5.4.2. Event Package Parameters 1162 If parameters are to be used on the "Event" header to modify the 1163 behavior of the event package, the syntax and semantics of such 1164 headers must be clearly defined. 1166 5.4.3. SUBSCRIBE Bodies 1168 It is expected that most, but not all, event packages will define 1169 syntax and semantics for SUBSCRIBE method bodies; these bodies 1170 will typically modify, expand, filter, throttle, and/or set 1171 thresholds for the class of events being requested. Designers of 1172 event packages are strongly encouraged to re-use existing MIME 1173 types for message bodies where practical. 1175 This mandatory section of an event package defines what type or 1176 types of event bodies are expected in SUBSCRIBE requests (or 1177 specify that no event bodies are expected). It should point to 1178 detailed definitions of syntax and semantics for all referenced 1179 body types. 1181 5.4.4. Subscription Duration 1183 It is recommended that event packages give a suggested range of 1184 times considered reasonable for the duration of a subscription. 1185 Such packages MUST also define a default "Expires" value to be 1186 used if none is specified. 1188 5.4.5. NOTIFY Bodies 1190 The NOTIFY body is used to report state on the resource being 1191 monitored. Each package must define a what type or types of event 1192 bodies are expected in NOTIFY requests. Such packages must 1193 specify or cite detailed specifications for the syntax and 1194 semantics associated with such event body. 1196 Event packages also need to define which MIME type is to be 1197 assumed if none are specified in the "Accept" header of the 1198 SUBSCRIBE request. 1200 5.4.6. Notifier processing of SUBSCRIBE requests 1202 This section describes the processing to be performed by the 1203 notifier upon receipt of a SUBSCRIBE request. Such a section is 1204 required. 1206 Information in this section includes details of how to 1207 authenticate subscribers and authorization issues for the 1208 package. Such authorization issues may include, for example, 1209 whether all SUBSCRIBE requests for this package are answered with 1210 202 responses (see section 6.2. ). 1212 5.4.7. Notifier generation of NOTIFY requests 1214 This section of an event package describes the process by which 1215 the notifier generates and sends a NOTIFY request. This includes 1216 detailed information about what events cause a NOTIFY to be sent, 1217 how to compute the state information in the NOTIFY, how to 1218 generate "neutral" or "fake" state information to hide 1219 authorization delays and decisions from users, and whether state 1220 information is complete or deltas for notifications (see section 1221 5.3. ) 1223 It may optionally describe the behavior used to processes the 1224 subsequent response. Such a section is required. 1226 5.4.8. Subscriber processing of NOTIFY requests 1227 This section of an event package describes the process followed 1228 by the subscriber upon receipt of a NOTIFY request, including any 1229 logic required to form a coherent resource state (if applicable). 1231 5.4.9. Handling of forked requests 1233 Each event package should specify whether forked SUBSCRIBE 1234 requests are allowed to install multiple subscriptions. If such 1235 behavior is not allowed, any NOTIFY messages not matching the 1236 200-class response to the initial SUBSCRIBE message are responded 1237 to with a 481. 1239 In the case that multiple subscriptions are allowed, the event 1240 package must specify whether merging of the notifications to form 1241 a single state is required, and how such merging is to be 1242 performed. Note that it is possible that some event packages may 1243 be defined in such a way that each dialog is tied to a mutually 1244 exclusive state which is unaffected by the other dialogs; this 1245 must be clearly stated if it is the case. 1247 5.4.10. Rate of notifications 1249 Each event package is expected to define a requirement 1250 (RECOMMENDED, SHOULD or MUST strength) which defines an absolute 1251 maximum on the rate at which notifications are allowed to be 1252 generated by a single notifier. 1254 Such packages may further define a throttle mechanism which 1255 allows subscribers to further limit the rate of notification. 1257 5.4.11. State Agents 1259 Designers of event packages should consider whether their package 1260 can benefit from network aggregation points ("State Agents") 1261 and/or nodes which act on behalf of other nodes. (For example, 1262 nodes which provide state information about a resource when such 1263 a resource is unable or unwilling to provide such state 1264 information itself). An example of such an application is a node 1265 which tracks the presence and availability of a user in the 1266 network. 1268 If state agents are to be used by the package, the package must 1269 specify how such state agents aggregate information and how they 1270 provide authentication and authorization. 1272 5.4.12. Examples 1274 Event packages should include several demonstrative message flow 1275 diagrams paired with several typical, syntactically correct and 1276 complete messages. 1278 It is recommended that documents describing event packages 1279 clearly indicate that such examples are informative and not 1280 normative, with instructions that implementors refer to the main 1281 text of the draft for exact protocol details. 1283 6. Security Considerations 1285 6.1. Access Control 1287 The ability to accept subscriptions should be under the direct 1288 control of the user, since many types of events may be considered 1289 sensitive for the purposes of privacy. Similarly, the notifier 1290 should have the ability to selectively reject subscriptions based 1291 on the calling party (based on access control lists), using 1292 standard SIP authentication mechanisms. The methods for creation 1293 and distribution of such access control lists is outside the 1294 scope of this draft. 1296 6.2. Release of Sensitive Policy Information 1298 The mere act of returning a 200 or certain 4xx and 6xx responses 1299 to SUBSCRIBE requests may, under certain circumstances, create 1300 privacy concerns by revealing sensitive policy information. In 1301 these cases, the notifier should always return a 202 response. 1302 While the subsequent NOTIFY message may not convey true state, it 1303 MUST appear to contain a potentially correct piece of data from 1304 the point of view of the subscriber, indistinguishable from a 1305 valid response. Information about whether a user is authorized to 1306 subscribe to the requested state is never conveyed back to the 1307 original user under these circumstances. 1309 6.3. Denial-of-Service attacks 1311 The current model (one SUBSCRIBE request triggers a SUBSCRIBE 1312 response and one or more NOTIFY requests) is a classic setup for 1313 an amplifier node to be used in a smurf attack. 1315 Also, the creation of state upon receipt of a SUBSCRIBE request 1316 can be used by attackers to consume resources on a victim's 1317 machine, rendering it unusable. 1319 To reduce the chances of such an attack, implementations of 1320 notifiers SHOULD require authentication. Authentication issues 1321 are discussed in RFC2543 [1] . 1323 7. IANA Considerations 1325 (This section is not applicable until this document is published 1326 as an RFC.) 1328 This document defines an event-type namespace which requires a 1329 central coordinating body. The body chosen for this coordination 1330 is the Internet Assigned Numbers Authority (IANA). 1332 There are two different types of event-types: normal event 1333 packages, and event sub-packages; see section 5.2. To avoid 1334 confusion, subpackage names and package names share the same 1335 namespace; in other words, a sub-package MUST NOT share a name 1336 with a package. 1338 Following the policies outlined in "Guidelines for Writing an 1339 IANA Considerations Section in RFCs" [7] , normal event package 1340 identification tokens are allocated as First Come First Served, 1341 and event sub-package identification tokens are allocated on a 1342 IETF Consensus basis. 1344 Registrations with the IANA MUST include the token being 1345 registered and whether the token is a package or a subpackage. 1346 Further, packages MUST include contact information for the party 1347 responsible for the registration and/or a published document 1348 which describes the event package. Sub-package token 1349 registrations MUST include a pointer to the published RFC which 1350 defines the sub-package. 1352 Registered tokens to designate packages and sub-packages MUST NOT 1353 contain the character ".", which is used to separate sub-packages 1354 from packages. 1356 7.1. Registration Template 1358 As this document specifies no package or sub-package names, the 1359 initial IANA registration for event types will be empty. The 1360 remainder of the text in this section gives an example of the 1361 type of information to be maintained by the IANA; it also 1362 demonstrates all five possible permutations of package type, 1363 contact, and reference. 1365 The table below lists the event packages and sub-packages defined 1366 in "SIP-Specific Event Notification" [RFC xxxx]. Each name is 1367 designated as a package or a subpackage under "Type." 1368 Package Name Type Contact Reference 1369 ------------ ---- ------- --------- 1370 example1 package [Roach] 1371 example2 package [Roach] [RFC xxxx] 1372 example3 package [RFC xxxx] 1373 example4 sub-package [Roach] [RFC xxxx] 1374 example5 sub-package [RFC xxxx] 1376 PEOPLE 1377 ------ 1378 [Roach] Adam Roach 1380 REFERENCES 1381 ---------- 1382 [RFC xxxx] A. Roach "SIP-Specific Event Notification", RFC XXXX, 1383 August 2002. 1385 8. Open Issues 1387 In addition to the three issues listed below, the BNF in this 1388 document needs to be converted to explicit LWS to match the 1389 latest bis draft; this change will be reflected in the next 1390 version. 1392 8.1. CANCEL Handling 1394 This is actually a protocol-wide open issue which has impacts on 1395 this specification: there hasn't been a clear consensus about 1396 cancellation of non-INVITE requests yet. If non-INVITE requests 1397 cannot be cancelled, we need to remove section 4.1.3. 1399 8.2. Version of SIP to reference 1401 Much of the handling in this document is rather different than 1402 what is described in RFC2543; in fact, many of the recent changes 1403 to this document have been tracking changes in the "bis" versions 1404 of the SIP specification. We can continue to reference RFC2543 1405 while pulling in huge chunks of the bis draft for compatibility 1406 (for example, the Route handling would essentially be copied 1407 word-for-word from the bis draft), or we can start referencing 1408 the bis drafts. 1410 Of course, referencing the bis drafts allows us to pick up 1411 changes to protocol semantics "for free," while importing chunks 1412 of it requires constant maintanance and runs the risk of getting 1413 out of sync. 1415 On the other hand, placing a dependency on the bis draft pushes 1416 the timeframe for this draft (and the drafts that depend on it) 1417 out past the time that the next SIP RFC is published. 1419 8.3. Immediate NOTIFYs 1421 There has been discussion, but no consensus, on the issue of 1422 whether each SUBSCRIBE must have an immediate NOTIFY message sent 1423 in response. In attempts to follow the prevailing sentiment, this 1424 draft had become internally inconsistent. 1426 This version of this document has eliminated these 1427 inconsistancies by requiring notifiers always to send a NOTIFY 1428 immediately upon receiving a SUBSCRIBE. This decision does not 1429 necessarily represent group consensus, and further discussion may 1430 be warranted. 1432 9. Changes 1434 9.1. Changes from draft-ietf-...-00 1436 - Fixed confusing typo in section describing correlation 1437 of SUBSCRIBE requests 1439 - Added explanitory text to clarify tag handling when 1440 generating re-subscriptions 1442 - Expanded general handling section to include specific 1443 discussion of Route/Record-Route handling. 1445 - Included use of "methods" parameter on Contact as 1446 a means for detecting support for SUBSCRIBE and NOTIFY. 1448 - Added definition of term "dialog"; changed "leg" to 1449 "dialog" everwhere. 1451 - Added syntax for "Subscription-Expires" header. 1453 - Changed NOTIFY messages to refer to "Subscription-Expires" 1454 everywhere (instead of "Expires.") 1456 - Added information about generation and handling of 1457 481 responses to SUBSCRIBE requests 1459 - Changed having Expires header in SUBSCRIBE from 1460 MUST to SHOULD; this aligns more closely with 1461 REGISTER behavior 1463 - Removed experimental/private event package names, 1464 per list consensus 1466 - Cleaned up some legacy text left over from very early 1467 drafts that allowed multiple contacts per subscription 1469 - Strengthened language requiring the removal of subscriptions 1470 if a NOTIFY request fails with a 481. Clarified that such 1471 removal is required for all subscriptions, including 1472 administrative ones. 1474 - Removed description of delaying NOTIFY requests until 1475 authorization is granted. Such behavior was inconsistent 1476 with other parts of this document. 1478 - Moved description of event packages to later in document, 1479 to reduce the number of forward references. 1481 - Minor editorial and nits changes 1483 - Added new open issues to open issues section. All 1484 previous open issues have been resolved. 1486 9.2. Changes from draft-roach-...-03 1488 - Added DOS attacks section to open issues. 1490 - Added discussion of forking to open issues 1492 - Changed response to PINT request for notifiers who don't 1493 support PINT from 400 to 489. 1495 - Added sentence to security section to call attention to 1496 potential privacy issues of delayed NOTIFY responses. 1498 - Added clarification: access control list handling is out 1499 of scope. 1501 - (Hopefully) Final resolution on out-of-band subscriptions: 1502 mentioned in section 1503 4.3. 1504 Removed from open issues. 1506 - Made "Contact" header optional for SUBSCRIBE 1xx responses. 1508 - Added description clarifying tag handling (section 1509 4.2.1. 1510 ) 1512 - Removed event throttling from open issues. 1514 - Editorial cleanup to remove term "extension draft" and 1515 similar; "event package" is now (hopefully) used consistently 1516 throughout the document. 1518 - Remove discussion of event agents from open issues. 1519 This is covered in the event packages section now. 1521 - Added discussion of forking to open issues. 1523 - Added discussion of sub-packages 1525 - Added clarification that, upon receiving a "NOTIFY" 1526 with an expires of "0", the subscriber can re-subscribe. 1527 This allows trivial migration of subscriptions between 1528 nodes. 1530 - Added preliminary IANA Considerations section 1531 - Changed syntax for experimental event tokens to avoid 1532 possibly ambiguity between experimental tokens and 1533 sub-packages. 1535 - Slight adjustment to "Event" syntax to accommodate sub-packages. 1537 - Added section describing the information which is to be 1538 included in documents describing event packages. 1540 - Made 481 responses mandatory for unexpected notifications 1541 (allowing notifiers to remove subscriptions in error cases) 1543 - Several minor non-semantic editorial changes. 1545 9.3. Changes from draft-roach-...-02 1547 - Clarification under "Notifier SUBSCRIBE behavior" which 1548 indicates that the first NOTIFY message (sent immediately 1549 in response to a SUBSCRIBE) may contain an empty body, if 1550 resource state doesn't make sense at that point in time. 1552 - Text on message flow in overview section corrected 1554 - Removed suggestion that clients attempt to unsubscribe 1555 whenever they receive a NOTIFY for an unknown event. 1556 Such behavior opens up DOS attacks, and will lead to 1557 message loops unless additional precautions are taken. 1558 The 481 response to the NOTIFY should serve the same 1559 purpose. 1561 - Changed processing of non-200 responses to NOTIFY from 1562 "SHOULD remove contact" to "MUST remove contact" to support 1563 the above change. 1565 - Re-added discussion of out-of-band subscription mechanisms 1566 (including open issue of resource identification). 1568 - Added text specifying that SUBSCRIBE transactions are not 1569 to be prolonged. This is based on the consensus that non-INVITE 1570 transactions should never be prolonged; such consensus within 1571 the SIP working group was reached at the 49th IETF. 1573 - Added "202 Accepted" response code to support the above 1574 change. The behavior of this 202 response code is a 1575 generalization of that described in the presence draft. 1577 - Updated to specify that the response to an unauthorized 1578 SUBSCRIBE request is 603 or 403. 1580 - Level-4 subheadings added to particularly long sections to 1581 break them up into logical units. This helps make the 1582 behavior description seem somewhat less rambling. This also 1583 caused some re-ordering of these paragraphs (hopefully in a 1584 way that makes them more readable). 1586 - Some final mopping up of old text describing "call related" 1587 and "third party" subscriptions (deprecated concepts). 1589 - Duplicate explanation of subscription duration removed from 1590 subscriber SUBSCRIBE behavior section. 1592 - Other text generally applicable to SUBSCRIBE (instead of just 1593 subscriber handling of SUBSCRIBE) moved to parent section. 1595 - Updated header table to reflect mandatory usage of "Expires" 1596 header in SUBSCRIBE requests and responses 1598 - Removed "Event" header usage in responses 1600 - Added sentence suggesting that notifiers may notify 1601 subscribers when a subscription has timed out. 1603 - Clarified that a failed attempt to refresh a subscription 1604 does not imply that the original subscription has been 1605 cancelled. 1607 - Clarified that 489 is a valid response to "NOTIFY" requests. 1609 - Minor editorial changes to clean up awkward and/or unclear 1610 grammar in several places 1612 9.4. Changes from draft-roach-...-01 1614 - Multiple contacts per SUBSCRIBE message disallowed. 1616 - Contact header now required in NOTIFY messages. 1618 - Distinction between third party/call member events removed. 1620 - Distinction between call-related/resource-related events removed. 1622 - Clarified that subscribers must expect NOTIFY messages before 1623 the SUBSCRIBE transaction completes 1625 - Added immediate NOTIFY message after successful SUBSCRIBE; 1626 this solves a myriad of issues, most having to do with forking. 1628 - Added discussion of "undefined state" (before a NOTIFY arrives). 1630 - Added mechanism for notifiers to shorten/cancel outstanding 1631 subscriptions. 1633 - Removed open issue about appropriateness of new "489" response. 1635 - Removed all discussion of out-of-band subscriptions. 1637 - Added brief discussion of event state polling. 1639 10. References 1641 [1] M. Handley/H. Schulzrinne/E. Schooler/J. Rosenberg, "SIP: 1642 Session Initiation Protocol", RFC 2543, IETF; March 1999. 1644 [2] J. Rosenberg, H. Schulzrinne, "Guidelines for Authors of SIP 1645 Extensions", , IETF; March 1646 2001. Work in progress. 1648 [3] S. Petrack, L. Conroy, "The PINT Service Protocol", RFC 2848, 1649 IETF; June 2000. 1651 [4] J. Rosenberg et. al., "SIP Extensions for Presence", 1652 , IETF; September 2001. 1653 Work in progress. 1655 [5] R. Fielding et. al., "Hypertext Transfer Protocol -- 1656 HTTP/1.1", RFC2068, IETF, January 1997. 1658 [6] J. Postel, J. Reynolds, "Instructions to RFC Authors", 1659 RFC2223, IETF, October 1997. 1661 [7] T. Narten, H. Alvestrand, "Guidelines for Writing an IANA 1662 Considerations Section in RFCs", BCP 26, IETF, October 1998. 1664 [8] Schulzrinne/Rosenberg, "SIP Caller Preferences and Callee 1665 Capabilities", , IETF; 1666 June 2001. Work in progress. 1668 11. Acknowledgements 1670 Thanks to the participants in the Events BOF at the 48th IETF 1671 meeting in Pittsburgh, as well as those who gave ideas and 1672 suggestions on the SIP Events mailing list. In particular, I wish 1673 to thank Henning Schulzrinne of Columbia University for coming up 1674 with the final three-tiered event identification scheme, Sean 1675 Olson of Ericsson for miscellaneous guidance, Jonathan Rosenberg 1676 for a thorough scrubbing of the -00 draft, and the authors of the 1677 "SIP Extensions for Presence" draft for their input to SUBSCRIBE 1678 and NOTIFY request semantics. 1680 12. Author's Address 1682 Adam Roach 1683 Ericsson Inc. 1684 Mailstop L-04 1685 740 E. Campbell Rd. 1686 Richardson, TX 75081 1687 USA 1688 Phone: +1 972 583 7594 1689 Fax: +1 972 669 0154 1690 E-Mail: adam.roach@ericsson.com