GEOPRIV WG J. Winterbottom
Internet-Draft M. Thomson
Expires: July 5, 2006 Andrew
B. Stark
BellSouth
January 2006
HTTP Enabled Location Delivery (HELD) - Sighting
draft-winterbottom-geopriv-held-sighting-00.txt
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of 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 July 5, 2006.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
A Geopriv sighting protocol is described that is used for retrieving
location information from a server within an access network. The
protocol includes options for retrieving location information either
by-value or by-reference. The protocol supports mobile and nomadic
devices through Location URIs and location update URIs, which enables
generation of location information at the Device. The protocol is an
Winterbottom, et al. Expires July 5, 2006 [Page 1]
Internet-Draft HELD Sighting January 2006
application-layer protocol that is independent of session-layer; an
HTTP, web services binding is specified.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Exclusions . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Device or Target . . . . . . . . . . . . . . . . . . . . . 5
1.3. The Bigger Picture . . . . . . . . . . . . . . . . . . . . 5
2. Conventions used in this document . . . . . . . . . . . . . . 7
2.1. GEOPRIV Terminology . . . . . . . . . . . . . . . . . . . 7
3. HELD Sighting Overview . . . . . . . . . . . . . . . . . . . . 9
3.1. Acquiring Location Information . . . . . . . . . . . . . . 9
3.1.1. Shaping the PIDF-LO . . . . . . . . . . . . . . . . . 10
3.2. Requesting a Location URI . . . . . . . . . . . . . . . . 10
3.2.1. Establishing a Location Server Context . . . . . . . . 11
3.2.2. Locating Mobile Devices . . . . . . . . . . . . . . . 12
4. Protocol Description . . . . . . . . . . . . . . . . . . . . . 13
4.1. Protocol Binding . . . . . . . . . . . . . . . . . . . . . 13
4.2. Location Request . . . . . . . . . . . . . . . . . . . . . 14
4.3. Contexts . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.3.1. Creating Contexts . . . . . . . . . . . . . . . . . . 15
4.3.2. Updating Contexts . . . . . . . . . . . . . . . . . . 15
4.3.3. Terminating Contexts . . . . . . . . . . . . . . . . . 16
4.4. Indicating Errors . . . . . . . . . . . . . . . . . . . . 16
5. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 18
5.1. "responseTime" Attribute . . . . . . . . . . . . . . . . . 19
5.2. "assert" Element . . . . . . . . . . . . . . . . . . . . . 19
5.2.1. "method" Attribute . . . . . . . . . . . . . . . . . . 19
5.2.2. "timestamp" Attribute . . . . . . . . . . . . . . . . 19
5.2.3. "expires" Attribute . . . . . . . . . . . . . . . . . 20
5.3. "locationType" Element . . . . . . . . . . . . . . . . . . 20
5.4. "exact" Attribute . . . . . . . . . . . . . . . . . . . . 21
5.5. "profile" Element . . . . . . . . . . . . . . . . . . . . 21
5.5.1. "presentity" Element . . . . . . . . . . . . . . . . . 21
5.5.2. SAML "Assertion" or "EncryptedAssertion" Element . . . 22
5.5.3. "retentionExpiry" Element . . . . . . . . . . . . . . 22
5.5.4. "retentionInterval" Element . . . . . . . . . . . . . 22
5.5.5. "retransmission" Element . . . . . . . . . . . . . . . 23
5.5.6. "rulesetURI" Element . . . . . . . . . . . . . . . . . 23
5.6. "signed" Attribute . . . . . . . . . . . . . . . . . . . . 23
5.7. "lifetime" Element . . . . . . . . . . . . . . . . . . . . 23
5.8. "rules" Element . . . . . . . . . . . . . . . . . . . . . 24
5.8.1. "rulesetURI" Element . . . . . . . . . . . . . . . . . 24
5.8.2. Common-Policy "ruleset" Element . . . . . . . . . . . 24
5.9. "updates" Element . . . . . . . . . . . . . . . . . . . . 25
5.9.1. "responseTime" Attribute . . . . . . . . . . . . . . . 25
Winterbottom, et al. Expires July 5, 2006 [Page 2]
Internet-Draft HELD Sighting January 2006
5.10. "code" Attribute . . . . . . . . . . . . . . . . . . . . . 25
5.11. "message" Attribute . . . . . . . . . . . . . . . . . . . 26
5.12. "context" Element . . . . . . . . . . . . . . . . . . . . 27
5.12.1. "locationURI" Element . . . . . . . . . . . . . . . . 27
5.12.2. "password" Element . . . . . . . . . . . . . . . . . . 27
5.12.3. "expires" Attribute . . . . . . . . . . . . . . . . . 27
6. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7. HTTP Binding . . . . . . . . . . . . . . . . . . . . . . . . . 36
7.1. HTTP Binding WSDL . . . . . . . . . . . . . . . . . . . . 36
8. Security Considerations . . . . . . . . . . . . . . . . . . . 39
8.1. Return Routability . . . . . . . . . . . . . . . . . . . . 39
8.2. Transaction Layer Security . . . . . . . . . . . . . . . . 40
8.3. Veracity of Asserted LI . . . . . . . . . . . . . . . . . 40
9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
9.1. Simple HTTP Binding Example Messages . . . . . . . . . . . 41
9.2. Location Request Examples . . . . . . . . . . . . . . . . 43
9.3. Context Creation and Update Examples . . . . . . . . . . . 45
9.4. Sample LG WSDL Document . . . . . . . . . . . . . . . . . 49
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50
10.1. IANA Registry for HELD Result Codes . . . . . . . . . . . 50
10.2. URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:geopriv:held . . . . . . . . . . . 50
10.3. XML Schema Registration . . . . . . . . . . . . . . . . . 51
10.4. URN Sub-Namespace Registration for
urn:ietf:params:xml:ns:geopriv:held:http . . . . . . . . . 51
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53
11.1. Normative References . . . . . . . . . . . . . . . . . . . 53
11.2. Informative References . . . . . . . . . . . . . . . . . . 54
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 56
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 57
Intellectual Property and Copyright Statements . . . . . . . . . . 58
Winterbottom, et al. Expires July 5, 2006 [Page 3]
Internet-Draft HELD Sighting January 2006
1. Introduction
The location of a Device is information that is useful for a number
of applications. A Device might be able to determine this
information using its own resources, but more often than not, the
Device must rely on its access network to provide this information.
This document describes a protocol that can be used to acquire
Location Information (LI) from a service within an access network.
This specification identifies two methods for acquiring LI. Location
may be retrieved from a Location Generator (LG) by-value, that is,
the Device may acquire LI directly. Alternatively, the Device may
request that the LG provide a location URI so that LI can be
distributed by-reference. Both of these methods are compatible, and
both can be provided concurrently from the same LG so that
application needs can be addressed individually.
This specification defines an XML-based protocol that enables the
retrieval of LI from a LG. This protocol can be bound to any
session-layer protocol, particularly those capable of MIME transport;
an HTTP binding is included as a minimum requirement.
The protocol described has specific support for mobile devices
through the assertion of LI to the LG and update URIs, which allow
the LG to query a Device for its current location. This feature, in
combination with Location URIs enables location determination at the
time that it is needed by the Location Recipient (LR), and in the
form requested by the LR.
1.1. Exclusions
This document defines a protocol for sighting only; that is, a
protocol for requesting (and receiving) the information necessary to
use LI. This document does not define a Geopriv Using Protocol. The
LG is assumed to be present within the same administrative domain as
the Device (the access network), which limits the security threats
that this protocol is exposed to.
This document does not specify how LI is derived. Determination of
the physical location of a device is dependent on the type of access
network and the capabilities of the device. The specific methods
that could be used are innumerable, therefore this is left to
individual network and device implementations.
Providing LI by-reference implies that a server is able to provide
the Device with a public, globally-routable URI. How this URI is
provided is not covered by this specification. This includes any
interactions between the LG and LS necessary to facilitate the
Winterbottom, et al. Expires July 5, 2006 [Page 4]
Internet-Draft HELD Sighting January 2006
provision of a Location URI.
This document does not define how an LG is discovered or configured.
1.2. Device or Target
LI provided for a device is often represented as the location of a
user. However, in this document LI is attributed to a device and not
a person. Primarily, this is because location determination
technologies are generally designed to locate a device and not a
person. In addition to this, unless the device requires active user
authentication, there is no guarantee that any particular individual
is using the device at that instant. Thus, if any claim of veracity
is to be made for LI, the distinction between user and device must be
made explicit.
This distinction should not lead to the impression that the location
of a device does not impact the privacy constraints required by this
protocol. Revealing the location of a device almost invariably
reveals some information about the location of the user of that
device, therefore the same level of privacy protection demanded by a
user is required for their device.
It is expected that, for most applications, this distinction will be
unnecessary and LI for a device will be used as an adequate
substitute for the user's LI. This requires either some additional
assurances about the link between device and user, or an acceptance
of the aforementioned limitations.
This document assumes that the Device is responsible for the protocol
interactions described and that it does so with the authority of the
Target and Rule Maker (RM).
1.3. The Bigger Picture
This document describes an interface between a Device and a Location
Generator (LG). Detailing the interactions between these two
entities requires a wider understanding of other interested parties.
For the Device, the most important consideration is the Target. In
some cases, this is the same as the Device, but it is more likely to
be a human user. The foundation of this protocol is that the Target
is able to direct the dissemination of LI, that is, the Target
provides authorization policies and otherwise controls how LI is
granted to Location Recipients (LRs). This extends to when a
Location Server (LS) is employed to provide a Location URI; the LS
cannot provide LI to an LR without express permission from the
Target.
Winterbottom, et al. Expires July 5, 2006 [Page 5]
Internet-Draft HELD Sighting January 2006
The LG exists as an access network service. An Access Provider (AP)
operates this service so that Devices (and Targets) can retrieve LI.
The LG exists because not all Devices are capable of determining LI,
and because, even if a Device is able to determine its own LI, it may
be more efficient with assistance.
This interface between Device and LG includes some features that
could be equally described by a direct interface between Device and
LS. Communication with the LS is directed through the LG because it
places the complexity on the LG; this enables the implementation of a
very simple client in the Device.
The following diagram shows one possible configuration of the roles
identified in [RFC3693] and where this protocol applies.
+-----------+ +-----------+
| Location | | Location |
| Generator | - - - - | Server |
| | | |
+-----------+ +-----------+
| |
HELD Sighting |
| |
Rule Maker - _ +-----------+ +-----------+
o - - | Device | | Location |
| (Target) |----Object--->| Recipient |
| | (Sighting) | (LS, RH) | (Applic.) | |
+-----------+ +----------+ +-----------+
Figure 2: Simple Location Request Model
In this model, the Device in this scenario acts as a Location Server
(LS) and Rule Holder (RH); it is responsible for making authorization
decisions about which Location Recipients are given LOs.
The LG needs to uniquely identify the Device within the access
network. The source address of the request message is sufficient in
most cases. Once the Device is identified, the LG uses network
domain-specific information to determine the location of the Device.
An LI request does not need to include any identification information
other than return addressing. In fact, the HTTP binding (Section 7)
includes the option for a GET request. Return routability also
addresses a number of security concerns, see Section 8.
The response from the LG is a PIDF-LO document [RFC4119], unless
there were errors in processing the request.
The interface between Device (acting as LS) and Location Recipient
(LR) is application-specific and outside the scope of this
specification.
Winterbottom, et al. Expires July 5, 2006 [Page 9]
Internet-Draft HELD Sighting January 2006
3.1.1. Shaping the PIDF-LO
A Device can include additional information in an LI request that
controls how the LG populates the fields in a PIDF-LO document.
Related to privacy, a presentity URI and usage rules can be
specified. The Device can also include a location estimate, or
request a specific type of location information, including a request
for a signed PIDF-LO.
When requesting LI, the Device can include a presentity URI for the
Target and a ruleset reference. The LG incorporates this information
in the PIDF-LO document, or modifies the document accordingly.
LI contained within a PIDF-LO document can be either geodetic
(coordinates using latitude and longitude or some other coordinate
system) or civic (street or postal addresses). The Device can
request that the LG provide a specific type of LI, including whether
a jurisdictional or postal civic address is required.
If a Device is capable of providing its own location it can include
this in a request. The LG is then able to include this LI in the
returned PIDF-LO. The type of LI is inferred from the request when
LI is provided.
The PIDF-LO document generated by an LG MUST follow the rules in
[I-D.ietf-geopriv-pdif-lo-profile]. The LI sent in a request MUST
follow the rules relating to the construction of the "location-info"
element.
3.2. Requesting a Location URI
Requesting LI directly does not always address the requirements of an
application. A Location URI is a URI [RFC3986] of any scheme, which
a Location Recipient (LR) can use to retrieve LI. A Device can
request a Location URI instead of LI.
Figure 3 illustrates how this usage of HELD Sighting fits within the
model presented in [RFC3693]. The first aspect of the diagram shows
how the Device acts as an agent for the Target and retrieves a
Location URI, which it then provides to the Location Recipient. The
second aspect has the Device acting as an agent for the Rule Maker;
the Device forwards rules to the LG, which forwards them to the LS.
Winterbottom, et al. Expires July 5, 2006 [Page 10]
Internet-Draft HELD Sighting January 2006
+-----------+ Location +--------------+
| Location |------URI------>| Device |
| Generator | | (Target) |
| |<-----Rules-----| (Rule Maker) |
+-----------+ (Sighting) +--------------+
| |
LO & Rules Location URI
(Publish) (Application)
| |
V V
+----------+ +------------+
| Location | Location | Location |
| Server |------Object----->| Recipient |
| | (Notification) | |
+----------+ +------------+
Figure 3: Location URI Usage Model
Note that the Location Server takes the role of a (Private) Rule
Holder when the rules are provided by-value. The rules may also be
provided to the LG and LS by-reference, in which case, a Public Rule
Holder is required; the Public Rule Holder is not shown in this
diagram.
The interface between Device (acting as LS) and Location Recipient
(LR) is application-specific and outside the scope of this
specification. Also, any interface between Device (acting as RM) and
a Public Rule Holder is not relevant to this specification.
The merits and drawbacks of using a Location URI approach are
discussed in [I-D.winterbottom-location-uri].
3.2.1. Establishing a Location Server Context
A Location URI is allocated for a Device by the LS. If the LS is to
be able to service queries for location directed at the Location URI,
it must maintain certain information. When the LG receives a request
for a Location URI, it requests that the LS allocate a URI for a
particular Device. As a part of providing a Location URI, the LS
also creates a _context_, which contains the information that it
requires to properly service requests to the URI.
This document does not make any normative statements about the
interface between the LG and LS. Any assumptions that are made about
the nature of this interface are stated where necessary.
A context contains sufficient information for the LS to identify the
Device to the LG, so that LI can be generated as required, which
Winterbottom, et al. Expires July 5, 2006 [Page 11]
Internet-Draft HELD Sighting January 2006
could be on a per-request basis. The context also includes
instructions from the Device on how the PIDF-LO is to be generated,
as described in Section 3.1.1.
Most importantly, the context contains an authorization policy that
describes to whom, and how, LI is granted. This is a common-policy
document [I-D.ietf-geopriv-common-policy] that is provided by the
Device in the context creation request, either directly, or by
reference.
3.2.2. Locating Mobile Devices
This protocol expands support for mobile devices by allowing for the
generation of LI at the time that an LR requests it. This is a
feature of Location URIs that is enhanced through the use of a
location update URI.
The Device is able to provide a location update URI that is stored
within its context. When the LG is determining the location of the
Device, it is then able to query the Device for its location through
the location update URI.
A location update URI therefore enables location determination of the
highest available precision at the time that an LR requires it.
Winterbottom, et al. Expires July 5, 2006 [Page 12]
Internet-Draft HELD Sighting January 2006
4. Protocol Description
As discussed in Section 3, this protocol provides two basic
functions: LI request and Location URI request. Messages are defined
as XML documents.
The Location Request message is described in Section 4.2. A Location
Request from a Device results in a PIDF-LO document in case of
success, or an error message.
In requesting a Location URI, the Device requests that a context be
created on the LS. The parameters for the create context request are
described in Section 4.3.1. The response to a context creation
request includes Location URIs and a password that can be used to
update the information contained in the context. The details stored
by the LS can be updated at any time after creation using the update
context request, described in Section 4.3.2.
Table 1 shows the basic set of messages supported by this protocol
and their respective responses, successful or otherwise.
+-----------+--------------------+------------------+---------------+
| Operation | Request Message | Successful | Error |
| | | Response | Response |
+-----------+--------------------+------------------+---------------+
| Request | locationRequest | PIDF-LO document | error |
| Location | (Section 4.2) | [RFC4119] | (Section 4.4) |
| | | | |
| Create | createContext | contextResponse | error |
| Context | (Section 4.3.1) | | (Section 4.4) |
| | | | |
| Update | updateContext | contextResponse | error |
| Context | (Section 4.3.2) | | (Section 4.4) |
+-----------+--------------------+------------------+---------------+
Table 1: HELD Sighting Operations
Section 5 contains a more thorough description of the protocol
parameters, valid values, and how each should be handled. Section 6
contains a more specific definition of the structure of these
messages in the form of an XML Schema [W3C.REC-xmlschema-1-20041028].
4.1. Protocol Binding
The HELD sighting protocol is an application-layer protocol that is
defined independently of any lower layers. This means that any
protocol can be used to transport this protocol providing that it can
provide a few basic features:
Winterbottom, et al. Expires July 5, 2006 [Page 13]
Internet-Draft HELD Sighting January 2006
o The protocol must have acknowledged delivery.
o The protocol must be able to correlate a response with a request.
o The protocol must provide authentication, privacy and protection
against modification.
Candidate protocols that could be used to address these purposes
include: TCP [RFC0793], TLS [RFC2246], SASL [RFC2222], HTTP
[RFC2616], SIP [RFC3261], BEEP [RFC3080] and SOAP [W3C.REC-soap12-
part1-20030624] [W3C.REC-soap12-part2-20030624]. This document
includes a binding that uses a combination of HTTP, TLS and TCP in
Section 7.
4.2. Location Request
A location request is sent from the Device to the LG when it requires
LI. This request can be very simple, including no parameters; in
fact, the HTTP binding includes a GET request that does not include a
message body.
A Device MAY make an assertion about its own location as part of a
location request. Devices that have some means of acquiring LI,
either from embedded technology like Global Positioning System (GPS)
receivers or from user input, can use this to convey that information
to the LG. The "assert" element can be used to convey this
information.
The type of LI that a Device requests is determined by the type of LI
that is included in the "assert" element. When asserted LI is not
provided, the Device MAY specify the type of location requested using
the "locationType" element.
LI provided by the Device is potentially more precise than that
provided by the LG, therefore the LG MAY use this information to
create a response. The LG SHOULD validate the LI provided for
accuracy and precision before using this information.
The Device MAY specify a "profile" element that instructs the LG on
how to construct the LO. Alternatively, if the Device has created a
profile in an LS context, the Device can provide a "context" element
so that the LG can retrieve the profile from the LS.
The location request is made by sending a document formed of a
"locationRequest" element. The successful response to a location
request is a PIDF-LO document, unless the request fails, in which
case the LG SHOULD provide an error indication document.
Winterbottom, et al. Expires July 5, 2006 [Page 14]
Internet-Draft HELD Sighting January 2006
4.3. Contexts
4.3.1. Creating Contexts
The Device uses the "createContext" message to request that the LG,
and the LS, assign a Location URI. This establishes a context at the
LS.
The LS MUST maintain the information provided in the create context
request. The create context request includes a time limit, which
sets the maximum time that this context can be maintained.
The response to a create context request contains information that
the Device can use to identify a context. A set of Location URIs are
included, each one MUST uniquely identify the context; that is, the
LS MUST be able to identify a context based on a single Location URI.
A Device can distribute a Location URI to an LR to allow it retrieve
LI from the LS.
A Location URI MUST NOT contain any information that could be used to
identify the Device or Target. It is RECOMMENDED that a Location URI
contain a public address for the LS and a random sequence of
characters that the LS can use to identify a particular context. The
presentity identifier included in a PIDF-LO document SHOULD NOT be
used for either part or the entirety of a Location URI.
The response to a create context request MUST include the time when
the LS will terminate the context. The LS MUST NOT respond to any
queries to the context beyond this time. A response to a context
creation also includes a password that the Device uses to identify
itself when updating the context at any time before the context
expiry time.
4.3.2. Updating Contexts
A Device can update any of the information it has provided for a
context at any time. The update context request includes the same
information as the create context request with the addition of
information that identifies an existing context.
A Device uses any one of the Location URIs provided to uniquely
identify a context when updating context information. The context
password MUST be provided when updating context information.
If a Device includes an authorization policy (or ruleset) in an
update context request, the LS MUST refresh any stored copy of the
authorization policy. This is especially important for authorization
policies that are provided by-reference; the LS MUST update the
Winterbottom, et al. Expires July 5, 2006 [Page 15]
Internet-Draft HELD Sighting January 2006
authorization policy, even if the URI has not changed. Updated
authorization policies SHOULD be processed by the LG and LS
immediately.
The update context request is constructed using the "updateContext"
element. A successful response is the "contextResponse" element,
which is the same as the response to a create context response.
The update context request can also indicate that data can be removed
by the context by specifying a _nil_ value for any of the parameters,
using the "xsi:nil" attribute. This applies to the profile
(Section 5.5) and updates (Section 5.9) values.
The response to an update context request is identical in form to the
create context response, with updated information about the context.
The Location URIs SHOULD be the same as those in the response to the
initial create context request, but the password and expiry time MAY
be changed.
4.3.3. Terminating Contexts
The update context request can be used to instruct the LS to
terminate a context. The "lifetime" element in the request is set to
a zero duration. Once the context has been terminated, or it has
expired, Location URIs that reference that context can no longer be
used and the Device MUST NOT use the Location URIs or password
relating to that context.
The LS MAY terminate a context without notifying the Device. The LS
SHOULD terminate contexts if it, or the LG, detect that any
information relating to the Device changes in a way that invalidates
the context.
When the Device requests that a context be terminated, the LG
responds with a "contextResponse" message that does not include any
context information; this message SHOULD include the "201" response
code.
4.4. Indicating Errors
In the event of an error, the LG SHOULD respond to the Device with an
error document. The error response applies to all request types and
SHOULD also be sent in response to any unrecognized request.
An error indication document consists of an "error" element. The
"error" element MUST include a "code" attribute that indicates the
type of error. A set of predefined error codes are included in
Section 5.10.
Winterbottom, et al. Expires July 5, 2006 [Page 16]
Internet-Draft HELD Sighting January 2006
Reponses MAY also include a "message" attribute that can include
additional information. This information SHOULD be for diagnostic
purposes only, and MAY be in any language. The language of the
message SHOULD be indicated with an "xml:lang" attribute.
Winterbottom, et al. Expires July 5, 2006 [Page 17]
Internet-Draft HELD Sighting January 2006
5. Protocol Parameters
This section describes, in detail the parameters that are used for
this protocol. Table 2 lists the top-level components used within
the protocol and where they are used.
+---------------------+-------------+--------------+----------------+
| Parameter | Location | Create | Update Context |
| | Request | Context | |
+---------------------+-------------+--------------+----------------+
| responseTime | Request | Request | Request |
| (Section 5.1) | | | |
| | | | |
| assert | Request | | |
| (Section 5.2) | | | |
| | | | |
| locationType | Request | | |
| (Section 5.3) | | | |
| | | | |
| exact (Section 5.4) | Request | | |
| | | | |
| profile | Request | Request | Request |
| (Section 5.5) | | | |
| | | | |
| signed | Request | | |
| (Section 5.6) | | | |
| | | | |
| lifetime | | Request | Request |
| (Section 5.7) | | | |
| | | | |
| rules (Section 5.8) | | Request | Request |
| | | | |
| updates | | Request | Request |
| (Section 5.9) | | | |
| | | | |
| code (Section 5.10) | Error | Error & | Error & |
| | | Response | Response |
| | | | |
| message | Error | Error & | Error & |
| (Section 5.11) | | Response | Response |
| | | | |
| context | Request | Response | Request & |
| (Section 5.12) | | | Response |
+---------------------+-------------+--------------+----------------+
Table 2: Message Parameter Usage
Winterbottom, et al. Expires July 5, 2006 [Page 18]
Internet-Draft HELD Sighting January 2006
5.1. "responseTime" Attribute
The "responseTime" attribute indicates to the LG how long the Device
is prepared to wait for a response. This attribute MAY be added to
any request message, although it is primarily used with the location
request. The value of this attribute is indicative only, the LG is
under no obligation to strictly adhere to the time limit implied; any
enforcement of the time limit is left to the Device.
This attribute MAY be either a duration value as defined in XML
Schema [W3C.REC-xmlschema-2-20041028], or a decimal seconds value,
which may include a decimal point. It is RECOMMENDED that systems
support millisecond precision for this parameter.
The LG SHOULD provide the most accurate LI that can be determined
within the specified interval. This parameter could be used as input
when selecting the method of location determination, where multiple
such methods exist. If this parameter is absent, then the LG SHOULD
return the most precise LI it is capable of determining.
5.2. "assert" Element
This attribute allows a Device to provide LI to the LG as part of a
location request. Two types of content are allowed: a geodetic
structure made up of a Geography Markup Language (GML) geometry
object, "_Geometry" as defined by [OGC.GML-3.1.1]; and a civic
address structure, "civicAddress" as defined by [I-D.ietf-geopriv-
revised-civic-lo]. The contents of this element SHOULD follow the
rules in [I-D.ietf-geopriv-pdif-lo-profile].
When used in combination with the "context" element, this LI MAY be
used by the LS for requests to Location URIs for that context.
This element is mutually exclusive with the "locationType" parameter,
defined in Section 5.3. The type of LI requested is implied by the
types included in the assertion.
5.2.1. "method" Attribute
The "method" attribute SHOULD be attached to the "assert" element to
indicate the means by which the LI was derived. This attribute
follows the rules of the similarly named method element of the
PIDF-LO.
5.2.2. "timestamp" Attribute
The "timestamp" attribute SHOULD be attached to the "assert" element
to indicate when the LI was generated.
Winterbottom, et al. Expires July 5, 2006 [Page 19]
Internet-Draft HELD Sighting January 2006
5.2.3. "expires" Attribute
The "expires" attribute MAY be attached to the "assert" element to
indicate when the included LI is no longer valid. The LG SHOULD set
the "retention-expires" element in the returned PIDF-LO to no later
than this time if it uses the LI. This attribute SHOULD NOT be
included unless this time is definite.
5.3. "locationType" Element
The "locationType" element is included in a location request. It
contains a list of LI types that are requested by the Device. The
following list describes the possible values:
any: The LG SHOULD attempt to provide LI in all forms available to
it. This value MUST be assumed as the default if no
"locationType" is specified.
geodetic: The LG SHOULD return a geodetic location for the Target.
civic: The LG SHOULD return a civic address for the Target. Any type
of civic address may be returned. The LG SHOULD ignore this value
if a request for jurisdictional or postal civic address has been
made and can be satisfied.
jurisdictionalCivic: The LG SHOULD return a jurisdictional civic
address for the Target.
postalCivic: The LG SHOULD return a postal civic address for the
Target.
The "locationType" element is mutually exclusive with the "assert"
element, defined in Section 5.2.
The LG SHOULD return the requested location type or types. The LG
MAY provide additional location types, or it MAY provide alternative
types if the request cannot be satisfied for a requested location
type. If the "exact" attribute is present and set to "true" in a
location request, then a successful LG response MUST provide the
requested location type only, with no additional location
information. The "exact" attribute has no effect when this element
is set to "any".
The "SHOULD"-strength requirement on this parameter is included to
allow for soft-failover. This enables a fixed client configuration
that prefers a specific location type without causing location
requests to fail when that location type is unavailable. Unless the
"exact" attribute is set, the LG is always able to provide LI in some
Winterbottom, et al. Expires July 5, 2006 [Page 20]
Internet-Draft HELD Sighting January 2006
form.
For example, a notebook computer could be configured to retrieve
civic addresses, which is usually available from typical home or work
situations. However, when using a wireless modem, the LG might be
unable to provide a civic address.
5.4. "exact" Attribute
The "exact" attribute is used for the location request message in
conjunction with either the "locationType" or "assert" elements.
When this value is set to "true", it indicates to the LG that the
contents of these parameters MUST be strictly followed. The default
value of "false" allows the LG the option of ignoring these values.
When used with the "assert" element, this attribute indicates that
the asserted LI MUST be included in the PIDF-LO response. If the LG
cannot do this for any reason, which is usually because it determines
that the LI was inaccurate or insufficiently precise, the LG MUST
indicate an error.
When used with the "locationType" element, a value of "true"
indicates that the LG MUST provide a PIDF-LO that includes LI of the
requested type or types. The LG MUST provide the requested types
only and these types SHOULD be specified in the same order as they
were requested. The LG SHOULD handle an exact request that includes
a "locationType" element set to "any" as if the "exact" attribute
were set to "false".
5.5. "profile" Element
The "profile" element contains a presentity identifier and usage
rules information. All fields are optional within this element, but
when these fields are included, the LG MUST use these parameters when
constructing the PIDF-LO document.
This element MAY be included in location requests, create context
requests and update context requests. When included in a location
request, the profile is used immediately; when used in create context
or update context requests, the profile is stored on the LS and is
provided to the LG when the LS responds to requests from LRs.
5.5.1. "presentity" Element
The "presentity" element contains a presentity identifier that the LG
SHOULD include in the "pres" attribute of the PIDF-LO document.
Winterbottom, et al. Expires July 5, 2006 [Page 21]
Internet-Draft HELD Sighting January 2006
The LG MAY require authentication of the presentity through any
means; the LG SHOULD ignore this parameter if authentication
information is not present or authentication information cannot be
verified. A SAML assertion MAY be provided in place of this element.
5.5.2. SAML "Assertion" or "EncryptedAssertion" Element
The "Assertion" or "EncryptedAssertion" element MAY be included in
place of the "presentity" element to carry identity information.
This element is taken from SAML 2.0 Core [OASIS.saml-core-2.0-os],
which allows for an assertion about identity to be made by an
external entity.
The assertion MUST include a "Subject" that identifies a user. For
_addr-spec_ -type addresses, such as are used in "pres" and "sip"
URIs, the name identifier format identifier SHOULD be
"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress".
To use this element, the Device SHOULD support the web browser single
sign-on profile of SAML, identified by
"urn:oasis:names:tc:SAML:2.0:profiles:SSO:browser". This profile is
defined in [OASIS.saml-profiles-2.0-os].
The LG or LS MAY choose not to support this method for
authentication. Requests including this element MAY be rejected with
an error response; alternatively the element MAY be ignored.
5.5.3. "retentionExpiry" Element
The "retentionExpiry" element contains an absolute "dateTime"
[W3C.REC-xmlschema-2-20041028] value for the "retention-expires"
element of the PIDF-LO usage rules. This element is mutually
exclusive with the "retentionInterval" element.
The LG MAY use a different value than that specified (or the
suggested default) as circumstances dictate, but MUST NOT use a value
later than specified. If this value indicates a time that has
already passed, the request MUST be rejected with an error. See
retentionInterval (Section 5.5.4) for more details.
5.5.4. "retentionInterval" Element
The "retentionInterval" element contains a time duration value that
is specified in the same fashion as the responseTime attribute
(Section 5.1).
This value MUST be added to the time at which the PIDF-LO document is
created to set the value of the "retention-expires" element. This
Winterbottom, et al. Expires July 5, 2006 [Page 22]
Internet-Draft HELD Sighting January 2006
element enables the Target to set an interval over which a LR can
retain a LO, rather than an absolute time. This element is mutually
exclusive with the "retentionExpires" element.
If neither "retentionExpiry" nor "retentionInterval" are specified,
the LG SHOULD provide a default value for the "retention-expires"
element of the generated PIDF-LO document. The default for this
value SHOULD be 24 hours from the receipt of the location request as
defined in [RFC4119].
The LG MAY use a different value than that specified (or the
suggested default) as circumstances dictate, but MUST NOT use a value
larger than specified.
5.5.5. "retransmission" Element
The "retransmission" element contains a boolean value that MUST be
included in the "retransmission-allowed" element of the generated
PIDF-LO usage rules. When this element is not provided, the LG MUST
set the "retransmission-allowed" element to "false".
5.5.6. "rulesetURI" Element
The "rulesetURI" element contains a URI value that MUST be included
in the "ruleset-reference" element of the generated PIDF-LO usage
rules.
This datum is only used to construct the PIDF-LO document. Within
the context of a profile, this ruleset is not used by either LG or
LS, and the LS does not apply the rules found at the URI.
5.6. "signed" Attribute
The "signed" attribute indicates whether the Device requires a
digitally signed PIDF-LO. When present and set to "true", the LG
MUST provide a PIDF-LO document that is signed according to XML-
Signature [RFC3275].
5.7. "lifetime" Element
The "lifetime" element specifies the maximum time that a context
should be maintained by the LS. This parameter MUST be included in
the context creation request to indicate to the LS the latest time
that the context is allowed to be retained. The parameter MAY be
included in context update requests to modify this time; when
included in an update request with a zero value, it indicates that
the context MUST be removed immediately.
Winterbottom, et al. Expires July 5, 2006 [Page 23]
Internet-Draft HELD Sighting January 2006
The "lifetime" element is a duration value that is specified in the
same fashion as the "responseTime" attribute.
This value MUST be added to the current time when received by the LS
to determine the time at which the context expires. An LS MAY use
any value less than or equal to this value, but MUST NOT use a longer
value. The actual expiry time of the context MUST be indicated in
the context response.
5.8. "rules" Element
The "rules" element contains the authorization policy of the Target
that dictates how and to whom LI is provided by the LS. This policy
MUST be applied by the LS when providing LI to LRs.
Authorization policies MUST conform to [I-D.ietf-geopriv-common-
policy]. If the authorization policy is invalid, cannot be
retrieved, or is otherwise not understood by the LS, the LG SHOULD
fail the request. Note that this implies that the LS SHOULD attempt
to retrieve an authorization policy that is provided by-reference at
the time of a create context request; however, an LS MAY choose to do
this later, if the requested response time might be exceeded.
In the absence of an authorization policy, the LS MUST NOT provide LI
to any LR. Note that in certain jurisdictions an LS might be
required to provide LI to specific parties irrespective of the
authorization policy, as mandated by legislation; for example,
emergency services in some countries.
5.8.1. "rulesetURI" Element
The "rulesetURI" element contains a URI that references the Target's
authorization policy. This URI should reference a document of type
"application/auth-policy+xml" as defined in [I-D.ietf-geopriv-common-
policy].
It is RECOMMENDED that a ruleset URI use the "https" scheme. It is
anticipated that, to improve responsiveness and reduce network usage,
an LS could cache an authorization policy, consistent with the rules
specified by the Rule Holder. For instance, the Rule Holder could
specified retention times using the "Expires" header in HTTP
[RFC2616]. The impact of changes to authorization policies are
discussed in Section 4.3.2.
5.8.2. Common-Policy "ruleset" Element
The "ruleset" element, which is in the
"urn:ietf:params:xml:ns:common-policy" namespace [I-D.ietf-geopriv-
Winterbottom, et al. Expires July 5, 2006 [Page 24]
Internet-Draft HELD Sighting January 2006
common-policy], allows for providing an authorization policy directly
as part of a request. It is RECOMMENDED that this method is only
used where the "rulesetURI" element cannot be provided.
5.9. "updates" Element
The "updates" element is provided by a Device that has some ability
to generate its own location. This consists of the URI where the LG
can request LI. Typically, the update URI is served by the Device,
but it MAY be served by any entity that can determine the location of
the Device.
The request to the update URI is a HELD Sighting location request
only. The entity serving the update URI SHOULD use the same binding
as was used to contact the LG.
Requests to an update URI MUST NOT contain any reference to contexts,
or request signed LI. The entity serving a request to an update URI
MAY ignore all parameters included in requests. Therefore, a simple
location request is RECOMMENDED where supported by the binding; for
the HTTP binding, this is the GET request.
5.9.1. "responseTime" Attribute
The "responseTime" attribute of the "updates" element indicates a
reasonable maximum time that a request to the given update URI is
expected to take. This provides assistance to the LG that uses this
URI in deciding whether or not to use the update URI when given time
constraints. This value is indicative only and the LG is responsible
for ensuring that responses are received in a timely manner.
The "responseTime" attribute of the "updates" element is a duration
value that is specified in the same fashion as the responseTime
attribute (Section 5.1).
For example, a GPS-enabled device might provide an update URI where
the LG can request a GPS-determined location; if the device generally
takes less than 45 seconds to determine its location, that value is
used for the "responseTime" attribute.
5.10. "code" Attribute
All responses, except a PIDF-LO document, MUST contain a response
code. The "code" attribute applies to the "error" and
"contextResponse" messages.
The following response codes follow a three decimal form similar to
that in HTTP [RFC2616] and SIP [RFC3261]:
Winterbottom, et al. Expires July 5, 2006 [Page 25]
Internet-Draft HELD Sighting January 2006
200 (Success): This code indicates that the request was successful.
This code MUST not be used for an error response.
201 (Context Terminated): This code indicates that the request to
terminate a context was successful.
400 (Request Error): This code indicates that the request was badly
formed in some fashion.
401 (XML Error): This code indicates that the XML content of the
request was either badly formed or invalid.
402 (Authentication Error): This code indicates that the request
either did not contain authentication information, or the
authentication provided was not accepted.
403 (Asserted Location Error): This code indicates that the LI that
was asserted in the request was not acceptable to the LG. This
code is used when the "exact" attribute is set to "true".
404 (Context Not Found): This code indicates that the context
identified in the request was not found. This code MAY also be
used if the password provided was incorrect.
500 (General LG Error): This code indicates that an unspecified error
occurred at the LG.
501 (Location Unknown): This code indicates that the LG could not
determine the location of the Device.
502 (Unsupported Message): This code indicates that the request was
not supported or understood by the LG.
503 (Timeout): This code indicates that the LG could not satisfy the
request within the time specified in the "requestTime" parameter.
504 (Cannot Provide LI Type): This code indicates that the LG was
unable to provide LI of the type or types requested. This code is
used when the "exact" attribute is set to "true".
Additional response codes within the x00 to x79 range MUST be
specified in published RFCs; the range from x80 to x99 is reserved
for private usage.
5.11. "message" Attribute
The "contextResponse" and "error" messages MAY include a "message"
attribute to convey some additional, human-readable information about
Winterbottom, et al. Expires July 5, 2006 [Page 26]
Internet-Draft HELD Sighting January 2006
the result of the request. This message MAY be included in any
language, which SHOULD be indicated by the "xml:lang", attribute.
5.12. "context" Element
The "context" element includes information that is used to identify a
context and control access to it. The context is identified by one
or more Location URIs and a Device is granted a password which MUST
be provided when accessing the context to update the information
contained.
When a context is created, the LG provides a "contextResponse"
message that contains the "context" element. This element contains
all of the Location URIs that can be used for the context, a
password, and an expiry time.
To update the details in a context, or reuse profile information
stored in the context, the Device provides a "context" element. When
identifying a context in this manner, the Device MUST provide only
one Location URI and the password.
5.12.1. "locationURI" Element
The "locationURI" element includes a single Location URI. Each
Location URI is allocated by the LS so that it is able to uniquely
identify the context.
A "contextResponse" message contains any number of "locationURI"
elements. It is RECOMMENDED that the LS allocate a Location URIs for
all schemes that it supports and that no scheme is present twice.
All "updateContext" request messages MUST contain only one
"locationURI" element. The Device MAY select any of the provided
Location URIs provided by the LS.
5.12.2. "password" Element
The "password" element carries a password that is used to access the
context after it has been created. The LS generates this value when
creating a context and the Device MUST use the exact same value when
it wishes to access the context. This value acts as a shared secret
between Device and LS.
This element MAY contain any valid XML character data.
5.12.3. "expires" Attribute
The "expires" attribute indicates the time at which the context
Winterbottom, et al. Expires July 5, 2006 [Page 27]
Internet-Draft HELD Sighting January 2006
created by the LS will expire. This attribute is included in the
"contextResponse" message only.
Responses to create and update context requests MUST include the
expiry time of the context. If the LS has expired a context in
response to an update context request, this value SHOULD include a
time in the past to avoid problems that could be caused by a slow
clock in the Device.
Winterbottom, et al. Expires July 5, 2006 [Page 28]
Internet-Draft HELD Sighting January 2006
6. XML Schema
Namespace for HELD Sighting Messages
urn:ietf:params:xml:ns:geopriv:held
[[NOTE TO IANA/RFC-EDITOR: Please update RFC URL and replace XXXX
with the RFC number for this specification.]]
See RFCXXXX.
END 10.3. XML Schema Registration This section registers an XML schema as per the guidelines in [RFC3688]. URI: urn:ietf:params:xml:schema:geopriv:held 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 6 of this document. 10.4. URN Sub-Namespace Registration for urn:ietf:params:xml:ns:geopriv:held:http This section registers a new XML namespace, "urn:ietf:params:xml:ns:geopriv:held:http", as per the guidelines in [RFC3688]. URI: urn:ietf:params:xml:ns:geopriv:held:http Registrant Contact: IETF, GEOPRIV working group, (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com). XML: Winterbottom, et al. Expires July 5, 2006 [Page 51] Internet-Draft HELD Sighting January 2006 BEGINSee RFCXXXX.
END Winterbottom, et al. Expires July 5, 2006 [Page 52] Internet-Draft HELD Sighting January 2006 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [RFC3275] Eastlake, D., Reagle, J., and D. Solo, "(Extensible Markup Language) XML-Signature Syntax and Processing", RFC 3275, March 2002. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. [RFC3693] Cuellar, J., Morris, J., Mulligan, D., Peterson, J., and J. Polk, "Geopriv Requirements", RFC 3693, February 2004. [RFC4119] Peterson, J., "A Presence-based GEOPRIV Location Object Format", RFC 4119, December 2005. [I-D.ietf-geopriv-revised-civic-lo] Thomson, M. and J. Winterbottom, "Revised Civic Location Format for PIDF-LO", draft-ietf-geopriv-revised-civic-lo-01 (work in progress), January 2006. [I-D.ietf-geopriv-pdif-lo-profile] Tschofenig, H., "GEOPRIV PIDF-LO Usage Clarification, Considerations and Recommendations", draft-ietf-geopriv-pdif-lo-profile-02 (work in progress), February 2006. [W3C.REC-xmlschema-2-20041028] Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes Second Edition", W3C REC REC-xmlschema-2-20041028, October 2004. [OGC.GML-3.1.1] Cox, S., Daisey, P., Lake, R., Portele, C., and A. Winterbottom, et al. Expires July 5, 2006 [Page 53] Internet-Draft HELD Sighting January 2006 Whiteside, "Geographic information - Geography Markup Language (GML)", OpenGIS 03-105r1, April 2004,