Internet Engineering Task Force Adam Roach Internet Draft Ericsson Inc. Category: Standards Track March 2000 Expires September 2000 Event Notification in SIP Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or cite them other than as "work in progress". The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/lid-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html This document is an individual submission to the IETF. Comments should be directed to the authors. Abstract This document describes an extension to the Session Initiation Protocol (SIP) [1] . The purpose of this extension is to provide a generic and extensible framework by which SIP nodes can request notification from remote nodes indicating that certain events have occured. Concrete uses of the mechanism described in this document may be standardized in the future. 1. Introduction The ability to request asynchronous notification of events proves useful in many types of services for which cooperation between end-nodes is required. An example of such a service is defined in "Automatic Call Back Service in SIP" [2] . The methods described in this document allow a framework by which notification of these events can be ordered. Roach [Page 1] Internet Draft Event Notification in SIP March 2000 2. New Methods This document describes two new SIP methods: "SUBSCRIBE" and "NOTIFY." Note that these methods have been defined elsewhere. This document attempts, as much as possible, to remain compatible with those proposals; however, some minor adjustments may be necessary due to the marked lack of extensibility present in other existing drafts. This table expands on tables 4 and 5 in RFC 2543 [1] . Roach [Page 2] Internet Draft Event Notification in SIP March 2000 Header Where SUB NTFY ------ ----- --- ---- Accept R o o Accept-Encoding R o o Accept-Language R o o Allow 200 - - Allow 405 o o Authorization R o o Call-ID gc m m Contact R o o Contact 1xx - - Contact 2xx - - Contact 3xx - - Contact 485 - - Content-Encoding e o o Content-Length e o o Content-Type e * * CSeq gc m m Date g o o Encryption g o o Event R m m Event r m - Expires g m - From gc m m Hide R o o Max-Forwards R o o Organization g o o Priority R o o Proxy-Authenticate 407 o o Proxy-Authorization R o o Proxy-Require R o o Require R o o Retry-After R - - Retry-After 404,480,486 o o Retry-After 503 o o Retry-After 600,603 o o Response-Key R o o Record-Route R o o Record-Route 2xx o o Route R o o Server r o o Subject R o o Timestamp g o o To gc(1) m m Unsupported 420 o o User-Agent g o o Via gc(2) m m Warning r o o WWW-Authenticate 401 o o Roach [Page 3] Internet Draft Event Notification in SIP March 2000 2.1. SUBSCRIBE method "SUBSCRIBE" is added to the definition of the element "Method" in the SIP message grammar. The SUBSCRIBE method is used to request notification of an event or set of events at a later time. 2.2. NOTIFY method "NOTIFY" is added to the definition of the element "Method" in the SIP message grammar. The NOTIFY method is used to notify a SIP node that an event which has been requested by an eariler SUBSCRIBE method has occured. It may also provide further details about the event. 3. New "Event" header The following header is added for the purposes of this extension. Event = "Event" ":" 1#event-type event-type = token Event is added to the definition of the element "general-header" in the SIP message grammar. This document does not define values for event-types. These values will be defined in further extensions that take advantage of the SUBCRIBE and NOTIFY methods. 4. Node Behavior Unless noted otherwise, call-member SUBSCRIBE and NOTIFY requests follow the same protocol rules governing the usage of tags, Route, Record-Route, retransmission, reliability, CSeq handling, and message formatting as those defined in RFC 2543 [1] for BYE. Similarly, unless noted otherwise, third-party SUBSCRIBE and NOTIFY requests follow the same protocol rules as those defined in RFC 2543 [1] for OPTIONS. For the purposes of generality, both SUBSCRIBE and NOTIFY MAY be canceled; however, doing so is not recommended. Sucessfully cancelled SUBSCRIBE and NOTIFY requests MUST be completed with a "487 Request Cancelled" response; the server acts as if the request were never received. Roach [Page 4] Internet Draft Event Notification in SIP March 2000 SUBSCRIBE and NOTIFY have two slightly different uses: (1) subscription to and notification of events by nodes which are involved in an ongoing call with the node from which notification is being ordered, and (2) subscription to and notification of events by nodes which are not actively involved as an endpoint in an ongoing call with the node from which notification is being ordered. For the purposes of brevity, these situations will be refered to as "call-member" and "third-party" respectively. Further, third-party SUBSCRIBE and NOTIFY requests may relate to call-related events (e.g. call-terminated) or resource-related events (e.g. terminal-free). 4.1. SUBSCRIBE 4.1.1. Correlation to legs, calls, and terminals Call-member SUBSCRIBE requests will be correlated in the same way that any other call-related request is (e.g. BYE) using To, From, and Call-ID; these subscriptions will generally be used to request information about the specific call. Third-party SUBSCRIBE requests will not correlate to any existing call leg in the server. The Call-ID of resource-related requests will be unique to the SUBSCRIBE and any subsequent NOTIFY requests. Third-party SUBSCRIBE requests may also request information about call-related events by specifying a Call-ID that is known to have significance to the UAS. Proxies in the call-setup path may obtain this Call-ID by examining the messages they proxy; other methods of obtaining the Call-ID of an ongoing call are outside the scope of this document. Note that third-party subscriptions have security implications; see section 7. 4.1.2. Subscription duration All SUBSCRIBE requests are required to contain an "Expires" header. This header specifies for how long the subscription is to remain in effect. The 200 response to a SUBSCRIBE request also MUST contain an "Expires" header. The period of time in the response MAY be shorter than specified in the request, but MUST NOT be longer. The period of time in the response is the one which defines the duration of the subscription. Simlar to REGISTER requests, SUBSCRIBE requests may be renewed at any time to prevent them from expiring at the end of the "Expires" period. These renewals will contain a the same "To," Roach [Page 5] Internet Draft Event Notification in SIP March 2000 "From," and "Call-ID" as the original request, and an incremented "CSeq" number. Subscriptions may similarly be cancelled by re-issuing them with an "Expires: 0" header. Further, call-related SUBSCRIBE requests (as opposed to resource-related) are automatically expired at the end of the call to which they relate (from the point of view of the device receiving the SUBSCRIBE request), regardless of the "Expire" values in the SUBSCRIBE response. 4.1.3. Events being requested SUBSCRIBE requests contain one or more events to which the client is attempting to subscribe; these events are listed in the "Event" header (see section 3. ). If the server being contacted understands the SUBSCRIBE mechanism and is willing to provide the types of notification being requested, it will respond with a "200 OK." This response will also contain an "Event" header, specifying of which events the client will be notified. Note that this list will be a subset of the events listed in the SUBSCRIBE request. Events that the server does not understand or is unwilling to provide notification for MUST NOT appear in the response. Responses of 400+ to a SUBSCRIBE request should not be considered fatal by the UAC; behaviour will be the same as if a blank "Event" header were included in a 200 response (i.e. no events have been sucessfully subscribed). The "Event" header is considered mandatory for the purposes of this document. However, to maintain compatibility with existing, non-extensible drafts which also make use of SUBSCRIBE, servers MAY interpret a SUBSCRIBE request with no "Event" header as requesting a subscription to all the events the server is willing to report. They MAY alternately return "400 Bad Request." 4.2. NOTIFY 4.2.1. Correlation NOTIFY requests MUST contain the same Call-ID, local URI, and remote URI as the SUBSCRIBE request which ordered them. This is the same definition as a call leg. 4.2.2. Events being reported NOTIFY requests will contain an "Event" header with a single event-type listed. This event-type will specify which subscribed event is being reported. Note that sending a NOTIFY does not cancel the SUBSCRIBE which requested it; in other words, a single Roach [Page 6] Internet Draft Event Notification in SIP March 2000 SUBSCRIBE request may trigger several NOTIFY requests. Further parameters relating to the event specified in the NOTIFY request may be present, as additional headers, in the body, or both. The specification of the syntax for these additional parameters is outside the scope of this document. 4.3. SIP User Agent Behavior User Agent Clients (UACs) are allowed to initiate both call-member and third-party SUBSCRIBE requests. Upon receipt of a SUBSCRIBE request, servers have the option of confirming the request (200 OK) or rejecting it (403 Forbidden). The other values defined in RFC 2543 [1] are also allowed, as appropriate. 4.4. SIP Proxy Behavior Note that, due to CSeq space collisions, proxies are not allowed to initiate call-member SUBSCRIBE requests. They can, however, initiate third-party SUBSCRIBE requests to existing calls; they would do so by including the Call-ID of an ongoing call. The "From:" field in this case, however, would indicate an address owned by the proxy, and thus be considered a new leg by the UAS. 5. Open Questions Should cancelling a subscription be performed with the UNSUBSCRIBE method defined in PINT for the sake of consistency, or is the REGISTER model of "Expires: 0" preferable? 6. References [1] M. Handley/H. Schulzrinne/E. Schooler/J. Rosenberg, "SIP: Session Initiation Protocol", RFC 2543, IETF; March 1999. [2] Adam Roach, "Automatic Call Back Service in SIP", Internet Draft , IETF; March 2000. Work in progress. 7. Security Considerations The ability to accept third-party subscriptions should be under the direct control of the user, since many types of events may be considered sensitive for the purposes of privacy. Similarly, the user agent should have the ability to selectively reject subscriptions based on the calling party (using either a white-list or black-list functionality). 8. Author's Address Roach [Page 7] Internet Draft Event Notification in SIP March 2000 Adam Roach Ericsson Inc. Mailstop L-04 851 International Pkwy. Richardson, TX 75081 USA Phone: 972-583-7594 Fax: 972-669-0154 E-Mail: adam.roach@ericsson.com Roach [Page 8]