One document matched: draft-thomson-geopriv-held-capabilities-07.xml
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2141 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2141.xml">
<!ENTITY RFC2818 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2818.xml">
<!ENTITY RFC3688 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3688.xml">
<!ENTITY RFC4119 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4119.xml">
<!ENTITY I-D.ietf-geopriv-http-location-delivery PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-geopriv-http-location-delivery.xml">
<!ENTITY I-D.ietf-geopriv-lis-discovery PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-geopriv-lis-discovery.xml">
<!ENTITY I-D.winterbottom-geopriv-held-context PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.winterbottom-geopriv-held-context.xml">
<!ENTITY I-D.thomson-geopriv-held-measurements PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.thomson-geopriv-held-measurements.xml">
<!ENTITY I-D.winterbottom-geopriv-deref-protocol PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.winterbottom-geopriv-deref-protocol.xml">
<!ENTITY I-D.thomson-geopriv-uncertainty PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.thomson-geopriv-uncertainty.xml">
<!ENTITY I-D.loreto-http-bidirectional PUBLIC "" "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.loreto-http-bidirectional.xml">
]>
<?rfc rfcedstyle="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="no"?>
<?rfc iprnotified="yes"?>
<?rfc strict="yes"?>
<?rfc toc="yes"?>
<?rfc tocindent="yes"?>
<rfc category="std" ipr="trust200902">
<front>
<title abbrev="HELD Capabilities">
Device Capability Negotiation for Device-Based Location Determination and Location Measurements in HELD
</title>
<author initials="M." surname="Thomson" fullname="Martin Thomson">
<organization>Andrew Corporation</organization>
<address>
<postal>
<street>Andrew Building (39)</street>
<street>Wollongong University Campus</street>
<street>Northfields Avenue</street>
<city>Wollongong</city>
<region>NSW</region>
<code>2522</code>
<country>AU</country>
</postal>
<email>martin.thomson@andrew.com</email>
</address>
</author>
<author initials="J." surname="Winterbottom" fullname="James Winterbottom">
<organization>Andrew Corporation</organization>
<address>
<postal>
<street>Andrew Building (39)</street>
<street>Wollongong University Campus</street>
<street>Northfields Avenue</street>
<city>Wollongong</city>
<region>NSW</region>
<code>2522</code>
<country>AU</country>
</postal>
<email>james.winterbottom@andrew.com</email>
</address>
</author>
<date month="January" year="2010"/>
<area>Application</area>
<workgroup>GEOPRIV</workgroup>
<keyword>Internet-Draft</keyword>
<keyword>HELD</keyword>
<keyword>Capabilities</keyword>
<keyword>Location</keyword>
<keyword>Measurements</keyword>
<keyword>Device-based</keyword>
<abstract>
<t>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.
</t>
</abstract>
</front>
<middle>
<section anchor="intro" title="Introduction">
<t>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.
</t>
<t>Requests that retrieve location information by value are largely covered by the measurement information and data formats described in <xref target="I-D.thomson-geopriv-held-measurements"/>. However, location information provided through location URIs cannot utilise this information.
</t>
<t>This document outlines a method whereby a Device indicates capabilities to a LIS during the creation of a HELD context (see <xref target="I-D.winterbottom-geopriv-held-context"/>). 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.
</t>
</section>
<section anchor="conventions" title="Conventions used in this document">
<t>This document relies on definitions from a range of specification. Use of the terms LIS and Device is consistent with <xref target="I-D.ietf-geopriv-http-location-delivery"/>. Location measurement is defined in <xref target="I-D.thomson-geopriv-held-measurements"/> and location estimate is defined in <xref target="I-D.thomson-geopriv-uncertainty"/>. The term HELD context (or just context) is used as defined in <xref target="I-D.winterbottom-geopriv-held-context"/>.
</t>
<t>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 <xref target="RFC2119"/>.
</t>
</section>
<section anchor="overview" title="Capabilities Exchange Overview">
<t>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.
</t>
<t><xref target="I-D.ietf-geopriv-http-location-delivery">HELD</xref> provides a basis for the relationship between Device and LIS. LIS Discovery <xref target="I-D.ietf-geopriv-lis-discovery"/> 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 <xref target="I-D.winterbottom-geopriv-held-context">HELD context</xref>. This document builds HELD contexts by providing a means for the LIS to request information from the Device.
</t>
<t>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.
</t>
<t>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.
</t>
<t>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.
</t>
<t>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 <xref target="I-D.thomson-geopriv-held-measurements"/>. 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. <xref target="logical"/> shows a logical overview of a simple scenario where the LIS uses a Device-provided measurement to service a request to a location URI.
</t>
<figure anchor="logical" title="Logical Overview of Operation">
<artwork><![CDATA[
+--------+ +-------+ +-----------+
| | | | | Location |
| Device | | LIS | | Recipient |
+--------+ +-------+ +-----------+
| | |
+-------createContext----->| |
| (capability indication) | |
| | |
|<------contextResponse----+ |
| (capability agreement) | |
| | |
|~ ~ ~ ~ ~ ~ ~ ~(convey location URI)~ ~ ~ ~ ~ >|
| | |
| |<--locationRequest--+
| capability | |
|<-------invocation--------+ |
| | |
|<- - - - exchange - - - ->| |
| (measurements/location) | |
| +--locationResponse->|
| | |
]]></artwork>
</figure>
<t>In practice, this scheme relies on HTTP polling to provide a channel for LIS communication. This mechanism is described in more detail in <xref target="poll"/>.
</t>
<t>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.
</t>
<section title="Capabilities Exchange">
<t>To indicate capabilities to a LIS, a Device sends a capability indication to the LIS in a HELD <spanx style="verb">createContext</spanx> 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 <spanx style="verb">contextResponse</spanx> message.
</t>
<figure anchor="capex" title="Capabilities Exchange">
<artwork><![CDATA[
+--------+ +-------+
| Device | | LIS |
+--------+ +-------+
| |
+-----------createContext----------->|
| (capability indication: A, B, C) |
| |
|<----------contextResponse----------+
| (capability agreement: A, C) |
| |
]]></artwork>
</figure>
<t>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.
</t>
<t>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.
</t>
<figure anchor="excap" title="Invoking Capabilities (Logical Process)">
<artwork><![CDATA[
+--------+ +-------+ +-----------+
| | | | | Location |
| Device | | LIS | | Recipient |
+--------+ +-------+ +-----------+
| | |
| |<--locationRequest--+
| capability | |
|<-------invocation--------+ |
| | |
|<- - - - exchange - - - ->| |
| (measurements/location) | |
| +--locationResponse->|
| | |
]]></artwork>
</figure>
<t>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.
</t>
<t>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.
</t>
</section>
</section>
<section title="The Capability Indication">
<t>A <spanx style="verb">capabilities</spanx> element is added to the create context or update context HELD requests. The Device initiates the exchange, including the <spanx style="verb">capind</spanx> element in the request message. The <spanx style="verb">capagree</spanx> element contain in the response from the LIS includes the set of capabilities that might be used.
</t>
<t>Both <spanx style="verb">capind</spanx> and <spanx style="verb">capagree</spanx> elements contain a set of capability indications. A single capability is represented by a <spanx style="verb">cap</spanx> element. Each <spanx style="verb">cap</spanx> element has a mandatory <spanx style="verb">uri</spanx> attribute that contains a URI unique to the type of capability. An <spanx style="verb">id</spanx> attribute identifies the individual capability within the context of an exchange; the value used by the LIS matches the corresponding indication by the Device.
</t>
<t>The <spanx style="verb">cap</spanx> 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.
</t>
<t>The optional <spanx style="verb">responseTime</spanx> attribute of the <spanx style="verb">cap</spanx> 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 <spanx style="verb">responseTime</spanx> attribute is an integer value in milliseconds. The <spanx style="verb">responseTime</spanx> attribute only appears in a capabilities indication.
<list style="empty"><t>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.
</t></list>
</t>
<t>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.
</t>
<figure>
<preamble>The following figure shows a capabilities indication that might be made by a Device with GNSS capabilities. This uses the location capability defined in <xref target="location"/>, as well as a second capability that includes additional parameters.
</preamble>
<artwork><![CDATA[
<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>
]]></artwork>
</figure>
<section anchor="defn" title="Capability Definitions">
<t>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:
<list style="hanging">
<t hangText="URI:">A capability is identified by a URI, which need only be unique and persistent. Common practice is to use an <spanx style="verb">http:</spanx> URI for a domain that is under the author's control. An IETF document MUST use a <xref target="RFC2141">URN</xref> that is registered with the IANA.
</t>
<t hangText="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 <spanx style="verb">cap</spanx> element. Separate descriptions and definitions SHOULD be provided for the Device to LIS indications and LIS to Device responses.
</t>
<t hangText="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 <xref target="poll"/> SHOULD be used as the basis for any LIS-to-Device communication, but other mechanisms more appropriate to the capability might be used.
</t>
<t hangText="Security and Privacy Implications:">A discussion of the security and the privacy implications associated with using the capability MUST be included with each definition.
</t>
<t hangText="Author Contact:">Details on how to contact the individual or organization responsible for the capability definition.
</t>
</list>
</t>
</section>
</section>
<section anchor="poll" title="Capability Invocation">
<t>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.
</t>
<t>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.
</t>
<figure>
<preamble>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.
</preamble>
<artwork><![CDATA[
<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>
]]></artwork>
</figure>
<section title="HTTP Polling">
<t>The Device monitors this resource, using either <xref target="I-D.loreto-http-bidirectional">HTTP long-polling</xref> or periodic requests (short-polling). Both methods use the GET method in order to take advantage of HTTP intermediaries.
</t>
<t>If long-polling is used, the Device indicates this by including a conditional request header, such as <spanx style="verb">If-Modified-Since</spanx> or <spanx style="verb">If-None-Match</spanx> [[This doesn't completely work; additional indicators are needed here]]. An HTTP 200 response is sent immediately when the resource is updated. In order to continue monitoring the state of the resource after receiving a response, the Device immediately sends another request.
</t>
<t>In the absence of the conditional HTTP headers, the server MAY assume that short-polling is in use. If short-polling is used, the Device MUST NOT continuous 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 <spanx style="verb">Retry-After</spanx> header. A client that receives this header SHOULD adjust its polling rate to match the indicated period.
</t>
<t>The LIS updates this resource to indicate which capability it wishes to invoke and any conditions on the invocation.
</t>
</section>
<section title="Invocation Resource">
<t>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.
</t>
<t>The value of the invocation resource determines what information is required. This document is an XML document with the MIME type of <spanx style="verb">application/held+xml</spanx> and a document element of <spanx style="verb">capinv</spanx>. Initially, this document is likely to be empty (containing a single, empty <spanx style="verb">capinv</spanx> element).
</t>
<t>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.
</t>
<figure>
<preamble>For instance, if the LIS wants to invoke the location capability of the Device, it updates the document to the following:
</preamble>
<artwork><![CDATA[
<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>
]]></artwork>
</figure>
<t>HELD notes that a Device avoid using proxies due to the effect that they have in masking the actual source address of a request. However, HTTP intermediaries cannot be avoided, and provide some advantages; these include private caches operated on the Device and gateways that are deployed to provide load balancing.
</t>
<t>In order to avoid unwanted caching of the invocation document by HTTP intermediaries, a LIS SHOULD include the <spanx style="verb">no-cache</spanx> tag in a <spanx style="verb">Cache-Control</spanx> header of the response. Intermediaries frequently might also time out a request; therefore, a LIS SHOULD limit the time that it holds a request open, responding with a 304 (Not Modified) response if the invocation document remains unchanged.
</t>
<t>The Device monitors the invocation resource as long as it is willing to respond to these requests. Using this, an outstanding request from the LIS 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.
</t>
</section>
<section title="Invocation Time">
<t>The <spanx style="verb">before</spanx> 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.
</t>
<t>The <spanx style="verb">periodic</spanx> 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 <spanx style="verb">before</spanx> attribute and periodically thereafter at the specified interval. Periodic invocations continue until the invocation is modified or removed.
</t>
<figure>
<preamble>For instance, the following invocation contains a request to provide Global Navigation Satellite System (GNSS) measurements before <spanx style="verb">2009-07-09T13:55:01+10:00</spanx> and at 60 second intervals (before 13:55:01, then before 13:56:01, then 13:57:01, and continuing indefinitely).
</preamble>
<artwork><![CDATA[
<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>
]]></artwork>
</figure>
</section>
<section title="Responding to a Capability Invocation">
<t>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 <spanx style="verb">target</spanx> element as an HTTP PUT. The format of the information provided depends on the capability.
</t>
<t>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 <xref target="I-D.thomson-geopriv-held-measurements"/>, MUST be respected.
</t>
</section>
<section title="Multiple Invocations">
<t>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.
</t>
<t>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.
</t>
</section>
</section>
<section anchor="location" title="The Location Capability">
<t>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.
</t>
<t>This section defines a location capability, identified by the URN <spanx style="verb">urn:ietf:params:xml:ns:geopriv:held:cap:location</spanx>. This capability indicates that the Device is able to provide location information to the LIS.
</t>
<t>The location capability is invoked using the method described in <xref target="poll"/>. 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 <spanx style="verb">Content-Type</spanx> of <spanx style="verb">application/pidf+xml</spanx>.
</t>
<t>Only the <spanx style="verb">location-info</spanx> 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 <spanx style="verb">entity</spanx> attribute of the presence document to avoid providing identity information.
</t>
<t>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.
</t>
<section title="Location Capability Summary">
<t>The following summarizes the location capability following the outline from <xref target="defn"/>:
<list style="hanging">
<t hangText="URI:">urn:ietf:params:xml:ns:geopriv:held:cap:location
</t>
<t hangText="Capability Parameters:">This capability indication includes no parameters; the capability agreement includes a URI that references an invocation document containing instructions for the Device.
</t>
<t hangText="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.
</t>
<t hangText="Security and Privacy Implications:">See <xref target="security"/> of this document.
</t>
<t hangText="Author Contact:">The authors of this document.
</t>
</list>
</t>
</section>
</section>
<section anchor="measurements" title="Location Measurement Capability">
<t>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 <xref target="I-D.thomson-geopriv-held-measurements"/> 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.
</t>
<t>The measurement capability is identified by the URN <spanx style="verb">urn:ietf:params:xml:ns:geopriv:held:cap:lm</spanx>. 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.
</t>
<t>The <spanx style="verb">lm</spanx> 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 <xref target="I-D.thomson-geopriv-held-measurements"/>.
</t>
<t>Inclusion of the <spanx style="verb">lm</spanx> element is only necessary in a capabilities indication, it MAY be omitted from any capabilities agreement or capabilities invocation.
</t>
<t>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 <spanx style="verb">application/xml</spanx> [[Ed: probably need to define new MIME type for this]] and has a document element of <spanx style="verb">measurements</spanx>. This document contains one or more measurement elements containing the requested measurement data.
</t>
<t>Multiple measurements can be provided at the same time. The <spanx style="verb">measurements</spanx> element simply contains multiple measurement elements. This can be used to simultaneously provide information for multiple different invocations of this capability.
</t>
<section title="Location Measurement Capability Summary">
<t>The following summarizes the location measurement capability following the outline from <xref target="defn"/>:
<list style="hanging">
<t hangText="URI:">urn:ietf:params:xml:ns:geopriv:held:cap:lm
</t>
<t hangText="Capability Parameters:">This capability includes a single <spanx style="verb">lm</spanx> 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.
<vspace blankLines="1"/>
The capability agreement includes a URI that references an invocation document containing instructions for the Device.
</t>
<t hangText="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.
</t>
<t hangText="Security and Privacy Implications:">See <xref target="security"/> of this document.
</t>
<t hangText="Author Contact:">The authors of this document.
</t>
</list>
</t>
</section>
</section>
<section anchor="capschema" title="XML Schema for Capabilities">
<figure>
<artwork><![CDATA[
<?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>
]]></artwork>
</figure>
</section>
<section title="Example Capabilities Exchange and Invocation">
<t>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.</t>
<figure>
<preamble>The following HELD request from a Device creates a context, including a capabilities indication:
</preamble>
<artwork><![CDATA[
<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>
]]></artwork>
<postamble>Two capabilities are included: location and measurement. The measurement capability indicates that GNSS measurements can be provided by the Device.
</postamble>
</figure>
<figure>
<preamble>The LIS response includes context details, along with a capabilities agreement:
</preamble>
<artwork><![CDATA[
<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>
]]></artwork>
<postamble>This indication instructs the Device to monitor the same URI to determine when the LIS wants to invoke either capability.
</postamble>
</figure>
<figure>
<preamble>The Device then monitors the state of the resource: [[ TODO: Add long-polling-specific headers.]]
</preamble>
<artwork><![CDATA[
GET /cap/SEVMRCBpcyBncmVhdC4 HTTP/1.1
Host: lis.example.com
]]></artwork>
</figure>
<figure>
<preamble>The resource initially contains no invocation instructions:
</preamble>
<artwork><![CDATA[
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"/>
]]></artwork>
</figure>
<figure>
<preamble>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:
</preamble>
<artwork><![CDATA[
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>
]]></artwork>
</figure>
<figure>
<preamble>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:
</preamble>
<artwork><![CDATA[
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>
]]></artwork>
</figure>
<figure>
<preamble>The LIS immediately provides an empty response to the Device:
</preamble>
<artwork><![CDATA[
HTTP/1.1 204 No Content
Server: Example LIS
Date: Fri, 10 Jul 2009 05:08:08 GMT
]]></artwork>
<postamble>The LIS is then able to use the provided measurement data to provide highly accurate location information in response to the request it received.
</postamble>
</figure>
</section>
<section anchor="security" title="Security Considerations">
<t>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.
</t>
<t>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.
</t>
<t>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 <xref target="I-D.ietf-geopriv-lis-discovery"/>, are more important for a Device that provides capability information to a LIS. Protocols used for the exchange of location information or location measurements MUST also provide protection from eavesdropping.
</t>
<t>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 non-trivial effort, with little initial investment. This could be exploited by a malicious LIS to exhaust batteries or perform other denial of service attacks. A Device SHOULD limit the resources it makes available to a LIS in relation to capabilities it advertises.
</t>
<t>The LIS is responsible for the veracity of location information it provides, even when it relies on information that comes from the Device. This and other considerations described in <xref target="I-D.thomson-geopriv-held-measurements"/> apply to the use of Device-provided information.
</t>
<t>Server authentication for all stages of the process are important, not only for the HELD <spanx style="verb">createContext</spanx> 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. <xref target="RFC2818">HTTP over TLS</xref> is strongly RECOMMENDED for each of these exchanges.
</t>
<section title="URI Secrecy">
<t>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.
</t>
<t>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.
</t>
<t>The LIS MUST use confidentiality protection on the channel it uses to provide these two resources. <xref target="RFC2818">HTTP over TLS</xref> MUST be used unless confidentiality can be guaranteed by other means.
</t>
<t>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.
</t>
</section>
</section>
<section anchor="iana" title="IANA Considerations">
<t>This section registers a URN for a capabilities XML namespace (<xref target="iana-nscap"/>) and a corresponding schema (<xref target="iana-schemacap"/>). URNs are registered for the location (<xref target="iana-nsloc"/>) and location measurement (<xref target="iana-nslm"/>) capabilities.
</t>
<section anchor="iana-nscap" title="URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap">
<t>This section registers a new XML namespace, <spanx style="verb">urn:ietf:params:xml:ns:held:cap</spanx>, as per the guidelines in <xref target="RFC3688"/>.
<list style="empty">
<t>URI: urn:ietf:params:xml:ns:held:cap</t>
<t>Registrant Contact: IETF, GEOPRIV working group, (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com).</t>
<t>XML:
<figure>
<artwork><![CDATA[
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
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section anchor="iana-nsloc" title="URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap:location">
<t>This section registers a new XML namespace, <spanx style="verb">urn:ietf:params:xml:ns:held:cap:location</spanx>, as per the guidelines in <xref target="RFC3688"/>.
<list style="empty">
<t>URI: urn:ietf:params:xml:ns:held:cap:location</t>
<t>Registrant Contact: IETF, GEOPRIV working group, (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com).</t>
<t>XML:
<figure>
<artwork><![CDATA[
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
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section anchor="iana-nslm" title="URN Sub-Namespace Registration for urn:ietf:params:xml:ns:held:cap:lm">
<t>This section registers a new XML namespace, <spanx style="verb">urn:ietf:params:xml:ns:held:cap:lm</spanx>, as per the guidelines in <xref target="RFC3688"/>.
<list style="empty">
<t>URI: urn:ietf:params:xml:ns:held:cap:lm</t>
<t>Registrant Contact: IETF, GEOPRIV working group, (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com).</t>
<t>XML:
<figure>
<artwork><![CDATA[
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
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section anchor="iana-schemacap" title="XML Schema Registration for HELD Capabilities">
<t>This section registers an XML schema as per the guidelines in <xref target="RFC3688"/>.
<list style="hanging">
<t hangText="URI:">urn:ietf:params:xml:schema:held:cap</t>
<t hangText="Registrant Contact:">IETF, GEOPRIV working group, (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com).</t>
<t hangText="Schema:">The XML for this schema can be found as the entirety of <xref target="capschema"/> of this document.
</t>
</list>
</t>
</section>
</section>
<!--
<appendix title="Change Log">
<t>[[The RFC Editor is requested to remove this section at publication.]]</t>
<t>Changes since -0-1:
<list style="symbols">
<t>Document created.</t>
</list>
</t>
</appendix>
-->
</middle>
<back>
<references title="Normative References">
&RFC2119;
&RFC2818;
&I-D.ietf-geopriv-http-location-delivery;
&I-D.ietf-geopriv-lis-discovery;
&I-D.winterbottom-geopriv-held-context;
&I-D.thomson-geopriv-held-measurements;
&I-D.winterbottom-geopriv-deref-protocol;
</references>
<references title="Informative References">
&RFC2141;
&RFC3688;
&RFC4119;
&I-D.loreto-http-bidirectional;
&I-D.thomson-geopriv-uncertainty;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 04:09:24 |