HTTP-Enabled Location Delivery (HELD)
updated by
- rfc-7840 — A Routing Request Extension for the HTTP-Enabled Location Delivery (HELD) Protocol
Extracted elements (32)
HELD uses HTTP as a transport but intentionally restricts its feature set so that a LIS is not required to be a fully compliant HTTP server. This allows LIS implementations to be built on standard HTTP servers with extensibility mechanisms and simplifies client implementation using existing HTTP libraries.
The LIS SHOULD NOT require Device authentication because requiring it could prevent Devices from accessing emergency location services. The default authorization mechanism is IP return routability — the LIS responds to the source IP address, implicitly authorizing only the holder of that address.
The 'locationType' parameter uses SHOULD-strength requirements (rather than MUST) for specific location types to allow soft-failover, enabling fixed client configurations that prefer a specific type without failing when that type is unavailable from the LIS.
When NAT or VPN exists between the Device and LIS, the source IP address seen by the LIS may not accurately identify the Device's physical location. Devices SHOULD perform their HELD query prior to establishing VPN or proxy connections to avoid receiving location based on a tunneled address.
A HELD request is carried in the body of an HTTP POST request. The Device MUST include a Host header, and LIS and Device MUST provide 'application/held+xml' in the HTTP Content-Type and Accept header fields.
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'.
All date-time values used in HELD MUST be expressed in UTC using the Gregorian calendar, and the time zone offset option MUST NOT be used. The extended date-time form using upper case 'T' and 'Z' characters MUST be used.
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.
HELD protocol messages MUST be encoded in UTF-8, and the 'charset' parameter MUST be included with the XML document. HELD messages use the MIME type 'application/held+xml'.
If a 'locationUriSet' element is received in a 'locationResponse' message, it MUST contain an 'expires' attribute. The 'expires' attribute is RECOMMENDED not to exceed 24 hours and SHOULD be a minimum of 30 minutes.
If the LIS is unable to provide location information based on the received locationRequest message, it MUST return an error message. All error responses MUST contain a response code, and HELD error messages MUST be carried by a 200 OK HTTP/HTTPS response.
If the 'locationType' element is absent, a value of 'any' MUST be assumed as the default. When the 'exact' attribute is set to 'true', the LIS MUST return either the requested location type or provide an error response.
Implementations of HELD that implement HTTP transport MUST implement transport over TLS. The Device MUST implement the server authentication method described in Section 3.1 of RFC 2818; the leftmost label MAY contain the wildcard string '*' matching any single domain name label.
Location URIs MUST have a limited lifetime as reflected by the value of the 'expires' element. The LIS and network SHOULD be configured so that when the LIS detects a change resulting in it no longer being able to determine the location of the Device, all Location URIs for that Device SHOULD be invalidated.
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, and the type of URI provided by LIS discovery is RECOMMENDED to be an HTTPS URI.
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.
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. A unique, unlinked presentity URI SHOULD be generated by the LIS for the mandatory presence 'entity' attribute.
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. LIS implementations MUST support a mode of operation in which IP return routability is the only client authentication.
The 'locationURI' SHOULD NOT contain any information that could identify the Device or Target. It is RECOMMENDED that the locationURI contain a public LIS address and an anonymous identifier such as an unlinked pseudonym. Devices SHOULD treat locationURIs as Location Objects and transmit them only over encrypted channels to authorized entities.
The 'error' element is returned by the LIS on failure, carrying a required 'code' attribute (IANA-registered token) and optional 'message' child elements with human-readable diagnostic text and 'xml:lang' attribute.
The 'locationRequest' element is the top-level XML element sent from Device to LIS. It optionally includes a 'responseTime' attribute and a 'locationType' element specifying the desired location type(s).
The 'locationResponse' element is returned by the LIS on success and MAY contain a 'locationUriSet' element with one or more 'locationURI' elements, and/or a PIDF-LO 'presence' document.
The 'locationType' element MAY appear in a locationRequest and contains a space-separated list of requested location types: 'any', 'geodetic', 'civic', or 'locationURI'. An optional 'exact' boolean attribute (default false) requires strict type adherence.
The 'locationUriSet' element in a locationResponse contains one or more 'locationURI' elements (any URI scheme) and a required 'expires' dateTime attribute indicating when the URIs expire.
The 'responseTime' attribute MAY appear in a locationRequest. Its value is either a non-negative integer in milliseconds or one of the tokens 'emergencyRouting' or 'emergencyDispatch', indicating urgency of the request.
IANA created a new 'Geopriv HELD Registries' registry including an 'Error codes for HELD' sub-registry. Initial values (Standards Action required for additions): requestError, xmlError, generalLisError, locationUnknown, unsupportedMessage, timeout, cannotProvideLiType, notLocatable.
IANA registered the XML namespace 'urn:ietf:params:xml:ns:geopriv:held', the XML schema 'urn:ietf:params:xml:schema:geopriv:held', and the MIME media type 'application/held+xml' for the HELD protocol.
A rogue LIS could return inaccurate location information. The client must authenticate the LIS using TLS with a server certificate containing a subjectAltName matching the discovered LIS URI. Any HELD binding MUST support TLS for this authentication.
HELD messages must be transmitted over TLS to prevent modification en route and to protect location information from access by unauthorized parties. Without TLS, responses are neither integrity-protected nor confidential.
Location information is vulnerable to IP address spoofing attacks, which could cause a Device to receive another Device's location. Mitigations include limiting Location URI lifetime via 'expires' and configuring the LIS to invalidate URIs upon detecting Device movement or address changes.
HELD messages are XML documents encoded in UTF-8, using the namespace 'urn:ietf:params:xml:ns:geopriv:held', carried as 'application/held+xml' MIME type in HTTP POST request and response bodies.
The 'expires' attribute in 'locationUriSet' is an xs:dateTime value expressed in UTC using the extended format with uppercase 'T' and 'Z' characters; time zone offsets MUST NOT be used.