TOC 
GEOPRIVM. Thomson
Internet-DraftJ. Winterbottom
Intended status: Standards TrackAndrew Corporation
Expires: January 1, 2011M. Barnes
 Polycom
 June 30, 2010


Device Capability Negotiation for Device-Based Location Determination and Location Measurements in HELD
draft-thomson-geopriv-held-capabilities-08

Abstract

A Device is a valuable source of information about its location. A Location Information Server (LIS) that serves a location URI about a Device is unable to acquire this information. Extensions to HTTP-Enabled Location Delivery (HELD) are described for negotiating and exercising Device capabilities for location determination or location measurement collection.

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

This Internet-Draft will expire on January 1, 2011.

Copyright Notice

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.



Table of Contents

1.  Introduction
2.  Conventions used in this document
3.  Capabilities Exchange Overview
    3.1.  Capabilities Exchange
    3.2.  Capabilities Invocation
4.  The Capability Exchange
    4.1.  Capabilities Advertisement
    4.2.  Capabilities Agreement
5.  Capability Invocation
    5.1.  HTTP Polling
    5.2.  Invocation Resource
    5.3.  Invocation Time
    5.4.  Responding to a Capability Invocation
    5.5.  Error Reponse to an Invocation
    5.6.  Multiple Invocations
6.  The Location Capability
    6.1.  Parameters
    6.2.  Invocation
7.  Location Measurement Capability
    7.1.  Parameters
    7.2.  Invocation
8.  Example Capabilities Exchange and Invocation
9.  Security Considerations
    9.1.  Privacy Considerations
    9.2.  URI Secrecy
    9.3.  Location Veracity
10.  IANA Considerations
    10.1.  Registration of HELD 'noMeasurement' Error Code
    10.2.  URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap
    10.3.  XML Schema Registration for HELD Capabilities
11.  XML Schema for Capabilities
12.  Acknowledgements
13.  References
    13.1.  Normative References
    13.2.  Informative References
§  Authors' Addresses




 TOC 

1.  Introduction

A Device is a good source of information about its location. Even where a Device is unable to independently determine its location, it can often make observations about its environment and network attachment that are of use in determining its position. Making this information available to the Location Information Server (LIS) in the access network can improve the quality of location estimates for the Device.

Requests that retrieve location information by value can benefit from Device-provided measurement data, as described in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” May 2010.). However, location information provided through location URIs (Marshall, R., “Requirements for a Location-by-Reference Mechanism,” May 2010.) [RFC5808] cannot effectively use this information. The LIS that serves the URI is unable to contact the Device to acquire information.

Access to some form of location determination is a necessary precondition of providing a location URI. The LIS that serves that location URI is assumed to be capable of determining the location of the Device. A LIS might only have a limited capacity for determining location in serving a location URI. The quality and timeliness of responses can be improved with Device assistance.

Acquiring location measurements or information from a Device is made difficult by the nature of the relationship between the LIS, or access network, and the Device. The relationship between a LIS and the Devices that it serves is often transient. A Device is not necessarily a permanent part of an access network, so it is not possible to pre-arrange trust relationships between Device and LIS.

HELD (Barnes, M., Winterbottom, J., Thomson, M., and B. Stark, “HTTP Enabled Location Delivery (HELD),” August 2009.) [I‑D.ietf‑geopriv‑http‑location‑delivery] provides a basis for the relationship between Device and LIS. LIS Discovery [I‑D.ietf‑geopriv‑lis‑discovery] (Thomson, M. and J. Winterbottom, “Discovering the Local Location Information Server (LIS),” March 2010.) provides a means for the Device to initiate the relationship. This document extends the basic HELD location request to include negotiation of a mechanism that allows the LIS to request information from the Device.

Location-related Device capabilities include the ability to generate or acquire location information, or the ability to make observations about the mode of network attachment or environment. For instance, a Device with Global Navigation Satellite System (GNSS) hardware can determine its own position by taking a set of measurements and performing a calculation, or it can provide GNSS measurement data.

This document describes how a Device can advertise its ability to locate itself or provide location-related measurement data to a LIS. This advertisement is made in a HELD location request where the Device acquires a location URI (see [I‑D.ietf‑geopriv‑http‑location‑delivery] (Barnes, M., Winterbottom, J., Thomson, M., and B. Stark, “HTTP Enabled Location Delivery (HELD),” August 2009.)). The LIS is then able to exercise advertised capabilities to acquire location-related measurement data or location information from the Device when serving the location URI.



 TOC 

2.  Conventions used in this document

This document relies on definitions from [I‑D.ietf‑geopriv‑arch] (Barnes, R., Lepinski, M., Cooper, A., Morris, J., Tschofenig, H., and H. Schulzrinne, “An Architecture for Location and Location Privacy in Internet Applications,” May 2010.). Use of the terms LIS and Device is consistent with [I‑D.ietf‑geopriv‑http‑location‑delivery] (Barnes, M., Winterbottom, J., Thomson, M., and B. Stark, “HTTP Enabled Location Delivery (HELD),” August 2009.). Location-related measurement data (and location measurement) is defined in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” May 2010.) and location estimate is defined in [I‑D.thomson‑geopriv‑uncertainty] (Thomson, M. and J. Winterbottom, “Representation of Uncertainty and Confidence in PIDF-LO,” May 2010.).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).



 TOC 

3.  Capabilities Exchange Overview

A Device provides the LIS with a capabilities advertisement when it requests a location URI. A Device can advertise the ability to acquire location-related measurement data of any type (see [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” May 2010.)), or the ability to autonomously determine its own location.

The LIS responds with a capabilities agreement, that includes which of these capabilities it might use. As part of the agreement, the LIS identifies an HTTP resource (the invocation resource) that it will use to request Device assistance. The Device monitors this resource as long as it is willing to provide the advertised data.

In the process of serving requests to a location URI, a LIS might determine that certain Device capabilities could be useful or necessary in completing the request. The LIS alters the invocation resource to include a request that details what data is desired. The Device acquires the updated resource and provides the requested information.

Figure 1 (Logical Overview of Operation) shows a logical overview of a simple scenario where the LIS uses a Device-provided measurement to service a request to a location URI.



  +--------+                   +-------+            +-----------+
  |        |                   |       |            | Location  |
  | Device |                   |  LIS  |            | Recipient |
  +--------+                   +-------+            +-----------+
      |                            |                      |
      +----- locationRequest ----->|                      |
      | (capability advertisement) |                      |
      |                            |                      |
      |<----- locationResponse ----+                      |
      |   (capability agreement)   |                      |
      |                            |                      |
      |~ ~ ~ ~ ~ ~ ~ ~ ~(convey location URI)~ ~ ~ ~ ~ ~ >|
      |                            |                      |
      |                            |<-- locationRequest --+
      |         capability         |                      |
      |<------- invocation --------+                      |
      |                            |                      |
      +--------- publish --------->|                      |
      |  (measurements/location)   |                      |
      |                            +-- locationResponse ->|
      |                            |                      |
 Figure 1: Logical Overview of Operation 

In practice, this scheme relies on HTTP polling to provide a channel for capability invocation. This mechanism is described in more detail in Section 5 (Capability Invocation).



 TOC 

3.1.  Capabilities Exchange

To indicate capabilities to a LIS, a Device advertises its location determination or measurement capabilities to the LIS in a HELD locationRequest message. The LIS selects those capabilities that it might make use of and provides a capabilities agreement that includes the selected capabilities in the locationResponse message, along with the location URI.



    +--------+                            +-------+
    | Device |                            |  LIS  |
    +--------+                            +-------+
        |                                     |
        +---------- locationRequest --------->|
        | (capability advertisement: A, B, C) |
        |                                     |
        |<--------- locationResponse ---------+
        |          (location URI set)         |
        |     (capability agreement: A, C)    |
        |                                     |
 Figure 2: Capabilities Exchange 

Once a common set of capabilities are agreed upon, the LIS is able invoke these capabilities to assist in the generation of location information. Agreed capabilities and associated parameters are stored in association with the contextual information necessary for serving the location URI.



 TOC 

3.2.  Capabilities Invocation

The LIS invokes capabilities as it is necessary to service requests to the location URIs it provides.



  +--------+                 +-------+              +-----------+
  |        |                 |       |              | Location  |
  | Device |                 |  LIS  |              | Recipient |
  +--------+                 +-------+              +-----------+
      |                          |                        |
      +--------- poll ---------->|                        |
      |                          |                        |
      .                          .                        .
      |                          |                        |
      |                          |<--- locationRequest ---+
      |        capability        |                        |
      |<------ invocation -------+                        |
      |                          |                        |
      |<- - - - exchange - - - ->|                        |
      | (measurements/location)  |                        |
      |                          +--- locationResponse -->|
      |                          |                        |
 Figure 3: Invoking Capabilities 

Capabilities are bound to the location URIs that are provided in the response that indicates the mutually agreed capabilities. The LIS MUST NOT use capabilities for any purpose other than serving those location URIs.

The set of capabilities associated with a location URI is fixed. A Device instead applies local policy in determining whether to respond to a capability invocation. A Device can choose to discontinue selected capabilities by refusing to respond to a capability invocation. A Device can also cease to monitor the resource used for capability invocation to terminate all capabilities.



 TOC 

4.  The Capability Exchange

A capabilities exchange is initiated with a location request from a Device. The Device includes a capbilities advertisement in the location request. The LIS responds with agreed capabilities in the location response.



 TOC 

4.1.  Capabilities Advertisement

A Device capabilities advertisement (the deviceCapabilities element) is added to the HELD location request by the Device. This element can contain a location element to indicate that the Device is capable of determining its own location autonomously; it can also contain one or more measurement elements, each indicating that the Device is cable of providing location measurement data.

Each capability is uniquely identified with a id attribute.

A responseTime attribute indicates the expected time that acquiring the location or measurement data takes, in milliseconds. The advertised response time assists the LIS in deciding whether or not to invoke a capability when serving a request for location information.

The Device is only able to quantify the time for its own involvement in the process; additional delays from polling, network transit and LIS processing need to be included in any decision to invoke a Device capability.

Location measurement capabilities include a type attribute, which identifies the type of measurement. Types are identified using the qualified name of the XML element for the measurement, as with the measurementRequest element defined in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” May 2010.).

Each capability element can also contain arbitrary content that carries supplementary information specific to the capability. This supplementary information includes, but is not restricted to, measurement parameters that identify specific aspects of a measurement capability. Different supplementary information can be provided by the Device and LIS.

The following figure shows a capabilities advertisement that might be made by a Device with GNSS capabilities. This includes both autonomous GNSS location determination capability as well as GNSS measurement capability with additional parameters.

  <deviceCapabilities
      xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
    <location id="loc" responseTime="45000"/>
    <measurement xmlns:g="urn:ietf:params:xml:ns:geopriv:lm:gnss"
                 type="g:gnss" id="gps" responseTime="12000">
      <g:gnss system="gps" signal="L1"/>
    </measurement>
  </deviceCapabilities>


 TOC 

4.2.  Capabilities Agreement

A capabilities agreement (agreedCapabilities element) is included in the HELD location response. This element contains a subset of the advertised capabilities, indicating which capabilities the LIS wishes to use. Capabilities are identified using the id attribute, but other attributes are omitted.

A capabilities agreement contains an HTTP URI for an invocation resource. The monitor element indicates a resource that the Device is requested to monitor for capability invocations (Capability Invocation).

The following figure shows a capabilities agreement that might be made in response to a device capabilities advertisement. This includes an invoke resource and a reference to each device capability, using the id attribute for each location and measurement capability.

  <agreedCapabilities
      xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
    <monitor>https://lis.example.com/inv/C90dXBsZT4KPC</monitor>
    <location id="loc"/>
    <measurement id="gps"/>
  </agreedCapabilities>


 TOC 

5.  Capability Invocation

The LIS includes a URI for an HTTP "invocation" resource in the capabilities agreement. A Device that wishes to provide advertised capabilities monitors this resource.

The contents of the invocation resource identify the information that the LIS desires. The LIS updates the invocation resource when a request to a location URI is made that could benefit from location or measurement data acquired by the Device.

The invocation resource is updated to identify one or more capabilities when information is requested by the LIS. For each capability, the resource includes a destination URI for the requested data, and a time. By monitoring the invocation resource, the Device is informed when the LIS requires more information and the Device is then able to provide that information.



 TOC 

5.1.  HTTP Polling

The Device monitors the invocation resource, using either HTTP long-polling (Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, “Best Practices for the Use of Long Polling and Streaming in Bidirectional HTTP,” February 2010.) [I‑D.loreto‑http‑bidirectional] or periodic requests (short-polling). Both methods use the HTTP GET method. Client and server developers are reminded that full support of HTTP (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” June 1999.) [RFC2616] facilities is expected.

The Device SHOULD retrieve an initial representation of the resource and poll for updates using conditional request headers, such as If-Modified-Since or If-None-Match. The Device SHOULD use long-polling and indicate this using a Timeout header (Loreto, S., Thomson, M., and G. Wilkins, “Hypertext Transfer Protocol (HTTP) Timeouts,” June 2010.) [I‑D.loreto‑http‑timeout] [[...or whatever replaces this, since Timeout is already taken]]. An HTTP 200 (OK) response is sent immediately when the resource is updated, or an HTTP 304 (Not Modified) response is sent if the timeout period lapses . In order to continue monitoring the state of the resource, the Device immediately sends another request upon receiving a response.

In the absence of the Timeout header, the server MAY assume that short-polling is in use. If short-polling is used, the Device MUST NOT continuously poll for updates. The server can limit the rate that a client is able to poll by sending a 503 (Service Unavailable) response with an appropriate Retry-After header. A client that receives this header MUST adjust its polling rate to match the indicated period.



 TOC 

5.2.  Invocation Resource

The resource that the Device monitors identifies individual capabilities and when the information that they provide is requested.

The value of the invocation resource determines what information is required. This document is an XML document with the MIME type of application/held+xml and a document element of invokeCapability. Initially, this document is likely to be empty.

A Device monitors the invocation resource for changes. A change in the state of the invocation resource indicates that the LIS requests some data. The value of the invocation resource indicates the capability, where the data associated with the capability is to be pushed by the Device, and when the associated data is to be provided.

For instance, if the LIS wants to invoke the location capability of the Device, it updates the resource to produce the following representation:

  <invokeCapabilities
      xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
    <measurement id="gps" before="2011-07-09T13:55:01+10:00">
      <push>https://lis.example.com/push/U2Nob29sIGlzIGNvb2wu</push>
    </measurement>
  </invokeCapabilities>

The Device monitors the invocation resource as long as it is willing to respond to capability invocation requests, though it MAY suspend any monitoring while it responds to a request for data. Upon expiry of the location URI, the Device SHOULD stop monitoring the resource. An HTTP 404 (Not Found) or 410 (Gone) response can be provided to indicate to the Device that the resource no longer exists.



 TOC 

5.3.  Invocation Time

The before attribute on the capability invocation serves to advise the Device on the latest time when a response is desired. This time is the latest moment that information from the Device is of use to the LIS. If this time has passed, or the requested information cannot be provided before this time, then the capability invocation can be ignored.

The periodic attribute on a capability requests periodic updates. The attribute contains a time interval in milliseconds, which specifies the periodicity desired. This indicates that the Device provide information before the time specified in the before attribute and periodically thereafter at the specified interval.

Periodic invocations continue until the invocation is modified or removed. The Device SHOULD continue to monitor the invocation resource to be informed of any changes.

For instance, the following invocation contains a request to provide measurements for the capability identified with the id attribute of gps. This information should be provided before 2011-07-09T13:55:01+10:00 and at 60 second intervals thereafter (before 13:55:01, then before 13:56:01, then 13:57:01, and so on).

  <invokeCapabilities
      xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
    <measurement id="gps" before="2011-07-09T13:55:01+10:00"
                 periodic="60000">
      <push>https://lis.example.com/push/U2Nob29sIGlzIGNvb2wu</push>
    </measurement>
  </invokeCapabilities>

The following figure shows that a Device acquires measurement data immediately upon receiving a capability invocation with a periodic interval. After these measurements are pushed to the LIS, the Device waits for a period. The time that is waited is the difference between the periodic interval (p) and the expected time to acquire measurement data (m). This ensures that measurement data is provided to the LIS prior to the requested time.


                    +--------+           +-------+
                    | Device |           |  LIS  |
                    +--------+           +-------+
                        |                    |
                        |      periodic      |
                        |<--- capability ----+
                        |     invocation     |
                 .--------------.            |
                 |   Acquire    |            |
                 | Measurements |            |
 Before          `--------------'            |
  Time                  |                    |
    \                   +------ push ------->|
     \______________    |    measurements    +--...
       ^     ^          |                    |
       |     |          '                    '
       |   (p-m)     <wait>
       |     |          .                    .
       |     v______    |                    |
       |     ^   .--------------.            |
      (p)    |   |   Acquire    |            |
       |     |   | Measurements |            |
       |    (m)  `--------------'            |
       |     |          |                    |
       |     |          +------ push ------->|
       v_____v______    |    measurements    +--...
       ^                |                    |
       '                '                    '


 TOC 

5.4.  Responding to a Capability Invocation

A Device that wishes to provide information SHOULD do so when it receives an invocation that it can comply with. Any information is pushed to the URI indicated in the push element as an HTTP PUT. The format of the information provided depends on the capability.

A Device can choose to ignore a capability invocation at any time.

Information provided in this manner can be considered as additional supplementary information that is provided for the purposes of serving the location URI. The same authorization rules that apply to the location URI apply to this data. A LIS is able to redistribute this information and any results based on this information under the same policy that the location URI operates. Any information MUST only be used as permitted by the Device. Explicit data expiration indications, such as that used in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” May 2010.), MUST be respected.



 TOC 

5.5.  Error Reponse to an Invocation

A Device might be unable to acquire the requested location or measurement information when it is requested. In this case, a HELD error message is sent to the resource indicated in the push element of the invocation, in place of the requested data. The HELD error message is defined in Section 5.3 of [I‑D.ietf‑geopriv‑http‑location‑delivery] (Barnes, M., Winterbottom, J., Thomson, M., and B. Stark, “HTTP Enabled Location Delivery (HELD),” August 2009.).

Requests for location information can elicit a push containing any of the applicable HELD error codes (including locationUnknown). Requests for measurement data can result in the same set of codes, plus a newly defined error code: noMeasurement is defined in Section 10.1 (Registration of HELD 'noMeasurement' Error Code).



 TOC 

5.6.  Multiple Invocations

The same invoke resource is used for multiple capabilities. Devices that support multiple capabililties identify the capability that the LIS desires to use through the id attribute on the capability. If multiple capabilities are invoked at the same time, the Device MAY choose to provide all information concurrently or separately, and in whole, in part or not at all.

The measurement capability inherently supports provision of multiple measurements concurrently. A single measurement container can be provided with multiple different forms of measurement. Measurement and location capabilities are pushed separately.

A LIS MUST provide a different push resource for each separate capability that it invokes. Without this, information from the Device cannot be reliably correlated with a specific capability. For instance, an error response for one capability might be misinterpreted as an error for all capabilities.



 TOC 

6.  The Location Capability

The location capability indicates that the Device can determine its own location. This is represented by the inclusion of a location element.

The ability to locate itself is a trait that is applicable to Devices in a range of networks. This includes automated location determination, like Global Navigation Satellite Systems (GNSS), user input, an alternative location service, or a range of location techniques.



 TOC 

6.1.  Parameters

The location element MAY include a locationType element that includes a value of civic or geodetic, a space-separated list containing both values, or the value any. A basic description of the semantics of location type is included in Section 6.3 of HELD (Barnes, M., Winterbottom, J., Thomson, M., and B. Stark, “HTTP Enabled Location Delivery (HELD),” August 2009.) [I‑D.ietf‑geopriv‑http‑location‑delivery].

When included in the capabilities advertisement, the locationType element indicates the type of location information that the device is capable of providing. When included in other messages, the locationType element indicates the type of location information that the LIS requests that the Device provide. Omitting the locationType element indicates that the previous value from the most recent message is requested; if there is no such value, then any form of location information is acceptable.



 TOC 

6.2.  Invocation

When invoked, the Device provides location information in the form of a PIDF-LO. The Device uses an HTTP PUT to the URI identified in the push element of the capability invocation. The PUT request includes a PIDF-LO document and a Content-Type of application/pidf+xml.

Only the location-info element of the PIDF-LO is used by the LIS; other PIDF-LO fields SHOULD be minimally populated by the Device. It is RECOMMENDED that the Device generate an unlinked pseudonym for the entity attribute of the presence document to avoid providing identity information.

In providing location information in this manner, the Device implicitly grants the LIS the ability to redistribute location information under the same conditions that apply to the location URI that the capability was negotiated with.



 TOC 

7.  Location Measurement Capability

The location capability indicates that the Device can acquire location-related measurement data of a specified type. This is represented by the inclusion of a measurement element.

Measurement data from the Device can be invaluable in improving the quality of location information. Measurement information from a Device can improve the accuracy of location estimates or enable positioning methods that would not otherwise be available. See [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” May 2010.) for more information on location measurements. Providing access to measurement data by using the capability exchange makes these advantages available when a location recipient uses a location URI to retrieve location information.



 TOC 

7.1.  Parameters

A capability advertisement for location measurements includes the type of measurement that is supported, using the type attribute of the measurement element. Measurement types are identified using the XML qualified name of the measurement element, as defined for the measurement request in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” May 2010.).

The type attribute is omitted from the capabilities agreement and capability invocation. If the LIS supports or requires a subset of the measurement data, it MAY indicate this using measurement parameters in the agreement or the capability invocation. Omission of parameters in either message indicates that the last set parameters are to be applied. For instance, if parameters are included in the capabilities advertisement and revised in the capabilities agreement, a capability invocation can omit these and have the parameters from the agreement applied.

A capability invocation MAY include a samples parameter to request that the Device provide a certain number of samples of the indicated measurement type. The samples parameter defaults to 1.

The Device MAY ignore this parameter and provide a smaller (or larger) number of samples. However, a Device SHOULD indicate how many samples were acquired for a given measurement type, either by including multiple measurements, by providing multiple separate responses, or by setting the samples attribute for elements of the measurement where available.



 TOC 

7.2.  Invocation

The Device acquires and pushes location measurements to the identified URI when a measurement capability is invoked. The Device uses an HTTP PUT to the URI identified in the target element of the capability indication. This document contains the MIME type application/held+xml and has a document element of measurements. This document contains one or more measurement elements containing the requested measurement data.

Multiple measurements can be provided at the same time. The measurements element simply contains multiple measurement elements. This can be used to simultaneously provide information for multiple different invocations of this capability. Measurements that are acquired at different times are provided in different requests.



 TOC 

8.  Example Capabilities Exchange and Invocation

This section shows sample messages relating to a location request with capabilities, monitoring the invocation resource and the provision of measurement or location information. HTTP headers are shown on messages where it is relevant to do so.

The following HELD request from a Device includes a capabilities advertisement; HTTP headers are omitted:

  <held:locationRequest
      xmlns:held="urn:ietf:params:xml:ns:geopriv:held">
    <held:locationType exact="true">locationURI</held:locationType>
    <requestPolicyUri
        xmlns="urn:ietf:params:xml:ns:geopriv:held:policy"/>

    <cap:deviceCapabilities
        xmlns:cap="urn:ietf:params:xml:ns:geopriv:held:cap">
      <cap:location id="loc" responseTime="45000">
        <held:locationType>geodetic</held:locationType>
      </cap:location>
      <cap:measurement
          xmlns:gnss="urn:ietf:params:xml:ns:geopriv:lm:gnss"
          type="gnss:gnss" id="gps" responseTime="12000">
        <gnss:gnss system="gps" signal="L1"/>
      </cap:measurement>
    </cap:deviceCapabilities>
  </held:locationRequest>

Two capabilities are included: location and measurement. The measurement capability indicates that GNSS measurements can be provided by the Device. The GNSS capability indicates that measurement for the GPS L1 signal are the only GNSS measurement supported.

The LIS response includes location URIs, along with a capabilities agreement:

  <held:locationResponse
      xmlns:held="urn:ietf:params:xml:ns:geopriv:held">
    <held:locationUriSet expires="2011-07-11T15:06:00+10:00">
      <held:locationURI>
        https://lis.example.com/OnBhcmFtczp4bWw6bnM6c
      </held:locationURI>
    </held:locationUriSet>

    <cap:agreedCapabilities
        xmlns:cap="urn:ietf:params:xml:ns:geopriv:held:cap">
      <cap:monitor>
        https://lis.example.com/inv/OnBhcmFtczp4C90dXBsZT4KPC
      </cap:monitor>
      <cap:location id="loc"/>
      <cap:measurement id="gps"/>
    </cap:agreedCapabilities>
  </held:locationResponse>

This indication instructs the Device to monitor a URI to determine when the LIS wants to invoke either capability.

The Device then monitors the state of the resource:

GET /inv/OnBhcmFtczp4C90dXBsZT4KPC HTTP/1.1
Host: lis.example.com

The resource initially contains no invocation instructions:

HTTP/1.1 200 OK
Server: Example LIS
Date: Sat, 9 Jul 2011 03:06:12 GMT
Expires: Sat, 9 Jul 2011 03:08:42 GMT
ETag: "xyzzy"
Cache-Control: private
Content-Type: application/held+xml
Content-Length: 76

<invokeCapabilities
    xmlns="urn:ietf:params:xml:ns:geopriv:held:cap"/>

The Device then issues a long-polling request to monitor the state of the resource:

GET /inv/OnBhcmFtczp4C90dXBsZT4KPC HTTP/1.1
Host: lis.example.com
If-None-Match: "xyzzy"
Timeout: 600

Some time later, the LIS receives a location request and decides that the GNSS measurement capability of the Device would be useful or necessary in completing the reqeust. The LIS updates the invocation resource with instructions to the Device to provide location measurements:

HTTP/1.1 200 OK
Server: Example LIS
Date: Sat, 9 Jul 2011 03:54:44 GMT
Expires: Sat, 9 Jul 2011 03:55:01 GMT
Cache-Control: private
Content-Type: application/held+xml
Content-Length: 245

<invokeCapabilities
    xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
  <measurement id="gps" before="2011-07-09T13:55:01+10:00">
    <push>https://lis.example.com/push/U2Nob29sIGlzIGNvb2wu</push>
  </measurement>
</invokeCapabilities>

The Device decides that it is able to provide these data. It takes the requested measurement and pushes the measurement data to the indicated destination:

PUT /push/U2Nob29sIGlzIGNvb2wu HTTP/1.1
Host: lis.example.com
Content-Type: application/held+xml
Content-Length: 688

<measurements xmlns="urn:ietf:params:xml:ns:geopriv:lm"
              time="2011-07-09T13:54:56.490+10:00" timeError="2e-5">
  <gnss xmlns="urn:ietf:params:xml:ns:geopriv:lm:gnss"
        system="gps" signal="L1">
    <sat num="19">
      <doppler>499.9395</doppler>
      <codephase rmsError="1.6e-9">0.87595747</codephase>
      <cn0>45</cn0>
    </sat>
    <sat num="27">
      <doppler>378.2657</doppler>
      <codephase rmsError="1.6e-9">0.56639479</codephase>
      <cn0>52</cn0>
    </sat>
    <sat num="20">
      <doppler>-633.0309</doppler>
      <codephase rmsError="1.6e-9">0.57016835</codephase>
      <cn0>48</cn0>
    </sat>
  </gnss>
</measurements>

The LIS immediately provides an empty response to the Device:

HTTP/1.1 204 No Content
Server: Example LIS
Date: Sat, 9 Jul 2011 03:54:58 GMT

The LIS is then able to use the provided measurement data to provide highly accurate location information in response to the request it received.



 TOC 

9.  Security Considerations

Use of location or measurement capabilities has privacy considerations (Privacy Considerations). Protecting privacy depends on the secrecy of the URIs used (URI Secrecy). Use of Device capability also exposes a LIS to the possibility of a Device that falsifies location or measurement data (Location Veracity).



 TOC 

9.1.  Privacy Considerations

The information provided by a Device in the course of responding to a capabilities invocation privacy-sensitive data. This is either location information, or measurement data that could be use to produce location information. The GEOPRIV architecture (Barnes, R., Lepinski, M., Cooper, A., Morris, J., Tschofenig, H., and H. Schulzrinne, “An Architecture for Location and Location Privacy in Internet Applications,” May 2010.) [I‑D.ietf‑geopriv‑arch] provides a framework for the handling of location and location-related information.

Information about the capabilities of a Device might be privacy sensitive. Similarly, willingness to provide capabilities might be sensitive.

HTTP over TLS (Rescorla, E., “HTTP Over TLS,” May 2000.) [RFC2818] MUST be used to provide confidentiality for Device capabilities and the location or measurement data that is provided by the Device.

All data acquired by the LIS in relation to a location URI MUST only be used for the purpose of serving the location URI. Any access control policy - such as that installed using [I‑D.barnes‑geopriv‑policy‑uri] (Barnes, R., Thomson, M., and J. Winterbottom, “Location Configuration Extensions for Policy Management,” May 2010.) - that applies to the location URI also applies to any information acquired using Device capabilities.

Any information that is provided to the LIS by the Device increases the impact of LIS impersonation. Measures that aim to prevent impersonation, as outlined in [I‑D.ietf‑geopriv‑lis‑discovery] (Thomson, M. and J. Winterbottom, “Discovering the Local Location Information Server (LIS),” March 2010.), MUST be applied if a Device provides capability information to a LIS. These measures include server authentication (Saint-Andre, P. and J. Hodges, “Representation and Verification of Domain-Based Application Server Identity in Certificates Used with Transport Layer Security,” June 2010.) [I‑D.saintandre‑tls‑server‑id‑check] for all stages of the process.

Server authentication MUST be used for the HELD location request containing the capability exchange, for retrieving the capabilities invocation and for publishing any requested information. Resources that are identified by the LIS do no need to be provided by the same server identity, but each resource MUST be authenticated based on the domain name in the URI. HTTP over TLS (Rescorla, E., “HTTP Over TLS,” May 2000.) [RFC2818] is strongly RECOMMENDED for each of these exchanges.



 TOC 

9.2.  URI Secrecy

Using capabilities offers attackers a means to provide invalid location or measurement data. The URI offered by the LIS for receiving location or measurement data is not protected by an access policy. Knowledge of this URI is all that is required to provide information. If an attacker is able to learn this URI, they could provide misleading information that could be used by the LIS.

The only protection provided is secrecy. Only the Device is given the URI to the invocation resource, which is where the URI used for providing information is made available. To guarantee this secrecy, the URI of the invocation resource and any URIs contained therein need to be difficult to acquire or guess.

The LIS MUST use confidentiality protection on the channel it uses to provide all resources used in the capability exchange and subsequent requests: the LIS URI used for the location request, the invocation resource, and the resource that location or measurement data is pushed to. HTTP over TLS (Rescorla, E., “HTTP Over TLS,” May 2000.) [RFC2818] MUST be used unless confidentiality can be guaranteed by other means.

To lower the probability of these URIs being discovered by guessing or inference, these URIs MUST include sufficient randomness. The LIS SHOULD also periodically change the URIs it provides to limit any exposure in the case that these URIs become known to an attacker.



 TOC 

9.3.  Location Veracity

The LIS is responsible for the veracity of location information it provides, especially when serving a location URI. Information acquired from a location URI is attributed to the LIS, unless there is an explicit indication as to the provenance of the data.

A Device might exploit this by spoofing location or measurement data. A Device thereby falsely gains any credibility that recipients of that data might attribute to the LIS.

This and other related considerations described in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” May 2010.) apply to the use of Device-provided information. At a minimum, a LIS SHOULD mark location tuples with the source element.



 TOC 

10.  IANA Considerations

This section registers a URN for a HELD capabilities XML namespace (Section 10.2 (URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap)) and a corresponding schema (Section 10.3 (XML Schema Registration for HELD Capabilities)).



 TOC 

10.1.  Registration of HELD 'noMeasurement' Error Code

This section registers the noMeasurement error code in the "Geopriv HELD Registries, Error codes for HELD" IANA registry.

noMeasurement
This error code indicates that all requested location-related measurement data could not be acquired by the Device.


 TOC 

10.2.  URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap

This section registers a new XML namespace, urn:ietf:params:xml:ns:held:cap, as per the guidelines in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).

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

Registrant Contact: IETF, GEOPRIV working group, (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com).

XML:

      BEGIN
        <?xml version="1.0"?>
        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
        <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
          <head>
            <title>HELD Capabilities Indication</title>
          </head>
          <body>
            <h1>Namespace for HELD Capabilities Indication</h1>
            <h2>urn:ietf:params:xml:ns:held:cap</h2>
[[NOTE TO IANA/RFC-EDITOR: Please update RFC URL and replace XXXX
    with the RFC number for this specification.]]
            <p>See <a href="[[RFC URL]]">RFCXXXX</a>.</p>
          </body>
        </html>
      END



 TOC 

10.3.  XML Schema Registration for HELD Capabilities

This section registers an XML schema as per the guidelines in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).

URI:
urn:ietf:params:xml:schema:held:cap
Registrant Contact:
IETF, GEOPRIV working group, (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com).
Schema:
The XML for this schema can be found as the entirety of Section 11 (XML Schema for Capabilities) of this document.



 TOC 

11.  XML Schema for Capabilities

<?xml version="1.0"?>
<xs:schema
     xmlns:cap="urn:ietf:params:xml:ns:geopriv:held:cap"
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     targetNamespace="urn:ietf:params:xml:ns:geopriv:held:cap"
     elementFormDefault="qualified"
     attributeFormDefault="unqualified">

  <xs:annotation>
    <xs:appinfo
        source="urn:ietf:params:xml:schema:geopriv:held:cap">
      HELD Capabilities
    </xs:appinfo>
    <xs:documentation source="http://www.ietf.org/rfc/rfcXXXX.txt">
<!-- [[NOTE TO RFC-EDITOR: Please replace above URL with URL of
                       published RFC and remove this note.]] -->
      This schema is the basis for HELD capabilities negotiation.
    </xs:documentation>
  </xs:annotation>

  <xs:element name="deviceCapabilities" type="cap:deviceCapType"/>
  <xs:complexType name="deviceCapType">
    <xs:complexContent>
      <xs:restriction base="xs:anyType">
        <xs:sequence>
          <xs:element name="location"
                      type="cap:deviceCapLocationType"
                      minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="measurement"
                      type="cap:deviceCapMeasurementType"
                      minOccurs="0" maxOccurs="unbounded"/>
          <xs:any namespace="##other" processContents="lax"
                  minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="deviceCapLocationType">
    <xs:complexContent>
      <xs:extension base="cap:agreedCapLocationType">
        <xs:attribute name="responseTime" type="xs:nonNegativeInteger"
                      use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="deviceCapMeasurementType">
    <xs:complexContent>
      <xs:extension base="cap:agreedCapMeasurementType">
        <xs:attribute name="responseTime" type="xs:nonNegativeInteger"
                      use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>

  <xs:element name="agreedCapabilities" type="cap:agreedCapType"/>
  <xs:complexType name="agreedCapType">
    <xs:complexContent>
      <xs:restriction base="xs:anyType">
        <xs:sequence>
          <xs:element name="monitor" type="xs:anyURI"/>
          <xs:element name="location"
                      type="cap:agreedCapLocationType"
                      minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="measurement"
                      type="cap:agreedCapMeasurementType"
                      minOccurs="0" maxOccurs="unbounded"/>
          <xs:any namespace="##other" processContents="lax"
                  minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <xs:attributeGroup name="baseCapAttrs">
    <xs:attribute name="id" type="xs:NCName" use="required"/>
    <xs:anyAttribute namespace="##local" processContents="strict"/>
  </xs:attributeGroup>

  <xs:complexType name="agreedCapLocationType">
    <xs:complexContent>
      <xs:restriction base="xs:anyType">
        <xs:sequence>
          <xs:any namespace="##any" processContents="lax"
                  minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attributeGroup ref="cap:baseCapAttrs"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="agreedCapMeasurementType">
    <xs:complexContent>
      <xs:restriction base="xs:anyType">
        <xs:sequence>
          <xs:any namespace="##any" processContents="lax"
                  minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="type" type="xs:QName" use="optional"/>
        <xs:attributeGroup ref="cap:baseCapAttrs"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <!-- not included in agreedCapLocationType due to UPA -->
  <xs:element name="locationType" type="cap:locationTypeType"/>
  <xs:simpleType name="locationTypeType">
    <xs:union>
      <xs:simpleType>
        <xs:restriction base="xs:token">
          <xs:enumeration value="any"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType>
        <xs:restriction base="cap:locationTypeList">
          <xs:minLength value="1"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:union>
  </xs:simpleType>

  <xs:simpleType name="locationTypeList">
    <xs:list>
      <xs:simpleType>
        <xs:restriction base="xs:token">
          <xs:enumeration value="civic"/>
          <xs:enumeration value="geodetic"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:list>
  </xs:simpleType>

  <xs:element name="invokeCapabilities" type="cap:invokeCapType"/>
  <xs:complexType name="invokeCapType">
    <xs:complexContent>
      <xs:restriction base="xs:anyType">
        <xs:sequence>
          <xs:element name="location"
                      type="cap:invokeCapLocationType"
                      minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="measurement"
                      type="cap:invokeCapMeasurementType"
                      minOccurs="0" maxOccurs="unbounded"/>
          <xs:any namespace="##other" processContents="lax"
                  minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <xs:attributeGroup name="invokeTimeGroup">
    <xs:attribute name="before" type="xs:dateTime" use="required"/>
    <xs:attribute name="periodic" type="xs:positiveInteger"
                  use="optional"/>
  </xs:attributeGroup>

  <xs:complexType name="invokeCapLocationType">
    <xs:complexContent>
      <xs:restriction base="cap:agreedCapLocationType">
        <xs:sequence>
          <xs:element name="push" type="xs:anyURI"/>
          <xs:any namespace="##any" processContents="lax"
                  minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attributeGroup ref="cap:invokeTimeGroup"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

  <xs:complexType name="invokeCapMeasurementType">
    <xs:complexContent>
      <xs:restriction base="cap:agreedCapMeasurementType">
        <xs:sequence>
          <xs:element name="push" type="xs:anyURI"/>
          <xs:any namespace="##any" processContents="lax"
                  minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attributeGroup ref="cap:invokeTimeGroup"/>
        <xs:attribute name="samples" type="xs:positiveInteger"
                      use="optional" default="1"/>
      </xs:restriction>
    </xs:complexContent>
  </xs:complexType>

</xs:schema>


 TOC 

12.  Acknowledgements

Richard Barnes provided useful input on the state management mechanisms that are used in this document.



 TOC 

13.  References



 TOC 

13.1. Normative References

[I-D.ietf-geopriv-http-location-delivery] Barnes, M., Winterbottom, J., Thomson, M., and B. Stark, “HTTP Enabled Location Delivery (HELD),” draft-ietf-geopriv-http-location-delivery-16 (work in progress), August 2009 (TXT).
[I-D.ietf-geopriv-lis-discovery] Thomson, M. and J. Winterbottom, “Discovering the Local Location Information Server (LIS),” draft-ietf-geopriv-lis-discovery-15 (work in progress), March 2010 (TXT).
[I-D.loreto-http-timeout] Loreto, S., Thomson, M., and G. Wilkins, “Hypertext Transfer Protocol (HTTP) Timeouts,” draft-loreto-http-timeout-00 (work in progress), June 2010 (TXT).
[I-D.saintandre-tls-server-id-check] Saint-Andre, P. and J. Hodges, “Representation and Verification of Domain-Based Application Server Identity in Certificates Used with Transport Layer Security,” draft-saintandre-tls-server-id-check-06 (work in progress), June 2010 (TXT).
[I-D.thomson-geopriv-held-measurements] Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” draft-thomson-geopriv-held-measurements-06 (work in progress), May 2010 (TXT).
[I-D.winterbottom-geopriv-deref-protocol] Winterbottom, J., Tschofenig, H., Schulzrinne, H., Thomson, M., and M. Dawson, “A Location Dereferencing Protocol Using HELD,” draft-winterbottom-geopriv-deref-protocol-05 (work in progress), January 2010 (TXT).
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML).
[RFC2818] Rescorla, E., “HTTP Over TLS,” RFC 2818, May 2000 (TXT).
[RFC3688] Mealling, M., “The IETF XML Registry,” BCP 81, RFC 3688, January 2004 (TXT).


 TOC 

13.2. Informative References

[I-D.barnes-geopriv-policy-uri] Barnes, R., Thomson, M., and J. Winterbottom, “Location Configuration Extensions for Policy Management,” draft-barnes-geopriv-policy-uri-01 (work in progress), May 2010 (TXT).
[I-D.ietf-geopriv-arch] Barnes, R., Lepinski, M., Cooper, A., Morris, J., Tschofenig, H., and H. Schulzrinne, “An Architecture for Location and Location Privacy in Internet Applications,” draft-ietf-geopriv-arch-02 (work in progress), May 2010 (TXT).
[I-D.loreto-http-bidirectional] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, “Best Practices for the Use of Long Polling and Streaming in Bidirectional HTTP,” draft-loreto-http-bidirectional-02 (work in progress), February 2010 (TXT).
[I-D.thomson-geopriv-uncertainty] Thomson, M. and J. Winterbottom, “Representation of Uncertainty and Confidence in PIDF-LO,” draft-thomson-geopriv-uncertainty-05 (work in progress), May 2010 (TXT).
[RFC2141] Moats, R., “URN Syntax,” RFC 2141, May 1997 (TXT, HTML, XML).
[RFC5808] Marshall, R., “Requirements for a Location-by-Reference Mechanism,” RFC 5808, May 2010 (TXT).


 TOC 

Authors' Addresses

  Martin Thomson
  Andrew Corporation
  Andrew Building (39)
  Wollongong University Campus
  Northfields Avenue
  Wollongong, NSW 2522
  AU
Email:  martin.thomson@andrew.com
  
  James Winterbottom
  Andrew Corporation
  Andrew Building (39)
  Wollongong University Campus
  Northfields Avenue
  Wollongong, NSW 2522
  AU
Email:  james.winterbottom@andrew.com
  
  Mary Barnes
  Polycom
  US
Email:  mary.ietf.barnes@gmail.com