diff options
| author | Thomas Voss <mail@thomasvoss.com> | 2024-11-27 20:54:24 +0100 |
|---|---|---|
| committer | Thomas Voss <mail@thomasvoss.com> | 2024-11-27 20:54:24 +0100 |
| commit | 4bfd864f10b68b71482b35c818559068ef8d5797 (patch) | |
| tree | e3989f47a7994642eb325063d46e8f08ffa681dc /doc/rfc/rfc5985.txt | |
| parent | ea76e11061bda059ae9f9ad130a9895cc85607db (diff) | |
doc: Add RFC documents
Diffstat (limited to 'doc/rfc/rfc5985.txt')
| -rw-r--r-- | doc/rfc/rfc5985.txt | 2187 |
1 files changed, 2187 insertions, 0 deletions
diff --git a/doc/rfc/rfc5985.txt b/doc/rfc/rfc5985.txt new file mode 100644 index 0000000..f30923e --- /dev/null +++ b/doc/rfc/rfc5985.txt @@ -0,0 +1,2187 @@ + + + + + + +Internet Engineering Task Force (IETF) M. Barnes, Ed. +Request for Comments: 5985 Polycom +Category: Standards Track September 2010 +ISSN: 2070-1721 + + + HTTP-Enabled Location Delivery (HELD) + +Abstract + + This document defines a Layer 7 Location Configuration Protocol (L7 + LCP) and describes the use of HTTP and HTTP/TLS as transports for the + L7 LCP. The L7 LCP is used for retrieving location information from + a server within an access network. It includes options for + retrieving location information in two forms: by value and by + reference. The protocol is an extensible application-layer protocol + that is independent of the session layer. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc5985. + +Copyright Notice + + Copyright (c) 2010 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + +Barnes Standards Track [Page 1] + +RFC 5985 HELD September 2010 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3 + 3. Overview and Scope . . . . . . . . . . . . . . . . . . . . . . 4 + 4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5 + 4.1. Device Identifiers, NAT and VPNs . . . . . . . . . . . . . 6 + 4.1.1. Devices and VPNs . . . . . . . . . . . . . . . . . . . 6 + 4.1.2. LIS Handling of NATs and VPNs . . . . . . . . . . . . 7 + 4.2. Location by Value . . . . . . . . . . . . . . . . . . . . 7 + 4.3. Location by Reference . . . . . . . . . . . . . . . . . . 8 + 5. Protocol Description . . . . . . . . . . . . . . . . . . . . . 8 + 5.1. Location Request . . . . . . . . . . . . . . . . . . . . . 9 + 5.2. Location Response . . . . . . . . . . . . . . . . . . . . 9 + 5.3. Indicating Errors . . . . . . . . . . . . . . . . . . . . 9 + 6. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 10 + 6.1. "responseTime" Parameter . . . . . . . . . . . . . . . . . 10 + 6.2. "locationType" Parameter . . . . . . . . . . . . . . . . . 11 + 6.2.1. "exact" Attribute . . . . . . . . . . . . . . . . . . 13 + 6.3. "code" Parameter . . . . . . . . . . . . . . . . . . . . . 13 + 6.4. "message" Parameter . . . . . . . . . . . . . . . . . . . 14 + 6.5. "locationUriSet" Parameter . . . . . . . . . . . . . . . . 14 + 6.5.1. "locationURI" Parameter . . . . . . . . . . . . . . . 14 + 6.5.2. "expires" Parameter . . . . . . . . . . . . . . . . . 15 + 6.6. "Presence" Parameter (PIDF-LO) . . . . . . . . . . . . . . 16 + 7. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 16 + 8. HTTP Binding . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 22 + 9.1. Assuring That the Proper LIS Has Been Contacted . . . . . 23 + 9.2. Protecting Responses from Modification . . . . . . . . . . 23 + 9.3. Privacy and Confidentiality . . . . . . . . . . . . . . . 23 + 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 10.1. Examples of HTTPS Messages . . . . . . . . . . . . . . . . 25 + 10.2. Example of a Simple Location Request . . . . . . . . . . . 26 + 10.3. An Example of a Location Request for Multiple Location + Types . . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 + 11.1. URN Sub-Namespace Registration for + urn:ietf:params:xml:ns:geopriv:held . . . . . . . . . . . 28 + 11.2. XML Schema Registration . . . . . . . . . . . . . . . . . 29 + 11.3. MIME Media Type Registration for 'application/held+xml' . 29 + 11.4. Error Code Registry . . . . . . . . . . . . . . . . . . . 30 + 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 32 + 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 32 + 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 33 + 14.1. Normative References . . . . . . . . . . . . . . . . . . . 33 + 14.2. Informative References . . . . . . . . . . . . . . . . . . 34 + + + + +Barnes Standards Track [Page 2] + +RFC 5985 HELD September 2010 + + + Appendix A. HELD Compliance to IETF LCP Requirements . . . . . . 36 + A.1. L7-1: Identifier Choice . . . . . . . . . . . . . . . . . 36 + A.2. L7-2: Mobility Support . . . . . . . . . . . . . . . . . . 36 + A.3. L7-3: ASP and Access Network Provider Relationship . . . . 37 + A.4. L7-4: Layer 2 and Layer 3 Provider Relationship . . . . . 37 + A.5. L7-5: Legacy Device Considerations . . . . . . . . . . . . 37 + A.6. L7-6: VPN Awareness . . . . . . . . . . . . . . . . . . . 38 + A.7. L7-7: Network Access Authentication . . . . . . . . . . . 38 + A.8. L7-8: Network Topology Unawareness . . . . . . . . . . . . 38 + A.9. L7-9: Discovery Mechanism . . . . . . . . . . . . . . . . 39 + A.10. L7-10: PIDF-LO Creation . . . . . . . . . . . . . . . . . 39 + +1. Introduction + + The location of a Device is information that is useful for a number + of applications. The L7 Location Configuration Protocol (LCP) + problem statement and requirements document [RFC5687] provides some + scenarios in which a Device might rely on its access network to + provide location information. The Location Information Server (LIS) + service applies to access networks employing both wired technology + (e.g., DSL, cable) and wireless technology (e.g., WiMAX) with varying + degrees of Device mobility. This document describes a protocol that + can be used to acquire Location Information (LI) from a LIS within an + access network. + + This specification identifies two types of location information that + may be retrieved from the LIS. Location may be retrieved from the + LIS by value; that is, the Device may acquire a literal location + object describing the location of the Device. The Device may also + request that the LIS provide a location reference in the form of a + Location URI or set of Location URIs, allowing the Device to + distribute its LI by reference. Both of these methods can be + provided concurrently from the same LIS to accommodate application + requirements for different types of location information. + + This specification defines an extensible XML-based protocol that + enables the retrieval of LI from a LIS by a Device. This protocol + can be bound to any session-layer protocol, particularly those + capable of MIME transport. This document describes the use of HTTP + and HTTP/TLS as transports for the protocol. + +2. Conventions and Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + + + + +Barnes Standards Track [Page 3] + +RFC 5985 HELD September 2010 + + + This document uses the terms (and their acronym forms): Access + Provider (AP), Location Information (LI), Location Object (LO), + Device, Target, Location Generator (LG), Location Recipient (LR), and + Rule Maker (RM) and Rule Holder (RH) as defined in GEOPRIV + Requirements [RFC3693]. The terms Location Information Server (LIS), + Access Network, Access Provider (AP), and Access Network Provider are + used in the same context as defined in the L7 LCP Problem statement + and Requirements document [RFC5687]. The usage of the terms Civic + Location/Address and Geodetic Location follows the usage in many of + the referenced documents. + + In describing the protocol, the terms "attribute" and "element" are + used according to their context in XML. The term "parameter" is used + in a more general protocol context and can refer to either an XML + "attribute" or "element". + +3. Overview and Scope + + This document describes an interface between a Device and a Location + Information Server (LIS). This document assumes that the LIS is + present within the same administrative domain as the Device (e.g., + the access network). The LIS 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 + document does not specify how LI is determined. An Access Provider + (AP) operates the LIS so that Devices (and Targets) can retrieve + their LI. This document assumes that the Device and Access Provider + have no prior relationship other than what is necessary for the + Device to obtain network access. + + This document is based on the attribution of the LI to a Device and + not specifically a person (end user) or Target, based on the premise + that location determination technologies are generally designed to + locate a Device and not a person. It is expected that, for most + applications, LI for the Device can be used as an adequate substitute + for the end user's LI. Since revealing the location of the Device + almost invariably reveals some information about the location of the + user of the Device, the same level of privacy protection demanded by + a user is required for the Device. This approach may require either + some additional assurances about the link between Device and target, + or an acceptance of the limitation that unless the Device requires + active user authentication, there is no guarantee that any particular + individual is using the Device at that instant. + + The following diagram shows the logical configuration of some of the + functional elements identified in [RFC3693] and the LIS defined in + [RFC5687]. It also shows where this protocol applies, with the Rule + + + + +Barnes Standards Track [Page 4] + +RFC 5985 HELD September 2010 + + + Maker and Target represented by the role of the Device. Note that + only the interfaces relevant to the Device are identified in the + diagram. + + +---------------------------------------------+ + | Access Network Provider | + | | + | +--------------------------------------+ | + | | Location Information Server | | + | | | | + | | | | + | | | | + | | | | + | +------|-------------------------------+ | + +----------|----------------------------------+ + | + | + HELD + | + Rule Maker - - _ +-----------+ +-----------+ + o - - | Device | | Location | + <U\ | | - - - - | Recipient | + / \ _ - - | | APP | | + Target - - +-----------+ +-----------+ + + Figure 1: Significant Roles + + The interface between the Location Recipient (LR) and the Device + and/or LIS is application specific, as indicated by the APP + annotation in the diagram and it is outside the scope of the + document. An example of an APP interface between a Device and LR can + be found in the SIP Location Conveyance document [LOC-CONVEY]. + +4. Protocol Overview + + A Device uses the HTTP-Enabled Location Delivery (HELD) protocol to + retrieve its location either directly in the form of a Presence + Information Data Format Location Object (PIDF-LO) document (by value) + or indirectly as a Location URI (by reference). The security + necessary to ensure the accuracy, privacy, and confidentiality of the + Device's location is described in the Security Considerations + (Section 9). + + As described in the L7 LCP problem statement and requirements + document [RFC5687], the Device MUST first discover the URI for the + LIS for sending the HELD protocol requests. The URI for the LIS + SHOULD be obtained from an authorized and authenticated entity. The + details for ensuring that an appropriate LIS is contacted are + + + +Barnes Standards Track [Page 5] + +RFC 5985 HELD September 2010 + + + provided in Section 9 and in particular Section 9.1. The LIS + discovery protocol details are out of scope of this document and are + specified in [RFC5986]. The type of URI provided by LIS discovery is + RECOMMENDED to be an HTTPS URI. + + The LIS requires an identifier for the Device in order to determine + the appropriate location to include in the location response message. + In this document, the IP address of the Device, as reflected by the + source IP address in the location request message, is used as the + identifier. Other identifiers are possible, but are beyond the scope + of this document. + +4.1. Device Identifiers, NAT and VPNs + + Use of the HELD protocol is subject to the viability of the + identifier used by the LIS to determine location. This document + describes the use of the source IP address sent from the Device as + the identifier used by the LIS. When Network Address Translation + (NAT), a Virtual Private Network (VPN), or other forms of address + modification occur between the Device and the LIS, the location + returned could be inaccurate. + + Not all cases of NATs introduce inaccuracies in the returned + location. For example, a NAT used in a residential Local Area + Network (LAN) is typically not a problem. The external IP address + used on the Wide Area Network (WAN) side of the NAT is an acceptable + identifier for all of the Devices in the residence (on the LAN side + of the NAT), since the covered geographical area is small. + + On the other hand, if there is a VPN between the Device and the LIS + (for example, for a teleworker), then the IP address seen by a LIS + inside the enterprise network might not be the right address to + identify the location of the Device. Section 4.1.2 provides + recommendations to address this issue. + +4.1.1. Devices and VPNs + + To minimize the impact of connections or tunnels setup for security + purposes or for traversing middleboxes, Devices that connect to + servers such as VPN servers, SOCKS servers, and HTTP proxy servers + should perform their HELD query on the LIS prior to establishing a + connection to other servers. It is RECOMMENDED that discovery + [RFC5986] and an initial query be performed before establishing any + connections to other servers. If a Device performs the HELD query + after establishing a connection to another server, the Device may + receive inaccurate location information. + + + + + +Barnes Standards Track [Page 6] + +RFC 5985 HELD September 2010 + + + Devices that establish VPN connections for use by other Devices + inside a LAN or other closed network could serve as a LIS, that + implements the HELD protocol, for those other Devices. Devices + within the closed network are not necessarily able to detect the + presence of the VPN. In this case, a VPN Device should provide the + address of the LIS server it provides, in response to discovery + queries, rather than passing such queries through the VPN tunnel. + Otherwise, the other Devices would be totally unaware that they could + receive inaccurate location information. + + It could also be useful for a VPN Device to serve as a LIS for other + location configuration options such as Dynamic Host Configuration + Protocol (DHCP) [RFC3825] or Link Layer Discovery Protocol - Media + Endpoint Discovery [LLDP-MED]. For this case, the VPN Device that + serves as a LIS may first acquire its own location using HELD. + +4.1.2. LIS Handling of NATs and VPNs + + In the cases where the Device connects to the LIS through a VPN or a + NAT that serves a large geographic area or multiple geographic + locations (for example, a NAT used by an enterprise to connect their + private network to the Internet), the LIS might not be able to return + accurate LI. If the LIS cannot determine LI for the Device, it + should provide an error response to the requesting Device. The LIS + needs to be configured to recognize identifiers that represent these + conditions. + + LIS operators have a large role in ensuring the best possible + environment for location determination. The LIS operator needs to + ensure that the LIS is properly configured with identifiers that + indicate Devices on the remote side of a NAT or VPN. In order to + serve the Devices on the remote side of a NAT or VPN, a LIS needs to + have a presence on the side of the NAT or VPN nearest the Device. + +4.2. Location by Value + + Where a Device requires LI directly, it can request that the LIS + create a PIDF-LO document. This approach fits well with a + configuration whereby the Device directly makes use of the provided + PIDF-LO document. The details on the information that may be + included in the PIDF-LO MUST follow the subset of those rules + relating to the construction of the "location-info" element in the + PIDF-LO Usage Clarification, Considerations, and Recommendations + document [RFC5491]. Further detail is included in "Protocol + Parameters" (Section 6). + + + + + + +Barnes Standards Track [Page 7] + +RFC 5985 HELD September 2010 + + +4.3. Location by Reference + + Requesting location directly does not always address the requirements + of an application. A Device can request a Location URI instead of + literal location. A Location URI is a URI [RFC3986] of any scheme, + which a Location Recipient (LR) can use to retrieve LI. A Location + URI provided by a LIS can be assumed to be globally addressable; that + is, anyone in possession of the URI can access the LIS. + + However, possession of the URI does not in any way suggest that the + LIS indiscriminately reveals the location associated with the + Location URI. The specific requirements associated with the + dereference of the location are specified in [RFC5808]. The location + dereference protocol details are out of scope of this document. As + such, many of the requirements in [RFC5808] (e.g., canceling of + location references) are not intended to be supported by this + specification. It is anticipated that future specifications may + address these requirements. + +5. Protocol Description + + As discussed in Section 4, the HELD protocol provides for the + retrieval of the Device's location in the form of a PIDF-LO document + and/or Location URI(s) from a LIS. Three messages are defined to + support the location retrieval: locationRequest, locationResponse, + and error. + + The Location Request (locationRequest) message is described in + Section 5.1. A Location Request message from a Device indicates + whether location should be returned in the form of a PIDF-LO document + (with specific type(s) of location) and/or Location URI(s). In case + of success, the LIS replies with a locationResponse message, + including a PIDF-LO document and/or one or more Location URIs. In + the case of an error, the LIS replies with an error message. + + The HELD protocol messages are defined as XML documents that MUST be + encoded in UTF-8. A MIME type "application/held+xml" is registered + in Section 11.3 to distinguish HELD messages from other XML document + bodies. This specification follows the recommendations and + conventions described in [RFC3023], including the naming convention + of the type ('+xml' suffix) and the usage of the 'charset' parameter. + The 'charset' parameter MUST be included with the XML document. + + Section 6 contains a more thorough description of the protocol + parameters, valid values, and how each should be handled. Section 7 + contains a more specific definition of the structure of these + messages in the form of an XML Schema [W3C.REC-xmlschema-1-20041028]. + + + + +Barnes Standards Track [Page 8] + +RFC 5985 HELD September 2010 + + + Section 8 describes the use of a combination of HTTP [RFC2616], TLS + [RFC5246], and TCP [RFC0793] for transporting the HELD messages. + +5.1. Location Request + + A location request message is sent from the Device to the LIS when + the Device requires its own LI. The type of LI that a Device + requests is determined by the type of LI that is included in the + "locationType" element. + + The location request is made by sending a document formed of a + "locationRequest" element. The LIS uses the source IP address of the + location request message as the primary source of identity for the + requesting Device or target. It is anticipated that other Device + identities may be provided through schema extensions. + + The LIS MUST ignore any part of a location request message that it + does not understand, except the document element. If the document + element of a request is not supported, the LIS MUST return an error + with the unsupportedMessage error code. + +5.2. Location Response + + A successful response to a location request MUST contain a PIDF-LO + and/or Location URI(s). The response SHOULD contain location + information of the requested "locationType". The cases whereby a + different type of location information MAY be returned are described + in Section 6.2. + +5.3. Indicating Errors + + If the LIS is unable to provide location information based on the + received locationRequest message, it MUST return an error message. + The LIS may return an error message in response to requests for any + "locationType". + + 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 6.3. + + Error responses 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. + + + + + + +Barnes Standards Track [Page 9] + +RFC 5985 HELD September 2010 + + +6. Protocol Parameters + + This section describes in detail the parameters that are used for + this protocol. Table 1 lists the top-level components used within + the protocol and where they are mandatory (m) or optional (o) for + each of the messages. + + +----------------+-----------+------------+------------+------------+ + | Parameter | Section | Location | Location | Error | + | | | Request | Response | | + +----------------+-----------+------------+------------+------------+ + | responseTime | 6.1 | o | | | + | | | | | | + | locationType | 6.2 | o | | | + | | | | | | + | code | 6.3 | | | m | + | | | | | | + | message | 6.4 | | | o | + | | | | | | + | locationUriSet | 6.5 | | o | | + | | | | | | + | Presence | 6.6 | | o | | + | (PIDF-LO) | | | | | + +----------------+-----------+------------+------------+------------+ + + Table 1: Message Parameter Usage + +6.1. "responseTime" Parameter + + The "responseTime" attribute MAY be included in a location request + message. The "responseTime" attribute includes a time value + indicating to the LIS how long the Device is prepared to wait for a + response or a purpose for which the Device needs the location. + + In the case of emergency services, the purpose of obtaining the LI + could be either for routing a call to the appropriate Public Safety + Answering Point (PSAP) or indicating the location to which responders + should be dispatched. The values defined for the purpose, + "emergencyRouting" and "emergencyDispatch", will likely be governed + by jurisdictional policies and should be configurable on the LIS. + + The time value in the "responseTime" attribute is expressed as a non- + negative integer in units of milliseconds. The time value is + indicative only, and the LIS is under no obligation to strictly + adhere to the time limit implied; any enforcement of the time limit + is left to the requesting Device. The LIS provides the most accurate + LI that can be determined within the specified interval for the + specific service. + + + +Barnes Standards Track [Page 10] + +RFC 5985 HELD September 2010 + + + The LIS may use the value of the time in the "responseTime" attribute + as input when selecting the method of location determination, where + multiple such methods exist. If the "responseTime" attribute is + absent, then the LIS should return the most precise LI it is capable + of determining, with the time interval being implementation + dependent. + +6.2. "locationType" Parameter + + The "locationType" element MAY be included in a location request + message. It contains a list of LI types that are requested by the + Device. The following list describes the possible values: + + any: The LIS SHOULD attempt to provide LI in all forms available to + it. + + geodetic: The LIS SHOULD return a location by value in the form of a + geodetic location for the Target. + + civic: The LIS SHOULD return a location by value in the form of a + civic address for the Target. + + locationURI: The LIS SHOULD return a set of Location URIs for the + Target. + + The LIS SHOULD return the requested location type or types. The + location types the LIS returns also depend on the setting of the + optional "exact" attribute. If the "exact" attribute is set to + "true", then the LIS MUST return either the requested location type + or provide an error response. The "exact" attribute does not apply + (is ignored) for a request for a location type of "any". Further + detail of the "exact" attribute processing is provided in the + following Section 6.2.1. + + When there is a request for specific locationType(s) and the "exact" + attribute is "false", the LIS MAY provide additional location types, + or it MAY provide alternative types if the request cannot be + satisfied for a requested location type. The "SHOULD"-strength + requirements on this parameter for specific location types are + 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. + 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 LIS might be + unable to provide a civic address and thus provides a geodetic + address. + + + + +Barnes Standards Track [Page 11] + +RFC 5985 HELD September 2010 + + + The LIS SHOULD return location information in a form that is suited + for routing and responding to an emergency call in its jurisdiction, + specifically by value. The LIS MAY alternatively or additionally + return a Location URI. If the "locationType" element is absent, a + value of "any" MUST be assumed as the default. A Location URI + provided by the LIS is a reference to the most current available LI + and is not a stable reference to a specific location. + + It should be noted that the protocol does not support a request to + just receive one of a subset of location types. For example, in the + case where a Device has a preference for just "geodetic" or "civic", + it is necessary to make the request without an "exact" attribute, + including both location types. In this case, if neither is + available, a LIS SHOULD return a locationURI if available. + + The LIS SHOULD provide the locations in the response in the same + order in which they were included in the "locationType" element in + the request. Indeed, the primary advantage of including specific + location types in a request when the "exact" attribute is set to + "false" is to ensure that one receives the available locations in a + specific order. For example, a locationRequest for "civic" could + yield any of the following location types in the response: + + o civic + + o civic, geodetic + + o civic, locationURI + + o civic, geodetic, locationURI + + o civic, locationURI, geodetic + + o geodetic, locationURI (only if civic is not available) + + o locationURI, geodetic (only if civic is not available) + + o geodetic (only if civic is not available) + + o locationURI (only if civic is not available) + + For the example above, if the "exact" attribute was "true", then the + only possible response is either a "civic" location or an error + message. + + + + + + + +Barnes Standards Track [Page 12] + +RFC 5985 HELD September 2010 + + +6.2.1. "exact" Attribute + + The "exact" attribute MAY be included in a location request message + when the "locationType" element is included. When the "exact" + attribute is set to "true", it indicates to the LIS that the contents + of the "locationType" parameter MUST be strictly followed. The + default value of "false" allows the LIS the option of returning + something beyond what is specified, such as a set of Location URIs + when only a civic location was requested. + + A value of "true" indicates that the LIS MUST provide a location of + the requested type or types or MUST provide an error. The LIS MUST + provide the requested types only. The LIS MUST handle an exact + request that includes a "locationType" element set to "any" as if the + "exact" attribute were set to "false". + +6.3. "code" Parameter + + All "error" responses MUST contain a response code. All errors are + application-level errors and MUST only be provided in successfully + processed transport-level responses. For example, where HTTP/HTTPS + is used as the transport, HELD error messages MUST be carried by a + 200 OK HTTP/HTTPS response. + + The value of the response code MUST be an IANA-registered value. The + following tokens are registered by this document: + + requestError: This code indicates that the request was badly formed + in some fashion (other than the XML content). + + xmlError: This code indicates that the XML content of the request + was either badly formed or invalid. + + generalLisError: This code indicates that an unspecified error + occurred at the LIS. + + locationUnknown: This code indicates that the LIS could not + determine the location of the Device. The same request can be + sent by the Device at a later time. Devices MUST limit any + attempts to retry requests. + + unsupportedMessage: This code indicates that an element in the XML + document for the request was not supported or understood by the + LIS. This error code is used when a HELD request contains a + document element that is not supported by the receiver. + + timeout: This code indicates that the LIS could not satisfy the + request within the time specified in the "responseTime" parameter. + + + +Barnes Standards Track [Page 13] + +RFC 5985 HELD September 2010 + + + cannotProvideLiType: This code indicates that the LIS was unable to + provide LI of the type or types requested. This code is used when + the "exact" attribute on the "locationType" parameter is set to + "true". + + notLocatable: This code indicates that the LIS is unable to locate + the Device and that the Device MUST NOT make further attempts to + retrieve LI from this LIS. This error code is used to indicate + that the Device is outside the access network served by the LIS, + for instance, the VPN and NAT scenarios discussed in + Section 4.1.2. + +6.4. "message" Parameter + + The "error" message MAY include one or more "message" attributes to + convey some additional, human-readable information about the result + of the request. The message MAY be included in any language, which + SHOULD be indicated by the "xml:lang", attribute. The default + language is assumed to be English ("en") [RFC5646]. + +6.5. "locationUriSet" Parameter + + The "locationUriSet" element received in a "locationResponse" message + MAY contain any number of "locationURI" elements. It is RECOMMENDED + that the LIS allocate a Location URI for each scheme that it supports + and that each scheme is present only once. URI schemes and their + secure variants, such as HTTP and HTTPS, MUST be regarded as two + separate schemes. + + If a "locationUriSet" element is received in a "locationResponse" + message, it MUST contain an "expires" attribute, which defines the + length of time for which the set of "locationURI" elements are valid. + +6.5.1. "locationURI" Parameter + + The "locationURI" element includes a single Location URI. In order + for a URI of any particular scheme to be included in a response, + there MUST be a specification that defines how that URI can be used + to retrieve location information. The details of the protocol for + dereferencing must meet the location dereference protocol + requirements as specified in [RFC5808] and are outside the scope of + this base HELD specification. + + Each Location URI that is allocated by the LIS is unique to the + Device that is requesting it. At the time the Location URI is + provided in the response, there is no binding to a specific location + + + + + +Barnes Standards Track [Page 14] + +RFC 5985 HELD September 2010 + + + type and the Location URI is totally independent of the specific type + of location it might reference. The specific location type is + determined at the time of dereference. + + A "locationURI" SHOULD NOT contain any information that could be used + to identify the Device or Target. Thus, it is RECOMMENDED that the + "locationURI" element contain a public address for the LIS and an + anonymous identifier, such as a local identifier or unlinked + pseudonym. + + When a LIS returns a "locationURI" element to a Device, the policy on + the "locationURI" is set by the LIS alone. This specification does + not include a mechanism for the HELD client to set access control + policies on a "locationURI". Conversely, there is no mechanism, in + this protocol as defined in this document, for the LIS to provide a + Device the access control policy to be applied to a "locationURI". + Since the Device is not aware of the access controls to be applied to + (subsequent) requests to dereference a "locationURI", the client + SHOULD protect a "locationURI" as if it were a Location Object -- + i.e., the Device SHOULD send a "locationURI" over encrypted channels + and only to entities that are authorized to have access to the + location. + + Further guidelines to ensure the privacy and confidentiality of the + information contained in the "locationResponse" message, including + the "locationURI", are included in Section 9.3. + +6.5.2. "expires" Parameter + + The "expires" attribute is only included in a "locationResponse" + message when a "locationUriSet" element is included. The "expires" + attribute indicates the date/time at which the Location URIs provided + by the LIS will expire. The "expires" attribute does not define the + length of time a location received by dereferencing the Location URI + will be valid. The "expires" attribute is RECOMMENDED not to exceed + 24 hours and SHOULD be a minimum of 30 minutes. + + All date-time values used in HELD MUST be expressed in Universal + Coordinated Time (UTC) using the Gregorian calendar. The XML schema + allows use of time zone identifiers to indicate offsets from the zero + meridian, but this option MUST NOT be used with HELD. The extended + date-time form using upper case "T" and "Z" characters defined in + [W3C.REC-xmlschema-2-20041028] MUST be used to represent date-time + values. + + + + + + + +Barnes Standards Track [Page 15] + +RFC 5985 HELD September 2010 + + + Location responses that contain a "locationUriSet" element MUST + include the expiry time in the "expires" attribute. If a Device + dereferences a Location URI after the expiry time, the dereference + SHOULD fail. + +6.6. "Presence" Parameter (PIDF-LO) + + A single "presence" parameter MAY be included in the + "locationResponse" message when specific locationTypes (e.g., + "geodetic" or "civic") are requested or a "locationType" of "any" is + requested. The LIS MUST follow the subset of the rules relating to + the construction of the "location-info" element in the PIDF-LO Usage + Clarification, Considerations, and Recommendations document [RFC5491] + in generating the PIDF-LO for the presence parameter. + + The LIS MUST NOT include any means of identifying the Device in the + PIDF-LO unless it is able to verify that the identifier is correct + and inclusion of identity is expressly permitted by a Rule Maker. + Therefore, PIDF parameters that contain identity are either omitted + or contain unlinked pseudonyms [RFC3693]. A unique, unlinked + presentity URI SHOULD be generated by the LIS for the mandatory + presence "entity" attribute of the PIDF document. Optional + parameters such as the "contact" and "deviceID" elements [RFC4479] + are not used. + + Note that the presence parameter is not explicitly shown in the XML + schema in Section 7 for a location response message, due to XML + schema constraints, since PIDF is already defined and registered + separately. Thus, the "##other" namespace serves as a placeholder + for the presence parameter in the schema. + +7. XML Schema + + This section gives the XML Schema Definition + [W3C.REC-xmlschema-1-20041028] [W3C.REC-xmlschema-2-20041028] of the + "application/held+xml" format. This is presented as a formal + definition of the "application/held+xml" format. Note that the XML + Schema Definition is not intended to be used with on-the-fly + validation of the presence XML document. Whitespaces are included in + the schema to conform to the line length restrictions of the RFC + format without having a negative impact on the readability of the + document. Any conforming processor should remove leading and + trailing white spaces. + + + + + + + + +Barnes Standards Track [Page 16] + +RFC 5985 HELD September 2010 + + + <?xml version="1.0"?> + <xs:schema + targetNamespace="urn:ietf:params:xml:ns:geopriv:held" + xmlns:xs="http://www.w3.org/2001/XMLSchema" + xmlns:held="urn:ietf:params:xml:ns:geopriv:held" + xmlns:xml="http://www.w3.org/XML/1998/namespace" + elementFormDefault="qualified" + attributeFormDefault="unqualified"> + + <xs:annotation> + <xs:documentation> + This document (RFC 5985) defines HELD messages. + </xs:documentation> + </xs:annotation> + + <xs:import namespace="http://www.w3.org/XML/1998/namespace"/> + + <!-- Return Location --> + <xs:complexType name="returnLocationType"> + <xs:complexContent> + <xs:restriction base="xs:anyType"> + <xs:sequence> + <xs:element name="locationURI" type="xs:anyURI" + maxOccurs="unbounded"/> + </xs:sequence> + <xs:attribute name="expires" type="xs:dateTime" + use="required"/> + </xs:restriction> + </xs:complexContent> + </xs:complexType> + + <!-- responseTime Type --> + <xs:simpleType name="responseTimeType"> + <xs:union> + <xs:simpleType> + <xs:restriction base="xs:token"> + <xs:enumeration value="emergencyRouting"/> + <xs:enumeration value="emergencyDispatch"/> + </xs:restriction> + </xs:simpleType> + <xs:simpleType> + <xs:restriction base="xs:nonNegativeInteger"> + <xs:minInclusive value="0"/> + </xs:restriction> + </xs:simpleType> + </xs:union> + </xs:simpleType> + + + + +Barnes Standards Track [Page 17] + +RFC 5985 HELD September 2010 + + + <!-- Location Type --> + <xs:simpleType name="locationTypeBase"> + <xs:union> + <xs:simpleType> + <xs:restriction base="xs:token"> + <xs:enumeration value="any"/> + </xs:restriction> + </xs:simpleType> + <xs:simpleType> + <xs:restriction base="held:locationTypeList"> + <xs:minLength value="1"/> + </xs:restriction> + </xs:simpleType> + </xs:union> + </xs:simpleType> + + <xs:simpleType name="locationTypeList"> + <xs:list> + <xs:simpleType> + <xs:restriction base="xs:token"> + <xs:enumeration value="civic"/> + <xs:enumeration value="geodetic"/> + <xs:enumeration value="locationURI"/> + </xs:restriction> + </xs:simpleType> + </xs:list> + </xs:simpleType> + + <xs:complexType name="locationTypeType"> + <xs:simpleContent> + <xs:extension base="held:locationTypeBase"> + <xs:attribute name="exact" type="xs:boolean" + use="optional" default="false"/> + </xs:extension> + </xs:simpleContent> + </xs:complexType> + + <!-- Message Definitions --> + <xs:complexType name="baseRequestType"> + <xs:complexContent> + <xs:restriction base="xs:anyType"> + <xs:sequence/> + <xs:attribute name="responseTime" type="held:responseTimeType" + use="optional"/> + <xs:anyAttribute namespace="##any" processContents="lax"/> + </xs:restriction> + </xs:complexContent> + </xs:complexType> + + + +Barnes Standards Track [Page 18] + +RFC 5985 HELD September 2010 + + + <xs:complexType name="errorType"> + <xs:complexContent> + <xs:restriction base="xs:anyType"> + <xs:sequence> + <xs:element name="message" type="held:errorMsgType" + minOccurs="0" maxOccurs="unbounded"/> + <xs:any namespace="##other" processContents="lax" + minOccurs="0" maxOccurs="unbounded"/> + </xs:sequence> + <xs:attribute name="code" type="xs:token" + use="required"/> + <xs:anyAttribute namespace="##any" processContents="lax"/> + </xs:restriction> + </xs:complexContent> + </xs:complexType> + + <xs:complexType name="errorMsgType"> + <xs:simpleContent> + <xs:extension base="xs:token"> + <xs:attribute ref="xml:lang"/> + <xs:anyAttribute namespace="##any" processContents="lax"/> + </xs:extension> + </xs:simpleContent> + </xs:complexType> + + <xs:element name="error" type="held:errorType"/> + + <!-- Location Response --> + <xs:complexType name="locationResponseType"> + <xs:complexContent> + <xs:restriction base="xs:anyType"> + <xs:sequence> + <xs:element name="locationUriSet" + type="held:returnLocationType" + minOccurs="0"/> + <xs:any namespace="##other" processContents="lax" + minOccurs="0" maxOccurs="unbounded"/> + </xs:sequence> + </xs:restriction> + </xs:complexContent> + </xs:complexType> + + <xs:element name="locationResponse" + type="held:locationResponseType"/> + + <!-- Location Request --> + <xs:complexType name="locationRequestType"> + <xs:complexContent> + + + +Barnes Standards Track [Page 19] + +RFC 5985 HELD September 2010 + + + <xs:extension base="held:baseRequestType"> + <xs:sequence> + <xs:element name="locationType" + type="held:locationTypeType" + minOccurs="0"/> + <xs:any namespace="##other" processContents="lax" + minOccurs="0" maxOccurs="unbounded"/> + </xs:sequence> + </xs:extension> + </xs:complexContent> + </xs:complexType> + + <xs:element name="locationRequest" + type="held:locationRequestType"/> + + </xs:schema> + +8. HTTP Binding + + This section describes the use of HTTP [RFC2616] and HTTP over TLS + [RFC2818] as transport mechanisms for the HELD protocol, which a + conforming LIS and Device MUST support. + + Although HELD uses HTTP as a transport, it uses a strict subset of + HTTP features, and due to the restrictions of some features, a LIS is + not a fully compliant HTTP server. It is intended that a LIS can + easily be built using an HTTP server with extensibility mechanisms + and that a HELD Device can trivially use existing HTTP libraries. + This subset of requirements helps implementors avoid ambiguity with + the many options that the full HTTP protocol offers. + + A Device that conforms to this specification MAY choose not to + support HTTP authentication [RFC2617] or cookies [RFC2965]. Because + the Device and the LIS may not necessarily have a prior relationship, + the LIS SHOULD NOT require a Device to authenticate, either using the + above HTTP authentication methods or TLS client authentication. + Unless all Devices that access a LIS can be expected to be able to + authenticate in a certain fashion, denying access to location + information could prevent a Device from using location-dependent + services, such as emergency calling. Extensions to this protocol + might result in the addition of request parameters that a LIS might + use to decide to request Device authentication. + + A HELD request is carried in the body of an HTTP POST request. The + Device MUST include a Host header in the request. + + + + + + +Barnes Standards Track [Page 20] + +RFC 5985 HELD September 2010 + + + The MIME type of HELD request and response bodies is + "application/held+xml". LIS and Device MUST provide this value in + the HTTP Content-Type and Accept header fields. If the LIS does not + receive the appropriate Content-Type and Accept header fields, the + LIS SHOULD fail the request, returning a 406 (not acceptable) + response. HELD responses SHOULD include a Content-Length header. + + Devices MUST NOT use the "Expect" header or the "Range" header in + HELD requests. The LIS MAY return 501 (not implemented) errors if + either of these HTTP features are used. In the case that the LIS + receives a request from the Device containing an If-* (conditional) + header, the LIS SHOULD return a 412 (precondition failed) response. + + The POST method is the only method REQUIRED for HELD. If a LIS + chooses to support GET or HEAD, it SHOULD consider the kind of + application doing the GET. Since a HELD Device only uses a POST + method, the GET or HEAD MUST be either an escaped URL (e.g., somebody + found a URL in protocol traces or log files and fed it into their + browser) or somebody doing testing/debugging. The LIS could provide + information in the HELD response indicating that the URL corresponds + to a LIS server and only responds to HELD POST requests, or the LIS + could instead try to avoid any leak of information by returning a + very generic HTTP error message such as 404 (not found). + + The LIS populates the HTTP headers of responses so that they are + consistent with the contents of the message. In particular, the + "CacheControl" header SHOULD be set to disable caching of any PIDF-LO + document or Location URIs by HTTP intermediaries. Otherwise, there + is the risk of stale locations and/or the unauthorized disclosure of + the LI. This also allows the LIS to control any caching with the + HELD "expires" parameter. The HTTP status code MUST indicate a 2xx + series response for all HELD locationResponse and HELD error + messages. + + The LIS MAY redirect a HELD request. A Device MUST handle redirects + by using the Location header provided by the server in a 3xx + response. When redirecting, the Device MUST observe the delay + indicated by the Retry-After header. The Device MUST authenticate + the server that returns the redirect response before following the + redirect, if a Device requires that the server is authenticated. A + Device SHOULD authenticate the LIS indicated in a redirect. + + The LIS SHOULD support persistent connections and request pipelining. + If pipelining is not supported, the LIS MUST NOT allow persistent + connections. The Device MUST support termination of a response by + the closing of a connection. + + + + + +Barnes Standards Track [Page 21] + +RFC 5985 HELD September 2010 + + + Implementations of HELD that implement HTTP transport MUST implement + transport over TLS [RFC2818]. TLS provides message integrity and + confidentiality between the Device and LIS. The Device MUST + implement the server authentication method described in Section 3.1 + of [RFC2818], with an exception in how wildcards are handled. The + leftmost label MAY contain the wildcard string "*", which matches any + single domain name label. Additional characters in this leftmost + label are invalid (that is, "f*.example.com" is not a valid name and + does not match any domain name). + + The Device uses the URI obtained during LIS discovery to authenticate + the server. The details of this authentication method are provided + in Section 3.1 of HTTPS [RFC2818]. When TLS is used, the Device + SHOULD fail a request if server authentication fails, except in the + event of an emergency. + +9. Security Considerations + + HELD is a location acquisition protocol whereby the client requests + its location from a LIS. Specific requirements and security + considerations for location acquisition protocols are provided in + [RFC5687]. An in-depth discussion of the security considerations + applicable to the use of Location URIs and by-reference provision of + LI is included in [RFC5808]. + + By using the HELD protocol, the client and the LIS expose themselves + to two types of risk: + + Accuracy: The client receives incorrect location information. + + Privacy: An unauthorized entity receives location information. + + The provision of an accurate and privacy- and confidentiality- + protected location to the requestor depends on the success of five + steps: + + 1. The client must determine the proper LIS. + + 2. The client must connect to the proper LIS. + + 3. The LIS must be able to identify the Device by its identifier (IP + address). + + 4. The LIS must be able to return the desired location. + + 5. HELD messages must be transmitted unmodified between the LIS and + the client. + + + + +Barnes Standards Track [Page 22] + +RFC 5985 HELD September 2010 + + + Of these, only steps 2, 3, and 5 are within the scope of this + document. Step 1 is based on either manual configuration or on the + LIS discovery defined in [RFC5986], in which appropriate security + considerations are already discussed. Step 4 is dependent on the + specific positioning capabilities of the LIS and is thus outside the + scope of this document. + +9.1. Assuring That the Proper LIS Has Been Contacted + + This document assumes that the LIS to be contacted is identified + either by an IP address or a domain name, as is the case for a LIS + discovered as described in LIS Discovery [RFC5986]. When the HELD + transaction is conducted using TLS [RFC5246], the LIS can + authenticate its identity, either as a domain name or as an IP + address, to the client by presenting a certificate containing that + identifier as a subjectAltName (i.e., as an iPAddress or dNSName, + respectively). In the case of the HTTP binding described above, this + is exactly the authentication described by TLS [RFC2818]. If the + client has external information as to the expected identity or + credentials of the proper LIS (e.g., a certificate fingerprint), + these checks MAY be omitted. Any binding of HELD MUST be capable of + being transacted over TLS so that the client can request the above + authentication, and a LIS implementation for a binding MUST include + this feature. Note that in order for the presented certificate to be + valid at the client, the client must be able to validate the + certificate. In particular, the validation path of the certificate + must end in one of the client's trust anchors, even if that trust + anchor is the LIS certificate itself. + +9.2. Protecting Responses from Modification + + In order to prevent that response from being modified en route, + messages must be transmitted over an integrity-protected channel. + When the transaction is being conducted over TLS (a required feature + per Section 9.1), the channel will be integrity protected by + appropriate ciphersuites. When TLS is not used, this protection will + vary depending on the binding; in most cases, without protection from + TLS, the response will not be protected from modification en route. + +9.3. Privacy and Confidentiality + + Location information returned by the LIS must be protected from + access by unauthorized parties, whether those parties request the + location from the LIS or intercept it en route. As in Section 9.2, + transactions conducted over TLS with appropriate ciphersuites are + protected from access by unauthorized parties en route. Conversely, + in most cases, when not conducted over TLS, the response will be + accessible while en route from the LIS to the requestor. + + + +Barnes Standards Track [Page 23] + +RFC 5985 HELD September 2010 + + + Because HELD is an LCP and identifies clients and targets by IP + addresses, a requestor is authorized to access location for an IP + address only if it is the holder of that IP address. The LIS MUST + verify that the client is the target of the returned location, i.e., + the LIS MUST NOT provide location to other entities than the target. + Note that this is a necessary, but not sufficient, criterion for + authorization. A LIS MAY deny requests according to any local + policy. + + A prerequisite for meeting this requirement is that the LIS must have + some assurance of the identity of the client. Since the target of + the returned location is identified by an IP address, simply sending + the response to this IP address will provide sufficient assurance in + many cases. This is the default mechanism in HELD for assuring that + location is given only to authorized clients; LIS implementations + MUST support a mode of operation in which this is the only client + authentication. + + Using IP return routability as an authenticator means that location + information is vulnerable to exposure through IP address spoofing + attacks. A temporary spoofing of an IP address could mean that when + a Device requests a Location Object or Location URI, it receives + another Device's location because the attacker is able to receive + packets sent to the spoofed address. In addition, in cases where a + Device drops off the network for various reasons, the re-use of the + Device's IP address could result in another Device receiving the + original Device's location rather than its own location. These + exposures are limited by the following: + + o Location URIs MUST have a limited lifetime, as reflected by the + value for the "expires" element in Section 6.5.2. The lifetime of + Location URIs necessarily depends on the nature of the access. + + o The LIS and network SHOULD be configured so that the LIS is made + aware of Device movement within the network and addressing + changes. If the LIS detects a change in the network that results + in it no longer being able to determine the location of the + Device, then all Location URIs for that Device SHOULD be + invalidated. + + The above measures are dependent on network configuration, which + SHOULD be considered. For instance, in a fixed Internet access, + providers may be able to restrict the allocation of IP addresses to a + single physical line, ensuring that spoofing is not possible; in such + an environment, additional measures may not be necessary. + + + + + + +Barnes Standards Track [Page 24] + +RFC 5985 HELD September 2010 + + +10. Examples + + The following sections provide examples of basic HTTP/HTTPS, a simple + location request, and a location request for multiple location types, + along with the relevant location responses. To focus on important + portions of messages, the examples in Sections 10.2 and 10.3 do not + show HTTP/HTTPS headers or the XML prologue. In addition, sections + of XML not relevant to the example are replaced with comments. + +10.1. Examples of HTTPS Messages + + The examples in this section show complete HTTP/HTTPS messages that + include the HELD request or response document. + + This example shows the most basic request for a LO. The POST + includes an empty "locationRequest" element. + + POST /location HTTP/1.1 + Host: lis.example.com:49152 + Content-Type: application/held+xml;charset=utf-8 + Content-Length: 87 + + <?xml version="1.0"?> + <locationRequest xmlns="urn:ietf:params:xml:ns:geopriv:held"/> + + Since the above request does not include a "locationType" element, + the successful response to the request may contain any type of + location. The following shows a response containing a minimal + PIDF-LO. + + HTTP/1.1 200 OK + Server: Example LIS + Date: Tue, 10 Jan 2006 03:42:29 GMT + Expires: Tue, 10 Jan 2006 03:42:29 GMT + Cache-control: private + Content-Type: application/held+xml;charset=utf-8 + Content-Length: 856 + + <?xml version="1.0"?> + <locationResponse xmlns="urn:ietf:params:xml:ns:geopriv:held"> + <presence xmlns="urn:ietf:params:xml:ns:pidf" + entity="pres:3650n87934c@ls.example.com"> + <tuple id="b650sf789nd"> + <status> + <geopriv xmlns="urn:ietf:params:xml:ns:pidf:geopriv10"> + <location-info> + <Point xmlns="http://www.opengis.net/gml" + srsName="urn:ogc:def:crs:EPSG::4326"> + + + +Barnes Standards Track [Page 25] + +RFC 5985 HELD September 2010 + + + <pos>-34.407 150.88001</pos> + </Point> + </location-info> + <usage-rules + xmlns:gbp="urn:ietf:params:xml:ns:pidf:geopriv10:basicPolicy"> + <gbp:retention-expiry>2006-01-11T03:42:28+00:00 + </gbp:retention-expiry> + </usage-rules> + <method>Wiremap</method> + </geopriv> + </status> + <timestamp>2006-01-10T03:42:28+00:00</timestamp> + </tuple> + </presence> + </locationResponse> + + The error response to the request is an error document. The + following response shows an example error response. + + HTTP/1.1 200 OK + Server: Example LIS + Expires: Tue, 10 Jan 2006 03:49:20 GMT + Cache-control: private + Content-Type: application/held+xml;charset=utf-8 + Content-Length: 182 + + <?xml version="1.0"?> + <error xmlns="urn:ietf:params:xml:ns:geopriv:held" + code="locationUnknown"> + <message xml:lang="en">Unable to determine location + </message> + </error> + +10.2. Example of a Simple Location Request + + The location request shown below doesn't specify any location types + or response time. + + <locationRequest xmlns="urn:ietf:params:xml:ns:geopriv:held"/> + + The example response to this location request contains a list of + Location URIs. + + <locationResponse xmlns="urn:ietf:params:xml:ns:geopriv:held"> + <locationUriSet expires="2006-01-01T13:00:00.0Z"> + <locationURI>https://ls.example.com:9768/357yc6s64ceyoiuy5ax3o + </locationURI> + <locationURI>sip:9769+357yc6s64ceyoiuy5ax3o@ls.example.com + + + +Barnes Standards Track [Page 26] + +RFC 5985 HELD September 2010 + + + </locationURI> + </locationUriSet> + </locationResponse> + + An error response to this location request is shown below: + + <error xmlns="urn:ietf:params:xml:ns:geopriv:held" + code="locationUnknown"> + <message xml:lang="en">Location not available + </message> + </error> + +10.3. An Example of a Location Request for Multiple Location Types + + The following Location Request message includes a request for + geodetic, civic, and any Location URIs. + + <locationRequest xmlns="urn:ietf:params:xml:ns:geopriv:held"> + <locationType exact="true"> + geodetic + civic + locationURI + </locationType> + </locationRequest> + + The corresponding Location Response message includes the requested + location information, including two Location URIs. + + <locationResponse xmlns="urn:ietf:params:xml:ns:geopriv:held"> + <locationUriSet expires="2006-01-01T13:00:00.0Z"> + <locationURI>https://ls.example.com:9768/357yc6s64ceyoiuy5ax3o + </locationURI> + <locationURI>sip:9769+357yc6s64ceyoiuy5ax3o@ls.example.com: + </locationURI> + </locationUriSet> + <presence xmlns="urn:ietf:params:xml:ns:pidf" + entity="pres:ae3be8585902e2253ce2@10.102.23.9"> + <tuple id="lisLocation"> + <status> + <geopriv xmlns="urn:ietf:params:xml:ns:pidf:geopriv10"> + <location-info> + <gs:Circle xmlns:gs="http://www.opengis.net/pidflo/1.0" + xmlns:gml="http://www.opengis.net/gml" + srsName="urn:ogc:def:crs:EPSG::4326"> + <gml:pos>-34.407242 150.882518</gml:pos> + <gs:radius uom="urn:ogc:def:uom:EPSG::9001">30 + </gs:radius> + </gs:Circle> + + + +Barnes Standards Track [Page 27] + +RFC 5985 HELD September 2010 + + + <ca:civicAddress + xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr" + xml:lang="en-au"> + <ca:country>AU</ca:country> + <ca:A1>NSW</ca:A1> + <ca:A3>Wollongong</ca:A3> + <ca:A4>Gwynneville</ca:A4> + <ca:STS>Northfield Avenue</ca:STS> + <ca:LMK>University of Wollongong</ca:LMK> + <ca:FLR>2</ca:FLR> + <ca:NAM>Andrew Corporation</ca:NAM> + <ca:PC>2500</ca:PC> + <ca:BLD>39</ca:BLD> + <ca:SEAT>WS-183</ca:SEAT> + <ca:POBOX>U40</ca:POBOX> + </ca:civicAddress> + </location-info> + <usage-rules + xmlns:gbp="urn:ietf:params:xml:ns:pidf:geopriv10:basicPolicy"> + <gbp:retransmission-allowed>false + </gbp:retransmission-allowed> + <gbp:retention-expiry>2007-05-25T12:35:02+10:00 + </gbp:retention-expiry> + </usage-rules> + <method>Wiremap</method> + </geopriv> + </status> + <timestamp>2007-05-24T12:35:02+10:00</timestamp> + </tuple> + </presence> + </locationResponse> + +11. IANA Considerations + + IANA has made the registrations detailed in the following sections. + +11.1. URN Sub-Namespace Registration for + urn:ietf:params:xml:ns:geopriv:held + + This section registers a new XML namespace, + "urn:ietf:params:xml:ns:geopriv:held", per the guidelines in + [RFC3688]. + + URI: urn:ietf:params:xml:ns:geopriv:held + + Registrant Contact: IETF, GEOPRIV working group, (geopriv@ietf.org), + Mary Barnes (mary.ietf.barnes@gmail.com). + + + + +Barnes Standards Track [Page 28] + +RFC 5985 HELD September 2010 + + + XML: + + BEGIN + <?xml version="1.0"?> + <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> + <head> + <title>HELD Messages</title> + </head> + <body> + <h1>Namespace for HELD Messages</h1> + <h2>urn:ietf:params:xml:ns:geopriv:held</h2> + <p>See RFC 5985</p> + </body> + </html> + END + +11.2. 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), + Mary Barnes (mary.ietf.barnes@gmail.com). + + Schema: The XML for this schema can be found as the entirety of + Section 7 of this document. + +11.3. MIME Media Type Registration for 'application/held+xml' + + This section registers the "application/held+xml" MIME type. + + To: ietf-types@iana.org + + Subject: Registration of MIME media type application/held+xml + + MIME media type name: application + + MIME subtype name: held+xml + + Required parameters: (none) + + Optional parameters: charset + Same as the charset parameter of "application/xml" as specified in + RFC 3023 [RFC3023], Section 3.2. + + + +Barnes Standards Track [Page 29] + +RFC 5985 HELD September 2010 + + + Encoding considerations: Same as the encoding considerations of + "application/xml" as specified in RFC 3023 [RFC3023], Section 3.2. + + Security considerations: This content type is designed to carry + protocol data related to the location of an entity, which could + include information that is considered private. Appropriate + precautions should be taken to limit disclosure of this + information. + + Interoperability considerations: This content type provides a basis + for a protocol. There are multiple interoperable implementations + of this protocol. + + Published specification: RFC 5985 + + Applications which use this media type: Location information + providers and consumers. + + Additional Information: + Magic Number(s): (none) + File extension(s): .heldxml + Macintosh File Type Code(s): "TEXT" + + Person & email address to contact for further information: + Mary Barnes <mary.ietf.barnes@gmail.com> + + Intended usage: LIMITED USE + + Author/Change controller: The IETF + + Other information: This media type is a specialization of + application/xml [RFC3023], and many of the considerations + described there also apply to application/held+xml. + +11.4. Error Code Registry + + As defined in this document, IANA created a new registry for the HELD + protocol including an initial registry for error codes. The error + codes are included in HELD error messages as described in Section 6.3 + and defined in the schema in the 'codeType' token in the XML schema + in Section 7. + + The following is a summary of the registry: + + Related Registry: Geopriv HELD Registries, Error codes for HELD + + Defining RFC: RFC 5985 + + + + +Barnes Standards Track [Page 30] + +RFC 5985 HELD September 2010 + + + Registration/Assignment Procedures: Following the policies outlined + in [RFC5226], the IANA policy for assigning new values for the + Error codes for HELD is Standards Action: Values are assigned only + for Standards Track RFCs approved by the IESG. + + Registrant Contact: IETF, GEOPRIV working group, (geopriv@ietf.org), + Mary Barnes (mary.ietf.barnes@gmail.com). + + This section registers the following eight initial error codes as + described in Section 6.3: + + requestError: This code indicates that the request was badly formed + in some fashion. + + xmlError: This code indicates that the XML content of the request + was either badly formed or invalid. + + generalLisError: This code indicates that an unspecified error + occurred at the LIS. + + locationUnknown: This code indicates that the LIS could not + determine the location of the Device. + + unsupportedMessage: This code indicates that the request was not + supported or understood by the LIS. This error code is used when + a HELD request contains a document element that is not supported + by the receiver. + + timeout: This code indicates that the LIS could not satisfy the + request within the time specified in the "responseTime" parameter. + + cannotProvideLiType: This code indicates that the LIS was unable to + provide LI of the type or types requested. This code is used when + the "exact" attribute on the "locationType" parameter is set to + "true". + + notLocatable: This code indicates that the LIS is unable to locate + the Device and that the Device MUST NOT make further attempts to + retrieve LI from this LIS. This error code is used to indicate + that the Device is outside the access network served by the LIS; + for instance, the VPN and NAT scenarios discussed in + Section 4.1.2. + + + + + + + + + +Barnes Standards Track [Page 31] + +RFC 5985 HELD September 2010 + + +12. Contributors + + James Winterbottom, Martin Thomson and Barbara Stark are the authors + of the original document, from which this WG document was derived. + Their contact information is included below. They made additional + contributions to the WG document, including the XML schema. + + James Winterbottom + Andrew + Andrew Building (39) + University of Wollongong + Northfields Avenue + Wollongong, NSW 2522 + AU + + Phone: +61 2 4221 2938 + EMail: james.winterbottom@andrew.com + URI: http://www.andrew.com/ + + + Martin Thomson + Andrew + Andrew Building (39) + University of Wollongong + Northfields Avenue + Wollongong, NSW 2522 + AU + + Phone: +61 2 4221 2915 + EMail: martin.thomson@andrew.com + URI: http://www.andrew.com/ + + Barbara Stark + BellSouth + Room 7A43 + 725 W Peachtree St. + Atlanta, GA 30308 + US + + EMail: barbara.stark@att.com + +13. Acknowledgements + + The author and contributors would like to thank the participants in + the GEOPRIV WG and the following people for their constructive input + and feedback on this document (in alphabetical order): Nadine Abbott, + Bernard Aboba, Eric Arolick, Richard Barnes (in particular, the + security considerations section), Peter Blatherwick, Ben Campbell, + + + +Barnes Standards Track [Page 32] + +RFC 5985 HELD September 2010 + + + Guy Caron, Eddy Corbett, Martin Dawson, Lisa Dusseault, Robins + George, Jerome Grenier, Ted Hardie, Cullen Jennings, Neil Justusson, + Tat Lam, Marc Linsner, Patti McCalmont, Alexey Melnikov, Roger + Marshall, Tim Polk, Perry Prozeniuk, Carl Reed, Julian Reschke, Eric + Rescorla, Dan Romascanu, Brian Rosen, John Schnizlein, Shida + Schubert, Henning Schulzrinne, Ed Shrum, Doug Stuard, Hannes + Tschofenig, and Karl Heinz Wolf. + +14. References + +14.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [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. + + [RFC2965] Kristol, D. and L. Montulli, "HTTP State Management + Mechanism", RFC 2965, October 2000. + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + January 2004. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, August 2008. + + [RFC5491] Winterbottom, J., Thomson, M., and H. Tschofenig, "GEOPRIV + Presence Information Data Format Location Object (PIDF-LO) + Usage Clarification, Considerations, and Recommendations", + RFC 5491, March 2009. + + [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying + Languages", BCP 47, RFC 5646, September 2009. + + [RFC5986] Thomson, M. and J. Winterbottom, "Discovering the Local + Location Information Server (LIS)", RFC 5986, + September 2010. + + [W3C.REC-xmlschema-1-20041028] + Thompson, H., Mendelsohn, N., Beech, D., and M. Maloney, + "XML Schema Part 1: Structures Second Edition", World Wide + Web Consortium Recommendation REC-xmlschema-1-20041028, + October 2004, + <http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>. + + + +Barnes Standards Track [Page 33] + +RFC 5985 HELD September 2010 + + + [W3C.REC-xmlschema-2-20041028] + Malhotra, A. and P. Biron, "XML Schema Part 2: Datatypes + Second Edition", World Wide Web Consortium + Recommendation REC-xmlschema-2-20041028, October 2004, + <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>. + +14.2. Informative References + + [LLDP-MED] + TIA, "ANSI/TIA-1057 Link Layer Discovery Protocol - Media + Endpoint Discovery". + + [LOC-CONVEY] + Polk, J., Rosen, B., and J. Peterson, "Location Conveyance + for the Session Initiation Protocol", Work in Progress, + July 2010. + + [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, + RFC 793, September 1981. + + [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., + Leach, P., Luotonen, A., and L. Stewart, "HTTP + Authentication: Basic and Digest Access Authentication", + RFC 2617, June 1999. + + [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media + Types", RFC 3023, January 2001. + + [RFC3693] Cuellar, J., Morris, J., Mulligan, D., Peterson, J., and + J. Polk, "Geopriv Requirements", RFC 3693, February 2004. + + [RFC3825] Polk, J., Schnizlein, J., and M. Linsner, "Dynamic Host + Configuration Protocol Option for Coordinate-based + Location Configuration Information", RFC 3825, July 2004. + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, January 2005. + + [RFC4479] Rosenberg, J., "A Data Model for Presence", RFC 4479, + July 2006. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + + + + + +Barnes Standards Track [Page 34] + +RFC 5985 HELD September 2010 + + + [RFC5687] Tschofenig, H. and H. Schulzrinne, "GEOPRIV Layer 7 + Location Configuration Protocol: Problem Statement and + Requirements", RFC 5687, March 2010. + + [RFC5808] Marshall, R., "Requirements for a Location-by-Reference + Mechanism", RFC 5808, May 2010. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Barnes Standards Track [Page 35] + +RFC 5985 HELD September 2010 + + +Appendix A. HELD Compliance to IETF LCP Requirements + + This appendix describes HELD's compliance to the requirements + specified in [RFC5687]. + +A.1. L7-1: Identifier Choice + + "The L7 LCP MUST be able to carry different identifiers or MUST + define an identifier that is mandatory to implement. Regarding the + latter aspect, such an identifier is only appropriate if it is from + the same realm as the one for which the location information service + maintains identifier to location mapping." + + COMPLY + + HELD uses the IP address of the location request message as the + primary source of identity for the requesting Device or target. This + identity can be used with other contextual network information to + provide a physical location for the Target for many network + deployments. There may be network deployments where an IP address + alone is insufficient to identify a Target in a network. However, + any necessary identity extensions for these networks is beyond the + scope of this document. + +A.2. L7-2: Mobility Support + + "The GEOPRIV Layer 7 Location Configuration Protocol MUST support a + broad range of mobility from Devices that can only move between + reboots, to Devices that can change attachment points with the impact + that their IP address is changed, to Devices that do not change their + IP address while roaming, to Devices that continuously move by being + attached to the same network attachment point." + + COMPLY + + Mobility support is inherently a characteristic of the access network + technology, and HELD is designed to be access network agnostic. + Consequently, HELD complies with this requirement. In addition, HELD + provides specific support for mobile environments by providing an + optional responseTime attribute in location request messages. + Wireless networks often have several different mechanisms at their + disposal for position determination (e.g., assisted GPS versus + determining the location based on the identity of the serving base + station), each providing different degrees of accuracy and taking + different amounts of time to yield a result. The responseTime + parameter provides the LIS with a criterion which it can use to + select a location determination technique. + + + + +Barnes Standards Track [Page 36] + +RFC 5985 HELD September 2010 + + +A.3. L7-3: ASP and Access Network Provider Relationship + + "The design of the L7 LCP MUST NOT assume a business or trust + relationship between the Application Service Provider (ASP) and the + Access Network Provider. Requirements for resolving a reference to + location information are not discussed in this document." + + COMPLY + + HELD describes a location acquisition protocol between a Device and a + LIS. In the context of HELD, the LIS is within the Access Network. + Thus, HELD is independent of the business or trust relationship + between the Application Service Provider (ASP) and the Access Network + Provider. Location acquisition using HELD is subject to the + restrictions described in Section 9. + +A.4. L7-4: Layer 2 and Layer 3 Provider Relationship + + "The design of the GEOPRIV Layer 7 Location Configuration Protocol + MUST assume that there is a trust and business relationship between + the L2 and the L3 provider. The L3 provider operates the LIS and + needs to obtain location information from the L2 provider since this + one is closest to the end host. If the L2 and L3 provider for the + same host are different entities, they cooperate for the purposes + needed to determine end system locations." + + COMPLY + + HELD was specifically designed with this model in mind and readily + allows itself to chaining requests between operators without a change + in protocol being required. HELD is a webservices protocol which can + be bound to transports other than HTTP, such as BEEP. Using a + protocol such as BEEP offers the option of high request throughput + over a dedicated connection between an L3 provider and an L2 provider + without incurring the serial restriction imposed by HTTP. This is + less easy to do with protocols that do not decouple themselves from + the transport. + +A.5. L7-5: Legacy Device Considerations + + "The design of the GEOPRIV Layer 7 Location Configuration Protocol + MUST consider legacy residential NAT Devices and Network Termination + Equipment (NTE) in an DSL environment that cannot be upgraded to + support additional protocols, for example to pass additional + information through DHCP." + + + + + + +Barnes Standards Track [Page 37] + +RFC 5985 HELD September 2010 + + + COMPLY + + HELD is an application protocol and operates on top of IP. A HELD + request from a host behind a residential NAT will traverse the NAT + acquiring the external address of the home router. The location + provided to the host therefore will be the address of the home router + in this circumstance. No changes are required to the home router in + order to support this function, HELD was designed specifically to + address this deployment scenario. + +A.6. L7-6: VPN Awareness + + "The design of the GEOPRIV Layer 7 Location Configuration Protocol + MUST assume that at least one end of a VPN is aware of the VPN + functionality. In an enterprise scenario, the enterprise side will + provide the LIS used by the client and can thereby detect whether the + LIS request was initiated through a VPN tunnel." + + COMPLY + + HELD does not preclude a LIS on the far end of a VPN tunnel from + being aware that the client request is occurring over that tunnel. + It also does not preclude a client Device from accessing a LIS + serving the local physical network and subsequently using the + location information with an application that is accessed over a VPN + tunnel. + +A.7. L7-7: Network Access Authentication + + "The design of the GEOPRIV Layer 7 Location Configuration Protocol + MUST NOT assume prior network access authentication." + + COMPLY + + HELD makes no assumptions about prior network access authentication. + HELD strongly recommends the use of TLS with server-side certificates + for communication between the endpoint and the LIS. There is no + requirement for the endpoint to authenticate with the LIS. + +A.8. L7-8: Network Topology Unawareness + + "The design of the GEOPRIV Layer 7 Location Configuration Protocol + MUST NOT assume end systems being aware of the access network + topology. End systems are, however, able to determine their public + IP address(es) via mechanisms such as STUN or NSIS NATFW NSLP." + + + + + + +Barnes Standards Track [Page 38] + +RFC 5985 HELD September 2010 + + + COMPLY + + HELD makes no assumption about the network topology. HELD doesn't + require that the Device know its external IP address, except where + that is required for discovery of the LIS. + +A.9. L7-9: Discovery Mechanism + + "The L7 LCP MUST define a single mandatory to implement discovery + mechanism." + + COMPLY + + HELD uses the discovery mechanism in [RFC5986]. + +A.10. L7-10: PIDF-LO Creation + + "When a LIS creates a PIDF-LO per RFC 4119 then it MUST put the + <geopriv> element into the <device> element of the presence document + (see RFC 4479). This ensures that the resulting PIDF-LO document, + which is subsequently distributed to other entities, conforms to the + rules outlined in [now RFC 5941]." + + COMPLY + + HELD protocol overview (Section 4) describes the requirements on the + LIS in creating the PIDF-LO and prescribes that the PIDF-LO generated + by the LIS MUST conform to [RFC5491]. + +Author's Address + + Mary Barnes (editor) + Polycom + + EMail: mary.ietf.barnes@gmail.com + + + + + + + + + + + + + + + + +Barnes Standards Track [Page 39] + |