generally going to be provisioned for a reasonable signalling volume;
sending a notification every time a user's GPS position changes by
one hundredth of a second could easily overload such a network.
4.2. Event Template-packages
Normal event packages define a set of state applied to a specific
type of resource, such as user presence, call state, and messaging
mailbox state.
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.
To extend the object-oriented analogy made earlier, event template-
packages can be thought of as templatized C++ packages which must be
applied to other packages to be useful.
The name of an event template-package as applied to a package is
formed by appending a period followed by the event template-package
name to the end of the package. 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".
Event template-packages must be defined so that they can be applied
to any arbitrary package. In other words, event template-packages
cannot be specifically tied to one or a few "parent" packages in such
a way that they will not work with other packages.
4.3. Amount of State to be Conveyed
When designing event packages, it is important to consider the type
of information which will be conveyed during a notification.
A natural temptation is to convey merely the event (e.g., "a new
voice message just arrived") without accompanying state (e.g., "7
total voice messages"). This complicates implementation of
subscribing entities (since they have to maintain complete state for
the entity to which they have subscribed), and also is particularly
susceptible to synchronization problems.
There are two possible solutions to this problem that event packages
may choose to implement.
4.3.1. Complete State Information
For packages which typically convey state information that is
reasonably small (on the order of 1 kb or so), it is suggested that
event packages are designed so as to send complete state information
when an event occurs.
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. For example, conveying "no customer service
representatives available" may not be as useful as conveying "no
customer service representatives available; representative
sip:46@cs.xyz.int just logged off".
4.3.2. State Deltas
In the case that the state information to be conveyed is large, the
event package may choose to detail a scheme by which NOTIFY messages
contain state deltas instead of complete state.
Such a scheme would work as follows: 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.
4.4. Event Package Responsibilities
Event packages are not required to reiterate any of the behavior
described in this document, although they may choose to do so for
clarity or emphasis. In general, though, such packages are
expected to describe only the behavior that extends or modifies
the behavior described in this document.
Note that any behavior designated with "SHOULD" or "MUST" in this
document is not allowed to be weakened by extension documents;
however, such documents may elect to strengthen "SHOULD"
requirements to "MUST" strength if required by their application.
In addition to the normal sections expected in standards-track
RFCs and SIP extension documents, authors of event packages need
to address each of the issues detailed in the following
subsections, whenever applicable.
4.4.1. 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. For information
on registering such types, see section 6.
4.4.2. 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.
4.4.3. 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.
This mandatory section of an event package defines what type or types
of event bodies are expected in SUBSCRIBE requests (or specify that
no event bodies are expected). It should point to detailed
definitions of syntax and semantics for all referenced body types.
4.4.4. 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.
4.4.5. 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.
4.4.6. 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.).
4.4.7. 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.
4.4.8. 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).
4.4.9. Handling of forked requests
Each event package MUST specify whether forked SUBSCRIBE requests are
allowed to install multiple subscriptions.
If such behavior is not allowed, 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. Note that the 200-class
response to the SUBSCRIBE can arrive after a matching NOTIFY has been
received; such responses might not correlate to the same dialog
established by the NOTIFY. Except as required to complete the
SUBSCRIBE transaction, such non-matching 200-class responses are
ignored.
If installing of multiple subscriptions by way of a single forked
SUBSCRIBE is allowed, 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.
In the case that multiple subscriptions are allowed, 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.
Note that it is possible that some event packages may be defined in
such a way that each dialog is tied to a mutually exclusive state
which is unaffected by the other dialogs; this MUST be clearly stated
if it is the case.
4.4.10. Rate of notifications
Each event package is expected to define a requirement (SHOULD or
MUST strength) which 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.
4.4.11. State Agents
Designers of event packages should consider whether their package can
benefit from network aggregation points (state agents) and/or nodes
which act on behalf of other nodes. (For example, nodes which
provide state information about a resource when such a resource is
unable or unwilling to provide such state information itself). An
example of such an application is a node which tracks the presence
and availability of a user in the network.
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.
4.4.12. 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.
4.4.13. 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.
The precise mechanisms for conveying such URIs are out of the scope
of this document.
5. Security Considerations
5.1. Access Control
The ability to accept subscriptions should be under the direct
control of the notifier's user, since many types of events may be
considered sensitive for the purposes of privacy. Similarly, the
notifier should have the ability to selectively reject subscriptions
based on the subscriber identity (based on access control lists),
using standard SIP authentication mechanisms. The methods for
creation and distribution of such access control lists is outside the
scope of this document.
5.2. Notifier Privacy Mechanism
The mere act of returning a 200 or certain 4xx and 6xx responses to
SUBSCRIBE requests may, under certain circumstances, create privacy
concerns by revealing sensitive policy information. In these cases,
the notifier SHOULD always return a 202 response. While the
subsequent NOTIFY message may not convey true state, it MUST appear
to contain a potentially correct piece of data from the point of view
of the subscriber, indistinguishable from a valid response.
Information about whether a user is authorized to subscribe to the
requested state is never conveyed back to the original user under
these circumstances.
Individual packages and their related documents for which such a mode
of operation makes sense can further describe how and why to generate
such potentially correct data. For example, such a mode of operation
is mandated by RFC2779 [6] for user presence information.
5.3. Denial-of-Service attacks
The current model (one SUBSCRIBE request triggers a SUBSCRIBE
response and one or more NOTIFY requests) is a classic setup for an
amplifier node to be used in a smurf attack.
Also, the creation of state upon receipt of a SUBSCRIBE request can
be used by attackers to consume resources on a victim's machine,
rendering it unusable.
To reduce the chances of such an attack, implementations of notifiers
SHOULD require authentication. Authentication issues are discussed
in SIP [1].
5.4. Replay Attacks
Replaying of either SUBSCRIBE or NOTIFY can have detrimental effects.
In the case of SUBSCRIBE messages, attackers may be able to install
any arbitrary subscription which it witnessed being installed at some
point in the past. Replaying of NOTIFY messages may be used to spoof
old state information (although a good versioning mechanism in the
body of the NOTIFY messages may help mitigate such an attack). Note
that the prohibition on sending NOTIFY messages to nodes which have
not subscribed to an event also aids in mitigating the effects of
such an attack.
To prevent such attacks, implementations SHOULD require
authentication with anti-replay protection. Authentication issues
are discussed in SIP [1].
5.5. Man-in-the middle attacks
Even with authentication, man-in-the-middle attacks using SUBSCRIBE
may be used to install arbitrary subscriptions, hijack existing
subscriptions, terminate outstanding subscriptions, or modify the
resource to which a subscription is being made. To prevent such
attacks, implementations SHOULD provide integrity protection across
"Contact", "Route", "Expires", "Event", and "To" headers of SUBSCRIBE
messages, at a minimum. If SUBSCRIBE bodies are used to define
further information about the state of the call, they SHOULD be
included in the integrity protection scheme.
Man-in-the-middle attacks may also attempt to use NOTIFY messages to
spoof arbitrary state information and/or terminate outstanding
subscriptions. To prevent such attacks, implementations SHOULD
provide integrity protection across the "Call-ID", "CSeq", and
"Subscription-State" headers and the bodies of NOTIFY messages.
Integrity protection of message headers and bodies is discussed in
SIP [1].
5.6. Confidentiality
The state information contained in a NOTIFY message has the potential
to contain sensitive information. Implementations MAY encrypt such
information to ensure confidentiality.
While less likely, it is also possible that the information contained
in a SUBSCRIBE message contains information that users might not want
to have revealed. Implementations MAY encrypt such information to
ensure confidentiality.
To allow the remote party to hide information it considers sensitive,
all implementations SHOULD be able to handle encrypted SUBSCRIBE and
NOTIFY messages.
The mechanisms for providing confidentiality are detailed in SIP [1].
6. IANA Considerations
This document defines an event-type namespace which requires a
central coordinating body. The body chosen for this coordination is
the Internet Assigned Numbers Authority (IANA).
There are two different types of event-types: normal event packages,
and event template-packages; see section 4.2. To avoid confusion,
template-package names and package names share the same namespace; in
other words, an event template-package MUST NOT share a name with a
package.
Following the policies outlined in "Guidelines for Writing an IANA
Considerations Section in RFCs" [4], normal event package
identification tokens are allocated as First Come First Served, and
event template-package identification tokens are allocated on a IETF
Consensus basis.
Registrations with the IANA MUST include the token being registered
and whether the token is a package or a template-package. Further,
packages MUST include contact information for the party responsible
for the registration and/or a published document which describes the
event package. Event template-package token registrations MUST
include a pointer to the published RFCwhich defines the event
template-package.
Registered tokens to designate packages and template-packages MUST
NOT contain the character ".", which is used to separate template-
packages from packages.
6.1. Registration Information
As this document specifies no package or template-package names, the
initial IANA registration for event types will be empty. The
remainder of the text in this section gives an example of the type of
information to be maintained by the IANA; it also demonstrates all
five possible permutations of package type, contact, and reference.
The table below lists the event packages and template-packages
defined in "SIP-Specific Event Notification" [RFC3265]. Each name is
designated as a package or a template-package under "Type".
Package Name Type Contact Reference
------------ ---- ------- ---------
example1 package [Roach]
example2 package [Roach] [RFC3265]
example3 package [RFC3265]
example4 template [Roach] [RFC3265]
example5 template [RFC3265]
PEOPLE
------
[Roach] Adam Roach <adam@dynamicsoft.com>
REFERENCES
----------
[RFC3265] Roach, A., "SIP-Specific Event Notification", RFC3265,
June 2002.
6.2. Registration Template
To: ietf-sip-events@iana.org
Subject: Registration of new SIP event package
Package Name:
(Package names must conform to the syntax described in
section 7.2.1.)
Is this registration for a Template Package:
(indicate yes or no)
Published Specification(s):
(Template packages require a published RFC. Other packages
may reference a specification when appropriate).
Person & email address to contact for further information:
6.3. Header Field Names
This document registers three new header field names, described
elsewhere in this document. These headers are defined by the
following information, which is to be added to the header sub-
registry under http://www.iana.org/assignments/sip-parameters.
Header Name: Allow-Events
Compact Form: u
Header Name: Subscription-State
Compact Form: (none)
Header Name: Event
Compact Form: o
6.4. Response Codes
This document registers two new response codes. These response codes
are defined by the following information, which is to be added to the
method and response-code sub-registry under
http://www.iana.org/assignments/sip-parameters.
Response Code Number: 202
Default Reason Phrase: Accepted
Response Code Number: 489
Default Reason Phrase: Bad Event
7. Syntax
This section describes the syntax extensions required for event
notification in SIP. Semantics are described in section 3. Note
that the formal syntax definitions described in this document are
expressed in the ABNF format used in SIP [1], and contain references
to elements defined therein.
7.1. New Methods
This document describes two new SIP methods: SUBSCRIBE and
NOTIFY.
This table expands on tables 2 and 3 in SIP [1].
Header Where SUB NOT
------ ----- --- ---
Accept R o o
Accept 2xx - -
Accept 415 o o
Accept-Encoding R o o
Accept-Encoding 2xx - -
Accept-Encoding 415 o o
Accept-Language R o o
Accept-Language 2xx - -
Accept-Language 415 o o
Alert-Info R - -
Alert-Info 180 - -
Allow R o o
Allow 2xx o o
Allow r o o
Allow 405 m m
Authentication-Info 2xx o o
Authorization R o o
Call-ID c m m
Contact R m m
Contact 1xx o o
Contact 2xx m o
Contact 3xx m m
Contact 485 o o
Content-Disposition o o
Content-Encoding o o
Content-Language o o
Content-Length t t
Content-Type * *
CSeq c m m
Date o o
Error-Info 300-699 o o
Expires o -
Expires 2xx m -
From c m m
In-Reply-To R - -
Max-Forwards R m m
Min-Expires 423 m -
MIME-Version o o
Organization o -
Priority R o -
Proxy-Authenticate 407 m m
Proxy-Authorization R o o
Proxy-Require R o o
RAck R - -
Record-Route R o o
Record-Route 2xx,401,484 o o
Reply-To - -
Require o o
Retry-After 404,413,480,486 o o
Retry-After 500,503 o o
Retry-After 600,603 o o
Route R c c
RSeq 1xx o o
Server r o o
Subject R - -
Supported R o o
Supported 2xx o o
Timestamp o o
To c(1) m m
Unsupported 420 o o
User-Agent o o
Via c m m
Warning R - o
Warning r o o
WWW-Authenticate 401 m m
7.1.1. SUBSCRIBE method
"SUBSCRIBE" is added to the definition of the element "Method" in the
SIP message grammar.
Like all SIP method names, the SUBSCRIBE method name is case
sensitive. The SUBSCRIBE method is used to request asynchronous
notification of an event or set of events at a later time.
7.1.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 earlier SUBSCRIBE method has occurred. It
may also provide further details about the event.
7.2. New Headers
This table expands on tables 2 and 3 in SIP [1], as amended by the
changes described in section 7.1.
Header field where proxy ACK BYE CAN INV OPT REG PRA SUB NOT
-----------------------------------------------------------------
Allow-Events R o o - o o o o o o
Allow-Events 2xx - o - o o o o o o
Allow-Events 489 - - - - - - - m m
Event R - - - - - - - m m
Subscription-State R - - - - - - - - m
7.2.1. "Event" header
Event is added to the definition of the element "message-header" in
the SIP message grammar.
For the purposes of matching responses and NOTIFY messages with
SUBSCRIBE messages, the event-type portion of the "Event" header is
compared byte-by-byte, and the "id" parameter token (if present) is
compared byte-by-byte. An "Event" header containing an "id"
parameter never matches an "Event" header without an "id" parameter.
No other parameters are considered when performing a comparison.
Note that the forgoing text means that "Event: foo; id=1234" would
match "Event: foo; param=abcd; id=1234", but not "Event: foo" (id
does not match) or "Event: Foo; id=1234" (event portion does not
match).
This document does not define values for event-types. These values
will be defined by individual event packages, and MUST be registered
with the IANA.
There MUST be exactly one event type listed per event header.
Multiple events per message are disallowed.
7.2.2. "Allow-Events" Header
Allow-Events is added to the definition of the element "general-
header" in the SIP message grammar. Its usage is described in
section 3.3.7.
7.2.3. "Subscription-State" Header
Subscription-State is added to the definition of the element
"request-header" in the SIP message grammar. Its usage is described
in section 3.2.4.
7.3. New Response Codes
7.3.1. "202 Accepted" Response Code
The 202 response is added to the "Success" header field definition.
"202 Accepted" has the same meaning as that defined in HTTP/1.1 [3].
7.3.2. "489 Bad Event" Response Code
The 489 event response is added to the "Client-Error" header field
definition. "489 Bad Event" is used to indicate that the server did
not understand the event package specified in a "Event" header field.
7.4. Augmented BNF Definitions
The Augmented BNF definitions for the various new and modified syntax
elements follows. The notation is as used in SIP [1], and any
elements not defined in this section are as defined in SIP and the
documents to which it refers.
SUBSCRIBEm = %x53.55.42.53.43.52.49.42.45 ; SUBSCRIBE in caps
NOTIFYm = %x4E.4F.54.49.46.59 ; NOTIFY in caps
extension-method = SUBSCRIBEm / NOTIFYm / token
Event = ( "Event" / "o" ) HCOLON event-type
*( SEMI event-param )
event-type = event-package *( "." event-template )
event-package = token-nodot
event-template = token-nodot
token-nodot = 1*( alphanum / "-" / "!" / "%" / "*"
/ "_" / "+" / "`" / "'" / "~" )
event-param = generic-param / ( "id" EQUAL token )
Allow-Events = ( "Allow-Events" / "u" ) HCOLON event-type
*(COMMA event-type)
Subscription-State = "Subscription-State" HCOLON substate-value
*( SEMI subexp-params )
substate-value = "active" / "pending" / "terminated"
/ extension-substate
extension-substate = token
subexp-params = ("reason" EQUAL event-reason-value)
/ ("expires" EQUAL delta-seconds)
/ ("retry-after" EQUAL delta-seconds)
/ generic-param
event-reason-value = "deactivated"
/ "probation"
/ "rejected"
/ "timeout"
/ "giveup"
/ "noresource"
/ event-reason-extension
event-reason-extension = token
8. Normative References
[1] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP:
Session Initiation Protocol", RFC3261, June 2002.
[2] Petrack, S. and L. Conroy, "The PINT Service Protocol", RFC
2848, June 2000.
[3] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", RFC2616, June 1999.
[4] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
Considerations Section in RFCs", BCP 26, RFC2434, October
1998.
[5] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement
Levels", BCP 14, RFC2119, March 1997.
[6] Day, M., Aggarwal, S., Mohr, G. and J. Vincent, "Instant
Messaging/Presence Protocol Requirements", RFC2779, February
2000.
9. Informative References
[7] Rosenberg, J. and H. Schulzrinne, "Guidelines for Authors of
SIP Extensions", Work in Progress.
[8] Schulzrinne, H. and J. Rosenberg, "SIP Caller Preferences and
Callee Capabilities", Work in Progress.
10. Acknowledgements
Thanks to the participants in the Events BOF at the 48th IETF meeting
in Pittsburgh, as well as those who gave ideas and suggestions on the
SIP Events mailing list. In particular, I wish to thank Henning
Schulzrinne of Columbia University for coming up with the final
three-tiered event identification scheme, Sean Olson for
miscellaneous guidance, Jonathan Rosenberg for a thorough scrubbing
of the -00 draft, and the authors of the "SIP Extensions for
Presence" document for their input to SUBSCRIBE and NOTIFY request
semantics.
11. Notice Regarding Intellectual Property Rights
The IETF has been notified of intellectual property rights claimed in
regard to some or all of the specification contained in this
document. For more information, consult the online list of claimed
rights at http://www.ietf.org/ipr.html
12. Author's Address
Adam Roach
dynamicsoft
5100 Tennyson Parkway
Suite 1200
Plano, TX 75024
USA
EMail: adam@dynamicsoft.com
Voice: sip:adam@dynamicsoft.com
13. Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFCEditor function is currently provided by the
Internet Society.