| TOC |
|
This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.
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.”
The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 11, 2010.
Copyright (c) 2009 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 in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document.
A framework for the exchange of capabilities in HELD is described. Capabilities for enabling Device-based measurements and Device-based location generation are defined based on this framework.
1.
Introduction
2.
Conventions used in this document
3.
Capabilities Exchange Overview
3.1.
Capabilities Exchange
4.
The Capability Indication
4.1.
Capability Definitions
5.
Capability Invocation
5.1.
HTTP Polling
5.2.
Invocation Resource
5.3.
Invocation Time
5.4.
Responding to a Capability Invocation
5.5.
Multiple Invocations
6.
The Location Capability
6.1.
Location Capability Summary
7.
Location Measurement Capability
7.1.
Location Measurement Capability Summary
8.
XML Schema for Capabilities
9.
Example Capabilities Exchange and Invocation
10.
Security Considerations
10.1.
URI Secrecy
11.
IANA Considerations
11.1.
URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap
11.2.
URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap:location
11.3.
URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap:lm
11.4.
XML Schema Registration for HELD Capabilities
12.
References
12.1.
Normative References
12.2.
Informative References
| TOC |
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 are largely covered by the measurement information and data formats described in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” October 2009.). However, location information provided through location URIs cannot utilise this information.
This document outlines a method whereby a Device indicates capabilities to a LIS during the creation of a HELD context (see [I‑D.winterbottom‑geopriv‑held‑context] (Winterbottom, J., Tschofenig, H., and M. Thomson, “Location URI Contexts in HTTP-Enabled Location Delivery (HELD),” October 2009.)). The LIS is able to then exercise those capabilities to assist it in the generation of location information, or to acquire location information from the Device.
| TOC |
This document relies on definitions from a range of specification. 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 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,” October 2009.) and location estimate is defined in [I‑D.thomson‑geopriv‑uncertainty] (Thomson, M. and J. Winterbottom, “Representation of Uncertainty and Confidence in PIDF-LO,” November 2009.). The term HELD context (or just context) is used as defined in [I‑D.winterbottom‑geopriv‑held‑context] (Winterbottom, J., Tschofenig, H., and M. Thomson, “Location URI Contexts in HTTP-Enabled Location Delivery (HELD),” October 2009.).
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 |
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.
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. The relationship is extended to include stateful information at the LIS in the form of a HELD context (Winterbottom, J., Tschofenig, H., and M. Thomson, “Location URI Contexts in HTTP-Enabled Location Delivery (HELD),” October 2009.) [I‑D.winterbottom‑geopriv‑held‑context]. This document builds HELD contexts by providing a means for the LIS to request information from the Device.
This document describes how a HELD context can be used as the basis for cooperative location determination. A Device provides the LIS with a capabilities indication when it creates or updates its context data. The LIS responds with a capabilities agreement, that includes which of these capabilities it might use.
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 is able to invoke specific capabilities to request location information, location measurements, or any other information from the Device.
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 the GNSS measurement data.
This document defines a set of capabilities that a Device can use to indicate that it is able to provide location measurements. The form of location measurements is described in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” October 2009.). A Device is able to use these capabilities to indicate to the LIS the types of measurements that it can observe and the means by which the LIS can acquire these measurements when needed. 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 |
+--------+ +-------+ +-----------+
| | |
+-------createContext----->| |
| (capability indication) | |
| | |
|<------contextResponse----+ |
| (capability agreement) | |
| | |
|~ ~ ~ ~ ~ ~ ~ ~(convey location URI)~ ~ ~ ~ ~ >|
| | |
| |<--locationRequest--+
| capability | |
|<-------invocation--------+ |
| | |
|<- - - - exchange - - - ->| |
| (measurements/location) | |
| +--locationResponse->|
| | |
| Figure 1: Logical Overview of Operation |
In practice, this scheme relies on HTTP polling to provide a channel for LIS communication. This mechanism is described in more detail in Section 5 (Capability Invocation).
This document also defines a location capability, which indicates that the Device is able to determine its own location. Guidelines for the definition of other capabilities are also included.
| TOC |
To indicate capabilities to a LIS, a Device sends a capability indication to the LIS in a HELD createContext request. The capability indication includes a set of capabilities, each identified by a URI. The LIS selects those capabilities that it might make use of and provides a capabilities agreement that includes the selected capabilities in a contextResponse message.
+--------+ +-------+
| Device | | LIS |
+--------+ +-------+
| |
+-----------createContext----------->|
| (capability indication: A, B, C) |
| |
|<----------contextResponse----------+
| (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 generate location information. This might be an ability to generate geodetic location information at the Device, or the Device might be able provide the LIS with location measurements. Agreed capabilities and associated parameters can be stored in the HELD context for later use in serving requests.
The LIS invokes capabilities as it is necessary to service requests to the HELD context. For instance, capabilities might be used to respond to a location request made by a location recipient (LR) to one of the location URIs provided by the context.
+--------+ +-------+ +-----------+
| | | | | Location |
| Device | | LIS | | Recipient |
+--------+ +-------+ +-----------+
| | |
| |<--locationRequest--+
| capability | |
|<-------invocation--------+ |
| | |
|<- - - - exchange - - - ->| |
| (measurements/location) | |
| +--locationResponse->|
| | |
| Figure 3: Invoking Capabilities (Logical Process) |
Capabilities are related to a single context. The LIS MUST restrict its use of capabilities to requests relating to the context where the capabilities are provided by the Device. The LIS MUST remove any pre-existing capabilities from a context when it receives a capabilities indication. Therefore, a Device is able to remove specific capabilities from a context by providing a capabilities indication that omits that capability. An empty capabilities indication removes all capabilities.
A capabilities exchange may contain additional information that is specific to the associated measurement acquisition method. This additional information allows the Device and LIS to provide more information about individual capabilities. This information is stored along with the agreed capabilities in the HELD context.
| TOC |
A capabilities element is added to the create context or update context HELD requests. The Device initiates the exchange, including the capind element in the request message. The capagree element contain in the response from the LIS includes the set of capabilities that might be used.
Both capind and capagree elements contain a set of capability indications. A single capability is represented by a cap element. Each cap element has a mandatory uri attribute that contains a URI unique to the type of capability. An id attribute identifies the individual capability within the context of an exchange; the value used by the LIS matches the corresponding indication by the Device.
The cap element may also contain arbitrary content, which means that the element is able to carry supplementary information that is specific to the capability. This supplementary information could include addressing information, protocol selection, authentication details, or any data necessary for the successful retrieval of information. Different supplementary information can be provided by the Device and LIS.
The optional responseTime attribute of the cap element indicates the expected time that invoking that particular capability takes. This parameter assists the LIS in deciding whether or not to invoke a capability when serving a request for location information. The responseTime attribute is an integer value in milliseconds. The responseTime attribute only appears in a capabilities indication.
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.
Multiple capability indications are not necessary, since a set of capabilities can be specified in the same element. A LIS MAY either select an arbitrary capability indication, or combine capabilities from multiple indications.
The following figure shows a capabilities indication that might be made by a Device with GNSS capabilities. This uses the location capability defined in Section 6 (The Location Capability), as well as a second capability that includes additional parameters.
<capind xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:location"
id="cap-loc1" responseTime="45000"/>
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:lm"
id="cap-gnss1" responseTime="30000">
<lm xmlns:gnss="urn:ietf:params:xml:ns:geopriv:lm:gnss">
gnss:gnss
</lm>
</cap>
</capind>
| TOC |
Capabilities can be defined for access network or location measurement technologies as required. No special registration is required to define a capability; each capability is identified by a namespace URI. A capability definition includes the following information:
- URI:
- A capability is identified by a URI, which need only be unique and persistent. Common practice is to use an http: URI for a domain that is under the author's control. An IETF document MUST use a URN (Moats, R., “URN Syntax,” May 1997.) [RFC2141] that is registered with the IANA.
- Capability Parameters:
- Each capability may require additional information to be passed between LIS and Device in order for it to be exercised. This information must be described and defined as XML elements for inclusion in the cap element. Separate descriptions and definitions SHOULD be provided for the Device to LIS indications and LIS to Device responses.
- Procedures for Invoking Capabilities:
- Each capability MUST also include a description of how it can be exercised. This includes the protocol that is used for any network exchanges, the impact of each parameter. The HTTP polling mechanism described in Section 5 (Capability Invocation) SHOULD be used as the basis for any LIS-to-Device communication, but other mechanisms more appropriate to the capability might be used.
- Security and Privacy Implications:
- A discussion of the security and the privacy implications associated with using the capability MUST be included with each definition.
- Author Contact:
- Details on how to contact the individual or organization responsible for the capability definition.
| TOC |
This section describes the mechanism used for invoking the two Device capabilities defined in this document. Capabilities defined elsewhere MAY use other mechanisms that are more suited to the capability.
When agreeing upon a capability, the LIS indicates a resource that the Device is requested to monitor. The contents of this resource identify the information that the LIS desires. By monitoring this resource, the Device is informed when the LIS requires more information and the Device is then able to provide that information.
The following capability agreement from a LIS indicates that in order to allow for invocation of the agreed capabilities, a Device needs to monitor a specific resource. The same URI is provided for both capabilities in this instance, but different resources MAY be indicated.
<capagree xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:location"
id="cap-loc1">
<poll>https://lis.example.com/cap/SEVMRCBpcyBncmVhdC4</poll>
</cap>
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:lm"
id="cap-gnss1">
<poll>https://lis.example.com/cap/SEVMRCBpcyBncmVhdC4</poll>
<lm xmlns:gnss="urn:ietf:params:xml:ns:geopriv:lm:gnss">
gnss:gnss
</lm>
</cap>
</capagree>
| TOC |
The Device monitors this 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.
If long-polling is used, the Device indicates this by using the Response-Time (TBD) header and a conditional request header, such as If-Modified-Since or If-None-Match. If the request times out before the resource is updated, the server indicates this with an HTTP 304 response. An HTTP 200 response is sent immediately when the resource is updated. In order to continue monitoring the state of the resource after either response, the Device immediately sends another request.
In the absence of the conditional HTTP headers, the server can assume that short-polling is in use. If short-polling is used, the Device should limit the frequency of requests based on the time indicated in the HTTP Expires header.
The LIS updates this resource to indicate which capability it wishes to invoke and any conditions on the invocation.
| TOC |
The resource that the Device monitors contains instructions from the LIS. The information contained by this resource is used to invoke one or more capabilities.
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 capinv. Initially, this document is likely to be empty (containing a single, empty capinv element).
A change in the state of the invocation resource triggers the behaviour associated with a given capability. The value of the invocation resource indicates the capability, and any actions that is desired.
For instance, if the LIS wants to invoke the location capability of the Device, it updates the document to the following:
<capinv xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:location"
capid="cap-loc1" before="2009-07-09T13:55:01+10:00">
<target>https://lis.example.com/U2Nob29sIGlzIGNvb2wu</target>
</cap>
</capinv>
The Device MUST continue to monitor the invocation resource. Therefore, any request can be cancelled by removing capabilities from the invocation document; or updated by changing the capability details. Expiry of the HELD context, or removal of the invocation resource terminates any monitoring. An HTTP 404 (Not Found) or 410 (Gone) response is sufficient indication to the Device that the resource no longer exists.
| TOC |
The before attribute on the capability invocation serves to advise the Device on the latest time when a response is needed. For the two capabilities defined in this document, this time is the latest moment that information from the Device is of use to the LIS. If this time has passed, or the capability cannot be invoked before this time, then the capability invocation can be ignored.
The periodic attribute on a capability establishes a requirement for 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.
For instance, the following invocation contains a request to provide Global Navigation Satellite System (GNSS) measurements before 2009-07-09T13:55:01+10:00 and at 60 second intervals (before 13:55:01, then before 13:56:01, then 13:57:01, and continuing indefinitely).
<capinv xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:lm"
capid="cap-gnss1"
before="2009-07-09T13:55:01+10:00" periodic="60000">
<target>https://lis.example.com/TWVhc3VyZSBmaXJzdC4</target>
</cap>
</capinv>
| TOC |
A Device that wishes to provide information MUST do so when it receives an invocation that it can comply with. The information is pushed to the URI indicated in the target element as an HTTP PUT. The format of the information provided depends on the capability.
Information provided in this manner can be considered as additional supplementary information added to the HELD context. The same authorization rules that apply to the context apply to this data. A LIS is able to redistribute this information and anything results based on this information under the same terms as the context operates. This information MUST be removed when the context is removed. 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,” October 2009.), MUST be respected.
| TOC |
The same invoke resource MAY be used for multiple capabilities. Devices that support multiple capabililties identify the capability that the LIS desires to use through the capability identification provided. If multiple capabilities are invoked at the same time, the Device MAY choose to provide all information concurrently, or separately. The Device MAY choose to provide some information, then only provide the additional information if the invoke resource continues to include a request for the additional information.
The measurement capability inherently supports provision of multiple measurements concurrently. A single measurement container can be provided with multiple different forms of measurement. In comparison, the location capability does not provide this option. Unless specifically stated in the definition of a capability, responding to each invocation requires a separate HTTP request.
| TOC |
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. Because the Device produces complete location information, there is no need for technology- or network-specific features in messages. Therefore, this section describes how a Device may advertise its capability to source its own location.
This section defines a location capability, identified by the URN urn:ietf:params:xml:ns:geopriv:held:cap:location. This capability indicates that the Device is able to provide location information to the LIS.
The location capability is invoked using the method described in Section 5 (Capability Invocation). A URI is provided by the LIS and the Device monitors this resource. If the location capability is invoked, the Device provides location information, in the form of a PIDF-LO. The Device uses an HTTP PUT to the target URI. 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. 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 HELD context.
| TOC |
The following summarizes the location capability following the outline from Section 4.1 (Capability Definitions):
- URI:
- urn:ietf:params:xml:ns:geopriv:held:cap:location
- Capability Parameters:
- This capability indication includes no parameters; the capability agreement includes a URI that references an invocation document containing instructions for the Device.
- Procedures for Invoking Capabilities:
- The Device monitors the invocation resource using HTTP polling. If that document indicates this capability, an HTTP PUT is use to provide the LIS with information.
- Security and Privacy Implications:
- See Section 10 (Security Considerations) of this document.
- Author Contact:
- The authors of this document.
| TOC |
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,” October 2009.) 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.
The measurement capability is identified by the URN urn:ietf:params:xml:ns:geopriv:held:cap:lm. In addition to this URN, the Device also needs to indicate which measurements it can provide in the capability indication. This is done by identifying the location measurement element.
The lm element includes a qualified element name (using the namespace context of the enclosing document). This element name identifies a measurement element, as defined by the guidelines in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” October 2009.).
Inclusion of the lm element is only necessary in a capabilities indication, it MAY be omitted from any capabilities agreement or capabilities invocation.
When the LIS invokes this capability, the Device provides location measurements in the HTTP PUT to the specified URI. This document contains the MIME type application/xml [[Ed: probably need to define new MIME type for this]] 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.
| TOC |
The following summarizes the location measurement capability following the outline from Section 4.1 (Capability Definitions):
- URI:
- urn:ietf:params:xml:ns:geopriv:held:cap:lm
- Capability Parameters:
- This capability includes a single lm element in all capability indicates that identifies the type of location measurement that can be provided. This parameter is only used in the capabilities indication sent from Device to LIS.
The capability agreement includes a URI that references an invocation document containing instructions for the Device.- Procedures for Invoking Capabilities:
- The Device monitors the invocation resource using HTTP polling. If that document indicates this capability, an HTTP PUT is use to provide the LIS with the indicated measurement information.
- Security and Privacy Implications:
- See Section 10 (Security Considerations) of this document.
- Author Contact:
- The authors of this document.
| TOC |
<?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:attributeGroup name="capIdentity">
<xs:attribute name="id" type="xs:NCName" use="required"/>
<xs:attribute name="uri" type="xs:anyURI" use="required"/>
<xs:anyAttribute namespace="##any" processContents="lax"/>
</xs:attributeGroup>
<!-- Capability indication -->
<xs:element name="capind" type="cap:capindType"/>
<xs:complexType name="capindType">
<xs:complexContent>
<xs:restriction base="xs:anyType">
<xs:sequence>
<xs:element name="cap" type="cap:capind-capType"
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="capind-capType">
<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:capIdentity"/>
<xs:attribute name="responseTime" type="xs:nonNegativeInteger"
use="optional"/>
</xs:restriction>
</xs:complexContent>
</xs:complexType>
<!-- Capability agreement -->
<xs:element name="capagree" type="cap:capagreeType"/>
<xs:complexType name="capagreeType">
<xs:complexContent>
<xs:restriction base="xs:anyType">
<xs:sequence>
<xs:element name="cap" type="cap:capagree-capType"
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="capagree-capType">
<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:capIdentity"/>
</xs:restriction>
</xs:complexContent>
</xs:complexType>
<!-- Capability invocation -->
<xs:element name="capinv" type="cap:capinvType"/>
<xs:complexType name="capinvType">
<xs:complexContent>
<xs:restriction base="xs:anyType">
<xs:sequence>
<xs:element name="cap" type="cap:capinv-capType"
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="capinv-capType">
<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:capIdentity"/>
<xs:attribute name="before" type="xs:dateTime"/>
<xs:attribute name="periodic" type="xs:nonNegativeInteger"
use="optional"/>
</xs:restriction>
</xs:complexContent>
</xs:complexType>
<!-- Invocation resource URI -->
<xs:element name="poll" type="xs:anyURI"/>
<!-- Target URI for data provided by a Device -->
<xs:element name="target" type="xs:anyURI"/>
<!-- Location measurement element for measurement capability -->
<xs:element name="lm" type="cap:lmType"/>
<xs:complexType name="lmType">
<xs:simpleContent>
<xs:extension base="xs:QName">
<xs:anyAttribute namespace="##any" processContents="lax"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
| TOC |
This section shows sample messages relating to the creation of a context 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 creates a context, including a capabilities indication:
<createContext
xmlns="urn:ietf:params:xml:ns:geopriv:held:context">
<lifetime>7200</lifetime>
<snapshot>false</snapshot>
<capind xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:location"
id="cap-loc1" responseTime="45000"/>
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:lm"
id="cap-gnss1" responseTime="30000">
<lm xmlns:gnss="urn:ietf:params:xml:ns:geopriv:lm:gnss">
gnss:gnss
</lm>
</cap>
</capind>
</createContext>
Two capabilities are included: location and measurement. The measurement capability indicates that GNSS measurements can be provided by the Device.
The LIS response includes context details, along with a capabilities agreement:
<contextResponse code="created"
xmlns="urn:ietf:params:xml:ns:geopriv:held:context">
<context id="uhvuhdbnuiehudbnvcujevuijeijcvij4"
snapshot="false" expires="2009-07-11T15:06:00+10:00">
<locationUriSet>
<locationURI>
https://lis.example.com:9768/357yc6s64ceyoiuy5ax3o4
</locationURI>
</locationUriSet>
</context>
<capagree xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:location"
id="cap-loc1">
<poll>https://lis.example.com/cap/SEVMRCBpcyBncmVhdC4</poll>
</cap>
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:lm"
id="cap-gnss1">
<poll>https://lis.example.com/cap/SEVMRCBpcyBncmVhdC4</poll>
</cap>
</capagree>
</contextResponse>
This indication instructs the Device to monitor the same URI to determine when the LIS wants to invoke either capability.
The Device then monitors the state of the resource: [[ TODO: Add long-polling-specific headers.]]
GET /cap/SEVMRCBpcyBncmVhdC4 HTTP/1.1 Host: lis.example.com
The resource initially contains no invocation instructions:
HTTP/1.1 200 OK Server: Example LIS Date: Fri, 10 Jul 2009 05:06:12 GMT Expires: Fri, 10 Jul 2009 05:07:05 GMT ETag: "xyzzy" Cache-control: private Content-Type: application/held+xml Content-Length: 59 <capinv xmlns="urn:ietf:params:xml:ns:geopriv:held:cap"/>
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: Fri, 10 Jul 2009 05:07:54 GMT
Expires: Fri, 10 Jul 2009 05:08:25 GMT
Cache-control: private
Content-Type: application/held+xml
Content-Length: 269
<capinv xmlns="urn:ietf:params:xml:ns:geopriv:held:cap">
<cap uri="urn:ietf:params:xml:ns:geopriv:held:cap:lm"
id="cap-gnss1"
before="2009-07-10T15:08:25+10:00">
<target>https://lis.example.com/TWVhc3VyZSBmaXJzdC4</target>
</cap>
</capinv>
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 /TWVhc3VyZSBmaXJzdC4 HTTP/1.1
Host: lis.example.com
Content-Type: application/xml
Content-Length: 678
<measurements xmlns="urn:ietf:params:xml:ns:geopriv:lm"
time="2009-07-10T15:08:06.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: Fri, 10 Jul 2009 05:08:08 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 |
The information provided by a Device in the course of responding to a capabilities invocation could be private data. This information might grant the LIS the ability to locate the Device with greater accuracy than would be otherwise possible. Furthermore, information about the capabilities of a Device could also be considered sensitive. A Device SHOULD offer a user the option to suppress some or all capabilities.
Capabilities MUST only be exchanged with the LIS in the scope of a context. This precaution provides the Device with a means to cancel access to these capabilities at any time. This can be done by deleting the context, or by indicating an empty set of capabilities to the LIS.
Any information that is provided to the LIS by the Device increases the impact of LIS impersonation. Measures that mitigate the possibility of impersonation, as outlined in [I‑D.ietf‑geopriv‑lis‑discovery] (Thomson, M. and J. Winterbottom, “Discovering the Local Location Information Server (LIS),” March 2010.), are more important for a Device that provides capability information to a LIS. Protocols used for the exchange of location information or location measurements should also provide protection from eavesdropping.
Responding to a capabilities invocation might require significant investment of time and resources by a Device. Even the process of monitoring the invocation resource requires substantial effort, with little initial investment. This could be exploited by a malicious LIS to exhaust batteries of perform other denial of service attacks. A Device SHOULD limit the resources it makes available to a LIS in relation to capabilities it advertises.
The LIS is responsible for the veracity of location information it provides, even when it relies on information that comes from the Device. This considerations described in [I‑D.thomson‑geopriv‑held‑measurements] (Thomson, M. and J. Winterbottom, “Using Device-provided Location-Related Measurements in Location Configuration Protocols,” October 2009.) apply to all Device-provided information.
Server authentication for all stages of the process are important, not only for the HELD createContext request, but also for retrieving the capabilities invocation and publishing the requested information. These resources do no need to be provided by the same server, but each resource MUST be authenticated based on the domain name in the URI, if possible. HTTP over TLS (Rescorla, E., “HTTP Over TLS,” May 2000.) [RFC2818] is strongly RECOMMENDED for each of these exchanges.
| TOC |
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 authorized. If an attacker knows this URI, they are able to 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 these two resources. HTTP over TLS (Rescorla, E., “HTTP Over TLS,” May 2000.) [RFC2818] MUST be used unless confidentiality can be guaranteed by other means.
To make guessing more difficult, 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 |
This section registers a URN for a capabilities XML namespace (Section 11.1 (URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap)) and a corresponding schema (Section 11.4 (XML Schema Registration for HELD Capabilities)). URNs are registered for the location (Section 11.2 (URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap:location)) and location measurement (Section 11.3 (URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap:lm)) capabilities.
| TOC |
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 |
This section registers a new XML namespace, urn:ietf:params:xml:ns:held:cap:location, as per the guidelines in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).
URI: urn:ietf:params:xml:ns:held:cap:location
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 - Location Capability</title> </head> <body> <h1>Namespace for HELD Capabilities - Location Capability</h1> <h2>urn:ietf:params:xml:ns:held:cap:location</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 |
This section registers a new XML namespace, urn:ietf:params:xml:ns:held:cap:lm, as per the guidelines in [RFC3688] (Mealling, M., “The IETF XML Registry,” January 2004.).
URI: urn:ietf:params:xml:ns:held:cap:lm
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 - Location Measurement Capability</title> </head> <body> <h1>Namespace for HELD Capabilities - Location Measurement Capability</h1> <h2>urn:ietf:params:xml:ns:held:cap:lm</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 |
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 8 (XML Schema for Capabilities) of this document.
| TOC |
| TOC |
| [RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
| [RFC2818] | Rescorla, E., “HTTP Over TLS,” RFC 2818, May 2000 (TXT). |
| [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.winterbottom-geopriv-held-context] | Winterbottom, J., Tschofenig, H., and M. Thomson, “Location URI Contexts in HTTP-Enabled Location Delivery (HELD),” draft-winterbottom-geopriv-held-context-05 (work in progress), October 2009 (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-05 (work in progress), October 2009 (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). |
| TOC |
| [RFC2141] | Moats, R., “URN Syntax,” RFC 2141, May 1997 (TXT, HTML, XML). |
| [RFC3688] | Mealling, M., “The IETF XML Registry,” BCP 81, RFC 3688, January 2004 (TXT). |
| [RFC4119] | Peterson, J., “A Presence-based GEOPRIV Location Object Format,” RFC 4119, December 2005 (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-04 (work in progress), November 2009 (TXT). |
| TOC |
| Martin Thomson | |
| Andrew | |
| PO Box U40 | |
| Wollongong University Campus, NSW 2500 | |
| AU | |
| Phone: | +61 2 4221 2915 |
| EMail: | martin.thomson@andrew.com |
| URI: | http://www.andrew.com/ |
| James Winterbottom | |
| Andrew | |
| PO Box U40 | |
| Wollongong University Campus, NSW 2500 | |
| AU | |
| Phone: | +61 2 4221 2938 |
| EMail: | james.winterbottom@andrew.com |
| URI: | http://www.andrew.com/ |