compelling need for a subscription to registration information to
fork. As a result, a subscriber MUST NOT create multiple dialogs as
a result of a single subscription request. The required processing
to guarantee that only a single dialog is established is described in
Section 4.4.9 of the SIP Events framework [2].
4.10. Rate of Notifications
The SIP Events framework mandates that packages define a maximum rate
of notifications for their package.
For reasons of congestion control, it is important that the rate of
notifications not become excessive. As a result, it is RECOMMENDED
that the server not generate notifications for a single subscriber at
a rate faster than once every 5 seconds.
4.11. State Agents
The SIP Events framework asks packages to consider the role of state
agents in their design.
State agents have no role in the handling of this package.
5. Registration Information
5.1. Structure of Registration Information
Registration information is an XML document [4] that MUST be
well-formed and SHOULD be valid. Registration information documents
MUST be based on XML 1.0 and MUST be encoded using UTF-8. This
specification makes use of XML namespaces for identifying
registration information documents and document fragments. The
namespace URI for elements defined by this specification is a URN
[5], using the namespace identifier ’ietf’ defined by [6] and
extended by [7]. This URN is:
urn:ietf:params:xml:ns:reginfo
A registration information document begins with the root element tag
"reginfo". It consists of any number of "registration" sub-elements,
each of which contains the registration state for a particular
address-of-record. The registration information for a particular
address-of-record MUST be contained within a single "registration"
element; it cannot be spread across multiple "registration" elements
within a document. Other elements from different namespaces MAY be
present for the purposes of extensibility; elements or attributes
from unknown namespaces MUST be ignored. There are two attributes
associated with the "reginfo" element, both of which MUST be present:
version: This attribute allows the recipient of registration
information documents to properly order them. Versions
start at 0, and increment by one for each new document
sent to a subscriber. Versions are scoped within a
subscription. Versions MUST be representable using a
32 bit integer.
state: This attribute indicates whether the document contains
the full registration state, or whether it contains
only information on those registrations which have
changed since the previous document (partial).
Note that the document format explicitly allows for conveying
information on multiple addresses-of-record. This enables
subscriptions to groups of registrations, where such a group is
identified by some kind of URI. For example, a domain might define
sip:allusers@example.com as a subscribable resource that generates
notifications when the state of any address-of-record in the domain
changes.
The "registration" element has a list of any number of "contact"
sub-elements, each of which contains information on a single contact.
Other elements from different namespaces MAY be present for the
purposes of extensibility; elements or attributes from unknown
namespaces MUST be ignored. There are three attributes associated
with the "registration" element, all of which MUST be present:
aor: The aor attribute contains a URI which is the address-of-
record this registration refers to.
id: The id attribute identifies this registration. It MUST be
unique amongst all other id attributes present in other
registration elements conveyed to the subscriber within the
scope of their subscription. In particular, if two URI
identifying an address-of-record differ after their
canonicalization according to the procedures in step 5 of
Section 10.3 of RFC 3261 [1], the id attributes in the
"registration" elements for those addresses-of-record MUST
differ. Furthermore, the id attribute for a "registration"
element for a particular address-of-record MUST be the same
across all notifications sent within the subscription.
state: The state attribute indicates the state of the
registration. The valid values are "init", "active" and
"terminated".
The "contact" element contains a "uri" element, an optional
"display-name" element, and an optional "unknown-param" element.
Other elements from different namespaces MAY be present for the
purposes of extensibility; elements or attributes from unknown
namespaces MUST be ignored. There are several attributes associated
with the "contact" element which MUST be present:
id: The id attribute identifies this contact. It MUST be
unique amongst all other id attributes present in other
contact elements conveyed to the subscriber within the
scope of their subscription. In particular, if the URI for
two contacts differ (based on the URI comparison rules in
RFC 3261 [1]), the id attributes for those contacts MUST
differ. However, unlike the id attribute for an address-
of-record, if the URI for two contacts are the same, their
id attributes SHOULD be the same across notifications.
This requirement is at SHOULD strength, and not MUST
strength, since it is difficult to compute such an id as a
function of the URI without retaining additional state. No
hash function applied to the URI can, in fact, meet a MUST
requirement. This is because equality of the SIP URI is
not transitive. However, a hash function which includes
unknown URI parameters (that is, any not defined in RFC
3261), will always result in a value that is the different
if two URI are different, and usually the same if the URI
are equal.
state: The state attribute indicates the state of the contact.
The valid values are "active" and "terminated".
event: The event attribute indicates the event which caused the
contact state machine to go into its current state. Valid
values are registered, created, refreshed, shortened,
expired, deactivated, probation, unregistered and rejected.
If the event attribute has a value of shortened, the "expires"
attribute MUST be present. It contains an unsigned long integer
which indicates the number of seconds remaining until the binding is
due to expire. This attribute MAY be included with any event
attribute value for which the state of the contact is active.
If the event attribute has a value of probation, the "retry-after"
attribute MUST be present. It contains an unsigned long integer
which indicates the amount of seconds after which the owner of the
contact is expected to retry its registration.
The optional "duration-registered" attribute conveys the amount of
time that the contact has been bound to the address-of-record, in
seconds. The optional "q" attribute conveys the relative priority of
this contact compared to other registered contacts. The optional
"callid" attribute contains the current Call-ID carried in the
REGISTER that was last used to update this contact, and the optional
"cseq" attribute contains the last CSeq value present in a REGISTER
request that updated this contact value.
The "uri" element contains the URI associated with that contact. The
"display-name" element contains the display name for the contact.
The "display-name" element MAY contain the xml:lang attribute to
indicate the language of the display name.
The "unknown-param" element is used to convey contact header field
parameters that are not specified in RFC 3261. One example are the
user agent capability parameters specified in [11]. Each "unknown-
param" element describes a single contact header field parameter.
The name of the parameter is contained in the mandatory name
attribute of the "unknown-param" element, and the value of the
parameter is the content of the "unknown-param" element. For contact
header field parameters that have no value, the content of the
"unknown-param" element is empty.
5.2. Computing Registrations from the Document
Typically, the NOTIFY for registration information will only contain
information about those contacts whose state has changed. To
construct a coherent view of the total state of all registrations, a
subscriber will need to combine NOTIFYs received over time. The
subscriber maintains a table for each registration it receives
information for. Each registration is uniquely identified by the
"id" attribute in the "registration" element. Each table contains a
row for each contact in that registration. Each row is indexed by
the unique ID for that contact. It is conveyed in the "id" attribute
of the "contact" element. The contents of each row contain the state
of that contact as conveyed in the "contact" element. The tables are
also associated with a version number. The version number MUST be
initialized with the value of the "version" attribute from the
"reginfo" element in the first document received. Each time a new
document is received, the value of the local version number, and the
"version" attribute in the new document, are compared. If the value
in the new document is one higher than the local version number, the
local version number is increased by one, and the document is
processed. If the value in the document is more than one higher than
the local version number, the local version number is set to the
value in the new document, the document is processed, and the
subscriber SHOULD generate a refresh request to trigger a full state
notification. If the value in the document is less than the local
version, the document is discarded without processing.
The processing of the document depends on whether it contains full or
partial state. If it contains full state, indicated by the value of
the "state" attribute in the "reginfo" element, the contents of all
tables associated with this subscription are flushed. They are
re-populated from the document. A new table is created for each
"registration" element, and a new row in each table is created for
each "contact" element. If the reginfo contains partial state, as
indicated by the value of the "state" attribute in the "reginfo"
element, the document is used to update the existing tables. For
each "registration" element, the subscriber checks to see if a table
exists for that registration. This check is done by comparing the
value in the "id" attribute of the "registration" element with the ID
associated with the table. If a table doesn’t exist for that
registration, one is created. For each "contact" element in the
registration, the subscriber checks to see whether a row exists for
that contact. This check is done by comparing the ID in the "id"
attribute of the "contact" element with the ID associated with the
row. If the contact doesn’t exist in the table, a row is added, and
its state is set to the information from that "contact" element. If
the contact does exist, its state is updated to be the information
from that "contact" element. If a row is updated or created, such
that its state is now terminated, that entry MAY be removed from the
table at any time.
5.3. Example
The following is an example registration information document:
<?xml version="1.0"?>
<reginfo xmlns="urn:ietf:params:xml:ns:reginfo"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
version="0" state="full">
<registration aor="sip:user@example.com" id="as9"
state="active">
<contact id="76" state="active" event="registered"
duration-registered="7322"
q="0.8">
<uri>sip:user@pc887.example.com</uri>
</contact>
<contact id="77" state="terminated" event="expired"
duration-registered="3600"
q="0.5">
<uri>sip:user@university.edu</uri>
</contact>
</registration>
</reginfo>
5.4. XML Schema
The following is the schema definition of the reginfo format:
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:ietf:params:xml:ns:reginfo"
xmlns:tns="urn:ietf:params:xml:ns:reginfo"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<!-- This import brings in the XML language attribute xml:lang-->
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/03/xml.xsd"/>
<xs:element name="reginfo">
<xs:complexType>
<xs:sequence>
<xs:element ref="tns:registration" minOccurs="0"
maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="version" type="xs:nonNegativeInteger"
use="required"/>
<xs:attribute name="state" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="full"/>
<xs:enumeration value="partial"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="registration">
<xs:complexType>
<xs:sequence>
<xs:element ref="tns:contact" minOccurs="0" maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="aor" type="xs:anyURI" use="required"/>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="state" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="init"/>
<xs:enumeration value="active"/>
<xs:enumeration value="terminated"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name="contact">
<xs:complexType>
<xs:sequence>
<xs:element name="uri" type="xs:anyURI"/>
<xs:element name="display-name" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute ref="xml:lang" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="unknown-param" minOccurs="0"
maxOccurs="unbounded">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="state" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="active"/>
<xs:enumeration value="terminated"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="event" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="registered"/>
<xs:enumeration value="created"/>
<xs:enumeration value="refreshed"/>
<xs:enumeration value="shortened"/>
<xs:enumeration value="expired"/>
<xs:enumeration value="deactivated"/>
<xs:enumeration value="probation"/>
<xs:enumeration value="unregistered"/>
<xs:enumeration value="rejected"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="duration-registered" type="xs:unsignedLong"/>
<xs:attribute name="expires" type="xs:unsignedLong"/>
<xs:attribute name="retry-after" type="xs:unsignedLong"/>
<xs:attribute name="id" type="xs:string" use="required"/>
<xs:attribute name="q" type="xs:string"/>
<xs:attribute name="callid" type="xs:string"/>
<xs:attribute name="cseq" type="xs:unsignedLong"/>
</xs:complexType>
</xs:element>
</xs:schema>
6. Example Call Flow
User Registrar Application
| |(1) SUBSCRIBE |
| |Event:reg |
| |<------------------|
| |(2) 200 OK |
| |------------------>|
| |(3) NOTIFY |
| |------------------>|
| |(4) 200 OK |
| |<------------------|
|(5) REGISTER | |
|------------------>| |
|(6) 200 OK | |
|<------------------| |
| |(7) NOTIFY |
| |------------------>|
| |(8) 200 OK |
| |<------------------|
|(9) MESSAGE | |
|<--------------------------------------|
Figure 3: Example Call Flow
This section provides an example call flow, shown in Figure 3. It
shows an implementation of the welcome notice application described
in Section 3.3. First, the application SUBSCRIBEs to the
registration event package for the desired user (1):
SUBSCRIBE sip:joe@example.com SIP/2.0
Via: SIP/2.0/UDP app.example.com;branch=z9hG4bKnashds7
From: sip:app.example.com;tag=123aa9
To: sip:joe@example.com
Call-ID: 9987@app.example.com
CSeq: 9887 SUBSCRIBE
Contact: sip:app.example.com
Event: reg
Max-Forwards: 70
Accept: application/reginfo+xml
The registrar (which is acting as the notifier for the registration
event package) generates a 200 OK to the SUBSCRIBE:
SIP/2.0 200 OK
Via: SIP/2.0/UDP app.example.com;branch=z9hG4bKnashds7
;received=192.0.2.1
From: sip:app.example.com;tag=123aa9
To: sip:joe@example.com;tag=xyzygg
Call-ID: 9987@app.example.com
CSeq: 9987 SUBSCRIBE
Contact: sip:server19.example.com
Expires: 3600
The registrar then generates a notification (3) with the current
state. Since there is no active registration, the state of the
registration is "init":
NOTIFY sip:app.example.com SIP/2.0
Via: SIP/2.0/UDP server19.example.com;branch=z9hG4bKnasaii
From: sip:joe@example.com;tag=xyzygg
To: sip:app.example.com;tag=123aa9
Call-ID: 9987@app.example.com
CSeq: 1288 NOTIFY
Contact: sip:server19.example.com
Event: reg
Max-Forwards: 70
Content-Type: application/reginfo+xml
Content-Length: ...
<?xml version="1.0"?>
<reginfo xmlns="urn:ietf:params:xml:ns:reginfo"
version="0" state="full">
<registration aor="sip:joe@example.com" id="a7" state="init" />
</reginfo>
Later on, the user registers (5):
REGISTER sip:example.com SIP/2.0
Via: SIP/2.0/UDP pc34.example.com;branch=z9hG4bKnaaff
From: sip:joe@example.com;tag=99a8s
To: sip:joe@example.com
Call-ID: 88askjda9@pc34.example.com
CSeq: 9976 REGISTER
Contact: sip:joe@pc34.example.com
This results in a NOTIFY being generated to the application (7):
NOTIFY sip:app.example.com SIP/2.0
Via: SIP/2.0/UDP server19.example.com;branch=z9hG4bKnasaij
From: sip:joe@example.com;tag=xyzygg
To: sip:app.example.com;tag=123aa9
Call-ID: 9987@app.example.com
CSeq: 1289 NOTIFY
Contact: sip:server19.example.com
Event: reg
Max-Forwards: 70
Content-Type: application/reginfo+xml
Content-Length: ...
<?xml version="1.0"?>
<reginfo xmlns="urn:ietf:params:xml:ns:reginfo"
version="1" state="partial">
<registration aor="sip:joe@example.com" id="a7" state="active">
<contact id="76" state="active" event="registered"
duration-registered="0">
<uri>sip:joe@pc34.example.com</uri>
</contact>
</registration>
</reginfo>
The application can then send its instant message to the device (9):
MESSAGE sip:joe@pc34.example.com SIP/2.0
Via: SIP/2.0/UDP app.example.com;branch=z9hG4bKnashds8
From: sip:app.example.com;tag=123aa10
To: sip:joe@example.com
Call-ID: 9988@app.example.com
CSeq: 82779 MESSAGE
Max-Forwards: 70
Content-Type: text/plain
Content-Length: ...
Welcome to the example.com service!
7. Security Considerations
Security considerations for SIP event packages are discussed in RFC
3265 [2], and those considerations apply here.
Registration information is sensitive, potentially private,
information. Subscriptions to this event package SHOULD be
authenticated and authorized according to local policy. Some policy
guidelines are suggested in Section 4.6. In addition, notifications
SHOULD be sent in such a way to ensure confidentiality, message
integrity and verification of subscriber identity, such as sending
subscriptions and notifications using a SIPS URL or protecting the
notification bodies with S/MIME.
8. IANA Considerations
This document registers a new SIP Event Package, a new MIME type
(application/reginfo+xml), and a new XML namespace.
8.1. SIP Event Package Registration
Package name: reg
Type: package
Contact: Jonathan Rosenberg, <jdrosen@jdrosen.net>
Published Specification: RFC 3680.
8.2. application/reginfo+xml MIME Registration
MIME media type name: application
MIME subtype name: reginfo+xml
Mandatory parameters: none
Optional parameters: Same as charset parameter application/xml
as specified in RFC 3023 [8].
Encoding considerations: Same as encoding considerations of
application/xml as specified in RFC 3023 [8].
Security considerations: See Section 10 of RFC 3023 [8] and
Section 7 of this specification.
Interoperability considerations: none.
Published specification: This document.
Applications which use this media type: This document type is
being used in notifications to alert SIP user agents that
their registrations have expired and must be redone.
Additional Information:
Magic Number: None
File Extension: .rif or .xml