RFC 3265 SIP-Specific Event Notification SIP-Specific Event Notification is to provide an extensible framework by which SIP nodes can request notification from remote nodes indicating that certain events have occurred. Examples of such services include: automatic callback services (based on terminal state events) buddy lists (based on user presence events) message waiting indications (based on mailbox state change events) PSTN and Internet Internetworking (PINT) [2] status (based on call state events). Note, however, that event packages based on this framework may define arbitrarily elaborate rules which govern the subscription and notification for the events or classes of events they describe. 1 Definitions 1.1 Event Package An event package is an additional specification which defines a set of state information to be reported by a notifier to a subscriber. Event packages also define further syntax and semantics based on the framework defined by this document required to convey such state information. 1.2 Event Template-Package An event template-package is a special kind of event package which defines a set of states which may be applied to all possible event packages, including itself. 1.3 Notification Notification is the act of a notifier sending a NOTIFY message to a subscriber to inform the subscriber of the state of a resource. 1.4 Notifier A notifier is a user agent which generates NOTIFY requests for the purpose of notifying subscribers of the state of a resource. Notifiers typically also accept SUBSCRIBE requests to create subscriptions. 1.5 State Agent A state agent is a notifier which publishes state information on behalf of a resource; in order to do so, it may need to gather such state information from multiple sources. State agents always have complete state information for the resource for which they are creating notifications. 1.6 Subscriber A subscriber is a user agent which receives NOTIFY requests from notifiers; these NOTIFY requests contain information about the state of a resource in which the subscriber is interested. Subscribers typically also generate SUBSCRIBE requests and send them to notifiers to create subscriptions. 1.7 Subscription A subscription is a set of application state associated with a dialog. This application state includes a pointer to the associated dialog, the event package name, and possibly an identification token. Event packages will define additional subscription state information. By definition, subscriptions exist in both a subscriber and a notifier. 1.8 Subscription Migration Subscription migration is the act of moving a subscription from one notifier to another notifier. 2 Subscription Duration 2.1 Determine Subscription Duration The subscription duration, in the other word the length of subscription timeout, is finally determined by "Expires" header value of 200-class response to the first SUBSCRIBE request of that event. This value is no more than the value of "Expires" header in the SUBSCRIBE request, if there is an "Expires" header. Or, it is no more than the default value. 2.2 Unsubscribe Subscriber as sponsor: The subscriber MUST sending a SUBSCRIBE request with an "Expires" of 0. While the notifier receiving this un-SUBSCRIBE, he should send a NOTIFY with the "Subscription- State" of "terminated" and "reason=timeout". The Subscriber should wait for this NOTIFY, and take it as the successful flag of unsubscribe. ? How long should the subscriber wait for the NOTIFY? Or what to do if there is only a 200 response to un-SUBSCRIBE but isn't any NOTIFY? Notifier as sponsor: The notifier MUST send a NOTIFY request with the "Subscription-State" of "terminated". 2.3 Expires Header SUBSCRIBE requests SHOULD contain an "Expires" header. This expires value indicates the duration of the subscription. In order to keep subscriptions effective beyond the duration communicated in the "Expires" header, subscribers need to refresh subscriptions on a periodic basis using a new SUBSCRIBE message on the same dialog as defined in SIP. If no "Expires" header is present in a SUBSCRIBE request, the implied default is defined by the event package being used. 200-class responses to SUBSCRIBE requests also MUST contain an "Expires" header. The period of time in the response MAY be shorter but MUST NOT be longer than specified in the request. The period of time in the response is the one which defines the duration of the subscription. An "expires" parameter on the "Contact" header has no semantics for SUBSCRIBE and is explicitly not equivalent to an "Expires" header in a SUBSCRIBE request or response. 3 Subscriber Behavior 3.1 Requesting A Subscription SUBSCRIBE is a dialog-creating method. When a subscriber wishes to subscribe to a particular state for a resource, it forms a SUBSCRIBE message. If the initial SUBSCRIBE represents a request outside of a dialog (as it typically will), its construction follows the procedures outlined in SIP for UAC request generation outside of a dialog. This SUBSCRIBE request will be confirmed with a final response. 200- class responses indicate that the subscription has been accepted, and that a NOTIFY will be sent immediately. 3.2 Refreshing of Subscription At any time before a subscription expires, the subscriber may refresh the timer on such a subscription by sending another SUBSCRIBE request on the same dialog as the existing subscription, and with the same "Event" header "id" parameter (if one was present in the initial subscription). re-SUBSCRIBE: 1. on the same dialog 2. with the same "Event" header 3. the same "id" parameter of "Event" header 481 response: It means the subscription is invalid. If the subscriber wants to re-SUBSCRIBE the event, he should compose a new SUBSCRIBE request with new Call-ID and new From-Tag. non-481 response: It means the subscription is still valid, until the "Expire" of most recently 200-class response to SUBSCRIBE request, or the "expires" parameter in the "Subscription-State" of NOTIFY. 3.3 Unsubscribing Unsubscribing is handled in the same way as Refreshing of Subscription, with the "Expires" header set to "0". Note that a successful unsubscribe will also trigger a final NOTIFY message. 3.4 Confimation of Subscription Creation/Refreshing Only after received the first NOTIFY, the subscriber can consider the creation or refreshing of a subscription has been taken place successfully. The state of subscription should be in a neutral state before the first NOTIFY arrives. Documents which define new event packages MUST define this "neutral state" in such a way that makes sense for their application (see section 4.4.7.). The subscriber MUST be prepared to receive NOTIFY messages before the SUBSCRIBE transaction has completed. It means the NOTIFY to the SUBSCRIBE request may arrive before the 200-class response to the SUBSCRIBE request. 3.5 Received a NOTIFY Upon receiving a NOTIFY request, the subscriber should check that it matches at least one of its outstanding subscriptions; if not, it MUST return a "481 Subscription does not exist" response unless another 400- or 500-class response is more appropriate. Notifications for subscriptions which were created inside an existing dialog match if they are in the same dialog and the "Event" headers match. To prevent spoofing of events, NOTIFY requests SHOULD be authenticated, using any defined SIP authentication mechanism. 3.5.1 200 OK The notification is acceptable to the subscriber. 3.5.2 481 Subscription does not exist The NOTIFY doesn't match any subscriptions. 3.5.3 489 Bad Event The NOTIFY "Event" header is not supported. 3.5.4 Subscription-State This header MUST be contain in NOTIFY. active: the subscription has been accepted and has been authorized "expires": subscriber SHOULD take it as the authoritative subscription duration and adjust accordingly "retry-after": no semantics "reason": no semantics pending: the subscription has been received by the notifier, but there is insufficient policy information to grant or deny the subscription yet "expires": subscriber SHOULD take it as the authoritative subscription duration and adjust accordingly "retry-after": no semantics "reason": no semantics terminated: the subscriber should consider the subscription terminated "expires": no semantics "retry-after": the client SHOULD NOT attempt re-subscription until after the number of seconds specified by this parameter "reason": "deactivated": The subscription has been terminated, but the subscriber SHOULD retry immediately with a new subscription. use for migration of subscriptions "retry-after": no semantics "probation": The subscription has been terminated, but the client SHOULD retry at some later time. "retry-after": have semantics "rejected": subscription authorization failed the client SHOULD NOT attempt to re-subscirbe "retry-after": no semantics "timeout": The subscription was not refreshed before it expired. Clients MAY re-subscribe immediately. "retry-after": no semantics "giveup": the notifier could not obtain authorization in a timely fashion. "retry-after": have semantics "noresource": the resource state which was being monitored no longer exists. Clients SHOULD NOT attempt to re- subscribe. "retry-after": no semantics 4 Notifier behavior 4.1 General When a SUBSCRIBE request is answered with a 200-class response, the notifier MUST immediately construct and send a NOTIFY request to the subscriber. When a change in the subscribed state occurs, the notifier SHOULD immediately construct and send a NOTIFY request, subject to authorization, local policy, and throttling considerations. A NOTIFY request is considered failed if the response times out, or a non-200 class response code is received which has no "Retry-After" header and no implied further action which can be taken to retry the request (e.g., "401 Authorization Required".) Fail Reason SUBSCRIBE non-SUBSCRIBE ----------- --------- ------------- timeout remove error response remove 481 response remove remove SUBSCRIBE: The subscription is established by soft-state mechanism, such as SUBSCRIBE. non-SUBSCRIBE: The subsciption is established non-SUBSCRIBE means, such as an administrative interface. 4.2 Initial SUBSCRIBE Transaction Processing Notifiers MUST NOT wait for a user response before returning a final response to a SUBSCRIBE request. This requirement is imposed primarily to prevent the non-INVITE transaction timeout timer F from firing during the SUBSCRIBE transaction, since interaction with a user would often exceed 64*T1 seconds. The notifier SHOULD also perform any necessary authentication and authorization per its local policy. 4.2.1 200 OK The subsciption has been accepted and the user is authorized. The notifier create the subscription and store the the event package name and the "Event" header "id" parameter. "Expires" indicate the timeout of the subsciption. 4.2.2 202 Accepted The subsciption has just been accepted (authorization is in pending state). The notifier cannot immediately create the subscription (e.g., it needs to wait for user input for authorization, or is acting for another node which is not currently reachable), or wishes to mask authorization policy. 4.2.3 489 Bad Event It means the "Event" header in SUBSCRIBE request is not understood. 4.2.4 423 Interval Too Brief It means the "Expires" in SUBSCRIBE is too small and the response contains a "Min-Expires" header field. 4.3 Confirmation of Subscription Creation/Refreshing Note that a NOTIFY message is always sent immediately after any 200- class response to a SUBSCRIBE request, regardless of whether the subscription has already been authorized. If the duration specified in a SUBSCRIBE message is unacceptably short, the notifier SHOULD respond with a "423 Interval Too Brief" message. When a notifier receives a subscription refresh, assuming that the subscriber is still authorized, the notifier updates the expiration time for the subscription. (The "Expires" header is check as initial SUBSCRIBE) If no refresh before subscription timeout, the notifier removes the subscription, and sending a NOTIFY with "Subscription-State" of "terminated" and it's parameter is "reason=timeout". 4.4 NOTIFY When a SUBSCRIBE request is answered with a 200-class response, the notifier MUST immediately construct and send a NOTIFY request to the subscriber. When a change in the subscribed state occurs, the notifier SHOULD immediately construct and send a NOTIFY request, subject to authorization, local policy, and throttling considerations. NOTIFY requests MUST contain a "Subscription-State" header with a value of "active", "pending", or "terminated". 5 Proxy Behavior Proxies need no additional behavior beyond that described in SIP to support SUBSCRIBE and NOTIFY. If a proxy wishes to see all of the SUBSCRIBE and NOTIFY requests for a given dialog, it MUST record- route the initial SUBSCRIBE and any dialog-establishing NOTIFY and NOTIFY requests. Note that subscribers and notifiers may elect to use S/MIME encryption of SUBSCRIBE and NOTIFY requests; consequently, proxies cannot rely on being able to access any information that is not explicitly required to be proxy-readable by SIP. 6 General 6.1 Detecting support for SUBSCRIBE and NOTIFY The "Allow-Events" header in a message is sufficient to indicate support for SUBSCRIBE and NOTIFY. If necessary, clients may probe for the support of SUBSCRIBE and NOTIFY using the OPTIONS request defined in SIP. 6.2 CANCEL request No semantics are associated with cancelling SUBSCRIBE or NOTIFY. 6.3 Forking Each event package MUST specify whether forked SUBSCRIBE requests are allowed to install multiple subscriptions. 6.3.1 Not Allowed by Event Package The first potential dialog-establishing message will create a dialog. All subsequent NOTIFY messages which correspond to the SUBSCRIBE message (i.e., match "To", "From", "From" header "tag" parameter, "Call-ID", "CSeq", "Event", and "Event" header "id" parameter) but which do not match the dialog would be rejected with a 481 response. While the 200-class response to the SUBSCRIBE arriving after a matching NOTIFY has been received, the dialog-matching response is used to complete the SUBSCRIBE transaction, ignored the others. 6.3.2 Allowed by Evnet Package The subscriber establishes a new dialog towards each notifier by returning a 200-class response to each NOTIFY. Each dialog is then handled as its own entity, and is refreshed independent of the other dialogs. The event package MUST specify whether merging of the notifications to form a single state is required, and how such merging is to be performed. In the other word, the event package MUST define if the state of each dialog is affected by others. 6.4 Dialog Creation and Termination 6.4.1 Dialog Creation If an initial SUBSCRIBE request is not sent on a pre-existing dialog, the subscriber will wait for a response to the SUBSCRIBE request or a matching NOTIFY. Responses are matched to such SUBSCRIBE requests if they contain the same the same "Call-ID", the same "From" header "tag", and the same "CSeq". If a 200-class response matches such a SUBSCRIBE request, it creates a new subscription and a new dialog (unless they have already been created by a matching NOTIFY request; see below). NOTIFY requests are matched to such SUBSCRIBE requests if they contain the same "Call-ID", a "To" header "tag" parameter which matches the "From" header "tag" parameter of the SUBSCRIBE, and the same "Event" header field. If a matching NOTIFY request contains a "Subscription-State" of "active" or "pending", it creates a new subscription and a new dialog (unless they have already been created by a matching response, as described above). If an initial SUBSCRIBE is sent on a pre-existing dialog, a matching 200-class response or successful NOTIFY request merely creates a new subscription associated with that dialog. Multiple subscriptions can be associated with a single dialog. Subscriptions may also exist in dialogs associated with INVITE- created application state and other application state created by mechanisms defined in other specifications. These sets of application state do not interact beyond the behavior described for a dialog (e.g., route set handling). 6.4.2 Dialog Termination A subscription is destroyed when a notifier sends a NOTIFY request with a "Subscription-State" of "terminated". A subscriber may send a SUBSCRIBE request with an "Expires" header of 0 in order to trigger the sending of such a NOTIFY request; however, for the purposes of subscription and dialog lifetime, the subscription is not considered terminated until the NOTIFY with a "Subscription-State" of "terminated" is sent. If a subscription's destruction leaves no other application state associated with the dialog, the dialog terminates. The destruction of other application state (such as that created by an INVITE) will not terminate the dialog if a subscription is still associated with that dialog. Note that the above behavior means that a dialog created with an INVITE does not necessarily terminate upon receipt of a BYE. Similarly, in the case that several subscriptions are associated with a single dialog, the dialog does not terminate until all the subscriptions in it are destroyed. 6.5 State Agents and Notifier Migration Migration may be effected by sending a NOTIFY message with a "Subscription-State" header of "terminated", and a reason parameter of "deactivated". Upon receipt of this NOTIFY message, the subscriber SHOULD attempt to re-subscribe . Note that this subscription is established on a new dialog, and does not re-use the route set from the previous subscription dialog. 6.6 Polling Resource State While the subscriber wish to polling resource state, it will send a SUBSCRIBE request. If there is a persistent subscription, the "Expires" equals to number of seconds remaining in the subscription. If there isn't a persistent subscription, the "Expires" is 0. Upon receipt of this SUBSCRIBE request, the notifier (or notifiers, if the SUBSCRIBE request was forked) will send a NOTIFY request containing resource state in the same dialog. Polling SHOULD NOT be used in circumstances in which it will typically result in more network messages than long-running subscriptions. When polling is used, subscribers SHOULD attempt to cache authentication credentials between polls so as to reduce the number of messages sent. 6.7 Allow-Events Header Usage Any node implementing one or more event packages SHOULD include an appropriate "Allow-Events" header indicating all supported events in all methods which initiate dialogs and their responses (such as INVITE) and OPTIONS responses. Note that "Allow-Events" headers MUST NOT be inserted by proxies. 6.8 PINT Compatibility The "Event" header is considered mandatory for SUBSCRIBE and NOTIFY. However, to maintain compatibility with PINT, servers MAY interpret a SUBSCRIBE request with no "Event" header as requesting a subscription to PINT events. If a server does not support PINT, it SHOULD return "489 Bad Event" to any SUBSCRIBE messages without an "Event" header. 7 Event Packages 7.1 Appropriateness of Usage Is SIP an appropriate mechanism for the problem set? Is SIP being selected because of some unique feature provided by the protocol (e.g., user mobility), or merely because "it can be done?" This mechanism is not to be used in applications where the frequency of reportable events is excessively rapid (e.g., more than about once per second). 7.2 Event Template-packages Event template-packages are a special type of package which define a set of state applied to other packages, such as statistics, access policy, and subscriber lists. Event template-packages may even be applied to other event template-packages. For example, if a template-package called "winfo" were being applied to a package called "presence", the event token used in "Event" and "Allow-Events" would be "presence.winfo". 7.3 Amount of State to be Conveyed 7.3.1 Complete State Information For packages which typically convey state information that is reasonably small (on the order of 1 kb or so). In some circumstances, conveying the current state alone may be insufficient for a particular class of events. In these cases, the event packages should include complete state information along with the event that occurred. 7.3.2 State Deltas In the case that the state information to be conveyed is large. Any NOTIFY sent in immediate response to a SUBSCRIBE contains full state information. NOTIFY messages sent because of a state change will contain only the state information that has changed; the subscriber will then merge this information into its current knowledge about the state of the resource. Any event package that supports delta changes to states MUST include a version number that increases by exactly one for each NOTIFY transaction in a subscription. Note that the state version number appears in the body of the message, not in a SIP header. If a NOTIFY arrives that has a version number that is incremented by more than one, the subscriber knows that a state delta has been missed; it ignores the NOTIFY message containing the state delta (except for the version number, which it retains to detect message loss), and re-sends a SUBSCRIBE to force a NOTIFY containing a complete state snapshot. 7.4 Event Package Responsibilities 7.4.1 Identification of Events Identification of events is provided by three pieces of information: Request URI, Event Type, and (optionally) message body. Request URI --- who Event Type --- what "id" parameter is used to identify the subscriptions in one dialog which have the same type message body --- behavior information of event package 7.4.2 Event Package Name This section, which MUST be present, defines the token name to be used to designate the event package. It MUST include the information which appears in the IANA registration of the token. 7.4.3 Event Package Parameters If parameters are to be used on the "Event" header to modify the behavior of the event package, the syntax and semantics of such headers MUST be clearly defined. 7.4.4 SUBSCRIBE Bodies It is expected that most, but not all, event packages will define syntax and semantics for SUBSCRIBE method bodies; these bodies will typically modify, expand, filter, throttle, and/or set thresholds for the class of events being requested. Designers of event packages are strongly encouraged to re-use existing MIME types for message bodies where practical. 7.4.5 Subscription Duration It is RECOMMENDED that event packages give a suggested range of times considered reasonable for the duration of a subscription. Such packages MUST also define a default "Expires" value to be used if none is specified. 7.4.6 NOTIFY Bodies The NOTIFY body is used to report state on the resource being monitored. Each package MUST define what type or types of event bodies are expected in NOTIFY requests. Such packages MUST specify or cite detailed specifications for the syntax and semantics associated with such event body. Event packages also MUST define which MIME type is to be assumed if none are specified in the "Accept" header of the SUBSCRIBE request. 7.4.7 Notifier processing of SUBSCRIBE requests This section describes the processing to be performed by the notifier upon receipt of a SUBSCRIBE request. Such a section is required. Information in this section includes details of how to authenticate subscribers and authorization issues for the package. Such authorization issues may include, for example, whether all SUBSCRIBE requests for this package are answered with 202 responses (see section 5.2.). 7.4.8 Notifier generation of NOTIFY requests This section of an event package describes the process by which the notifier generates and sends a NOTIFY request. This includes detailed information about what events cause a NOTIFY to be sent, how to compute the state information in the NOTIFY, how to generate neutral or fake state information to hide authorization delays and decisions from users, and whether state information is complete or deltas for notifications; see section 4.3. Such a section is required. This section may optionally describe the behavior used to process the subsequent response. 7.4.9 Subscriber processing of NOTIFY requests This section of an event package describes the process followed by the subscriber upon receipt of a NOTIFY request, including any logic required to form a coherent resource state (if applicable). 7.4.10 Handling of forked requests As described in Forking of General 7.4.11 Rate of notifications Each event package SHOULD or MUST defines an absolute maximum on the rate at which notifications are allowed to be generated by a single notifier. Each package MAY further define a throttle mechanism which allows subscribers to further limit the rate of notification. 7.4.12 State Agents If state agents are to be used by the package, the package MUST specify how such state agents aggregate information and how they provide authentication and authorization. Event packages MAY also outline specific scenarios under which notifier migrations take place. 7.4.13 Examples Event packages SHOULD include several demonstrative message flow diagrams paired with several typical, syntactically correct, and complete messages. It is RECOMMENDED that documents describing event packages clearly indicate that such examples are informative and not normative, with instructions that implementors refer to the main text of the document for exact protocol details. 7.4.14 Use of URIs to Retrieve State Some types of event packages may define state information which is potentially too large to reasonably send in a SIP message. To alleviate this problem, event packages may include the ability to convey a URI instead of state information; this URI will then be used to retrieve the actual state information. 8 Security Considerations See RFC3265 Section 5 Security Considerations 9 IANA Considerations See RFC3265 Section 6 IANA Considerations