6. Event Package Definition
6.2. Event Package Parameters
This package defines the following new parameters for the event header:
"profile-type", "vendor", "model", "version", and "effective-by"
The following rules apply:
o All the new parameters, with the exception of the "effective-by"
parameter, MUST only be used in SUBSCRIBE requests and ignored if they appear in NOTIFY requests.
o The "effective-by" parameter is for use in NOTIFY requests only and MUST be ignored if it appears in SUBSCRIBE requests.
The semantics of these new parameters are specified in the following subsections.
6.2.1. "profile-type" Parameter
The "profile-type" parameter is used to indicate the token name of the profile type the user agent wishes to obtain and to be notified of subsequent changes. This document defines three logical types of profiles and their token names. They are as follows:
local-network: specifying the "local-network" type profile indicates the desire for profile data, and potentially, profile change
notifications specific to the local network.
device: specifying the "device" type profile(s) indicates the desire for the profile data, and potentially, profile change notification that is specific to the device or user agent.
user: specifying the "user" type profile indicates the desire for the profile data, and potentially, profile change notification specific to the user.
The profile type is identified in the Event header parameter:
"profile-type". A separate SUBSCRIBE dialog is used for each profile type. Thus, the subscription dialog on which a NOTIFY arrives
implies which profile’s data is contained in, or referred to, by the NOTIFY message body. The Accept header of the SUBSCRIBE request MUST include the MIME types for all profile content types for which the subscribing user agent wishes to retrieve profiles, or receive change notifications.
In the following syntax definition using ABNF, EQUAL and token are defined in [RFC3261]. It is to be noted that additional profile types may be defined in subsequent documents.
Profile-type = "profile-type" EQUAL profile-value profile-value = profile-types / token
profile-types = "device" / "user" / "local-network"
The "device", "user", or "local-network" token in the profile-type parameter may represent a class or set of profile properties.
Follow-on standards defining specific profile contents may find it desirable to define additional tokens for the profile-type parameter.
Also, additional content types may be defined along with the profile formats that can be used in the Accept header of the SUBSCRIBE to filter or indicate what data sets of the profile are desired.
6.2.2. "vendor", "model", and "version" Parameters
The "vendor", "model", and "version" parameter values are tokens specified by the implementer of the user agent. These parameters MUST be provided in the SUBSCRIBE request for all profile types. The implementer SHOULD use their DNS domain name (e.g., example.com) as the value of the "vendor" parameter so that it is known to be unique, unless there is a good reason not to. Examples of exceptions
include: if the vendor does not have an assigned DNS domain name, if they are using a different vendor’s implementation, etc. These
parameters are useful to the PDS to affect the profiles provided. In some scenarios, it is desirable to provide different profiles based upon these parameters. For example, feature property X in a profile may work differently on two versions of the same user agent. This gives the PDS the ability to compensate for or take advantage of the differences. In the following ABNF defining the syntax, EQUAL and quoted-string are defined in [RFC3261].
Vendor = "vendor" EQUAL quoted-string Model = "model" EQUAL quoted-string Version = "version" EQUAL quoted-string 6.2.3. "effective-by" Parameter
The "effective-by" parameter in the Event header of the NOTIFY
request specifies the maximum number of seconds before the user agent MUST attempt to make the new profile effective. The "effective-by"
parameter MAY be provided in the NOTIFY request for any of the profile types. A value of 0 (zero) indicates that the subscribing user agent MUST attempt to make the profiles effective immediately (despite possible service interruptions). This gives the PDS the power to control when the profile is effective. This may be important to resolve an emergency problem or disable a user agent immediately. If it is absent, the device SHOULD attempt to make the profile data effective at the earliest possible opportunity that does not disrupt any services being offered. The "effective-by" parameter is ignored in all messages other than the NOTIFY request. In the following ABNF, EQUAL and DIGIT are defined in [RFC3261].
Effective-By = "effective-by" EQUAL 1*DIGIT 6.2.4. Summary of Event Parameters
The following are example Event headers that may occur in SUBSCRIBE requests. These examples are not intended to be complete SUBSCRIBE requests.
Event: ua-profile;profile-type=device;
vendor="vendor.example.com";model="Z100";version="1.2.3"
Event: ua-profile;profile-type=user;
vendor="premier.example.com";model="trs8000";version="5.5"
The following are example Event headers that may occur in NOTIFY requests. These example headers are not intended to be complete SUBSCRIBE requests.
Event: ua-profile;effective-by=0 Event: ua-profile;effective-by=3600
The following table shows the use of Event header parameters in SUBSCRIBE requests for the three profile types:
profile-type || device | user | local-network =============================================
vendor || m | m | m model || m | m | m version || m | m | m effective-by || | |
m - MUST be provided s - SHOULD be provided o - OPTIONAL to be provided
Non-specified means that the parameter has no meaning and should be ignored.
The following table shows the use of Event header parameters in NOTIFY requests for the three profile types:
profile-type || device | user | local-network =============================================
vendor || | | model || | | version || | |
effective-by || o | o | o 6.3. SUBSCRIBE Bodies
This package defines no use of the SUBSCRIBE request body. If present, it SHOULD be ignored. Exceptions include future enhancements to the framework that may specify a use for the SUBSCRIBE request body.
6.4. Subscription Duration
The duration of a subscription is specific to SIP deployments, and no specific recommendation is made by this event package. If absent, a value of 86400 seconds (24 hours; 1 day) is RECOMMENDED since the presence (or absence) of a device subscription is not time critical to the regular functioning of the PDS.
It is to be noted that a one-time fetch of a profile, without ongoing subscription, can be accomplished by setting the ’Expires’ parameter to a value of Zero, as specified in [RFC3265].
6.5. NOTIFY Bodies
The framework specifying the event package allows for the NOTIFY body to contain the profile data, or a pointer to the profile data using content indirection. For profile data delivered via content
indirection, i.e., a pointer to a PCC, then the Content-ID MIME header, as described in [RFC4483], MUST be used for each profile document URI. At a minimum, the "http:" [RFC2616] and "https:"
[RFC2818] URI schemes MUST be supported; other URI schemes MAY be supported based on the Profile Data Frameworks (examples include FTP [RFC0959], Lightweight Directory Access Protocol (LDAP) [RFC4510], and XCAP [RFC4825] ).
A non-empty NOTIFY body MUST include a MIME type specified in the Accept header of the SUBSCRIBE. Further, if the Accept header of the SUBSCRIBE included the MIME type message/external-body (indicating support for content indirection) then the PDS MAY use content indirection in the NOTIFY body for providing the profiles.
6.6. Notifier Processing of SUBSCRIBE Requests
A successful SUBSCRIBE request results in a NOTIFY with either profile contents or a pointer to it (via content indirection). The SUBSCRIBE SHOULD be either authenticated or transmitted over an integrity protected SIP communications channel. Exceptions include cases where the identity of the Subscriber is unknown and the
Notifier is configured to accept such requests.
The Notifier MAY also authenticate SUBSCRIBE messages even if the NOTIFY is expected to only contain a pointer to profile data.
Securing data sent via content indirection is covered in Section 9.
If the profile type indicated in the "profile-type" Event header parameter is unavailable or the Notifier is configured not to provide it, the Notifier SHOULD return a 404 response to the SUBSCRIBE
request. If the specific user or device is unknown, the Notifier MAY accept the subscription, or else it may reject the subscription (with a 403 response).
6.7. Notifier Generation of NOTIFY Requests
As specified in [RFC3265], the Notifier MUST always send a NOTIFY request upon accepting a subscription. If the device or user is unknown and the Notifier chooses to accept the subscription, the Notifier MAY either respond with profile data (e.g., default profile data) or provide no profile information (i.e., empty NOTIFY).
If the identity indicated in the SUBSCRIBE request (From header) is a known identity and the requested profile information is available (i.e., as specified in the "profile-type" parameter of the Event header), the Notifier SHOULD send a NOTIFY with profile data.
Profile data MAY be sent as profile contents or via content
indirection (if the content indirection MIME type was included in the Accept header). The Notifier MUST NOT use any scheme that was not indicated in the "schemes" Contact header field.
The Notifier MAY specify when the new profiles must be made effective by the Subscriber by specifying a maximum time in seconds (zero or more) in the "effective-by" Event header parameter.
If the SUBSCRIBE was received over an integrity protected SIP
communications channel, the Notifier SHOULD send the NOTIFY over the same channel.
6.8. Subscriber Processing of NOTIFY Requests
A Subscriber to this event package MUST adhere to the NOTIFY request processing behavior specified in [RFC3265]. If the Notifier
indicated an effective time (using the "effective-by" Event header parameter), the Subscriber SHOULD attempt to make the profiles
effective within the specified time. Exceptions include deployments that prohibit such behavior in certain cases (e.g., emergency
sessions are in progress). When profile data cannot be applied within the recommended time frame and this affects device behavior, any actions to be taken SHOULD be defined by the profile data
definitions. By default, the Subscriber is RECOMMENDED to make the profiles effective as soon as possible.
When accepting content indirection, the Subscriber MUST always
support "http:" or "https:" and be prepared to accept NOTIFY messages with those URI schemes. If the Subscriber wishes to support
alternative URI schemes they MUST each be indicated in the "schemes"
Contact header field parameter as defined in [RFC4483]. The
Subscriber MUST also be prepared to receive a NOTIFY request with no body. The subscriber MUST NOT reject the NOTIFY request with no body. The subscription dialog MUST NOT be terminated by a empty NOTIFY, i.e., with no body.
6.9. Handling of Forked Requests
This event package allows the creation of only one dialog as a result of an initial SUBSCRIBE request as described in Section 4.4.9 of [RFC3265]. It does not support the creation of multiple
subscriptions using forked SUBSCRIBE requests.
6.10. Rate of Notifications
The rate of notifications for the profiles in this framework is
deployment specific, but expected to be infrequent. Hence, the event package specification does not specify a throttling or minimum period between NOTIFY requests.
6.11. State Agents
State agents are not applicable to this event package.
7. Examples
This section provides examples along with sample SIP message bodies relevant to this framework. Both the examples are derived from the use case illustrated in Section 4.1, specifically the request for the device profile. The examples are informative only.
7.1. Example 1: Device Requesting Profile
This example illustrates the detailed message flows between the device and the SIP service provider’s network for requesting and retrieving the profile (the flow uses the device profile as an example).
The following are assumed for this example:
o Device is assumed to have established local network connectivity;
NAT and firewall considerations are assumed to have been addressed by the SIP service provider.
o Examples are snapshots only and do not illustrate all the
interactions between the device and the service provider’s network (and none between the entities in the SIP service provider’s
network).
o All SIP communication with the SIP service provider happens via a SIP proxy.
o HTTP over TLS is assumed to be the Content Retrieval method used (any suitable alternative can be used as well).
The flow diagram and an explanation of the messages follow.
+---+
+---+ | SIP Service Provider | | Device | | | |(SIP UA)| | SIP PDS HTTP | +---+ | PROXY Server | | | +---+
| | | | | | | | | SUBSCRIBE | | | (SReq)|---device profile--->| | | | |--->| | | |200 OK | | | 200 OK |<---| | (SRes)|<---| | | | | | | | | NOTIFY| | | NOTIFY (Content Indirection)|<---| | (NTFY)|<---| | | | 200 OK | | | (NRes)|--->|200 OK | | | |--->| | | | | | | | |<<<<<<<<<<<<< TLS establishment >>>>>>>>>>>>>|
| | | HTTP Request | (XReq)|--->|
| | | HTTP Response | (XRes)|<---|
| |
(SReq)
the device transmits a request for the ’device’ profile using the SIP SUBSCRIBE utilizing the event package specified in this
framework.
* Note: Some of the header fields (e.g., SUBSCRIBE, Event, Via) are continued on a separate line due to format constraints of this document.
SUBSCRIBE sip:urn%3auuid%3a00000000-0000-1000-0000-00FF8D82EDCB @example.com SIP/2.0
Event: ua-profile;profile-type=device;vendor="vendor.example.net";
model="Z100";version="1.2.3"
From: anonymous@example.com;tag=1234
To: sip:urn%3auuid%3a00000000-0000-1000-0000-00FF8D82EDCB@example.com Call-ID: 3573853342923422@192.0.2.44
CSeq: 2131 SUBSCRIBE
Contact: sip:urn%3auuid%3a00000000-0000-1000-0000-00FF8D82EDCB @192.168.1.44
;+sip.instance="<urn:uuid:00000000-0000-0000-0000-123456789AB0>"
;schemes="http,https"
Via: SIP/2.0/TCP 192.0.2.41;
branch=z9hG4bK6d6d35b6e2a203104d97211a3d18f57a
Accept: message/external-body, application/x-z100-device-profile Content-Length: 0
(SRes) the SUBSCRIBE request is received by a SIP proxy in the service provider’s network, which transmits it to the PDS. The PDS accepts the response and responds with a 200 OK.
* Note: The device and the SIP proxy may have established a secure communications channel (e.g., TLS).
(NTFY) subsequently, the PDS transmits a SIP NOTIFY message indicating the profile location.
* Note: Some of the fields (e.g., content-type) are continued on a separate line due to format constraints of this document.
NOTIFY sip:urn%3auuid%3a00000000-0000-1000-0000-00FF8D82EDCB @192.168.1.44 SIP/2.0
Event: ua-profile;effective-by=3600
From: sip:urn%3auuid%3a00000000-0000-1000-0000-00FF8D82EDCB@example.com ;tag=abca
To: sip:urn%3auuid%3a00000000-0000-1000-0000-00FF8D82EDCB@example.com ;tag=1234
Call-ID: 3573853342923422@192.0.2.44 CSeq: 322 NOTIFY
Via: SIP/2.0/UDP 192.0.2.3;
branch=z9hG4bK1e3effada91dc37fd5a0c95cbf6767d0 MIME-Version: 1.0
Content-Type: message/external-body; access-type="URL";
expiration="Mon, 01 Jan 2010 09:00:00 UTC";
URL="http://example.com/z100-000000000000.html";
size=9999;
hash=10AB568E91245681AC1B
Content-Type: application/x-z100-device-profile Content-ID: <39EHF78SA@example.com>
. . .
(NRes) Device accepts the NOTIFY message and responds with a 200 OK.
(XReq) once the necessary secure communications channel is
established, the device sends an HTTP request to the HTTP server indicated in the NOTIFY.
(XRes) the HTTP server responds to the request via a HTTP response containing the profile contents.
7.2. Example 2: Device Obtaining Change Notification
The following example illustrates the case where a user (X) is simultaneously accessing services via two different devices (e.g., multimedia entities on a PC and PDA) and has access to a user interface that allows for changes to the user profile.
The following are assumed for this example:
o The devices (A & B) obtain the necessary profiles from the same SIP service provider.
o The SIP service provider also provides a user interface that allows the user to change preferences that impact the user profile.
The flow diagram and an explanation of the messages follow.
o Note: The example only shows retrieval of user X’s profile, but it may request and retrieve other profiles (e.g., local-network, device).
|User |_________| UI* | * = User Interface | X | | |
/ \
/ \
/ \ +---+
+---+ +---+ | SIP Service Provider | | Device | | Device | | | | A | | B | | SIP PDS HTTP | +---+ +---+ | PROXY Server | +---+
| | | | | | | | (A-EX)|<=Enrolls for User X’s profile=>|<=====>| | | | | | | | (A-RX)|<===Retrieves User X’s profile================>|
| | | | | | | | | Enrolls for | | | | (B-EX)|<== User X’s ==>|<=====>| | | | profile | | | | | | | | | | | | (B-RX)|<= Retrieves User X’s profile=>|
| | | | | | (HPut)|--->|
| | | | (HRes)|<---|
| | | | | | | | NOTIFY| | | NOTIFY |<---| | (A-NT)|<---| | | | 200 OK | | | (A-RS)|--->|200 OK | | | |--->| |
| | | | | NOTIFY| | | | NOTIFY |<---| | | (B-NT)|<---| | | | | 200 OK | | | | (B-RS)|--->|200 OK | | | | |--->| | | | | | (A-RX)|<===Retrieves User X’s profile================>|
| | | | | | | | | (B-RX)|<= Retrieves User X’s profile=>|
| | |
(A-EX) Device A discovers, enrolls, and obtains notification related to user X’s profile.
(A-RX) Device A retrieves user X’s profile.
(B-EX) Device B discovers, enrolls, and obtains notification related to user X’s profile.
(B-RX) Device B retrieves user X’s profile.
(HPut) Changes affected by the user via the user interface are uploaded to the HTTP server.
* Note: The Unique Identifier (UI) itself can act as a device and subscribe to user X’s profile. This is not the case in the example shown.
(HRes) Changes are accepted by the HTTP server.
(A-NT) PDS transmits a NOTIFY message to device A indicating the changed profile. A sample message is shown below:
* Note: Some of the fields (e.g., Via) are continued on a separate line due to format constraints of this document.
NOTIFY sip:userX@192.0.2.44 SIP/2.0 Event: ua-profile;effective-by=3600 From: sip:userX@sip.example.net;tag=abcd To: sip:userX@sip.example.net.net;tag=1234 Call-ID: 3573853342923422@192.0.2.44
CSeq: 322 NOTIFY
Via: SIP/2.0/UDP 192.0.2.3;
branch=z9hG4bK1e3effada91dc37fd5a0c95cbf6767d1 MIME-Version: 1.0
Content-Type: message/external-body; access-type="URL";
expiration="Mon, 01 Jan 2010 09:00:00 UTC";
URL="http://www.example.com/user-x-profile.html";
size=9999;
hash=123456789AAABBBCCCDD .
. .
(A-RS) Device A accepts the NOTIFY and sends a 200 OK.
(B-NT) PDS transmits a NOTIFY message to device B indicating the changed profile. A sample message is shown below:
* Note: Some of the fields (e.g., Via) are continued on a separate line due to format constraints of this document.
NOTIFY sip:userX@192.0.2.43 SIP/2.0 Event: ua-profile;effective-by=3600 From: sip:userX@sip.example.net;tag=abce To: sip:userX@sip.example.net.net;tag=1234 Call-ID: 3573853342923422@192.0.2.43
CSeq: 322 NOTIFY
Via: SIP/2.0/UDP 192.0.2.3;
branch=z9hG4bK1e3effada91dc37fd5a0c95cbf6767d2 MIME-Version: 1.0
Content-Type: message/external-body; access-type="URL";
expiration="Mon, 01 Jan 2010 09:00:00 UTC";
URL="http://www.example.com/user-x-profile.html";
size=9999;
hash=123456789AAABBBCCCDD .
. .
(B-RS) Device B accepts the NOTIFY and sends a 200 OK.
(A-RX) Device A retrieves the updated profile pertaining to user X.
(B-RX) Device B retrieves the updated profile pertaining to user X.
8. IANA Considerations
IANA has registered a SIP event package, event header parameters, and SIP configuration profile types as outlined in the following
subsections.
8.1. SIP Event Package
This specification registers a new event package as defined in [RFC3265]. The registration is as follows:
Package Name: ua-profile
Package or Template-Package: This is a package Published Document: RFC 6080
Persons to Contact: Daniel Petrie <dan.ietf@SIPez.com>, Sumanth Channabasappa <sumanth@cablelabs.com>
New event header parameters: profile-type, vendor, model, version, effective-by (The profile-type parameter has predefined values.
The new event header parameters do not.)
The following table illustrates the additions to the IANA SIP "Header Field Parameters and Parameter Values" registry:
Predefined
Header Field Parameter Name Values Reference - --- - Event profile-type Yes [RFC6080]
Event vendor No [RFC6080]
Event model No [RFC6080]
Event version No [RFC6080]
Event effective-by No [RFC6080]
8.2. Registry of SIP Configuration Profile Types
IANA has registered new SIP configuration profile types at http://www.iana.org in the "SIP Configuration Profile Types"
registry.
The registration procedures are "Specification Required", as
explained in "Guidelines for Writing an IANA Considerations Section in RFCs" ([RFC5226]).
Registrations with the IANA MUST include the profile type, and a published document that describes its purpose and usage.
As this document specifies three SIP configuration profile types, the initial IANA registration contains the information shown in the table below.
Profile Type Reference --- local-network [RFC6080]
device [RFC6080]
user [RFC6080]
9. Security Considerations
The framework specified in this document specifies profile delivery stages, an event package, and three profile types to enable profile delivery. The profile delivery stages are enrollment, content retrieval, and change notification. The event package helps with enrollment and change notifications. Each profile type allows for
The framework specified in this document specifies profile delivery stages, an event package, and three profile types to enable profile delivery. The profile delivery stages are enrollment, content retrieval, and change notification. The event package helps with enrollment and change notifications. Each profile type allows for