idnits 2.17.1 draft-petrie-sip-config-framework-00.txt: -(214): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(224): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(331): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(544): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(969): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 42 instances of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 349 has weird spacing: '... in the reque...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The SUBSCRIBE request is used by the UA to enroll in the configuration domain of the configuration server. It uniquely identifies the UA with vendor, model and serial number information. The UA also MUST specify its capabilities for configuration retrieval as well as the configuration data profiles that it requires. That is the UA MUST include the Config-Allow and Config-Require header fields and each MUST contain at least one token. The configuration server MUST not send an error if it is not able to provide all of the configuration data profiles listed in the SUBSCRIBE request Config-Require header field. The configuration server SHOULD provide the configuration data profile that it is able to or desires (see example at the end of section 4.3) to deliver to the UA. If the configuration server sends a 301 Moved Permanently response to the enrollment SUBSCRIBE, the UA SHOULD cache the URL contained in the response Contact header field in place of the address and port found during discovery for future enrollment. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: reused for some other UA (the DHCP lease timeout may be much shorter than the SUBSCRIBE/NOTIFY lease timeouts). The SUBSCRIBE lease SHOULD not exceed the DHCP lease? The UA SHOULD reenroll if its IP address changes?] == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: In the enrollment and configuration change notification messages (i.e. SUBSCRIBE and NOTIFY requests and responses) the SIP-URL [6] MUST not contain userinfo if the default UA user is not known (e.g. first time startup of new UA out of the box). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: is not permitted to make the changes on the configuration server the configuration server returns an HTTP error response code of 403 Forbidden. If the configuration server returns a 403 the UA SHOULD disallow the changes from being effective on the UA. The UA SHOULD not make the changes effective until it receives a successful response (e.g. for HTTP 2xx). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: If the URL is for HTTP/HTTPS the server MUST return the changed configuration data profile in the response (assuming it was allowed). The configuration server SHOULD include an incremented sequence number in the HTTP/HTTPS response if the configuration data profile contents changed [Sip-Ua-Config-Seq header field?]. The UA SHOULD use the configuration data profile contents from the HTTP response as opposed to the data that was pushed in the request as changes may occur from other sources. The configuration server SHOULD send out a NOTIFY for this change, using the same sequence number in the configuration data profile URL parameter. This allows the UA to know that it already has the current contents of the configuration data profile and SHOULD not download that configuration data profile. [TBD � in 403 case restrict and provide feedback as to what specifically is not allowed to be modified by the UA or user] == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: [ What happens when the config server receives multiple SUBSCRIBE requests from the same IP address but for different devices? This might happen if some entity is acting as a proxy for a bunch of other devices. It might also happen if the IP address for a UA gets reused for some other UA (the DHCP lease timeout may be much shorter than the SUBSCRIBE/NOTIFY lease timeouts). The SUBSCRIBE lease SHOULD not exceed the DHCP lease? The UA SHOULD re-enroll if its IP address changes?] -- 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 (March 2001) is 8414 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) -- Looks like a reference, but probably isn't: 'TBD' on line 202 == Unused Reference: '2' is defined on line 924, but no explicit reference was found in the text == Unused Reference: '3' is defined on line 928, but no explicit reference was found in the text == Unused Reference: '4' is defined on line 931, but no explicit reference was found in the text == Unused Reference: '12' is defined on line 961, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '3' ** Obsolete normative reference: RFC 2543 (ref. '6') (Obsoleted by RFC 3261, RFC 3262, RFC 3263, RFC 3264, RFC 3265) -- Possible downref: Non-RFC (?) normative reference: ref. '7' ** Obsolete normative reference: RFC 822 (ref. '8') (Obsoleted by RFC 2822) -- Possible downref: Non-RFC (?) normative reference: ref. '10' -- Possible downref: Non-RFC (?) normative reference: ref. '11' ** Obsolete normative reference: RFC 1738 (ref. '12') (Obsoleted by RFC 4248, RFC 4266) ** Obsolete normative reference: RFC 2818 (ref. '13') (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 2246 (ref. '14') (Obsoleted by RFC 4346) Summary: 8 errors (**), 0 flaws (~~), 13 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 D. Petrie 3 Internet Draft Pingtel Corp. 4 Document: draft-petrie-sip-config-framework-00.txt 5 Expires: September 2001 March 2001 7 A Framework for SIP User Agent Configuration 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance 12 with all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as Internet- 17 Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other documents 21 at any time. It is inappropriate to use Internet-Drafts as 22 reference material or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 Abstract 31 This document defines the application of a set of protocols for 32 configuring a SIP user agent. The SIP user agent must discover how 33 and from where to retrieve its initial configuration and be notified 34 of changes and updates which impact its configuration. The 35 objective is to define a means for automatically configuring a user 36 agent such that it can be functional without user or administrative 37 intervention. The framework for discovery, delivery, notification 38 and updates of user agent configuration is defined here. This 39 framework is also intended to ease ongoing administration, 40 configuration and upgrading of large scale deployments of SIP user 41 agents. The contents and format of the configuration data to be 42 defined is outside the scope of this document. 44 User Agent Configuration 46 Table of Contents 48 Status of this Memo................................................1 49 Abstract...........................................................1 50 1 Overview.......................................................3 51 2 Conventions used in this document..............................4 52 3 Discovery......................................................4 53 3.1 DHCP Option..................................................5 54 3.2 DNS SRV......................................................5 55 3.3 DNS..........................................................5 56 3.4 Multicast....................................................5 57 3.5 Manually Provisioned.........................................5 58 4 Enrollment and Change Notification.............................6 59 4.1 Header Field Definitions.....................................7 60 4.1.1 Config-Allow................................................7 61 4.1.2 Config-Require..............................................7 62 4.1.3 Config-Expires..............................................7 63 4.2 SUBSCRIBE....................................................8 64 4.2.1 Additional From Field Parameters............................9 65 4.3 NOTIFY.......................................................9 66 4.3.1 NOTIFY Body Content Format.................................10 67 5 Configuration Retrieval.......................................11 68 6 Configuration Upload..........................................11 69 7 Examples......................................................12 70 7.1 Example Message Flows.......................................12 71 7.2 Example Messages............................................14 72 8 Security Considerations.......................................17 73 9 Open Issues...................................................18 74 10 References....................................................19 75 11 Author's Addresses............................................20 76 User Agent Configuration 78 1 Overview 80 This document defines a framework which allows SIP user agents (UA) 81 to automatically: 82 - discover a configuration server (Discovery) 83 - enroll with the configuration server (Enrollment) 84 - retrieve configuration data (Configuration Retrieval) 85 - receive notification of configuration changes (Change 86 Notification) 87 - upload configuration data changes back up to the server 88 (Configuration Upload) 90 The content and format of the data is not defined in this document. 91 It is to be defined in configuration data profile(s) in other 92 document(s). The goal of this framework is to satisfy the 93 requirements defined in [10] and [11] excluding the requirements 94 which pertain to configuration data profile content and format. 96 Discovery is the process by which a UA SHOULD find the address and 97 port at which it SHOULD enroll with the configuration server. As 98 there is no single discovery mechanism which will work in all 99 network environments, a number of discovery mechanisms are defined 100 with a prescribed order in which the UA SHOULD try them until one 101 succeeds. 103 Enrollment is the process by which a UA SHOULD make itself known to 104 the configuration server. In enrolling the UA MUST provide identity 105 information, a named list of requested configuration data profiles 106 and supported protocols for configuration retrieval. It SHOULD also 107 SUBSCRIBE to a mechanism for notification of configuration changes. 108 As a result of enrollment the UA receives a URL for each of the 109 configuration data profiles that the configuration server is able to 110 provide. 112 Configuration Retrieval is the process of retrieving the content for 113 each of the configuration data profiles the UA requested. 115 Change Notification is the process by which the configuration server 116 notifies the UA that the content of one or more of the configuration 117 data profiles has changed. Subsequently the UA SHOULD retrieve the 118 data profile from the specified URL upon receipt of the change 119 notification. 121 Configuration Upload is the process by which a UA or other entity 122 pushes a change to a configuration data profile back up to the 123 configuration server. 125 Today all SIP UA vendors use proprietary means of delivering 126 configuration to the UA. This configuration framework is intended 127 to enable a first phase migration to a standard means of configuring 128 SIP user agents. It is expected that UA vendors should be able to 129 use this configuration framework as a means of delivering their 130 existing proprietary configuration data profiles (i.e. using their 131 User Agent Configuration 133 existing proprietary binary or text formats). This in itself is a 134 tremendous advantage in that a SIP environment can use a single 135 configuration server to deliver configuration data to UAs from 136 multiple vendors. Follow-on standardization activities can: 1) 137 define a standard format (e.g. XML or name-value pairs [8]) and 2) 138 specify the content (i.e. name the configuration parameters) of the 139 configuration data profiles. 141 2 Conventions used in this document 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 145 this document are to be interpreted as described in RFC-2119 [1]. 147 The syntax and semantics used here extend those defined in SIP (RFC 148 2543) [6]. SIP is described in an augmented Backus-Naur form (ABNF). 149 See [6, section C] for an overview of ABNF. 151 3 Discovery 153 The first time a UA is plugged in it does not know the address or 154 port at which to enroll with the local configuration server. It 155 must discover this address and port. A UA SHOULD support all of the 156 listed discovery mechanisms. It MUST support at least one of them. 157 Once the UA has discovered the address and port and has successfully 158 enrolled with the configuration server, the UA SHOULD cache the 159 address and port to avoid the need to re-discover the configuration 160 server. However if enrollment, configuration retrieval or 161 configuration upload fails at any time, the UA SHOULD apply the 162 discovery and enrollment process again. This provides a means for 163 configuration server fail over and load balancing. 164 The UA SHOULD use the following mechanisms to discover the host 165 address and port at which it SHOULD enroll with the configuration 166 server. Each mechanism should be tried in the following order until 167 an address and port is provided which results in successful 168 enrollment (i.e. the server responds with a successful 2xx class 169 response): 170 - DHCP site-specific option [1] 171 - DNS SRV 172 - DNS A record 173 - Multicast 174 - Manual provisioning 176 The rationale for this order follows. Assuming that most UAs are 177 going to use DHCP for IP configuration anyway, using a DHCP option 178 is the least costly in terms of lookup time (i.e. no additional 179 messages are required). Hence DHCP is first. DNS SRV allows the 180 more flexibility than DNS A records. Hence DNS SRV is tried before 181 DNS A records. Multicast is used last of the automated discovery 182 mechanisms as it is the most restricted in terms of network 183 environments that support it. Multicast is included, even though 184 the applicable environments are restricted, as it is the only 185 mechanism that can be used without the support of the local network 186 User Agent Configuration 188 administrator (The phone administrator and the network administrator 189 are often different people and perhaps in different departments.) 191 The UA implementer MAY provide the user or administrator with the 192 means to change the order in which these mechanisms are tried. 193 However by default without user interaction it SHOULD use the order 194 listed above. 196 3.1 DHCP Option 198 It is likely that most UAs in an environment of any significant 199 number will use DHCP for IP configuration. DHCP becomes a 200 convenient means to discover the configuration server. In the same 201 DHCP request for basic IP configuration, the UA can add the site- 202 specific option [TBD] [1] to the options field. This indicates a 203 request for the configuration server address and port. If the 204 configuration server address and port is not returned in the DHCP 205 response or the server does not respond with a successful 2xx class 206 response, the next discovery mechanism is attempted. 208 [site-specific DHCP option (i.e. > 128)?] 209 or 210 [DHCP Option for SIP Servers?] 212 3.2 DNS SRV 214 Using the service identifier �sipuaconfig� the DNS SRV records [5] 215 are requested for the local domain for the protocols (i.e. UDP 216 and/or TCP) that the UA supports. The UA tries to enroll using the 217 search order as prescribed in RFC 2782 [5]. If none of the servers 218 respond with a successful 2xx class response (or none are returned 219 in the SRV records) the next discovery mechanism is attempted. 221 3.3 DNS 223 The UA SHALL try a DNS A record lookup on the host name 224 �sipuaconfig�. If the server does not respond with a successful 2xx 225 class response, the next discovery mechanism is attempted. 227 3.4 Multicast 229 The enrollment request is sent to the multicast address for SIP 230 registration [6] "sip.mcast.net" (224.0.1.75). If a server does not 231 respond with a successful 2xx class response to the enrollment 232 request, the next discovery mechanism is attempted. 234 3.5 Manually Provisioned 236 The UA SHOULD let the user (or administrator) know if the automatic 237 discovery has failed and allow the user or administrator to manually 238 (or perhaps using some other out of band means e.g. beam, smart 239 card, etc.) enter the configuration server address and port to be 240 used for enrollment. 242 User Agent Configuration 244 4 Enrollment and Change Notification 246 The enrollment and configuration change notification are paired 247 together and provided via the SIP SUBSCRIBE/NOTIFY framework [7]. 248 This document defines the profile on top of the SUBSCRIBE/NOTIFY 249 framework [7] for this purpose. 251 UA enrollment with the configuration server is accomplished via the 252 SUBSCRIBE request. A UA MUST enroll with the configuration server 253 prior to retrieving configuration data profiles. As part of the 254 enrollment the UA MUST identify itself, its configuration retrieval 255 protocol capabilities and configuration data profile requirements. 257 The configuration server may use this information to decide how to 258 allocate resources (e.g. load balancing) to support the UA for its 259 specific configuration retrieval needs. The configuration server 260 may also use the UA enrollment event as the trigger to generate a 261 new set of configuration data for the specific UA (e.g. based upon 262 provisioned defaults and configuration profile context knowledge for 263 the environment). This would allow the configuration server to 264 provide configuration data for a new UA without previously 265 provisioning the specific UA on the server. 267 Configuration Change Notification is communicated to the UA via a 268 NOTIFY request from the configuration server. The NOTIFY request is 269 used by the configuration server to convey the URLs that the UA MUST 270 use to retrieve its requested configuration data profiles. The 271 NOTIFY is used immediately after enrollment. It MAY be subsequently 272 used by the configuration server to identify the list of 273 configuration data profile URLs which have changed (i.e. change 274 notification). 276 The SUBSCRIBE request for enrollment is sent to the address(es) 277 identified in the discovery process until the first successful 2xx 278 class response is received. As part of the binding of the 279 SUBSCRIBE/NOTIFY framework this document defines a new Event token: 280 �Config-Event�. The Event header field is mandatory in SUBSCRIBE 281 and NOTIFY requests and MUST contain this token value when used for 282 the purpose of enrollment and configuration change notification. 284 [Does Config-Event need to be registered with IANA?] 286 If enrollment fails (i.e. no 2xx response to SUBSCRIBE), the UA 287 SHOULD re-discover the configuration server address and port as 288 described in section 3. 290 The following new header fields are defined for use in SUBSCRIBE and 291 NOTIFY requests for the purpose of enrollment and configuration 292 change notification: 294 The keys used the following table: 295 R � request 296 User Agent Configuration 298 r � response 299 m � mandatory 300 o � optional 301 - - not applicable 303 Header Where SUBSCRIBE NOTIFY 304 ------ ----- --------- ------ 305 Config-Allow R m - 306 Config-Require R m - 307 Config-Expires R - o 309 4.1 Header Field Definitions 311 4.1.1 Config-Allow 313 The Config-Allow header field is used by the UA in the enrollment 314 request (SUBSCRIBE) to list the protocols that it is capable of 315 using to retrieve configuration data. The configuration server MUST 316 adhere to the protocol capabilities of the UA when providing the 317 list of URLs for the configuration profiles in the NOTIFY request. 319 Syntax: 320 Config-Allow = "Config-Allow" ":" 1#config-protocol 321 config-protocol = �tftp� | �http� | �https� | token 323 4.1.2 Config-Require 325 The Config-Require header field contains the names of all of the 326 configuration data profiles that the UA requires. The name(s) of 327 the configuration profiles are to be defined in a future document(s) 328 specifying the content and format of the specific profile. 330 Syntax: 331 Config-Require = �Config-Require� �:� 1#config-profile-name 332 config-profile-name = token 334 [experimental: x-� ?] 335 [IANA ?] 337 4.1.3 Config-Expires 339 The optional Config-Expires header field defines the lease length of 340 the configuration data. If Config-Expires was present in the last 341 NOTIFY received from the configuration server and the UA has not 342 received a notification from the configuration server within this 343 period of time, the UA SHOULD re-enroll by sending a new SUBSCRIBE 344 message to the configuration server. If the enrollment fails, the 345 UA SHOULD re-discover the configuration server using the mechanisms 346 described in section 3. The configuration server SHOULD send a 347 NOTIFY before the lease expires with the event Config-Event, a 348 renewed lease length in the Config-Expires header field and the 349 complete list of configuration data profile URLs in the request 350 User Agent Configuration 352 body for the UA�s configuration data. The configuration data 353 profile URLs SHOULD have the same sequence numbers if the content 354 has not changed. The sequence numbers MUST be different for 355 profiles whose content has changed. The absence of the Config- 356 Expires header field in the lease renewal indicates an indefinite 357 expiration. 359 Note: the Config-Expires header field sets a lease that the UA 360 observes to determine when its configuration is stale. This lease 361 is renewed with every NOTIFY message from the configuration server. 362 The Expires header field in the SUBSCRIBE request describes the 363 duration that the configuration server will continue to send change 364 notifications to the UA. This is renewed with every SUBSCRIBE 365 request from the UA. 367 Syntax: 368 Config-Expires = �Config-Expires� �:� delta-seconds 370 4.2 SUBSCRIBE 372 The SUBSCRIBE request is used by the UA to enroll in the 373 configuration domain of the configuration server. It uniquely 374 identifies the UA with vendor, model and serial number information. 375 The UA also MUST specify its capabilities for configuration 376 retrieval as well as the configuration data profiles that it 377 requires. That is the UA MUST include the Config-Allow and Config- 378 Require header fields and each MUST contain at least one token. The 379 configuration server MUST not send an error if it is not able to 380 provide all of the configuration data profiles listed in the 381 SUBSCRIBE request Config-Require header field. The configuration 382 server SHOULD provide the configuration data profile that it is able 383 to or desires (see example at the end of section 4.3) to deliver to 384 the UA. If the configuration server sends a 301 Moved Permanently 385 response to the enrollment SUBSCRIBE, the UA SHOULD cache the URL 386 contained in the response Contact header field in place of the 387 address and port found during discovery for future enrollment. 389 The configuration server MAY use the enrollment (SUBSCRIBE request) 390 as the stimulus to generate a new instance of a configuration data 391 profile unique to the UA. Alternately the configuration server MAY 392 be provisioned ahead of time to know about new UAs and their 393 specific configuration data content (for example based upon serial 394 number, MAC address). 396 [Request URI should not contain a user id? The user may not be 397 known yet.] 398 [ What happens when the config server receives multiple SUBSCRIBE 399 requests from the same UA but for different list of profiles. Does 400 the last request supercede all previous ones?] 401 [ What happens when the config server receives multiple SUBSCRIBE 402 requests from the same IP address but for different devices? This 403 might happen if some entity is acting as a proxy for a bunch of 404 other devices. It might also happen if the IP address for a UA gets 405 User Agent Configuration 407 reused for some other UA (the DHCP lease timeout may be much shorter 408 than the SUBSCRIBE/NOTIFY lease timeouts). The SUBSCRIBE lease 409 SHOULD not exceed the DHCP lease? The UA SHOULD reenroll if its IP 410 address changes?] 412 4.2.1 Additional From Field Parameters 414 In the enrollment and configuration change notification messages 415 (i.e. SUBSCRIBE and NOTIFY requests and responses) the SIP-URL [6] 416 MUST not contain userinfo if the default UA user is not known (e.g. 417 first time startup of new UA out of the box). 419 The following additional From field parameters are defined for the 420 purpose of identifying the UA device: 422 Vendor �a token used to identify the UA vendor name 424 Model �a token used to identify the UA hardware/software model 426 Version �a token used to identify the firmware/software version 427 currently installed on the UA 429 Serial �the token used to identify the serial number for the UA 431 Mac �the token used to identify the MAC address in hex for the UA 433 From RFC 2543 [6] the From header field syntax is extended to 434 include: 435 from-param = tag-param | generic-param | device-param 436 device-param = vendor-parm | model-parm | version-parm | 437 serial-parm | mac-parm 438 vendor-parm = �Vendor� �=� token 439 model-parm = �Model� �=� token 440 version-parm = �Version� �=� token 441 serial-parm = �Serial� �=� token 442 mac-parm = �Mac� �=� token 444 4.3 NOTIFY 446 The NOTIFY message is sent by the configuration server to convey the 447 URLs at which the UA can retrieve the requested configuration data 448 profiles. This occurs in two contexts: 450 Immediately following the enrollment SUBSCRIBE the configuration 451 server MUST send a NOTIFY providing URLs for the configuration 452 data profiles requested by the UA in the Config-Require header 453 field of the SUBSCRIBE request. If the configuration server is 454 not able to provide some specific configuration data profiles or 455 it does not want the UA to retrieve some specific configuration 456 profiles at that point in time, it MAY exclude those URL(s) from 457 the NOTIFY. At a later time when the configuration server is able 458 to provide the data profile(s) or it wishes the UA to retrieve the 459 data profiles at that point in time, the configuration server MAY 460 User Agent Configuration 462 send a NOTIFY request containing the URL(s) for the configuration 463 data profile(s) which the UA SHOULD retrieve immediately. 465 If the configuration server becomes aware of a configuration 466 change that it wishes to be effective immediately on the UA, the 467 configuration server SHOULD send a NOTIFY message containing the 468 complete list of URLs for the configuration data profiles that the 469 UA requested when it enrolled. The configuration data profiles 470 with changed content SHOULD have sequence number larger than that 471 of the last NOTIFY request. The UA SHOULD retrieve and make 472 effective the changed configuration URLs immediately upon receipt 473 of the NOTIFY request. The UA MAY choose to wait to make the 474 changes effective (e.g. to prevent the change from disrupting 475 active calls on the UA). 477 [Do we need an option for the configuration server to tell the UA 478 that it MUST make the change immediately regardless of state? 479 Should this be the default?] 481 The UA SHOULD send a 200 response to the NOTIFY immediately upon 482 receipt and validation of the solicited request. The configuration 483 server SHOULD include, in the change notification NOTIFY request, 484 the complete list of the configuration data profile URLs. The 485 sequence numbers associated with the configuration data profiles 486 with changed content should be larger than those in the previous 487 NOTIFY. These configuration data profile URLs MUST be among those 488 the UA named in the Config-Requires header field in the most recent 489 enrollment (SUBSCRIBE request). The URLs listed in the NOTIFY 490 request MUST use one of the protocols the UA listed in the Config- 491 Allow header field provided during enrollment in the most recent 492 SUBSCRIBE request. The sequence numbers for the configuration data 493 profile URLs are positive integers chosen by the configuration 494 server. The sequence number value MUST increase monotonically as 495 modifications are made to a data profile. 496 This mechanism may be used by the configuration server to provide 497 firmware updates. For example on a UA that caches or has a 498 persistent firmware image: if the server realizes (e.g. from the 499 enrollment information) the UA is running the most currently 500 available firmware version, it would not provide the URL for the 501 firmware. However at a later point in time when a new firmware 502 version was available the configuration server could send a NOTIFY 503 with the URL for the new firmware version, indicating the UA SHOULD 504 upgrade now. 505 4.3.1 NOTIFY Body Content Format 507 The NOTIFY request contains a body of Content-Type: text/plain. The 508 content is formatted according to RFC 822 [8]. For each of the 509 named configuration data profiles which the configuration server is 510 able to provide, the body contains a header field with the same name 511 as the configuration data profile. The value of the header field 512 MUST contain a URL and a sequence number as described in the syntax 513 below. The protocol of the URL MUST be one of those listed in the 514 Config-Allow header field provided by the UA in the enrollment 515 User Agent Configuration 517 SUBSCRIBE request. The sequence number associated with the URL is 518 intended to allow the UA to decide if it has the latest content of 519 the configuration data profile without having to download and 520 compare the contents. 522 Syntax: 523 config-profile = token �:� Seq-Param �;� Url-Param 524 Seq-Param = �Sequence� �=� 1*digit 525 Url-Param = �Url� �=� tftp-url | Http-url | Https-url 526 Tftp-url [need reference] 527 Http-Url as defined in [12, section 3.3] 528 Httpsw-Url [need reference] 530 Example: 532 X-Acme-Special: Sequence=1234567;Url=http://www.acme.com/config.txt 534 5 Configuration Retrieval 536 The UA MUST retrieve its configuration data profiles using the URLs 537 specified by the configuration server in the NOTIFY request. If any 538 of the retrievals fail, the UA SHOULD re-enroll as described in 539 section 4. Should the enrollment fail, the UA SHOULD re-discover 540 the configuration server as described in section 3. 542 [Is this a good idea? It might cause a nasty cascade effect if the 543 server for a bunch of URLs goes down. In all likelihood, the 544 configuration server won�t check whether the server is available for 545 each of the URLs it hands out � that would probably be too 546 expensive. The effect will be to have a bunch of UA spinning back 547 and forth between hitting the configuration server and hitting the 548 failed server for the URL. What are the alternatives? Leave the 549 precise procedure up to the UA since some may need more 550 sophisticated cutover mechanisms than others. Retry fetching the 551 URL using an exponential backoff timer between attempts up to some 552 maximum interval. When that limit is reached, the UA can try to re- 553 enroll. However, if the configuration server gives it the same 554 failing URL, it should continue to retry after waiting the maximum 555 interval timeout.] 557 6 Configuration Upload 559 If the UA or another entity wishes to modify a configuration data 560 profile it MAY make the change persistent on the configuration 561 server if it is authorized to do so. The configuration server 562 SHOULD support the ability to upload via the same URL the UA used to 563 retrieve the configuration data profile. For TFTP the UA does a put 564 [9]. For HTTP and HTTPS the UA does a POST with a multipart MIME 565 attachment containing any URL parameters in one part and the changed 566 configuration data profile [whole or changes only ?? define in 567 profiles ??] in another part as defined in [?]. If the UA or user 568 User Agent Configuration 570 is not permitted to make the changes on the configuration server the 571 configuration server returns an HTTP error response code of 403 572 Forbidden. If the configuration server returns a 403 the UA SHOULD 573 disallow the changes from being effective on the UA. The UA SHOULD 574 not make the changes effective until it receives a successful 575 response (e.g. for HTTP 2xx). 577 If the URL is for HTTP/HTTPS the server MUST return the changed 578 configuration data profile in the response (assuming it was 579 allowed). The configuration server SHOULD include an incremented 580 sequence number in the HTTP/HTTPS response if the configuration data 581 profile contents changed [Sip-Ua-Config-Seq header field?]. The UA 582 SHOULD use the configuration data profile contents from the HTTP 583 response as opposed to the data that was pushed in the request as 584 changes may occur from other sources. The configuration server 585 SHOULD send out a NOTIFY for this change, using the same sequence 586 number in the configuration data profile URL parameter. This allows 587 the UA to know that it already has the current contents of the 588 configuration data profile and SHOULD not download that 589 configuration data profile. 590 [TBD � in 403 case restrict and provide feedback as to what 591 specifically is not allowed to be modified by the UA or user] 593 7 Examples 595 Below is an example high level message flow for a new UA discovering 596 and using configuration data from a configuration server. Following 597 the high level message flows are some specific SIP messages 598 illustrating SUBSCRIBE and NOTIFY messages from enrollment and 599 configuration change notification. 601 7.1 Example Message Flows 603 The following high level message flows illustrate the configuration 604 process of discovery, enrollment, configuration retrieval and change 605 notification with associated configuration retrieval. The UA uses 606 DHCP with the local option requesting the configuration server 607 address and port. The DHCP server does not provide the 608 configuration server address or port. The UA then does a DNS SRV 609 lookup for the configuration service within the local domain. It 610 gets a response with one configuration server address and port. The 611 UA then enrolls with the configuration by sending a SUBSCRIBE 612 request for the Config-Event. The configuration server sends back a 613 successful response. The configuration server then sends a NOTIFY 614 request with the list of URLs for all the configuration data 615 profiles that the UA named in the enrollment SUBSCRIBE request. The 616 UA sends a 200 response to the NOTIFY. The UA then downloads all of 617 the configuration data profiles via the URLs from the NOTIFY 618 request. The UA is now configured as prescribed. 620 Later ... an administrator makes a change to the configuration for 621 the UA on the configuration server. The configuration server on 622 behalf of the administrator, sends a NOTIFY (change notification) 623 User Agent Configuration 625 request to the UA listing the configuration data profiles that 626 changed (the minimum subset of the list of configuration data 627 profiles the UA requested during enrollment). The UA downloads the 628 configuration data profiles that changed. 630 UA DHCP Server DNS Server Config. Server 632 Discovery 634 IP config. req. 635 ==============> 636 IP config. wo/ local option 637 <============== 638 DNS SRV req. for sipuaconfig service in local domain 639 =============================> 640 Host and port for config. server returned 641 <============================= 643 Enrollment 645 SIP SUBSCRIBE Config-Event w/ requested profile names 646 ==================================================> 647 200 OK 648 <================================================== 649 SIP NOTIFY Config-Event w/ requested profile URLs 650 <================================================== 651 200 OK 652 ==================================================> 654 Configuration retrieval 656 HTTP GET (For each profile URL) 657 ==================================================> 658 200 OK (specific profile data in body) 659 <================================================== 660 . 661 . 662 . 664 Administrative change on configuration server via user interface 665 . 666 . 667 . 669 Change Notification 671 SIP NOTIFY Config-Event w/ changed profile URLs 672 <================================================== 673 200 OK 674 ==================================================> 675 HTTP GET (for each changed profile) 676 ==================================================> 677 200 OK (profile data in body) 678 User Agent Configuration 680 <================================================== 681 . 682 . 683 . 685 User changes data in a profile on the user agent 686 . 687 . 688 . 690 Configuration Upload 692 HTTP POST (changed profile attached as multipart MIME) 693 ==================================================> 694 200 OK (profile data in body, as change confirmation) 695 <================================================== 696 . 697 . 698 . 700 7.2 Example Messages 702 The following SUBSCRIBE request example is from a UA enrolling with 703 a configuration server. As this SUBSCRIBE request is for 704 configuration enrollment the Event header field contains the token 705 Config-Event. The UA tells the configuration server that it 706 supports the TFTP, HTTP, HTTPS protocols for retrieving 707 configuration data profiles in the Config-Allow header field. The 708 UA tells the configuration server that it would like the 709 configuration data profiles named: sip-device, sip-user, x-acme- 710 special in the Config-Require header field. The UA tells the 711 configuration server that it is enrolling for 86400 seconds via the 712 Expires header field. During this period of time the configuration 713 server MUST send a change notification listing the configuration 714 data profiles which have changed. The UA has identified the 715 specifics about itself in the From field parameters: Vendor, Model, 716 Version, Serial, Mac. 718 UA => Config. Server 720 SUBSCRIBE sip:config.localdomain.com SIP/2.0 721 To: sip:config.localdomain.com 722 From: sip:10.1.1.123;Vendor=acme;Model=model-a 723 ;Version=1.5.0.1;Serial=1234567890;Mac=000aaa1234cd 724 Call-Id: 987654321@10.1.1.123 725 Cseq: 1 SUBSCRIBE 726 Event: Config-Event 727 Config-Allow: tftp, http, https 728 Config-Require: Sip-Device, Sip-User, X-Acme-Special, X-Acme-Kernel 729 Expires: 86400 730 Content-Length: 0 731 User Agent Configuration 733 The following is an example response to the above enrollment 734 request. 736 Config. Server => UA 738 SIP/2.0 202 Accepted 739 To: sip:config.localdomain.com 740 From: sip:10.1.1.123;Vendor=acme;Model=model-a 741 ;Version=1.5.0.1;Serial=1234567890;Mac=000aaa1234cd 742 Call-Id: 987654321@10.1.1.123 743 Cseq: 1 SUBSCRIBE 744 Content-Length: 0 746 The following example is the immediate NOTITY request the 747 configuration server sent to the UA following enrollment. The 748 Config-Expires header field indicates the lease length of the 749 configuration data profiles. After that period of time if the UA 750 had not received an additional NOTIFY request from the configuration 751 server it should re-retrieve the configuration data profiles from 752 the provided URLs. The URLs are listed in the request body for each 753 of the named configuration data profiles the UA listed in the 754 Config-Require header field in the above SUBSCRIBE request from the 755 UA, that the configuration server is able or wishes to provide. 756 Note that the configuration server did not provide a URL for X-Acme- 757 Kernel (perhaps it decided that the kernel image on the UA was 758 already current). 760 Config. Server => UA 762 NOTIFY sip:10.1.1.123 SIP/2.0 763 To: sip:10.1.1.123;Vendor=acme;Model=model-a 764 ;Version=1.5.0.1;Serial=1234567890;Mac=000aaa1234cd 765 From: sip:config.localdomain.com 766 Call-Id: 987654321@10.1.1.123 767 Cseq: 22 NOTIFY 768 Event: Config-Event 769 Config-Expires: 43200 770 Content-Type: text/plain 771 Content-Length: 175 773 Sip-Device: Sequence=1 774 ;Url=http://config.localdomain.com/device/1234567890 775 Sip-User: Sequence=1;Url=http://config.localdomain.com/user/fred 776 X-Acme-Special: Sequence=1 777 ;Url=http://www.acme.com/special/config/1234567890 778 User Agent Configuration 780 The following is an example response from the UA for the above 781 request. 783 UA => Config. Server 785 SIP/2.0 200 Ok 786 To: sip:10.1.1.123;Vendor=acme;Model=model-a 787 ;Version=1.5.0.1;Serial=1234567890;Mac=000aaa1234cd 788 From: sip:config.localdomain.com 789 Call-Id: 987654321@10.1.1.123 790 Cseq: 22 NOTIFY 791 Content-Length: 0 793 Assuming at some later point in time, an administrator makes a 794 change to the content of the Sip-Device configuration data profile 795 for the UA. The configuration server sends a NOTIFY request to the 796 UA for the configuration change notification. This example request 797 below indicates the changed URL(s) in the request body with a higer 798 sequence number. In this case only one URL has changed, that for 799 the configuration data profile named: Sip-Device. The configuration 800 server extends the configuration lease to 43200 seconds from when 801 this request is received. This lease applies to all of the 802 configuration data profiles that the UA requested when it last 803 enrolled. If the UA does not receive another NOTIFY request from 804 the configuration server before the lease expires, the UA SHOULD 805 download all of the configuration data profiles from the most recent 806 URLs provided for each of the configuration data profiles listed in 807 the enrollment SUBSCRIBE Config-Require header field. 809 Config. Server => UA 811 NOTIFY sip:10.1.1.123 SIP/2.0 812 To: sip:10.1.1.123;Vendor=acme;Model=model-a 813 ;Version=1.5.0.1;Serial=1234567890;Mac=000aaa1234cd 814 From: sip:config.localdomain.com 815 Call-Id: 987654321@10.1.1.123 816 Event: Config-Event 817 Cseq: 23 NOTIFY 818 Config-Expires: 43200 819 Content-Type: text/plain 820 Content-Length: 64 822 Sip-Device: Sequence=2 823 ;Url=http://config.localdomain.com/device/1234567890 824 Sip-User: Sequence=1;Url=http://config.localdomain.com/user/fred 825 X-Acme-Special: Sequence=1 826 ;Url=http://www.acme.com/special/config/1234567890 827 User Agent Configuration 829 The following is an example response to the above request. 831 UA => Config. Server 833 SIP/2.0 200 Ok 834 To: sip:10.1.1.123;Vendor=acme;Model=model-a 835 ;Version=1.5.0.1;Serial=1234567890;Mac=000aaa1234cd 836 From: sip:config.localdomain.com 837 Call-Id: 987654321@10.1.1.123 838 Cseq: 23 NOTIFY 839 Content-Length: 0 841 8 Security Considerations 843 [This section needs to be greatly expanded and elaborated] 845 SIP basic and digest authentication [6] MAY be used for 846 SUBSCRIBE/NOTIFY messages used for enrollment and configuration 847 change notification. As there is a chicken and egg problem as well 848 and the content of SUBSCRIBE/NOTIFY messages are transported in the 849 clear, the credentials that the UA uses in the SUBSCRIBE 401 850 challenge, or that the configuration server uses in the NOTIFY 401 851 challenge must be provisioned out of band (i.e. user or 852 administrator manual input, beamed via PDA, smart card, etc.) via a 853 secure means. 855 Configuration data profile URLs are communicated in the clear in the 856 NOTIFY requests from the configuration server. The security risk of 857 unauthorized access of the URL content can be mitigated if the 858 configuration server and UA both support basic authentication and 859 HTTP or HTTPS. There is a chicken and egg problem here as well 860 since the content of SUBSCRIBE/NOTIFY messages are transported in 861 the clear. Accordingly,the credentials that the UA uses for the 862 HTTP/HTTPS GET/POST 401 challenge must be provisioned out of band 863 (i.e. user or administrator manual input, beamed via PDA, smart 864 card, etc.) via a secure means. 866 Using HTTPS over TLS[13] the configuration server MAY request the 867 certificate of the UA [14]. If this level of authentication is 868 desired, the UA vendor SHOULD ship the UA with a digital certificate 869 or provide a means by which this can be installed out of band. The 870 configuration server MUST be provisioned with the certificates of 871 authority allowed for each model of UA to be supported. 873 Using HTTPS the UA MAY request the certificate of the configuration 874 server. If this level of authentication is desired the UA must be 875 provisioned with the allowed certificate(s) of authority and 876 identities for the configuration server out of band (i.e. user or 877 administrator manual input, beamed via PDA, smart card, etc.) via a 878 secure means. 880 User Agent Configuration 882 9 Open Issues 884 Local DHCP option (i.e. > 128)? 885 or 886 DHCP Option for SIP Servers? 888 How does the configuration server give feedback to a new UA that it 889 SHOULD/MAY prompt the user for or provide configuration data 890 specifics? 892 [Request URI should not contain a user id? The user may not be 893 known yet.] 895 [ What happens when the config server receives multiple SUBSCRIBE 896 requests from the same UA but for different list of profiles. Does 897 the last request supercede all previous ones?] 899 [ What happens when the config server receives multiple SUBSCRIBE 900 requests from the same IP address but for different devices? This 901 might happen if some entity is acting as a proxy for a bunch of 902 other devices. It might also happen if the IP address for a UA gets 903 reused for some other UA (the DHCP lease timeout may be much shorter 904 than the SUBSCRIBE/NOTIFY lease timeouts). The SUBSCRIBE lease 905 SHOULD not exceed the DHCP lease? The UA SHOULD re-enroll if its IP 906 address changes?] 908 [Do we need an option for the configuration server to tell the UA 909 that it MUST make the change immediately regardless of state? 910 Should this be the default?] 912 [Upload to configuration server configuration data profiles whole or 913 changes only ?? define in profiles ??] 915 [Security considerations section needs much elaboration] 916 User Agent Configuration 918 10 References 920 [1] R. Droms, "Dynamic host configuration protocol," Request for 921 Comments (Draft Standard) 2131, Internet Engineering Task Force, 922 Mar. 1997. 924 [2] S. Alexander and R. Droms, "DHCP options and BOOTP vendor 925 extensions," Request for Comments (Draft Standard) 2132, Internet 926 Engineering Task Force, Mar. 1997. 928 [3] G.Nair, H.Schulzrinne , �DHCP Option for SIP Servers�, 929 , IETF; Apr. 2000, Work in progress. 931 [4] S. Bradner, "Key words for use in RFCs to indicate 932 requirement levels," Request for Comments (Best Current Practice) 933 2119, Internet Engineering Task Force, Mar. 1997. 935 [5] A. Gulbrandsen, P. Vixie, and L. Esibov, �A DNS RR for 936 specifying the location of services (DNS SRV),� Request for 937 Comments 2782, Internet Engineering Task Force, Feb. 2000. 939 [6] M. Handley, H. Schulzrinne, E. Schooler, and J. Rosenberg, 940 �SIP: session initiation protocol,� Request for Comments 2543, 941 Internet Engineering Task Force, Mar. 1999. 943 [7] A. Roach, �Event Notification in SIP�, , IETF; Feb. 2001, Work in progress. 946 [8] D. Crocker, �STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT 947 MESSAGES�, Request for Comments 822, Internet Engineering Task 948 Force, Aug. 1982 950 [9] K. Sollins, �THE TFTP PROTOCOL (REVISION 2)�, Request for 951 Comments 1350, Internet Engineering Task Force, Jul. 1992 953 [10] H Schulzrinne, �Configuring IP Telephony End Systems�, 954 , IETF; Dec. 2000, Work in 955 progress 957 [11] D. Petrie, �Requirements for a SIP User Agent Configuration 958 Framework�, , IETF; 959 Feb. 2001, Work in progress 961 [12] T. Berners-Lee et al, �Uniform Resource Locators (URL)�, 962 Request for Comments 1738, Internet Engineering Task Force, Dec. 963 1994 965 [13] E. Rescorla, �HTTP Over TLS�, Request for Comments 2818, 966 Internet Engineering Task Force, May 2000 967 User Agent Configuration 969 [14] T. Dierks, C. Allen, �The TLS Protocol Version 1.0�, Request 970 for Comments 2246, Internet Engineering Task Force, Jan. 1999 972 11 Author's Addresses 974 Dan Petrie 975 Pingtel Corp. 976 400 W. Cummings Park Phone: +1 781 938 5306 977 Woburn, MA USA Email: dpetrie@pingtel.com