Request for Comments: 4235 Cisco Systems
Category: Standards Track H. Schulzrinne
Columbia University
R. Mahy, Ed.
SIP Edge LLC
November 2005
An INVITE-Initiated Dialog Event Package for the
Session Initiation Protocol (SIP)
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 01) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
This document defines a dialog event package for the SIP Events
architecture, along with a data format used in notifications for this
package. The dialog package allows users to subscribe to another
user and to receive notification of the changes in state of INVITE-
initiated dialog usages in which the subscribed-to user is involved.
Table of Contents
1. Introduction ....................................................3
2. Terminology .....................................................4
3. Dialog Event Package ............................................4
3.1. Event Package Name .........................................4
3.2. Event Package Parameters ...................................4
3.3. SUBSCRIBE Bodies ...........................................5
3.4. Subscription Duration ......................................6
3.5. NOTIFY Bodies ..............................................6
3.6. Notifier Processing of SUBSCRIBE Requests ..................7
3.7. Notifier Generation of NOTIFY Requests .....................8
3.7.1. The Dialog State Machine ............................8
3.7.2. Applying the State Machine .........................11
3.8. Subscriber Processing of NOTIFY Requests ..................12
3.9. Handling of Forked Requests ...............................12
3.10. Rate of Notifications ....................................13
3.11. State Agents .............................................13
4. Dialog Information Format ......................................13
4.1. Structure of Dialog Information ...........................13
4.1.1. Dialog Element .....................................14
4.1.2. State Element ......................................15
4.1.3. Duration Element ...................................15
4.1.4. Replaces Element ...................................15
4.1.5. Referred-By Element ................................16
4.1.6. Local and Remote Elements ..........................16
4.2. Sample Notification Body ..................................17
4.3. Constructing Coherent State ...............................18
4.4. Schema ....................................................19
5. Definition of New Media Feature Parameters .....................22
5.1. The "sip.byeless" Parameter ...............................22
5.2. The "sip.rendering" parameter .............................23
6. Examples .......................................................24
6.1. Basic Example .............................................24
6.2. Emulating a Shared-Line Phone System ......................26
6.3. Minimal Dialog Information with Privacy ...................31
7. Security Considerations ........................................32
8. IANA Considerations ............................................32
8.1. application/dialog-info+xml MIME Registration .............33
8.2. URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:dialog-info ........................34
8.3. Schema Registration .......................................34
8.4. Media Feature Parameter Registration ......................34
8.4.1. sip.byeless ........................................35
8.4.2. sip.rendering ......................................35
9. Acknowledgements ...............................................36
10. References ....................................................36
10.1. Normative References .....................................36
10.2. Informative References ...................................37
1. Introduction
The SIP Events framework [1] defines general mechanisms for
subscription to, and notification of, events within SIP networks. It
introduces the notion of a package, which is a specific
"instantiation" of the events mechanism for a well-defined set of
events. Packages have been defined for user presence [16], watcher
information [17], and message waiting indicators [18], amongst
others. This document defines an event package for INVITE-initiated
dialog usages. Dialogs refer to the SIP relationship established
between two SIP peers [2]. Dialogs can be created by many methods,
although RFC 3261 defines only one: the INVITE method. RFC 3265 [1]
defines the SUBSCRIBE and NOTIFY methods, which also create new
dialog usages. However, using this package to model state for non-
session dialog usages is out of the scope of this specification.
A variety of applications are enabled through knowledge of INVITE
dialog usage state. Some examples include:
Automatic Callback: In this basic Public Switched Telephone
Network (PSTN) application, user A calls user B but User B is
busy. User A would like to get a callback when user B hangs
up. When B hangs up, user A’s phone rings. When A picks up,
they hear ringing, while they are being connected to B. To
implement this with SIP, a mechanism is required for A to
receive a notification when the dialogs at B are complete.
Presence-Enabled Conferencing: In this application, user A wishes
to set up a conference call with users B and C. Rather than
being scheduled, the call is created automatically when A, B
and C are all available. To do this, the server providing the
application would like to know whether A, B, and C are
"online", not idle, and not in a phone call. Determining
whether or not A, B, and C are in calls can be done in two
ways. In the first, the server acts as a call-stateful proxy
for users A, B, and C, and therefore knows their call state.
This won’t always be possible, however, and it introduces
scalability, reliability, and operational complexities. In the
second way, the server subscribes to the dialog state of those
users and receives notifications as this state changes. This
enables the application to be provided in a distributed way;
the server need not reside in the same domain as the users.
IM Conference Alerts: In this application, a user can receive an
Instant Message (IM) on their phone whenever someone joins a
conference that the phone is involved in. The IM alerts are
generated by an application separate from the conference
server.
In general, the dialog package allows for construction of distributed
applications, where the application requires information on dialog
state but is not co-resident with the end user on which that state
resides.
This document also defines two new callee capability [10] feature
parameters:
o "sip.byeless", which indicates that a SIP user agent (UA) is not
capable of terminating a session itself (for example, in some
announcement or recording services, or in some call centers) in
which the UA is no longer interested in participating; and
o "sip.rendering", which positively describes whether the user
agent is rendering any of the media it is receiving. These
feature parameters are useful in many of the same applications
that motivated the dialog package, such as conferencing,
presence, and the shared-line example described in Section 6.2.
2. Terminology
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in RFC 2119 [9] and
indicate requirement levels for compliant implementations.
3. Dialog Event Package
This section provides the details for defining a SIP Events package,
as specified in [1].
3.1. Event Package Name
The name of this event package is "dialog". This package name is
carried in the Event and Allow-Events header fields, as defined in
[1].
3.2. Event Package Parameters
This package defines four Event Package parameters: call-id, to-tag,
from-tag, and include-session-description. If a subscription to a
specific dialog is requested, the first three of these parameters
MUST be present, to identify the dialog that is being subscribed to.
The to-tag is matched against the local tag, the from-tag is matched
against the remote tag, and the call-id is matched against the
Call-ID. The include-session-description parameter indicates whether
the subscriber would like to receive the session descriptions
associated with the subscribed dialog usage or usages.
It is also possible to subscribe to the set of dialogs created as a
result of a single INVITE sent by a UAC (user agent client). In that
case, the call-id and to-tag MUST be present. The to-tag is matched
against the local tag and the call-id is matched against the Call-ID.
The ABNF for these parameters is shown below. It refers to many
constructions from the ABNF of RFC3261, such as EQUAL, DQUOTE, and
token.
call-id = "call-id" EQUAL ( token / DQUOTE callid DQUOTE )
;; NOTE: any DQUOTEs inside callid MUST be escaped!
from-tag = "from-tag" EQUAL token
to-tag = "to-tag" EQUAL token
with-sessd = "include-session-description"
If any call-ids contain embedded double-quotes, those double-quotes
MUST be escaped using the backslash-quoting mechanism. Note that the
call-id parameter may need to be expressed as a quoted string. This
is because the ABNF for the callid production and the word
production, which is used by callid (both from RFC 3261 [1]), allow
some characters (such as "@", "[", and ":") that are not allowed
within a token.
3.3. SUBSCRIBE Bodies
A SUBSCRIBE request for a dialog package MAY contain a body. This
body defines a filter to be applied to the subscription. Filter
documents are not specified in this document, and at the time of
writing, they are expected to be the subject of future
standardization activity.
A SUBSCRIBE request for a dialog package MAY be sent without a body.
This implies the default subscription filtering policy. The default
policy is:
o If the Event header field contained dialog identifiers, a
notification is generated every time there is a change in the
state of any matching dialogs for the user identified in the
request URI of the SUBSCRIBE.
o If there were no dialog identifiers in the Event header field, a
notification is generated every time there is any change in the
state of any dialogs for the user identified in the request URI of
the SUBSCRIBE with the following exceptions. If the target
(Contact) URI of a subscriber is equivalent to the remote target
URI of a specific dialog, then the dialog element for that dialog
is suppressed for that subscriber. (The subscriber is already a
party in the dialog directly, so these notifications are
superfluous.) If no dialogs remain after suppressing dialogs, the
entire notification to that subscriber is suppressed and the
version number in the dialog-info element is not incremented for
that subscriber. Implicit filtering for one subscriber does not
affect notifications to other subscribers.
o Notifications do not normally contain full state; rather, they
only indicate the state of the dialog(s) whose state has changed.
The exceptions are a NOTIFY sent in response to a SUBSCRIBE, and a
NOTIFY that contains no dialog elements. These NOTIFYs contain
the complete view of dialog state.
o The notifications contain the identities of the participants in
the dialog, the target URIs, and the dialog identifiers. Session
descriptions are not included unless explicitly requested and
explicitly authorized.
3.4. Subscription Duration
Dialog state changes fairly quickly. Once established, a typical
phone call lasts a few minutes (this is different for other session
types, of course). However, the interval between new calls is
typically long. Clients SHOULD specify an explicit duration.
There are two distinct use cases for dialog state. The first is when
a subscriber is interested in the state of a specific dialog or
dialogs (and they are authorized to find out just the state of those
dialogs). In that case, when the dialogs terminate, so too does the
subscription. In these cases, the value of the subscription duration
is largely irrelevant; it SHOULD be longer than the typical duration
of a dialog. We recommend a default duration of two hours, which is
likely to cover most dialogs.
In another case, a subscriber is interested in the state of all
dialogs for a specific user. In these cases, a shorter interval
makes more sense. The default is one hour for these subscriptions.
3.5. NOTIFY Bodies
As described in RFC 3265 [1], the NOTIFY message will contain bodies
that describe the state of the subscribed resource. This body is in
a format listed in the Accept header field of the SUBSCRIBE, or in a
package-specific default format if the Accept header field was
omitted from the SUBSCRIBE.
In this event package, the body of the notification contains a dialog
information document. This document describes the state of one or
more dialogs associated with the subscribed resource. All
subscribers and notifiers MUST support the "application/
dialog-info+xml" data format described in Section 4. The subscribe
request MAY contain an Accept header field. If no such header field
is present, it has a default value of "application/dialog-info+xml".
If the header field is present, it MUST include "application/
dialog-info+xml", and it MAY include any other types capable of
representing dialog state.
Of course, the notifications generated by the server MUST be in one
of the formats specified in the Accept header field in the SUBSCRIBE
request.
3.6. Notifier Processing of SUBSCRIBE Requests
The dialog information for a user contains sensitive information.
Therefore, all subscriptions SHOULD be authenticated and then
authorized before approval. All implementors of this package MUST
support the digest authentication mechanism as a baseline. The
authorization policy is at the discretion of the administrator, as
always. However, a few recommendations can be made.
It is RECOMMENDED that, if the policy of user B is that user A is
allowed to call them, dialog subscriptions from user A be allowed.
However, the information provided in the notifications does not
contain any dialog identification information, merely an indication
of whether the user is in at least one call. Specifically, they
should not be able to find out any more information than if they sent
an INVITE. (This concept of a "virtual" dialog is discussed more in
Section 3.7.2, and an example of such a notification body is shown
below).
<?xml version="1.0"?>
<dialog-info xmlns="urn:ietf:params:xml:ns:dialog-info"
version="0" state="full"
entity="sip:alice@example.com">
<dialog id="as7d900as8">
<state>confirmed</state>
</dialog>
</dialog-info>
A user agent that registers with the address-of-record X SHOULD
authorize subscriptions that come from any entity that can
authenticate itself as X. Complete information on the dialog state
SHOULD be sent in this case. This authorization behavior allows a
group of devices representing a single user to become aware of each
other’s state. This is useful for applications such as
single-line-extension, also known as shared lines.
Note that many implementations of "shared-lines" have a feature
that allows details of calls on a shared address-of-record to be
made private. This is a completely reasonable authorization
policy that could result in notifications that contain only the id
attribute of the dialog element and the state element when
shared-line privacy is requested, and notifications with more
complete information when shared-line privacy is not requested.
3.7. Notifier Generation of NOTIFY Requests
Notifications are generated for the dialog package when an INVITE
request is sent, when a new dialog comes into existence at a UA, or
when the state or characteristics of an existing dialog changes.
Therefore, a model of dialog state is needed in order to determine
precisely when to send notifications, and what their content should
be. The SIP specification has a reasonably well defined lifecycle
for dialogs. However, it is not explicitly modelled. This
specification provides an explicit model of dialog state through a
finite state machine.
It is RECOMMENDED that NOTIFY requests only contain information on
the dialogs whose state or participation information has changed.
However, if a notifier receives a SUBSCRIBE request, the triggered
NOTIFY SHOULD contain the state of all dialogs that the subscriber is
authorized to see.
3.7.1. The Dialog State Machine
Modelling of dialog state is complicated by two factors. The first
is forking, which can cause a single INVITE to generate many dialogs
at a UAC. The second is the differing views of state at the UAC
(user agent client) and UAS (usage agent server). We have chosen to
handle the first issue by extending the dialog finite state machine
(FSM) to include the states between transmission of the INVITE and
the creation of actual dialogs through receipt of 1xx and 2xx
responses. As a result, this specification supports the notion of
dialog state for dialogs before they are fully instantiated.
We have also chosen to use a single FSM for both UAC and UAS.
+----------+ +----------+
| | 1xx-notag | |
| |----------->| |
| Trying | |Proceeding|-----+
| |---+ +-----| | |
| | | | | | |
+----------+ | | +----------+ |
| | | | | |
| | | | | |
+<--C-----C--+ |1xx-tag |
| | | | |
cancelled| | | V |
rejected| | |1xx-tag +----------+ |
| | +------->| | |2xx
| | | | |
+<--C--------------| Early |-----C---+ 1xx-tag
| | replaced | | | | w/new tag
| | | |<----C---+ (new FSM
| | +----------+ | instance
| | 2xx | | created)
| +----------------+ | |
| | |2xx |
| | | |
V V V |
+----------+ +----------+ |
| | | | |
| | | | |
|Terminated|<-----------| Confirmed|<----+
| | error | |
| | timeout | |
+----------+ replaced +----------+
local-bye | ^
remote-bye | |
| |
+------+
2xx w. new tag
(new FSM instance