idnits 2.17.1
draft-ietf-sipping-dialog-package-03.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
** Looks like you're using RFC 2026 boilerplate. This must be updated to
follow RFC 3978/3979, as updated by RFC 4748.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
== No 'Intended status' indicated for this document; assuming Proposed
Standard
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** There are 5 instances of too long lines in the document, the longest one
being 5 characters in excess of 72.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the RFC 3978 Section 5.4 Copyright Line does not
match the current year
== Line 10 has weird spacing: '...Package for t...'
== The document seems to lack the recommended RFC 2119 boilerplate, even if
it appears to use RFC 2119 keywords.
(The document does seem to have the reference to RFC 2119 which the
ID-Checklist requires).
-- The document seems to lack a disclaimer for pre-RFC5378 work, but may
have content which was first submitted before 10 November 2008. If you
have contacted all the original authors and they are all willing to grant
the BCP78 rights to the IETF Trust, then this is fine, and you can ignore
this comment. If not, you may need to add the pre-RFC5378 disclaimer.
(See the Legal Provisions document at
https://trustee.ietf.org/license-info for more information.)
-- The document date (October 25, 2003) is 7483 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
** Obsolete normative reference: RFC 3265 (ref. '1') (Obsoleted by RFC 6665)
-- Possible downref: Non-RFC (?) normative reference: ref. '4'
** Obsolete normative reference: RFC 2141 (ref. '5') (Obsoleted by RFC 8141)
** Downref: Normative reference to an Informational RFC: RFC 2648 (ref. '6')
== Outdated reference: A later version (-05) exists of
draft-mealling-iana-xmlns-registry-04
** Obsolete normative reference: RFC 3023 (ref. '8') (Obsoleted by RFC 7303)
== Outdated reference: A later version (-03) exists of
draft-ietf-sip-callee-caps-00
== Outdated reference: A later version (-05) exists of
draft-ietf-sip-referredby-01
== Outdated reference: A later version (-05) exists of
draft-ietf-sip-replaces-03
== Outdated reference: A later version (-04) exists of
draft-ietf-sipping-mwi-02
Summary: 6 errors (**), 0 flaws (~~), 9 warnings (==), 3 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 SIPPING J. Rosenberg
3 Internet-Draft dynamicsoft
4 Expires: April 24, 2004 H. Schulzrinne
5 Columbia University
6 R. Mahy, Ed.
7 Cisco Systems, Inc.
8 October 25, 2003
10 An INVITE Inititiated Dialog Event Package for the Session
11 Initiation Protocol (SIP)
12 draft-ietf-sipping-dialog-package-03.txt
14 Status of this Memo
16 This document is an Internet-Draft and is in full conformance with
17 all provisions of Section 10 of RFC2026.
19 Internet-Drafts are working documents of the Internet Engineering
20 Task Force (IETF), its areas, and its working groups. Note that other
21 groups may also distribute working documents as Internet-Drafts.
23 Internet-Drafts are draft documents valid for a maximum of six months
24 and may be updated, replaced, or obsoleted by other documents at any
25 time. It is inappropriate to use Internet-Drafts as reference
26 material or to cite them other than as "work in progress."
28 The list of current Internet-Drafts can be accessed at http://
29 www.ietf.org/ietf/1id-abstracts.txt.
31 The list of Internet-Draft Shadow Directories can be accessed at
32 http://www.ietf.org/shadow.html.
34 This Internet-Draft will expire on April 24, 2004.
36 Copyright Notice
38 Copyright (C) The Internet Society (2003). All Rights Reserved.
40 Abstract
42 This document defines a dialog event package for the SIP Events
43 architecture, along with a data format used in notifications for this
44 package. The dialog package allows users to subscribe to another
45 user, an receive notifications about the changes in state of INVITE
46 initiated dialogs that the user is involved in.
48 Table of Contents
50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . 3
51 2. Terminology . . . . . . . . . . . . . . . . . . . . . . 4
52 3. Dialog Event Package . . . . . . . . . . . . . . . . . . 4
53 3.1 Event Package Name . . . . . . . . . . . . . . . . . . . 4
54 3.2 Event Package Parameters . . . . . . . . . . . . . . . . 4
55 3.3 SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . 5
56 3.4 Subscription Duration . . . . . . . . . . . . . . . . . 6
57 3.5 NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . 6
58 3.6 Notifier Processing of SUBSCRIBE Requests . . . . . . . 6
59 3.7 Notifier Generation of NOTIFY Requests . . . . . . . . . 7
60 3.7.1 The Dialog State Machine . . . . . . . . . . . . . . . . 8
61 3.7.2 Applying the state machine . . . . . . . . . . . . . . . 10
62 3.8 Subscriber Processing of NOTIFY Requests . . . . . . . . 12
63 3.9 Handling of Forked Requests . . . . . . . . . . . . . . 12
64 3.10 Rate of Notifications . . . . . . . . . . . . . . . . . 12
65 3.11 State Agents . . . . . . . . . . . . . . . . . . . . . . 13
66 4. Dialog Information Format . . . . . . . . . . . . . . . 13
67 4.1 Structure of Dialog Information . . . . . . . . . . . . 13
68 4.1.1 Dialog Element . . . . . . . . . . . . . . . . . . . . . 14
69 4.1.2 State . . . . . . . . . . . . . . . . . . . . . . . . . 15
70 4.1.3 Duration . . . . . . . . . . . . . . . . . . . . . . . . 15
71 4.1.4 Replaces . . . . . . . . . . . . . . . . . . . . . . . . 15
72 4.1.5 Referred-By . . . . . . . . . . . . . . . . . . . . . . 16
73 4.1.6 Route-Set . . . . . . . . . . . . . . . . . . . . . . . 16
74 4.1.6.1 Local and Remote elements . . . . . . . . . . . . . . . 16
75 4.1.6.1.1 Identity . . . . . . . . . . . . . . . . . . . . . . . . 16
76 4.1.6.1.2 Target . . . . . . . . . . . . . . . . . . . . . . . . . 17
77 4.1.6.1.3 Session Description . . . . . . . . . . . . . . . . . . 17
78 4.1.6.1.4 CSeq . . . . . . . . . . . . . . . . . . . . . . . . . . 17
79 4.2 Constructing Coherent State . . . . . . . . . . . . . . 17
80 4.3 Schema . . . . . . . . . . . . . . . . . . . . . . . . . 18
81 4.4 Example . . . . . . . . . . . . . . . . . . . . . . . . 21
82 5. Security Considerations . . . . . . . . . . . . . . . . 25
83 6. IANA Considerations . . . . . . . . . . . . . . . . . . 25
84 6.1 application/dialog-info+xml MIME Registration . . . . . 25
85 6.2 URN Sub-Namespace Registration for
86 urn:ietf:params:xml:ns:dialog-info . . . . . . . . . . . 26
87 6.3 Schema Registration . . . . . . . . . . . . . . . . . . 26
88 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . 27
89 Normative References . . . . . . . . . . . . . . . . . . 27
90 Informative References . . . . . . . . . . . . . . . . . 28
91 Authors' Addresses . . . . . . . . . . . . . . . . . . . 28
92 Intellectual Property and Copyright Statements . . . . . 30
94 1. Introduction
96 The SIP Events framework [1] defines general mechanisms for
97 subscription to, and notification of, events within SIP networks. It
98 introduces the notion of a package, which is a specific
99 "instantiation" of the events mechanism for a well-defined set of
100 events. Packages have been defined for user presence [14], watcher
101 information [15], and message waiting indicators [16], amongst
102 others. Here, we define an event package for INVITE initiated
103 dialogs. Dialogs refer to the SIP relationship established between
104 two SIP peers [2]. Dialogs can be created by many methods, although
105 RFC 3261 defines only one - the INVITE method. RFC 3265 defines the
106 SUBSCRIBE and NOTIFY methods, which also create dialogs. However, the
107 usage of this package to model transitions in the state of those
108 dialogs is out of the scope of this specification.
110 There are a variety of applications enabled through the knowledge of
111 INVITE dialog state. Some examples include:
113 Automatic Callback: In this basic Public Switched Telephone Network
114 (PSTN) application, user A calls user B. User B is busy. User A
115 would like to get a callback when user B hangs up. When B hangs
116 up, user A's phone rings. When A picks it up, they here ringing,
117 and are being connected to B. To implement this with SIP, a
118 mechanism is required for B to receive a notification when the
119 dialogs at A are complete.
121 Presence-Enabled Conferencing: In this application, a user A wishes
122 to set up a conference call with users B and C. Rather than
123 scheduling it, it is to be created automatically when A, B and C
124 are all available. To do this, the server providing the
125 application would like to know whether A, B and C are "online",
126 not idle, and not in a phone call. Determining whether or not A, B
127 and C are in calls can be done in two ways. In the first, the
128 server acts as a call stateful proxy for users A, B and C, and
129 therefore knows their call state. This won't always be possible,
130 however, and it introduces scalability, reliability, and
131 operational complexities. Rather, the server would subscriber to
132 the dialog state of those users, and receive notifications as it
133 changes. This enables the application to be provided in a
134 distributed way; the server need not reside in the same domain as
135 the users.
137 IM Conference Alerts: In this application, a user can get an IM sent
138 to their phone whenever someone joins a conference that the phone
139 is involved in. The IM alerts are generated by an application
140 separate from the conference server.
142 In general, the dialog package allows for construction of distributed
143 applications, where the application requires information on dialog
144 state, but is not co-resident with the end user on which that state
145 resides.
147 2. Terminology
149 In this document, the key words "MUST", "MUST NOT", "REQUIRED",
150 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
151 and "OPTIONAL" are to be interpreted as described in RFC 2119 [9] and
152 indicate requirement levels for compliant implementations.
154 3. Dialog Event Package
156 This section provides the details for defining a SIP Events package,
157 as specified by [1].
159 3.1 Event Package Name
161 The name of this event package is "dialog". This package name is
162 carried in the Event and Allow-Events header, as defined in [1].
164 3.2 Event Package Parameters
166 This package defines four Event Package parameters. They are call-id,
167 to-tag, from-tag, and include-session-description. If a subscription
168 to a specific dialog is requested, all of the first three of these
169 parameters MUST be present. They identify the dialog that is being
170 subscribed to. The to-tag is matched against the local tag, the
171 from-tag is matched against the remote tag, and the call-id is
172 matched against the Call-ID. The include-session-description
173 parameter indicates if the subscriber would like to receive the
174 session descriptions associated with the subscribed dialog or
175 dialogs.
177 It is also possible to subscribe to the set of dialogs created as a
178 result of a single INVITE sent by a UAC. In that case, the call-id
179 and to-tag MUST be present. The to-tag is matched against the local
180 tag, and the call-id is matched against the Call-ID.
182 The ABNF for these parameters is shown below. It refers to many
183 constructions from the ABNF of RFC3261, such as word, callid, EQUAL,
184 DQUOTE, and token.
186 call-id = "call-id" EQUAL ( token / DQUOTE callid DQUOTE )
187 ;; NOTE: any DQUOTEs inside callid MUST be escaped!
188 from-tag = "from-tag" EQUAL token
189 to-tag = "to-tag" EQUAL token
190 with-sessd = "include-session-description"
192 Any callids which contain embedded double-quotes MUST escape those
193 double-quotes using the backslash-quoting mechanism. Note that the
194 call-id parameter may need to be expressed as a quoted string. This
195 is because the ABNF for callid and word (which is used by callid)
196 allow for some characters (such as "@", "[", and ":") which are not
197 allowed within a token.
199 3.3 SUBSCRIBE Bodies
201 A SUBSCRIBE for a dialog package MAY contain a body. This body
202 defines a filter to apply to the subscription. Filter documents are
203 not specified in this document, and at the time of writing, are
204 expected to be the subject of future standardization activity.
206 A SUBSCRIBE for a dialog package MAY be sent without a body. This
207 implies the default subscription filtering policy. The default policy
208 is:
210 o If the Event header field contained dialog identifiers,
211 notifications are generated every time there is a change in the
212 state of any matching dialogs for the user identified in the
213 request URI of the SUBSCRIBE.
215 o If there were no dialog identifiers in the Event header field,
216 notifications are generated every time there is any change in the
217 state of any dialogs for the user identified in the request URI of
218 the SUBSCRIBE with the following exceptions. If the target
219 (Contact) URI of a subscriber is equivalent to the remote target
220 URI of a specific dialog, then the dialog element for that dialog
221 is suppressed for that subscriber. (The subscriber is already a
222 party in the dialog directly, so these notifications are
223 superfluous.) If no dialogs remain after supressing dialogs, the
224 entire notification to that subscriber is supressed and the
225 version number in the dialog-info element is not incremented for
226 that subscriber. Implicit filtering for one subscriber does not
227 affect notifications to other subscribers.
229 o Notifications do not normally contain full state; rather, they
230 only indicate the state of the dialog whose state has changed. The
231 exception is a NOTIFY sent in response to a SUBSCRIBE. These
232 NOTIFYs contain the complete view of dialog state.
234 o The notifications contain the identities of the participants in
235 the dialog, and the dialog identifiers. Additional information,
236 such as the route set, CSeq numbers, SDP information, and so on,
237 are not included normally unless explicitly requested and/or
238 explicitly authorized.
240 3.4 Subscription Duration
242 Dialog state changes fairly quickly; once established, a typical
243 phone call lasts a few minutes (this is different for other session
244 types, of course). However, the interval between new calls is
245 typically infrequent. As such, we arbitrarily choose a default
246 duration of one hour. Clients SHOULD specify an explicit duration.
248 There are two distinct use cases for dialog state. The first is when
249 a subscriber is interested in the state of a specific dialog or
250 dialogs (and they are authorized to find out about just the state of
251 those dialogs). In that case, when the dialogs terminate, so too does
252 the subscription. In these cases, the value of the subscription
253 duration is largely irrelevant, and SHOULD be longer than the typical
254 duration of a dialog, about two hours would cover most dialogs.
256 In another case, a subscriber is interested in the state of all
257 dialogs for a specific user. In these cases, a shorter interval makes
258 more sense. The default is one hour for these subscriptions.
260 3.5 NOTIFY Bodies
262 As described in RFC 3265 [1], the NOTIFY message will contain bodies
263 that describe the state of the subscribed resource. This body is in a
264 format listed in the Accept header field of the SUBSCRIBE, or a
265 package-specific default if the Accept header field was omitted from
266 the SUBSCRIBE.
268 In this event package, the body of the notification contains a dialog
269 information document. This document describes the state of one or
270 more dialogs associated with the subscribed resource. All subscribers
271 and notifiers MUST support the "application/dialog-info+xml" data
272 format described in Section 4. The subscribe request MAY contain an
273 Accept header field. If no such header field is present, it has a
274 default value of "application/dialog-info+xml". If the header field
275 is present, it MUST include "application/dialog-info+xml", and MAY
276 include any other types capable of representing dialog state.
278 Of course, the notifications generated by the server MUST be in one
279 of the formats specified in the Accept header field in the SUBSCRIBE
280 request.
282 3.6 Notifier Processing of SUBSCRIBE Requests
284 The dialog information for a user contains sensitive information.
286 Therefore, all subscriptions SHOULD be authenticated and then
287 authorized before approval. All implementors of this package MUST
288 support the digest authentication mechanism as a baseline.
289 Authorization policy is at the discretion of the administrator, as
290 always. However, a few recommendations can be made.
292 It is RECOMMENDED that, if the policy of user B is that user A is
293 allowed to call them, dialog subscriptions from user A be allowed.
294 However, the information provided in the notifications does not
295 contain any dialog identification information; merely an indication
296 of whether the user is in at least one call, or not. Specifically,
297 they should not be able to find out any more information than if they
298 sent an INVITE. (This concept of a "virtual" dialog is discussed more
299 in Section 3.7.2, and an example of such a notification body is shown
300 below.)
301
302
305
308
310 It is RECOMMENDED that if a user agent registers with the
311 address-of-record X, that this user agent authorize subscriptions
312 that come from any entity that can authenticate itself as X. Complete
313 information on the dialog state SHOULD be sent in this case. This
314 authorization behavior allows a group of devices representing a
315 single user to all become aware of each other's state. This is useful
316 for applications such as single-line-extension.
318 Note that many implementations of "shared-lines" have a feature
319 which allows details of calls on a shared address-of-record to be
320 made private. This is a completely reasonable authorization policy
321 which could result in notifications which contain only the id
322 attribute of the dialog element and the state element when
323 shared-line privacy is requested, and notifications with more
324 complete information when shared-line privacy is not requested.
326 3.7 Notifier Generation of NOTIFY Requests
328 Notifications are generated for the dialog package when an INVITE
329 request is sent, when a new dialog comes into existence at a UA, or
330 when the state or characteristics of an existing dialog changes.
331 Therefore, a model of dialog state is needed in order to determine
332 precisely when to send notifications, and what their content should
333 be. The SIP specification has a reasonably well defined lifecycle for
334 dialogs. However, it is not explicitly modelled. This specification
335 provides an explicit model of dialog state through a finite state
336 machine.
338 It is RECOMMENDED that NOTIFY requests only contain information on
339 the dialogs whose state or participation information has changed.
340 However, if a notifier receives a SUBSCRIBE request, the triggered
341 NOTIFY SHOULD contain the state of all dialogs that the subscriber is
342 authorized to see.
344 3.7.1 The Dialog State Machine
346 Modelling of dialog state is complicated by two factors. The first is
347 forking, which can cause a single INVITE to generate many dialogs at
348 a UAC. The second is the differing views of state at the UAC and UAS.
349 We have chosen to handle the first issue by extending the dialog FSM
350 to include the states between transmission of the INVITE and the
351 creation of actual dialogs through receipt of 1xx and 2xx responses.
352 As a result, this specification supports the notion of dialog state
353 for dialogs before they are fully instantiated.
355 We have also chosen to use a single FSM for both UAC and UAS.
357 +----------+ +----------+
358 | | 1xx-notag | |
359 | |----------->| |
360 | Trying | |Proceeding|-----+
361 | |---+ +-----| | |
362 | | | | | | |
363 +----------+ | | +----------+ |
364 | | | | | |
365 | | | | | |
366 +<--C-----C--+ |1xx-tag |
367 | | | | |
368 cancelled| | | V |
369 rejected| | |1xx-tag +----------+ |
370 | | +------->| | |2xx
371 | | | | |
372 +<--C--------------| Early |-----C----+1xx-tag
373 | | replaced | | | | w. new tag
374 | | | |<----C----+ (new
375 | | +----------+ | FSM
376 | | 2xx | | instance
377 | +----------------+ | | created)
378 | | |2xx |
379 | | | |
380 V V V |
381 +----------+ +----------+ |
382 | | | | |
383 | | | | |
384 |Terminated|<-----------| Confirmed|<----+
385 | | error | |
386 | | timeout | |
387 +----------+ replaced +----------+
388 local-bye | ^
389 remote-bye | |
390 | |
391 +------+
392 2xx w. new tag
393 (new FSM instance
394 created)
396 Figure 3
398 The FSM for dialog state is shown in Figure 3. The FSM is best
399 understood by considering the UAC and UAS cases separately.
401 The FSM is created in the "trying" state when the UAC sends an INVITE
402 request. Upon receipt of a 1xx without a tag, the FSM transitions to
403 the "proceeding" state. Note that there is no actual dialog yet, as
404 defined by the SIP specification. However, there is a "half-dialog",
405 in the sense that two of the three components of the dialog ID are
406 known (the call identifier and local tag). If a 1xx with a tag is
407 received, the FSM transitions to the early state. The full dialog
408 identifier is now defined. Had a 2xx been received, the FSM would
409 have transitioned to the "confirmed" state.
411 If, after transitioning to the "early" or "confirmed" states, the UAC
412 receives another 1xx or 2xx respectively with a different tag,
413 another instance of the FSM is created, initialized into the "early"
414 or "confirmed" state respectively. The benefit of this approach is
415 that there will be a single FSM representing the entire state of the
416 invitation and resulting dialog when dealing with the common case of
417 no forking.
419 If the UAC should send a CANCEL, and then subsequently receive a 487
420 to its INVITE transaction, all FSMs spawned from that INVITE
421 transition to the "terminated" state with the event "cancelled". If
422 the UAC receives a new invitation (with a Replaces [13] header) which
423 replaces the current Early or Confirmed dialog, all INVITE
424 transactions spawned from the replaced invitation transition to the
425 "terminated" state with the event "replaced". If the INVITE
426 transaction terminates with a non-2xx response for any other reason,
427 all FSMs spawned from that INVITE transition to the terminated state
428 with the event "rejected".
430 Once in the confirmed state, the call is active. It can transition to
431 the terminated state if the UAC sends a BYE or receives a BYE
432 (corresponding to the "local-bye" and "remote-bye" events as
433 appropriate), if a mid-dialog request generates a 481 or 408 response
434 (corresponding to the "error" event), or a mid-dialog request
435 generates no response (corresponding to the "timeout" event).
437 From the perspective of the UAS, when an INVITE is received, the FSM
438 is created in the "trying" state. If it sends a 1xx without a tag,
439 the FSM transitions to the "proceeding" state. If a 1xx is sent with
440 a tag, the FSM transitions to the "early" state, and if a 2xx is
441 sent, it transitions to the "confirmed" state. If the UAS should
442 receive a CANCEL request and then generate a 487 response to the
443 INVITE (which can occur in the proceeding and early states), the FSM
444 transitions to the terminated state with the event "cancelled". If
445 the UAS should generate any other non-2xx final response to the
446 INVITE request, the FSM transitions to the terminated state with the
447 event "rejected". If the UAS receives a new invitation (with a
448 Replaces [13] header) which replaces the current Confirmed dialog,
449 the replaced invitation transition transitions to the "terminated"
450 state with the event "replaced". Once in the "confirmed" state, the
451 other transitions to the "terminated" state occur for the same
452 reasons they do in the case of UAC.
454 There should never be a transition from the "trying" state to the
455 "terminated" state with the event "cancelled", since the SIP
456 specification prohibits transmission of CANCEL until a provisional
457 response is received. However, this transition is defined in the
458 FSM just to unify the transitions from trying, proceeding, and
459 early to the terminated state.
461 OPEN ISSUE: Since there is only one possible event to cause
462 transitions to the Proceeding (1xx-notag), Early (1xx-tag), and
463 Confirmed (2xx) states, the only events which provide any
464 additional information are the events for transitions to
465 Terminated (error, timeout, cancelled, local-bye, remote-bye and
466 replaced). Of these, timeout may not be relevant, since it is
467 often indistinguishable from "rejected" (for example, a 408) or
468 "error". Likewise it is unclear if there is any value in
469 distinguishing "local-bye" from "cancelled"; perhaps we should use
470 a single event, such as "local-hangup" instead.
472 3.7.2 Applying the state machine
474 The notifier MAY generate a NOTIFY request on any event transition of
475 the FSM. Whether it does or not is policy dependent. However, some
476 general guidelines are provided.
478 When the subscriber is unauthenticated, or is authenticated, but
479 represents a third party with no specific authorization policies, it
480 is RECOMMENDED that subscriptions to an individual dialog, or to a
481 specific set of dialogs, is forbidden. Only subscriptions to all
482 dialogs (i.e., there are no dialog identifiers in the Event header
483 field) are permitted. In that case, actual dialog states across all
484 dialogs will not be reported. Rather, a single "virtual" dialog FSM
485 be used, and event transitions on that FSM be reported.
487 If there is any dialog at the UA whose state is "confirmed", the
488 virtual FSM is in the "confirmed" state. If there are no dialogs at
489 the UA in the confirmed state, but there is at least one in the
490 "early" state, the virtual FSM is in the "early" or "confirmed"
491 state. If there are no dialogs in the confirmed or early states, but
492 there is at least one in the "proceeding" state, the virtual FSM is
493 in the "proceeding", "early" or "confirmed" state. If there are no
494 dialogs in the confirmed, early, or proceeding states, but there is
495 at least one in the "trying" state, the virtual FSM is in the
496 "trying", "proceeding", "early" or "confirmed" state. The choice
497 about which state to use depends on whether the UA wishes to let
498 unknown users that their phone is ringing, as opposed to in an active
499 call.
501 It is RECOMMENDED that, in the absence of any preference, "confirmed"
502 is used in all cases (as shown in the example in Section 3.6.
503 Furthermore, it is RECOMMENDED that the notifications of changes in
504 the virtual FSM machine not convey any information except the state
505 of the FSM and its event transitions - no dialog identifiers (which
506 are ill-defined in this model in any case). The use of this virtual
507 FSM allows for minimal information to be conveyed. A subscriber
508 cannot know how many calls are in progress, or with whom, just that
509 there exists a call. This is the same information they would receive
510 if they simply sent an INVITE to the user instead; a 486 response
511 would indicate that they are on a call.
513 When the subscriber is authenticated, and has authenticated itself
514 with the same address-of-record that the UA itself uses, if no
515 explicit authorization policy is defined, it is RECOMMENDED that all
516 state transitions on dialogs that have been subscribed to (which is
517 either all of them, if no dialog identifiers were present in the
518 Event header field, or a specific set of them identified by the Event
519 header field parameters) be reported, along with complete dialog IDs.
521 The notifier MAY generate a NOTIFY request on any change in the
522 characteristics associated with the dialog. Since these include CSeq
523 numbers and SDP, receipt of re-INVITEs and UPDATE requests [3] which
524 modify this information MAY trigger notifications.
526 OPEN ISSUE: Is there a good reason to include CSeqs at all? Can
527 anyone come up with a use case? This seems to contradict the
528 "Rate of Notifications" section, and I can come up with some good
529 examples where this would be VERY BAD. For example, say Alice
530 sends an invitation to Bob, and then, on the same dialog,
531 subscribes to his dialog package, requesting CSeq information.
532 Every notification updates the CSeq which in turn generates
533 another notification, causing an infinite flood of messages.
535 3.8 Subscriber Processing of NOTIFY Requests
537 The SIP Events framework expects packages to specify how a subscriber
538 processes NOTIFY requests in any package specific ways, and in
539 particular, how it uses the NOTIFY requests to contruct a coherent
540 view of the state of the subscribed resource.
542 Typically, the NOTIFY for the dialog package will only contain
543 information about those dialogs whose state has changed. To construct
544 a coherent view of the total state of all dialogs, a subscriber to
545 the dialog package will need to combine NOTIFYs received over time.
547 Notifications within this package can convey partial information;
548 that is, they can indicate information about a subset of the state
549 associated with the subscription. This means that an explicit
550 algorithm needs to be defined in order to construct coherent and
551 consistent state. The details of this mechanism are specific to the
552 particular document type. See Section 4.2 for information on
553 constructing coherent information from an application/dialog-info+xml
554 document.
556 3.9 Handling of Forked Requests
558 Since dialog state is distributed across the UA for a particular
559 user, it is reasonable and useful for a SUBSCRIBE request for dialog
560 state to fork, and reach multiple UA.
562 As a result, a forked SUBSCRIBE request for dialog state can install
563 multiple subscriptions. Subscribers to this package MUST be prepared
564 to install subscription state for each NOTIFY generated as a result
565 of a single SUBSCRIBE.
567 3.10 Rate of Notifications
569 For reasons of congestion control, it is important that the rate of
570 notifications not become excessive. As a result, it is RECOMMENDED
571 that the server not generate notifications for a single subscriber at
572 a rate faster than once every 5 seconds.
574 Editors Note: This seems too slow to me. I think 1 second is
575 probably reasonable.
577 3.11 State Agents
579 Dialog state is ideally maintained in the user agents in which the
580 dialog resides. Therefore, the elements that maintain the dialog are
581 the ones best suited to handle subscriptions to it. However, in some
582 cases, a network agent may also know the state of the dialogs held by
583 a user. As such, state agents MAY be used with this package.
585 4. Dialog Information Format
587 Dialog information is an XML document [4] that MUST be well-formed
588 and SHOULD be valid. Dialog information documents MUST be based on
589 XML 1.0 and MUST be encoded using UTF-8. This specification makes use
590 of XML namespaces for identifying dialog information documents and
591 document fragments. The namespace URI for elements defined by this
592 specification is a URN [5], using the namespace identifier 'ietf'
593 defined by [6] and extended by [7]. This URN is:
595 urn:ietf:params:xml:ns:dialog-info
597 A dialog information document begins with the root element tag
598 "dialog-info".
600 4.1 Structure of Dialog Information
602 A dialog information document starts with a dialog-info element. This
603 element has three mandatory attributes:
605 version: This attribute allows the recipient of dialog information
606 documents to properly order them. Versions start at 0, and
607 increment by one for each new document sent to a subscriber.
608 Versions are scoped within a subscription. Versions MUST be
609 representable using a 32 bit integer.
611 state: This attribute indicates whether the document contains the
612 full dialog information, or whether it contains only information
613 on those dialogs which have changed since the previous document
614 (partial).
616 entity: This attribute contains a URI that identifies the user whose
617 dialog information is reported in the remainder of the document.
618 This user is referred to as the "observed user".
620 The dialog-info element has a series of zero or more dialog
621 sub-elements. Each of those represents a specific dialog.
622
623
626
628 4.1.1 Dialog Element
630 The dialog element reports information on a specific dialog or
631 "half-dialog". It has a single mandatory attribute, id. The id
632 attribute provides a single string that can be used as an identifier
633 for this dialog or "half-dialog". This is a different identifier than
634 the dialog ID defined in RFC 3261 [2], but related to it.
636 For a caller, the id is created when an INVITE request is sent. When
637 a 1xx with a tag, or a 2xx is received, the dialog is formally
638 created. The id remains unchanged. However, if an additional 1xx or
639 2xx is received, resulting in the creation of another dialog (and
640 resulting FSM), that dialog is allocated a new id.
642 For a callee, the id is created when an INVITE outside of an existing
643 dialog is received. When a 2xx or a 1xx with a tag is sent, creating
644 the dialog, the id remains unchanged.
646 The id MUST be unique amongst all dialogs at a UA.
648 There are a number of optional attributes which provide
649 identification information about the dialog:
651 call-id: This attribute is a string which represents the call-id
652 component of the dialog identifier. (Note that single and double
653 quotes inside a call-id must be escaped using "e; for " and
654 ' for ' .)
656 OPEN ISSUE: Is it legal to include escaped quotes in XML
657 attributes?
659 local-tag: This attribute is a string which represents the local-tag
660 component of the dialog identifier.
662 remote-tag: This attribute is a string which represents the
663 remote-tag component of the dialog identifier. The remote tag
664 attribute won't be present if there is only a "half-dialog",
665 resulting from the generation of an INVITE for which no final
666 responses or provisional responses with tags has been received.
668 direction: This attribute is either initiator or recipient, and
669 indicates whether the observed user was the initiator of the
670 dialog, or the recipient of the INVITE that created it.
672
673
676
680
682 The sub-elements of the dialog element provide additional information
683 about the dialog. Some of these sub-elements provide more detail
684 about the dialog itself, while the local and remote sub-elements
685 describe characteristics of the participants involved in the dialog.
686 The only mandatory sub-element is the state element.
688 4.1.2 State
690 The state element indicates the state of the dialog. Its value is an
691 enumerated type describing one of the states in the FSM above. It has
692 an optional event attribute that can be used to indicate the event
693 which caused any transition into the terminated state, and an
694 optional code attribute that indicates the response code associated
695 with any transition caused by a response to the original INVITE.
696 terminated
698 4.1.3 Duration
700 The duration element contains the amount of time, in seconds, since
701 the FSM was created.
702 145
704 4.1.4 Replaces
706 The replaces element is used to correlate a new dialog with one it
707 replaced as a result of an invitation with a Replaces header. This
708 element is present in the replacement dialog only (the newer dialog)
709 and contains attributes with the call-id, local-tag, and remote-tag
710 of the replaced dialog.
711
713 4.1.5 Referred-By
715 The referred-by element is used to correlate a new dialog with a
716 REFER [12] request which triggered it. The element is present in a
717 dialog which was triggered by a REFER request which contained a
718 Referred-By [11] header and contains the (optional) display name
719 attribute and the Referred-By URI as its value.
720 sip:bob@example.com
722 4.1.6 Route-Set
724 The route-set element conveys an ordered list of hop elements which
725 represents the complete route set of the dialog (not including the
726 local and remote target URIs) from the perspective of the notifier.
728 OPEN ISSUE: Does any one want/need this?
730
731 sip:proxy1.example.net;lr
732 sip:proxy2.example.com;lr
733
735 4.1.6.1 Local and Remote elements
737 The local and remote elements are sub-elements of the dialog element
738 which contain information about the local and remote participants
739 respectively. They both have a number of optional sub-elements which
740 indicate the identity conveyed by the participant, the target URI,
741 the feature-tags of the target, and the session-description of the
742 participant.
744 4.1.6.1.1 Identity
746 The identity element indicates a local or remote URI, as defined in
747 [2] as appropriate. It has an optional attribute, display-name, that
748 contains the display name from the appropriate URI.
750 Note that multiple identities (for example a sip: URI and a tel:
751 URI) could be included if they all correspond to the participant.
753 sip:anonymous@anonymous.invalid
755 4.1.6.1.2 Target
757 The target contains the local or remote target URI as constructed by
758 the user agent for this dialog, as defined in RFC 3261 [2] in a "uri"
759 attribute.
761 It can contain a list of Contact header parameters in param
762 sub-elements (such as those defined in [10]. The param element
763 contains a required pname attribute and an optional pval attribute
764 (some parameters merely exist and have no explicit value). The param
765 element itself has no contents.
766
767
768
769
771 4.1.6.1.3 Session Description
773 The session-description element contains the session description used
774 by the observed user for its end of the dialog. This element should
775 generally NOT be included in the notifications, unless explicitly
776 requested by the subscriber. It has a single attribute, type, which
777 indicates the MIME media type of the session description.
779 4.1.6.1.4 CSeq
781 The cseq element contains the most recent value of the CSeq header
782 used by the UA in an outgoing request on the dialog. This element
783 should generally NOT be included in the notifications, unless
784 explicitly requested by the subscriber. If no CSeq has yet been
785 defined, the value of the element is -1.
787 OPEN ISSUE: Is this really useful?
789 4.2 Constructing Coherent State
791 The dialog information subscriber maintains a table for the list of
792 dialogs. The table contains a row for each dialog. Each row is
793 indexed by an ID, present in the "id" attribute of the "dialog"
794 element. The contents of each row contain the state of that dialog as
795 conveyed in the document. The table is also associated with a version
796 number. The version number MUST be initialized with the value of the
797 "version" attribute from the "dialog-info" element in the first
798 document received. Each time a new document is received, the value of
799 the local version number, and the "version" attribute in the new
800 document, are compared. If the value in the new document is one
801 higher than the local version number, the local version number is
802 increased by one, and the document is processed. If the value in the
803 document is more than one higher than the local version number, the
804 local version number is set to the value in the new document, and the
805 document is processed. If the document did not contain full state,
806 the subscriber SHOULD generate a refresh request to trigger a full
807 state notification. If the value in the document is less than the
808 local version, the document is discarded without processing.
810 The processing of the dialog information document depends on whether
811 it contains full or partial state. If it contains full state,
812 indicated by the value of the "state" attribute in the "dialog-info"
813 element, the contents of the table are flushed. They are repopulated
814 from the document. A new row in the table is created for each
815 "dialog" element. If the document contains partial state, as
816 indicated by the value of the "state" attribute in the "dialog-info"
817 element, the document is used to update the table. For each "dialog"
818 element in the document, the subscriber checks to see whether a row
819 exists for that dialog. This check is done by comparing the ID in the
820 "id" attribute of the "dialog" element with the ID associated with
821 the row. If the dialog doesn't exist in the table, a row is added,
822 and its state is set to the information from that "dialog" element.
823 If the dialog does exist, its state is updated to be the information
824 from that "dialog" element. If a row is updated or created, such that
825 its state is now terminated, that entry MAY be removed from the table
826 at any time.
828 4.3 Schema
830 The following is the schema for the application/dialog-info+xml type:
832
833
839
840
842
843
844
845
847
850
851
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
870
871
872
874
876
878
879
880
882
883
884
885
887
888
889
890
892
894
896
897
898
900
902
904
905
906
907
908
909
910
911
912
913
914
915
916
918
919
920
921
923
924
926
928
929
930
931
932
933
934
936
938
940
941
942
943
944
945
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
988 4.4 Example
990 For example, if a UAC sends an INVITE that looks like, in part:
992 INVITE sip:bob@example.com SIP/2.0
993 Via: SIP/2.0/UDP pc33.example.com;branch=z9hG4bKnashds8
994 Max-Forwards: 70
995 To: Bob
996 From: Alice ;tag=1928301774
997 Call-ID: a84b4c76e66710
998 CSeq: 314159 INVITE
999 Contact:
1000 Content-Type: application/sdp
1001 Content-Length: 142
1003 [SDP not shown]
1005 The XML document in a notification from Alice might look like:
1007
1008
1012
1016
1018 If the following 180 response is received:
1020 SIP/2.0 180 Ringing
1021 Via: SIP/2.0/UDP pc33.example.com;branch=z9hG4bKnashds8
1022 To: Bob ;tag=456887766
1023 From: Alice ;tag=1928301774
1024 Call-ID: a84b4c76e66710
1025 CSeq: 314159 INVITE
1026 Contact:
1028 The XML document in a notification might look like:
1030
1031
1035
1040
1042 If it receives a second 180 with a different tag:
1044 SIP/2.0 180 Ringing
1045 Via: SIP/2.0/UDP pc33.example.com;branch=z9hG4bKnashds8
1046 To: Bob ;tag=hh76a
1047 From: Alice ;tag=1928301774
1048 Call-ID: a84b4c76e66710
1049 CSeq: 314159 INVITE
1050 Contact:
1052 This results in the creation of a second dialog:
1054
1055
1059
1064
1069
1071 If a 200 OK is received on the second dialog, it moves to confirmed:
1073
1074
1078
1084
1086 32 seconds later, the other early dialog terminates because no 2xx is
1087 received for it. This implies that it was successfully cancelled, and
1088 therefore the following notification is sent:
1090
1091
1095
1100
1102 EDITORS NOTE: should provide another example with a richer
1103 notification
1105
1106
1110
1125
1127 5. Security Considerations
1129 Subscriptions to dialog state can reveal sensitive information. For
1130 this reason, Section 3.6 discusses authentication and authorization
1131 of subscriptions, and provides guidelines on sensible authorization
1132 policies. All implementations of this package MUST support the digest
1133 authentication mechanism.
1135 Since the data in notifications is sensitive as well, end-to-end SIP
1136 encryption mechanisms using S/MIME MAY be used to protect it.
1138 6. IANA Considerations
1140 This document registers a new MIME type, application/dialog-info+xml
1141 and registers a new XML namespace.
1143 6.1 application/dialog-info+xml MIME Registration
1145 MIME media type name: application
1147 MIME subtype name: dialog-info+xml
1149 Mandatory parameters: none
1151 Optional parameters: Same as charset parameter application/xml as
1152 specified in RFC 3023 [8].
1154 Encoding considerations: Same as encoding considerations of
1155 application/xml as specified in RFC 3023 [8].
1157 Security considerations: See Section 10 of RFC 3023 [8] and Section 5
1158 of this specification.
1160 Interoperability considerations: none.
1162 Published specification: This document.
1164 Applications which use this media type: This document type has been
1165 used to support SIP applications such as call return and
1166 auto-conference.
1168 Additional Information:
1170 Magic Number: None
1172 File Extension: .dif or .xml
1173 Macintosh file type code: "TEXT"
1175 Personal and email address for further information: Jonathan
1176 Rosenberg,
1178 Intended usage: COMMON
1180 Author/Change controller: The IETF.
1182 6.2 URN Sub-Namespace Registration for
1183 urn:ietf:params:xml:ns:dialog-info
1185 This section registers a new XML namespace, as per the guidelines in
1186 [7].
1188 URI: The URI for this namespace is
1189 urn:ietf:params:xml:ns:dialog-info.
1191 Registrant Contact: IETF, SIPPING working group, ,
1192 Jonathan Rosenberg .
1194 XML:
1196 BEGIN
1197
1198
1200
1201
1202
1204 Dialog Information Namespace
1205
1207 Namespace for Dialog Information
1208 urn:ietf:params:xml:ns:dialog-info
1209 See RFCXXXX.
1210
1211