idnits 2.17.1 draft-thomson-geopriv-held-capabilities-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- 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 10, 2011) is 4796 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) == Unused Reference: 'I-D.winterbottom-geopriv-deref-protocol' is defined on line 1202, but no explicit reference was found in the text == Unused Reference: 'RFC2141' is defined on line 1249, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) == Outdated reference: A later version (-08) exists of draft-thomson-geopriv-uncertainty-05 -- Obsolete informational reference (is this intentional?): RFC 2141 (Obsoleted by RFC 8141) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 GEOPRIV M. Thomson 3 Internet-Draft J. Winterbottom 4 Intended status: Standards Track Andrew Corporation 5 Expires: September 11, 2011 M. Barnes 6 Polycom 7 March 10, 2011 9 Device Capability Negotiation for Device-Based Location Determination 10 and Location Measurements in HELD 11 draft-thomson-geopriv-held-capabilities-09 13 Abstract 15 A Device is a valuable source of information about its location. A 16 Location Information Server (LIS) that serves a location URI about a 17 Device is unable to acquire this information. Extensions to HTTP- 18 Enabled Location Delivery (HELD) are described for negotiating and 19 exercising Device capabilities for location determination or location 20 measurement collection. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on September 11, 2011. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Conventions used in this document . . . . . . . . . . . . . . 4 58 3. Capabilities Exchange Overview . . . . . . . . . . . . . . . . 4 59 3.1. Capabilities Exchange . . . . . . . . . . . . . . . . . . 5 60 3.2. Capabilities Invocation . . . . . . . . . . . . . . . . . 6 61 4. The Capability Exchange . . . . . . . . . . . . . . . . . . . 7 62 4.1. Capabilities Advertisement . . . . . . . . . . . . . . . . 7 63 4.2. Capabilities Agreement . . . . . . . . . . . . . . . . . . 8 64 5. Capability Invocation . . . . . . . . . . . . . . . . . . . . 8 65 5.1. HTTP Polling . . . . . . . . . . . . . . . . . . . . . . . 9 66 5.2. Invocation Resource . . . . . . . . . . . . . . . . . . . 9 67 5.3. Invocation Time . . . . . . . . . . . . . . . . . . . . . 10 68 5.4. Responding to a Capability Invocation . . . . . . . . . . 12 69 5.5. Error Reponse to an Invocation . . . . . . . . . . . . . . 13 70 5.6. Multiple Invocations . . . . . . . . . . . . . . . . . . . 13 71 6. The Location Capability . . . . . . . . . . . . . . . . . . . 13 72 6.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 14 73 6.2. Invocation . . . . . . . . . . . . . . . . . . . . . . . . 14 74 7. Location Measurement Capability . . . . . . . . . . . . . . . 14 75 7.1. Parameters . . . . . . . . . . . . . . . . . . . . . . . . 15 76 7.2. Invocation . . . . . . . . . . . . . . . . . . . . . . . . 15 77 8. Example Capabilities Exchange and Invocation . . . . . . . . . 16 78 9. Security Considerations . . . . . . . . . . . . . . . . . . . 19 79 9.1. Privacy Considerations . . . . . . . . . . . . . . . . . . 20 80 9.2. URI Secrecy . . . . . . . . . . . . . . . . . . . . . . . 20 81 9.3. Location Veracity . . . . . . . . . . . . . . . . . . . . 21 82 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 83 10.1. Registration of HELD 'noMeasurement' Error Code . . . . . 21 84 10.2. URN Sub-Namespace Registration for 85 urn:ietf:params:xml:ns:held:cap . . . . . . . . . . . . . 22 86 10.3. XML Schema Registration for HELD Capabilities . . . . . . 22 87 11. XML Schema for Capabilities . . . . . . . . . . . . . . . . . 23 88 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27 89 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 90 13.1. Normative References . . . . . . . . . . . . . . . . . . . 27 91 13.2. Informative References . . . . . . . . . . . . . . . . . . 28 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 94 1. Introduction 96 A Device is a good source of information about its location. Even 97 where a Device is unable to independently determine its location, it 98 can often make observations about its environment and network 99 attachment that are of use in determining its position. Making this 100 information available to the Location Information Server (LIS) in the 101 access network can improve the quality of location estimates for the 102 Device. 104 Requests that retrieve location information by value can benefit from 105 Device-provided measurement data, as described in 106 [I-D.thomson-geopriv-held-measurements]. However, location 107 information provided through location URIs [RFC5808] cannot 108 effectively use this information. The LIS that serves the URI is 109 unable to contact the Device to acquire information. 111 Access to some form of location determination is a necessary 112 precondition of providing a location URI. The LIS that serves that 113 location URI is assumed to be capable of determining the location of 114 the Device. A LIS might only have a limited capacity for determining 115 location in serving a location URI. The quality and timeliness of 116 responses can be improved with Device assistance. 118 Acquiring location measurements or information from a Device is made 119 difficult by the nature of the relationship between the LIS, or 120 access network, and the Device. The relationship between a LIS and 121 the Devices that it serves is often transient. A Device is not 122 necessarily a permanent part of an access network, so it is not 123 possible to pre-arrange trust relationships between Device and LIS. 125 HELD [I-D.ietf-geopriv-http-location-delivery] provides a basis for 126 the relationship between Device and LIS. LIS Discovery 127 [I-D.ietf-geopriv-lis-discovery] provides a means for the Device to 128 initiate the relationship. This document extends the basic HELD 129 location request to include negotiation of a mechanism that allows 130 the LIS to request information from the Device. 132 Location-related Device capabilities include the ability to generate 133 or acquire location information, or the ability to make observations 134 about the mode of network attachment or environment. For instance, a 135 Device with Global Navigation Satellite System (GNSS) hardware can 136 determine its own position by taking a set of measurements and 137 performing a calculation, or it can provide GNSS measurement data. 139 This document describes how a Device can advertise its ability to 140 locate itself or provide location-related measurement data to a LIS. 141 This advertisement is made in a HELD location request where the 142 Device acquires a location URI (see 143 [I-D.ietf-geopriv-http-location-delivery]). The LIS is then able to 144 exercise advertised capabilities to acquire location-related 145 measurement data or location information from the Device when serving 146 the location URI. 148 2. Conventions used in this document 150 This document relies on definitions from [I-D.ietf-geopriv-arch]. 151 Use of the terms LIS and Device is consistent with 152 [I-D.ietf-geopriv-http-location-delivery]. Location-related 153 measurement data (and location measurement) is defined in 154 [I-D.thomson-geopriv-held-measurements] and location estimate is 155 defined in [I-D.thomson-geopriv-uncertainty]. 157 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 158 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 159 document are to be interpreted as described in [RFC2119]. 161 3. Capabilities Exchange Overview 163 A Device provides the LIS with a capabilities advertisement when it 164 requests a location URI. A Device can advertise the ability to 165 acquire location-related measurement data of any type (see 166 [I-D.thomson-geopriv-held-measurements]), or the ability to 167 autonomously determine its own location. 169 The LIS responds with a capabilities agreement, that includes which 170 of these capabilities it might use. As part of the agreement, the 171 LIS identifies an HTTP resource (the invocation resource) that it 172 will use to request Device assistance. The Device monitors this 173 resource as long as it is willing to provide the advertised data. 175 In the process of serving requests to a location URI, a LIS might 176 determine that certain Device capabilities could be useful or 177 necessary in completing the request. The LIS alters the invocation 178 resource to include a request that details what data is desired. The 179 Device acquires the updated resource and provides the requested 180 information. 182 Figure 1 shows a logical overview of a simple scenario where the LIS 183 uses a Device-provided measurement to service a request to a location 184 URI. 186 +--------+ +-------+ +-----------+ 187 | | | | | Location | 188 | Device | | LIS | | Recipient | 189 +--------+ +-------+ +-----------+ 190 | | | 191 +----- locationRequest ----->| | 192 | (capability advertisement) | | 193 | | | 194 |<----- locationResponse ----+ | 195 | (capability agreement) | | 196 | | | 197 |~ ~ ~ ~ ~ ~ ~ ~ ~(convey location URI)~ ~ ~ ~ ~ ~ >| 198 | | | 199 | |<-- locationRequest --+ 200 | capability | | 201 |<------- invocation --------+ | 202 | | | 203 +--------- publish --------->| | 204 | (measurements/location) | | 205 | +-- locationResponse ->| 206 | | | 208 Figure 1: Logical Overview of Operation 210 In practice, this scheme relies on HTTP polling to provide a channel 211 for capability invocation. This mechanism is described in more 212 detail in Section 5. 214 3.1. Capabilities Exchange 216 To indicate capabilities to a LIS, a Device advertises its location 217 determination or measurement capabilities to the LIS in a HELD 218 "locationRequest" message. The LIS selects those capabilities that 219 it might make use of and provides a capabilities agreement that 220 includes the selected capabilities in the "locationResponse" message, 221 along with the location URI. 223 +--------+ +-------+ 224 | Device | | LIS | 225 +--------+ +-------+ 226 | | 227 +---------- locationRequest --------->| 228 | (capability advertisement: A, B, C) | 229 | | 230 |<--------- locationResponse ---------+ 231 | (location URI set) | 232 | (capability agreement: A, C) | 233 | | 235 Figure 2: Capabilities Exchange 237 Once a common set of capabilities are agreed upon, the LIS is able 238 invoke these capabilities to assist in the generation of location 239 information. Agreed capabilities and associated parameters are 240 stored in association with the contextual information necessary for 241 serving the location URI. 243 3.2. Capabilities Invocation 245 The LIS invokes capabilities as it is necessary to service requests 246 to the location URIs it provides. 248 +--------+ +-------+ +-----------+ 249 | | | | | Location | 250 | Device | | LIS | | Recipient | 251 +--------+ +-------+ +-----------+ 252 | | | 253 +--------- poll ---------->| | 254 | | | 255 . . . 256 | | | 257 | |<--- locationRequest ---+ 258 | capability | | 259 |<------ invocation -------+ | 260 | | | 261 |<- - - - exchange - - - ->| | 262 | (measurements/location) | | 263 | +--- locationResponse -->| 264 | | | 266 Figure 3: Invoking Capabilities 268 Capabilities are bound to the location URIs that are provided in the 269 response that indicates the mutually agreed capabilities. The LIS 270 MUST NOT use capabilities for any purpose other than serving those 271 location URIs. 273 The set of capabilities associated with a location URI is fixed. A 274 Device instead applies local policy in determining whether to respond 275 to a capability invocation. A Device can choose to discontinue 276 selected capabilities by refusing to respond to a capability 277 invocation. A Device can also cease to monitor the resource used for 278 capability invocation to terminate all capabilities. 280 4. The Capability Exchange 282 A capabilities exchange is initiated with a location request from a 283 Device. The Device includes a capbilities advertisement in the 284 location request. The LIS responds with agreed capabilities in the 285 location response. 287 4.1. Capabilities Advertisement 289 A Device capabilities advertisement (the "deviceCapabilities" 290 element) is added to the HELD location request by the Device. This 291 element can contain a "location" element to indicate that the Device 292 is capable of determining its own location autonomously; it can also 293 contain one or more "measurement" elements, each indicating that the 294 Device is cable of providing location measurement data. 296 Each capability is uniquely identified with a "id" attribute. 298 A "responseTime" attribute indicates the expected time that acquiring 299 the location or measurement data takes, in milliseconds. The 300 advertised response time assists the LIS in deciding whether or not 301 to invoke a capability when serving a request for location 302 information. 304 The Device is only able to quantify the time for its own 305 involvement in the process; additional delays from polling, 306 network transit and LIS processing need to be included in any 307 decision to invoke a Device capability. 309 Location measurement capabilities include a "type" attribute, which 310 identifies the type of measurement. Types are identified using the 311 qualified name of the XML element for the measurement, as with the 312 "measurementRequest" element defined in 313 [I-D.thomson-geopriv-held-measurements]. 315 Each capability element can also contain arbitrary content that 316 carries supplementary information specific to the capability. This 317 supplementary information includes, but is not restricted to, 318 measurement parameters that identify specific aspects of a 319 measurement capability. Different supplementary information can be 320 provided by the Device and LIS. 322 The following figure shows a capabilities advertisement that might be 323 made by a Device with GNSS capabilities. This includes both 324 autonomous GNSS location determination capability as well as GNSS 325 measurement capability with additional parameters. 327 329 330 332 333 334 336 4.2. Capabilities Agreement 338 A capabilities agreement ("agreedCapabilities" element) is included 339 in the HELD location response. This element contains a subset of the 340 advertised capabilities, indicating which capabilities the LIS wishes 341 to use. Capabilities are identified using the "id" attribute, but 342 other attributes are omitted. 344 A capabilities agreement contains an HTTP URI for an invocation 345 resource. The "monitor" element indicates a resource that the Device 346 is requested to monitor for capability invocations (Section 5). 348 The following figure shows a capabilities agreement that might be 349 made in response to a device capabilities advertisement. This 350 includes an invoke resource and a reference to each device 351 capability, using the "id" attribute for each location and 352 measurement capability. 354 356 https://lis.example.com/inv/C90dXBsZT4KPC 357 358 359 361 5. Capability Invocation 363 The LIS includes a URI for an HTTP "invocation" resource in the 364 capabilities agreement. A Device that wishes to provide advertised 365 capabilities monitors this resource. 367 The contents of the invocation resource identify the information that 368 the LIS desires. The LIS updates the invocation resource when a 369 request to a location URI is made that could benefit from location or 370 measurement data acquired by the Device. 372 The invocation resource is updated to identify one or more 373 capabilities when information is requested by the LIS. For each 374 capability, the resource includes a destination URI for the requested 375 data, and a time. By monitoring the invocation resource, the Device 376 is informed when the LIS requires more information and the Device is 377 then able to provide that information. 379 5.1. HTTP Polling 381 The Device monitors the invocation resource, using either HTTP long- 382 polling [I-D.loreto-http-bidirectional] or periodic requests (short- 383 polling). Both methods use the HTTP GET method. Client and server 384 developers are reminded that full support of HTTP [RFC2616] 385 facilities is expected. 387 The Device SHOULD retrieve an initial representation of the resource 388 and poll for updates using conditional request headers, such as 389 "If-Modified-Since" or "If-None-Match". The Device SHOULD use long- 390 polling and indicate this using a Timeout header 391 [I-D.loreto-http-timeout] [[...or whatever replaces this, since 392 Timeout is already taken]]. An HTTP 200 (OK) response is sent 393 immediately when the resource is updated, or an HTTP 304 (Not 394 Modified) response is sent if the timeout period lapses . In order 395 to continue monitoring the state of the resource, the Device 396 immediately sends another request upon receiving a response. 398 In the absence of the Timeout header, the server MAY assume that 399 short-polling is in use. If short-polling is used, the Device MUST 400 NOT continuously poll for updates. The server can limit the rate 401 that a client is able to poll by sending a 503 (Service Unavailable) 402 response with an appropriate "Retry-After" header. A client that 403 receives this header MUST adjust its polling rate to match the 404 indicated period. 406 5.2. Invocation Resource 408 The resource that the Device monitors identifies individual 409 capabilities and when the information that they provide is requested. 411 The value of the invocation resource determines what information is 412 required. This document is an XML document with the MIME type of 413 "application/held+xml" and a document element of "invokeCapability". 414 Initially, this document is likely to be empty. 416 A Device monitors the invocation resource for changes. A change in 417 the state of the invocation resource indicates that the LIS requests 418 some data. The value of the invocation resource indicates the 419 capability, where the data associated with the capability is to be 420 pushed by the Device, and when the associated data is to be provided. 422 For instance, if the LIS wants to invoke the location capability of 423 the Device, it updates the resource to produce the following 424 representation: 426 428 429 https://lis.example.com/push/U2Nob29sIGlzIGNvb2wu 430 431 433 The Device monitors the invocation resource as long as it is willing 434 to respond to capability invocation requests, though it MAY suspend 435 any monitoring while it responds to a request for data. Upon expiry 436 of the location URI, the Device SHOULD stop monitoring the resource. 437 An HTTP 404 (Not Found) or 410 (Gone) response can be provided to 438 indicate to the Device that the resource no longer exists. 440 5.3. Invocation Time 442 The "before" attribute on the capability invocation serves to advise 443 the Device on the latest time when a response is desired. This time 444 is the latest moment that information from the Device is of use to 445 the LIS. If this time has passed, or the requested information 446 cannot be provided before this time, then the capability invocation 447 can be ignored. 449 The "periodic" attribute on a capability requests periodic updates. 450 The attribute contains a time interval in milliseconds, which 451 specifies the periodicity desired. This indicates that the Device 452 provide information before the time specified in the "before" 453 attribute and periodically thereafter at the specified interval. 455 Periodic invocations continue until the invocation is modified or 456 removed. The Device SHOULD continue to monitor the invocation 457 resource to be informed of any changes. 459 For instance, the following invocation contains a request to provide 460 measurements for the capability identified with the "id" attribute of 461 "gps". This information should be provided before 462 "2011-07-09T13:55:01+10:00" and at 60 second intervals thereafter 463 (before 13:55:01, then before 13:56:01, then 13:57:01, and so on). 465 467 469 https://lis.example.com/push/U2Nob29sIGlzIGNvb2wu 470 471 473 The following figure shows that a Device acquires measurement data 474 immediately upon receiving a capability invocation with a periodic 475 interval. After these measurements are pushed to the LIS, the Device 476 waits for a period. The time that is waited is the difference 477 between the periodic interval (p) and the expected time to acquire 478 measurement data (m). This ensures that measurement data is provided 479 to the LIS prior to the requested time. 481 +--------+ +-------+ 482 | Device | | LIS | 483 +--------+ +-------+ 484 | | 485 | periodic | 486 |<--- capability ----+ 487 | invocation | 488 .--------------. | 489 | Acquire | | 490 | Measurements | | 491 Before `--------------' | 492 Time | | 493 \ +------ push ------->| 494 \______________ | measurements +--... 495 ^ ^ | | 496 | | ' ' 497 | (p-m) 498 | | . . 499 | v______ | | 500 | ^ .--------------. | 501 (p) | | Acquire | | 502 | | | Measurements | | 503 | (m) `--------------' | 504 | | | | 505 | | +------ push ------->| 506 v_____v______ | measurements +--... 507 ^ | | 508 ' ' ' 510 5.4. Responding to a Capability Invocation 512 A Device that wishes to provide information SHOULD do so when it 513 receives an invocation that it can comply with. Any information is 514 pushed to the URI indicated in the "push" element as an HTTP PUT. 515 The format of the information provided depends on the capability. 517 A Device can choose to ignore a capability invocation at any time. 519 Information provided in this manner can be considered as additional 520 supplementary information that is provided for the purposes of 521 serving the location URI. The same authorization rules that apply to 522 the location URI apply to this data. A LIS is able to redistribute 523 this information and any results based on this information under the 524 same policy that the location URI operates. Any information MUST 525 only be used as permitted by the Device. Explicit data expiration 526 indications, such as that used in 527 [I-D.thomson-geopriv-held-measurements], MUST be respected. 529 5.5. Error Reponse to an Invocation 531 A Device might be unable to acquire the requested location or 532 measurement information when it is requested. In this case, a HELD 533 error message is sent to the resource indicated in the "push" element 534 of the invocation, in place of the requested data. The HELD error 535 message is defined in Section 5.3 of 536 [I-D.ietf-geopriv-http-location-delivery]. 538 Requests for location information can elicit a push containing any of 539 the applicable HELD error codes (including "locationUnknown"). 540 Requests for measurement data can result in the same set of codes, 541 plus a newly defined error code: "noMeasurement" is defined in 542 Section 10.1. 544 5.6. Multiple Invocations 546 The same invoke resource is used for multiple capabilities. Devices 547 that support multiple capabililties identify the capability that the 548 LIS desires to use through the "id" attribute on the capability. If 549 multiple capabilities are invoked at the same time, the Device MAY 550 choose to provide all information concurrently or separately, and in 551 whole, in part or not at all. 553 The measurement capability inherently supports provision of multiple 554 measurements concurrently. A single measurement container can be 555 provided with multiple different forms of measurement. Measurement 556 and location capabilities are pushed separately. 558 A LIS MUST provide a different push resource for each separate 559 capability that it invokes. Without this, information from the 560 Device cannot be reliably correlated with a specific capability. For 561 instance, an error response for one capability might be 562 misinterpreted as an error for all capabilities. 564 6. The Location Capability 566 The location capability indicates that the Device can determine its 567 own location. This is represented by the inclusion of a "location" 568 element. 570 The ability to locate itself is a trait that is applicable to Devices 571 in a range of networks. This includes automated location 572 determination, like Global Navigation Satellite Systems (GNSS), user 573 input, an alternative location service, or a range of location 574 techniques. 576 6.1. Parameters 578 The "location" element MAY include a "locationType" element that 579 includes a value of "civic" or "geodetic", a space-separated list 580 containing both values, or the value "any". A basic description of 581 the semantics of location type is included in Section 6.3 of HELD 582 [I-D.ietf-geopriv-http-location-delivery]. 584 When included in the capabilities advertisement, the "locationType" 585 element indicates the type of location information that the device is 586 capable of providing. When included in other messages, the 587 "locationType" element indicates the type of location information 588 that the LIS requests that the Device provide. Omitting the 589 "locationType" element indicates that the previous value from the 590 most recent message is requested; if there is no such value, then any 591 form of location information is acceptable. 593 6.2. Invocation 595 When invoked, the Device provides location information in the form of 596 a PIDF-LO. The Device uses an HTTP PUT to the URI identified in the 597 "push" element of the capability invocation. The PUT request 598 includes a PIDF-LO document and a "Content-Type" of 599 "application/pidf+xml". 601 Only the "location-info" element of the PIDF-LO is used by the LIS; 602 other PIDF-LO fields SHOULD be minimally populated by the Device. It 603 is RECOMMENDED that the Device generate an unlinked pseudonym for the 604 "entity" attribute of the presence document to avoid providing 605 identity information. 607 In providing location information in this manner, the Device 608 implicitly grants the LIS the ability to redistribute location 609 information under the same conditions that apply to the location URI 610 that the capability was negotiated with. 612 7. Location Measurement Capability 614 The location capability indicates that the Device can acquire 615 location-related measurement data of a specified type. This is 616 represented by the inclusion of a "measurement" element. 618 Measurement data from the Device can be invaluable in improving the 619 quality of location information. Measurement information from a 620 Device can improve the accuracy of location estimates or enable 621 positioning methods that would not otherwise be available. See 622 [I-D.thomson-geopriv-held-measurements] for more information on 623 location measurements. Providing access to measurement data by using 624 the capability exchange makes these advantages available when a 625 location recipient uses a location URI to retrieve location 626 information. 628 7.1. Parameters 630 A capability advertisement for location measurements includes the 631 type of measurement that is supported, using the "type" attribute of 632 the "measurement" element. Measurement types are identified using 633 the XML qualified name of the measurement element, as defined for the 634 measurement request in [I-D.thomson-geopriv-held-measurements]. 636 The "type" attribute is omitted from the capabilities agreement and 637 capability invocation. If the LIS supports or requires a subset of 638 the measurement data, it MAY indicate this using measurement 639 parameters in the agreement or the capability invocation. Omission 640 of parameters in either message indicates that the last set 641 parameters are to be applied. For instance, if parameters are 642 included in the capabilities advertisement and revised in the 643 capabilities agreement, a capability invocation can omit these and 644 have the parameters from the agreement applied. 646 A capability invocation MAY include a "samples" parameter to request 647 that the Device provide a certain number of samples of the indicated 648 measurement type. The "samples" parameter defaults to 1. 650 The Device MAY ignore this parameter and provide a smaller (or 651 larger) number of samples. However, a Device SHOULD indicate how 652 many samples were acquired for a given measurement type, either by 653 including multiple measurements, by providing multiple separate 654 responses, or by setting the "samples" attribute for elements of the 655 measurement where available. 657 7.2. Invocation 659 The Device acquires and pushes location measurements to the 660 identified URI when a measurement capability is invoked. The Device 661 uses an HTTP PUT to the URI identified in the "target" element of the 662 capability indication. This document contains the MIME type 663 "application/held+xml" and has a document element of "measurements". 664 This document contains one or more measurement elements containing 665 the requested measurement data. 667 Multiple measurements can be provided at the same time. The 668 "measurements" element simply contains multiple measurement elements. 669 This can be used to simultaneously provide information for multiple 670 different invocations of this capability. Measurements that are 671 acquired at different times are provided in different requests. 673 8. Example Capabilities Exchange and Invocation 675 This section shows sample messages relating to a location request 676 with capabilities, monitoring the invocation resource and the 677 provision of measurement or location information. HTTP headers are 678 shown on messages where it is relevant to do so. 680 The following HELD request from a Device includes a capabilities 681 advertisement; HTTP headers are omitted: 683 685 locationURI 686 689 691 692 geodetic 693 694 697 698 699 700 702 Two capabilities are included: location and measurement. The 703 measurement capability indicates that GNSS measurements can be 704 provided by the Device. The GNSS capability indicates that 705 measurement for the GPS L1 signal are the only GNSS measurement 706 supported. 708 The LIS response includes location URIs, along with a capabilities 709 agreement: 711 713 714 715 https://lis.example.com/OnBhcmFtczp4bWw6bnM6c 716 717 719 721 722 https://lis.example.com/inv/OnBhcmFtczp4C90dXBsZT4KPC 723 724 725 726 727 729 This indication instructs the Device to monitor a URI to determine 730 when the LIS wants to invoke either capability. 732 The Device then monitors the state of the resource: 734 GET /inv/OnBhcmFtczp4C90dXBsZT4KPC HTTP/1.1 735 Host: lis.example.com 737 The resource initially contains no invocation instructions: 739 HTTP/1.1 200 OK 740 Server: Example LIS 741 Date: Sat, 9 Jul 2011 03:06:12 GMT 742 Expires: Sat, 9 Jul 2011 03:08:42 GMT 743 ETag: "xyzzy" 744 Cache-Control: private 745 Content-Type: application/held+xml 746 Content-Length: 76 748 751 The Device then issues a long-polling request to monitor the state of 752 the resource: 754 GET /inv/OnBhcmFtczp4C90dXBsZT4KPC HTTP/1.1 755 Host: lis.example.com 756 If-None-Match: "xyzzy" 757 Timeout: 600 759 Some time later, the LIS receives a location request and decides that 760 the GNSS measurement capability of the Device would be useful or 761 necessary in completing the reqeust. The LIS updates the invocation 762 resource with instructions to the Device to provide location 763 measurements: 765 HTTP/1.1 200 OK 766 Server: Example LIS 767 Date: Sat, 9 Jul 2011 03:54:44 GMT 768 Expires: Sat, 9 Jul 2011 03:55:01 GMT 769 Cache-Control: private 770 Content-Type: application/held+xml 771 Content-Length: 245 773 775 776 https://lis.example.com/push/U2Nob29sIGlzIGNvb2wu 777 778 779 The Device decides that it is able to provide these data. It takes 780 the requested measurement and pushes the measurement data to the 781 indicated destination: 783 PUT /push/U2Nob29sIGlzIGNvb2wu HTTP/1.1 784 Host: lis.example.com 785 Content-Type: application/held+xml 786 Content-Length: 688 788 790 792 793 499.9395 794 0.87595747 795 45 796 797 798 378.2657 799 0.56639479 800 52 801 802 803 -633.0309 804 0.57016835 805 48 806 807 808 810 The LIS immediately provides an empty response to the Device: 812 HTTP/1.1 204 No Content 813 Server: Example LIS 814 Date: Sat, 9 Jul 2011 03:54:58 GMT 816 The LIS is then able to use the provided measurement data to provide 817 highly accurate location information in response to the request it 818 received. 820 9. Security Considerations 822 Use of location or measurement capabilities has privacy 823 considerations (Section 9.1). Protecting privacy depends on the 824 secrecy of the URIs used (Section 9.2). Use of Device capability 825 also exposes a LIS to the possibility of a Device that falsifies 826 location or measurement data (Section 9.3). 828 9.1. Privacy Considerations 830 The information provided by a Device in the course of responding to a 831 capabilities invocation privacy-sensitive data. This is either 832 location information, or measurement data that could be use to 833 produce location information. The GEOPRIV architecture 834 [I-D.ietf-geopriv-arch] provides a framework for the handling of 835 location and location-related information. 837 Information about the capabilities of a Device might be privacy 838 sensitive. Similarly, willingness to provide capabilities might be 839 sensitive. 841 HTTP over TLS [RFC2818] MUST be used to provide confidentiality for 842 Device capabilities and the location or measurement data that is 843 provided by the Device. 845 All data acquired by the LIS in relation to a location URI MUST only 846 be used for the purpose of serving the location URI. Any access 847 control policy - such as that installed using 848 [I-D.barnes-geopriv-policy-uri] - that applies to the location URI 849 also applies to any information acquired using Device capabilities. 851 Any information that is provided to the LIS by the Device increases 852 the impact of LIS impersonation. Measures that aim to prevent 853 impersonation, as outlined in [I-D.ietf-geopriv-lis-discovery], MUST 854 be applied if a Device provides capability information to a LIS. 855 These measures include server authentication 856 [I-D.saintandre-tls-server-id-check] for all stages of the process. 858 Server authentication MUST be used for the HELD location request 859 containing the capability exchange, for retrieving the capabilities 860 invocation and for publishing any requested information. Resources 861 that are identified by the LIS do no need to be provided by the same 862 server identity, but each resource MUST be authenticated based on the 863 domain name in the URI. HTTP over TLS [RFC2818] is strongly 864 RECOMMENDED for each of these exchanges. 866 9.2. URI Secrecy 868 Using capabilities offers attackers a means to provide invalid 869 location or measurement data. The URI offered by the LIS for 870 receiving location or measurement data is not protected by an access 871 policy. Knowledge of this URI is all that is required to provide 872 information. If an attacker is able to learn this URI, they could 873 provide misleading information that could be used by the LIS. 875 The only protection provided is secrecy. Only the Device is given 876 the URI to the invocation resource, which is where the URI used for 877 providing information is made available. To guarantee this secrecy, 878 the URI of the invocation resource and any URIs contained therein 879 need to be difficult to acquire or guess. 881 The LIS MUST use confidentiality protection on the channel it uses to 882 provide all resources used in the capability exchange and subsequent 883 requests: the LIS URI used for the location request, the invocation 884 resource, and the resource that location or measurement data is 885 pushed to. HTTP over TLS [RFC2818] MUST be used unless 886 confidentiality can be guaranteed by other means. 888 To lower the probability of these URIs being discovered by guessing 889 or inference, these URIs MUST include sufficient randomness. The LIS 890 SHOULD also periodically change the URIs it provides to limit any 891 exposure in the case that these URIs become known to an attacker. 893 9.3. Location Veracity 895 The LIS is responsible for the veracity of location information it 896 provides, especially when serving a location URI. Information 897 acquired from a location URI is attributed to the LIS, unless there 898 is an explicit indication as to the provenance of the data. 900 A Device might exploit this by spoofing location or measurement data. 901 A Device thereby falsely gains any credibility that recipients of 902 that data might attribute to the LIS. 904 This and other related considerations described in 905 [I-D.thomson-geopriv-held-measurements] apply to the use of Device- 906 provided information. At a minimum, a LIS SHOULD mark location 907 tuples with the "source" element. 909 10. IANA Considerations 911 This section registers a URN for a HELD capabilities XML namespace 912 (Section 10.2) and a corresponding schema (Section 10.3). 914 10.1. Registration of HELD 'noMeasurement' Error Code 916 This section registers the "noMeasurement" error code in the "Geopriv 917 HELD Registries, Error codes for HELD" IANA registry. 919 noMeasurement This error code indicates that all requested location- 920 related measurement data could not be acquired by the Device. 922 10.2. URN Sub-Namespace Registration for 923 urn:ietf:params:xml:ns:held:cap 925 This section registers a new XML namespace, 926 "urn:ietf:params:xml:ns:held:cap", as per the guidelines in 927 [RFC3688]. 929 URI: urn:ietf:params:xml:ns:held:cap 931 Registrant Contact: IETF, GEOPRIV working group, 932 (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com). 934 XML: 936 BEGIN 937 938 940 941 942 HELD Capabilities Indication 943 944 945

Namespace for HELD Capabilities Indication

946

urn:ietf:params:xml:ns:held:cap

947 [[NOTE TO IANA/RFC-EDITOR: Please update RFC URL and replace XXXX 948 with the RFC number for this specification.]] 949

See RFCXXXX.

950 951 952 END 954 10.3. XML Schema Registration for HELD Capabilities 956 This section registers an XML schema as per the guidelines in 957 [RFC3688]. 959 URI: urn:ietf:params:xml:schema:held:cap 961 Registrant Contact: IETF, GEOPRIV working group, (geopriv@ietf.org), 962 Martin Thomson (martin.thomson@andrew.com). 964 Schema: The XML for this schema can be found as the entirety of 965 Section 11 of this document. 967 11. XML Schema for Capabilities 969 970 977 978 980 HELD Capabilities 981 982 983 985 This schema is the basis for HELD capabilities negotiation. 986 987 989 990 991 992 993 994 997 1000 1002 1003 1004 1005 1006 1008 1009 1010 1011 1013 1014 1015 1017 1018 1019 1020 1022 1023 1024 1026 1027 1028 1029 1030 1031 1032 1035 1038 1040 1041 1042 1043 1044 1046 1047 1048 1049 1051 1052 1053 1054 1055 1057 1058 1060 1061 1062 1064 1065 1066 1067 1068 1070 1071 1072 1073 1074 1075 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1105 1106 1107 1108 1109 1110 1113 1116 1118 1119 1120 1121 1122 1124 1125 1126 1128 1130 1131 1132 1133 1134 1135 1137 1138 1139 1140 1141 1143 1144 1145 1146 1147 1148 1150 1151 1152 1154 1155 1157 1159 1161 12. Acknowledgements 1163 Richard Barnes provided useful input on the state management 1164 mechanisms that are used in this document. 1166 13. References 1168 13.1. Normative References 1170 [I-D.ietf-geopriv-http-location-delivery] 1171 Barnes, M., Winterbottom, J., Thomson, M., and B. Stark, 1172 "HTTP Enabled Location Delivery (HELD)", 1173 draft-ietf-geopriv-http-location-delivery-16 (work in 1174 progress), August 2009. 1176 [I-D.ietf-geopriv-lis-discovery] 1177 Thomson, M. and J. Winterbottom, "Discovering the Local 1178 Location Information Server (LIS)", 1179 draft-ietf-geopriv-lis-discovery-15 (work in progress), 1180 March 2010. 1182 [I-D.loreto-http-timeout] 1183 Loreto, S., Thomson, M., and G. Wilkins, "Hypertext 1184 Transfer Protocol (HTTP) Timeouts", 1185 draft-loreto-http-timeout-00 (work in progress), 1186 June 2010. 1188 [I-D.saintandre-tls-server-id-check] 1189 Saint-Andre, P. and J. Hodges, "Representation and 1190 Verification of Domain-Based Application Service Identity 1191 within Internet Public Key Infrastructure Using X.509 1192 (PKIX) Certificates in the Context of Transport Layer 1193 Security (TLS)", draft-saintandre-tls-server-id-check-14 1194 (work in progress), January 2011. 1196 [I-D.thomson-geopriv-held-measurements] 1197 Thomson, M. and J. Winterbottom, "Using Device-provided 1198 Location-Related Measurements in Location Configuration 1199 Protocols", draft-thomson-geopriv-held-measurements-06 1200 (work in progress), May 2010. 1202 [I-D.winterbottom-geopriv-deref-protocol] 1203 Winterbottom, J., Tschofenig, H., Schulzrinne, H., 1204 Thomson, M., and M. Dawson, "A Location Dereferencing 1205 Protocol Using HELD", 1206 draft-winterbottom-geopriv-deref-protocol-05 (work in 1207 progress), January 2010. 1209 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1210 Requirement Levels", BCP 14, RFC 2119, March 1997. 1212 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1213 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1214 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1216 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 1218 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1219 January 2004. 1221 13.2. Informative References 1223 [I-D.barnes-geopriv-policy-uri] 1224 Barnes, R., Thomson, M., Winterbottom, J., and H. 1225 Tschofenig, "Location Configuration Extensions for Policy 1226 Management", draft-barnes-geopriv-policy-uri-02 (work in 1227 progress), November 2010. 1229 [I-D.ietf-geopriv-arch] 1230 Barnes, R., Lepinski, M., Cooper, A., Morris, J., 1231 Tschofenig, H., and H. Schulzrinne, "An Architecture for 1232 Location and Location Privacy in Internet Applications", 1233 draft-ietf-geopriv-arch-03 (work in progress), 1234 October 2010. 1236 [I-D.loreto-http-bidirectional] 1237 Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 1238 "Known Issues and Best Practices for the Use of Long 1239 Polling and Streaming in Bidirectional HTTP", 1240 draft-loreto-http-bidirectional-07 (work in progress), 1241 January 2011. 1243 [I-D.thomson-geopriv-uncertainty] 1244 Thomson, M. and J. Winterbottom, "Representation of 1245 Uncertainty and Confidence in PIDF-LO", 1246 draft-thomson-geopriv-uncertainty-05 (work in progress), 1247 May 2010. 1249 [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997. 1251 [RFC5808] Marshall, R., "Requirements for a Location-by-Reference 1252 Mechanism", RFC 5808, May 2010. 1254 Authors' Addresses 1256 Martin Thomson 1257 Andrew Corporation 1258 Andrew Building (39) 1259 Wollongong University Campus 1260 Northfields Avenue 1261 Wollongong, NSW 2522 1262 AU 1264 Email: martin.thomson@andrew.com 1266 James Winterbottom 1267 Andrew Corporation 1268 Andrew Building (39) 1269 Wollongong University Campus 1270 Northfields Avenue 1271 Wollongong, NSW 2522 1272 AU 1274 Email: james.winterbottom@andrew.com 1276 Mary Barnes 1277 Polycom 1278 US 1280 Email: mary.ietf.barnes@gmail.com