RFC 5985
HTTP-Enabled Location Delivery (HELD)
HTTP-Enabled Location Delivery (HELD) 🎀
- Publisher: Internet Engineering Task Force (IETF) 🌸
- Editor: M. Barnes, Ed. (Polycom) 💅
- Category: Standards Track ✨
- Date: September 2010 📅
- Number: RFC 5985, ISSN 2070-1721 🦋
- Obsoletes / Updates: the title block doesn't list any RFCs as obsoleted or updated, so this one stands on its own 💜
Abstract ✨
okay so this doc defines a Layer 7 Location Configuration Protocol (L7 LCP) 🗺️ and explains how HTTP and HTTP/TLS can be used as its transports 🚚. The L7 LCP is how you grab location info from a server sitting inside an access network 📡. It gives you two ways to get location info: by value and by reference 🎀. And it's an extensible application-layer protocol that doesn't care what session layer is underneath 🧚. It's giving flexible, it's giving future-proof 💖
Status of This Memo 🌈
This is an Internet Standards Track document 👑.
It's a product of the Internet Engineering Task Force (IETF) 🌸. It represents the consensus of the IETF community, received public review, and got approved for publication by the Internet Engineering Steering Group (IESG) 🫶. If you want more on Internet Standards, check Section 2 of RFC 5741 📚.
For the current status of this document, any errata, and how to send feedback, go to 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 read these carefully, because they spell out your rights and restrictions for 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 they're provided without warranty as described in the Simplified BSD License ⚖️.
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
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 . . . . . . . . . . . . . . . . . 391. Introduction 🧚
okay so a Device's location is seriously useful for a whole bunch of applications 📍. The L7 Location Configuration Protocol (LCP) problem statement and requirements document [RFC5687] walks through scenarios where a Device might lean on its access network to tell it where it is 🗺️. The Location Information Server (LIS) service works for access networks using wired tech (like DSL and cable) and wireless tech (like WiMAX), and it handles all sorts of Device mobility 🚗. This doc describes a protocol for grabbing Location Information (LI) from a LIS inside an access network 💖.
This spec names two types of location info you can pull from a LIS. First, you can get location by value, meaning the Device gets a literal location object that describes where it is 🎀. Second, the Device can ask the LIS for a location reference, either a Location URI or a set of Location URIs, so it can share its LI by reference 🔗. Both methods can come from the same LIS at the same time, which is super handy when different apps need different kinds of location info 🌈.
This spec defines an extensible XML-based protocol that lets a Device retrieve LI from a LIS 💅. The protocol can be bound to any session-layer protocol, especially ones that can carry MIME 🫶. This document covers using HTTP and HTTP/TLS as the transports 🦋.
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] 💜.
This doc uses a bunch of terms (and their acronyms) 🧾: 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). These are all defined in the GEOPRIV Requirements [RFC3693] 🌸. Location Information Server (LIS), Access Network, Access Provider (AP), and Access Network Provider are used the same way they're defined in the L7 LCP Problem statement and Requirements document [RFC5687] ✨. The way this doc uses Civic Location/Address and Geodetic Location matches how lots of the referenced docs use them 🌍.
When we describe the protocol, "attribute" and "element" mean what they mean in XML 🎀. "Parameter" is the more general protocol word, and it can refer to either an XML "attribute" or an "element" 💅.
3. Overview and Scope ✨
okay so this section is the big picture, bestie 🫶 it's about the interface between a Device and a Location Information Server (LIS). We're assuming the LIS lives in the same administrative domain as the Device (think: the access network) 🌐 The LIS exists because not every Device can figure out its own LI (location information), and even if a Device can, it might be way more efficient with some help 💅 This doc does NOT say how LI actually gets determined, so that's a separate convo 🙈 An Access Provider (AP) runs the LIS so Devices (and Targets) can grab their LI. We're also assuming the Device and the Access Provider have no prior relationship beyond what the Device needs to get network access. Super minimal, very chill 🎀
This whole thing is built around attributing LI to a Device, not to a specific person (end user) or Target. The reasoning is that location tech is usually designed to find a Device, not a human 🧚 For most apps, the Device's LI is an adequate stand-in for the end user's LI, which is giving reliable vibes ✨ But here's the tea: revealing where a Device is pretty much always reveals something about where its user is, so the same level of privacy protection a user asks for is required for the Device too 🔒 This approach might need some extra assurances about the link between the Device and the Target, or we accept the limitation that, unless the Device requires active user authentication, there's no guarantee that any particular individual is using the Device at that exact moment 😭 messy but honest!
Here's the logical setup of the functional elements from [RFC3693] and the LIS defined in [RFC5687] 🦋 It also shows where this protocol applies, with the Rule Maker and Target represented by the role of the Device. Only the interfaces that matter to the Device are labelled in the diagram, so don't panic if things look sparse 💖
+---------------------------------------------+
| Access Network Provider |
| |
| +--------------------------------------+ |
| | Location Information Server | |
| | | |
| | | |
| | | |
| | | |
| +------|-------------------------------+ |
+----------|----------------------------------+
|
|
HELD
|
Rule Maker - - _ +-----------+ +-----------+
o - - | Device | | Location |
<U\ | | - - - - | Recipient |
/ \ _ - - | | APP | |
Target - - +-----------+ +-----------+
Figure 1: Significant RolesThe interface between the Location Recipient (LR) and the Device and/or LIS is application specific 🎀 That's what the APP annotation in the diagram is pointing at, and it's outside the scope of this document. If you want an example of an APP interface between a Device and an LR, check out the SIP Location Conveyance document [LOC-CONVEY] 💅
4. Protocol Overview 🧚
okay the main event 🔥 A Device uses the HTTP-Enabled Location Delivery (HELD) protocol to retrieve its location, either directly as a Presence Information Data Format Location Object (PIDF-LO) document (by value), or indirectly as a Location URI (by reference) 💜 The security needed to keep the Device's location accurate, private, and confidential is covered in the Security Considerations (Section 9), so go read that when you get a chance 👑
As described in the L7 LCP problem statement and requirements document [RFC5687], the Device MUST first discover the URI for the LIS before it sends any HELD protocol requests 🚨 That URI SHOULD come from an authorized and authenticated entity 🔐 The details for making sure the right LIS gets contacted are in Section 9, especially Section 9.1 🌸 LIS discovery details are out of scope here and are specified in [RFC5986]. The type of URI LIS discovery gives you is RECOMMENDED to be an HTTPS URI 🌈
The LIS needs an identifier for the Device so it can work out the right location to put in the location response message ✨ In this document, that identifier is the IP address of the Device, as seen in the source IP address of the location request message 🦋 Other identifiers are possible, but they're beyond the scope of this document, so we're not going there today 💖
4.1. Device Identifiers, NAT and VPNs 🍓
Using HELD is only as good as the identifier the LIS uses to figure out location 🎀 This document uses the source IP address sent from the Device as that identifier. When Network Address Translation (NAT), a Virtual Private Network (VPN), or other forms of address modification happen between the Device and the LIS, the location that comes back could be inaccurate 😬
Not every NAT ruins the location, though! For example, a NAT in a residential Local Area Network (LAN) is typically not a problem 🏠 The external IP address on the Wide Area Network (WAN) side of that NAT works fine as an identifier for all the Devices in the house on the LAN side, because the area covered is small 🌸
On the other hand, if there's a VPN between the Device and the LIS (say, for a teleworker 💻), then the IP address a LIS inside the enterprise network sees might not be the right one for finding the Device's location 🙈 Section 4.1.2 has recommendations for dealing with this 🫶
4.1.1. Devices and VPNs 🔥
To keep the impact of connections or tunnels set up for security purposes, or for getting through middleboxes, as small as possible, Devices that connect to servers like VPN servers, SOCKS servers, and HTTP proxy servers should perform their HELD query on the LIS before connecting to other servers 💅 It is RECOMMENDED that discovery [RFC5986] and an initial query happen before any connections to other servers are set up 🧚 If a Device does its HELD query after connecting to another server, the Device may get inaccurate location information 😭
Devices that set up VPN connections for other Devices inside a LAN or other closed network could act as a LIS, implementing the HELD protocol, for those other Devices 🦋 The Devices inside the closed network can't necessarily detect the VPN exists 👀 So in this case, a VPN Device should give the address of the LIS server it provides in response to discovery queries, instead of passing those queries through the VPN tunnel 🎀 Otherwise, the other Devices would be totally unaware that they could get inaccurate location information. Yikes 💀
It could also be useful for a VPN Device to serve as a LIS for other location configuration options, like Dynamic Host Configuration Protocol (DHCP) [RFC3825] or Link Layer Discovery Protocol - Media Endpoint Discovery [LLDP-MED] 🌈 In that case, the VPN Device acting as a LIS may first get its own location using HELD ✨
4.1.2. LIS Handling of NATs and VPNs 💜
Here's the situation: the Device connects to the LIS through a VPN or NAT that covers a big geographic area or multiple locations (like a NAT an enterprise uses to connect its private network to the Internet 🏢). In that case the LIS might not be able to return accurate LI 😵 If the LIS can't determine LI for the Device, it should send an error response back to the requesting Device 🚫 The LIS also needs to be configured to recognize identifiers that represent these conditions 🧠
LIS operators play a huge role in making the environment as good as it can be for location determination 👑 The LIS operator needs to make sure the LIS is properly configured with identifiers that indicate Devices on the remote side of a NAT or VPN 🔧 And to serve those Devices, a LIS needs a presence on the side of the NAT or VPN closest to the Device 🌸
4.2. Location by Value 🎀
When a Device needs LI directly, it can ask the LIS to create a PIDF-LO document 💖 This works really well when the Device just uses the PIDF-LO document it gets back, no extra steps 🦋 The details on what information can go in the PIDF-LO MUST follow the subset of rules about building the "location-info" element from the PIDF-LO Usage Clarification, Considerations, and Recommendations document [RFC5491]. More detail is in "Protocol Parameters" (Section 6) 🧚
4.3. Location by Reference 🌸
Asking for location directly doesn't always meet an application's needs 🤷♀️ So a Device can ask for a Location URI instead of a literal location 🔗 A Location URI is a URI [RFC3986] of any scheme that a Location Recipient (LR) can use to retrieve LI 💜 A Location URI provided by a LIS can be assumed to be globally addressable, meaning anyone who has the URI can reach the LIS 🌍
BUT (and this is a big but) having the URI does not mean the LIS will just reveal the location tied to it to anyone who asks 🙅♀️ The specific requirements for dereferencing the location are in [RFC5808]. The location dereference protocol details are out of scope here 🫶 So a lot of the requirements in [RFC5808] (like canceling location references) aren't meant to be supported by this spec. Future specs might tackle them, and that's anticipated 🔮 iykyk 💅
5. Protocol Description ✨
Okay so, like we covered in Section 4, HELD is how a Device gets its location from a LIS 🗺️💖 It can come back as a PIDF-LO document and/or Location URI(s). There are three messages for this: locationRequest, locationResponse, and error 💅
A Location Request (locationRequest) message is described in Section 5.1. The Device uses it to say whether it wants location as a PIDF-LO document (with specific type(s) of location), as Location URI(s), or both 🎀 If things go well, the LIS sends back a locationResponse with a PIDF-LO document and/or one or more Location URIs ✨ If something goes wrong, the LIS sends an error message instead 🙈
The HELD protocol messages are XML documents that MUST be encoded in UTF-8 🌸 There's a MIME type, application/held+xml, registered in Section 11.3 so HELD messages can be told apart from other XML bodies. This spec follows the recommendations and conventions in [RFC3023], including the +xml suffix naming and how the charset parameter gets used. The charset parameter MUST be included with the XML document, no exceptions 🫶
Section 6 has the deep dive on protocol parameters, valid values, and how to handle each one 🧚 Section 7 has the exact structure of the messages, written as an XML Schema [W3C.REC-xmlschema-1-20041028] 💜 And Section 8 covers how HTTP [RFC2616], TLS [RFC5246], and TCP [RFC0793] work together to carry the HELD messages 🚀
5.1. Location Request
A location request message goes from the Device to the LIS whenever the Device needs its own LI 📍 The kind of LI the Device wants is set by whatever's inside the locationType element 🦋
The request is sent as a document built around a locationRequest element. The LIS uses the source IP address of the location request message as its main source of identity for the requesting Device or target 👑 Other Device identities might show up later through schema extensions, which is the plan anyway 🌈
The LIS MUST ignore any part of a location request message it doesn't understand, except the document element 🙈 If the document element isn't 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 💖 There are some cases where a different type of location info MAY come back instead, and those are covered in Section 6.2 🦋
5.3. Indicating Errors
If the LIS can't provide location info based on the locationRequest it got, it MUST return an error message 😭 The LIS may send an error back for requests asking for any locationType 🫶
An error indication document is made of an error element. That error element MUST include a code attribute that says what kind of error it is 🔥 A set of predefined error codes is listed in Section 6.3 💅
Error responses MAY also include a message attribute with extra info 🌸 That info SHOULD be for diagnostic purposes only, and it MAY be in any language 🌍 If it is in a particular language, that SHOULD be indicated with an xml:lang attribute 🎀
6. Protocol Parameters 🎀
This section goes into detail on the parameters this protocol uses 🧚 Table 1 shows the top-level components and whether each one is mandatory (m) or optional (o) for each message ✨
+----------------+-----------+------------+------------+------------+
| 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 Usage6.1. "responseTime" Parameter ⏱️
The responseTime attribute MAY be included in a location request message 💖 It's a time value that tells the LIS how long the Device is willing to wait for a response, or what the Device needs the location for 🦋
For emergency services, the purpose could be either routing a call to the right Public Safety Answering Point (PSAP), or showing responders where to go 🚨 The values defined for that purpose, emergencyRouting and emergencyDispatch, will probably be shaped by local jurisdictional policies, so the LIS should make them configurable 🫶
The time value in the responseTime attribute is a non-negative integer in milliseconds ⏱️ It's only indicative, though. The LIS is under no obligation to strictly stick to the time limit implied, and enforcing the limit is left up to the requesting Device 💅 The LIS gives the most accurate LI it can work out within that interval for the specific service ✨
The LIS MAY use the responseTime value as an input when picking a location determination method, if more than one method exists 🧠 If the responseTime attribute is absent, the LIS SHOULD return the most precise LI it can determine, and the time interval is implementation dependent 🌈
6.2. "locationType" Parameter 🗺️
The locationType element MAY be included in a location request message 💜 It holds a list of the LI types the Device is asking for. Here's what each possible value means 👑
- any: The LIS SHOULD try to provide LI in every form it has available to it.
- geodetic: The LIS SHOULD return a location by value, as a geodetic location for the Target.
- civic: The LIS SHOULD return a location by value, as 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 🎀 Which types come back also depends on the optional exact attribute. If exact is set to true, the LIS MUST return either the requested location type or an error response 🔥 The exact attribute doesn't apply (it's ignored) for a request for the any location type 🙈 More detail on how exact gets processed is in Section 6.2.1 🧚
When there's a request for specific locationTypes and exact is false, the LIS MAY give back additional location types 🌸 It MAY also give alternative types if a requested location type can't be satisfied 🦋 The should-strength requirements on this parameter for specific location types are there to allow soft-failover 💖 That means a fixed client configuration can prefer one location type without its requests failing when that type isn't available 🫶 For example, a notebook could be set up to get civic addresses, which are usually available at home or work 🏠 But when it's on a wireless modem, the LIS might not be able to give a civic address, so it gives a geodetic one instead 📡
The LIS SHOULD return location information in a form suited for routing and responding to an emergency call in its jurisdiction, specifically by value 🚨 The LIS MAY instead, or also, return a Location URI 🌈 If the locationType element is absent, the value any MUST be assumed as the default ✨ A Location URI from the LIS is a reference to the most current LI available, and it is not a stable reference to a specific location 🫧
It's worth knowing that the protocol doesn't let you ask for just one subset of location types 💅 For example, if a Device prefers just "geodetic" or just "civic", it has to make the request without an exact attribute and include both location types 🎀 In that case, if neither is available, a LIS SHOULD return a locationURI if one is available 🔥
The LIS SHOULD provide the locations in the response in the same order they were listed in the locationType element of the request 👑 The main reason to include specific location types in a request with exact set to false is to get the available locations back in a specific order 🧚 For example, a locationRequest for civic could come back with any of these:
- civic
- civic, geodetic
- civic, locationURI
- civic, geodetic, locationURI
- civic, locationURI, geodetic
- geodetic, locationURI (only if civic is not available)
- locationURI, geodetic (only if civic is not available)
- geodetic (only if civic is not available)
- locationURI (only if civic is not available)
For the example above, if the exact attribute were true, the only possible responses would be a civic location or an error message 💀
6.2.1. "exact" Attribute 🎯
The exact attribute MAY be included in a location request message when the locationType element is included 💖 When exact is set to true, it tells the LIS that the contents of the locationType parameter MUST be strictly followed 🔥 The default value of false lets the LIS return something beyond what was asked for, like a set of Location URIs when only a civic location was requested 🌸
A value of true means the LIS MUST provide a location of the requested type or types, or MUST provide an error 😭 The LIS MUST provide only the requested types 🫶 The LIS MUST handle an exact request that has a locationType element set to any as if the exact attribute were set to false ✨
6.3. "code" Parameter 💅
Okay bestie, every single "error" response MUST contain a response code 🫶. All errors are application-level errors, and they MUST only be provided in successfully processed transport-level responses. Like, if HTTP/HTTPS is the transport, HELD error messages MUST be carried by a 200 OK HTTP/HTTPS response. Yes, even when something goes wrong, the wrapper is still a 200 OK 😭
The value of the response code MUST be an IANA-registered value. These are the tokens this document registers:
requestError: the request was badly formed somehow (but not in the XML content) 🙈xmlError: the XML content of the request was badly formed or invalid 💀generalLisError: something unspecified went wrong at the LIS 🌸locationUnknown: the LIS couldn't figure out where the Device is. The same request can be sent again by the Device later on. Devices MUST limit any attempts to retry requests, so no spamming, bestie 🦋unsupportedMessage: an element in the XML document for the request wasn't supported or understood by the LIS. This one shows up when a HELD request has a document element the receiver doesn't support 🧚timeout: the LIS couldn't get the request done within the time set in the"responseTime"parameter ⏰cannotProvideLiType: the LIS couldn't provide LI of the type or types requested. This is used when the"exact"attribute on the"locationType"parameter is set to"true"🍓notLocatable: the LIS can't locate the Device, and the Device MUST NOT make further attempts to retrieve LI from this LIS. This is the "you're outside the access network this LIS serves" code, like in the VPN and NAT situations from Section 4.1.2 👑
6.4. "message" Parameter ✨
The "error" message MAY include one or more "message" attributes to share some extra, human-readable info about how the request went 🎀. The message MAY be included in any language, and the language 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 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. Not the same thing, babe 🙅♀️
If a "locationUriSet" element is received in a "locationResponse" message, it MUST contain an "expires" attribute. That attribute defines how long the set of "locationURI" elements stays valid ⏳
6.5.1. "locationURI" Parameter 🔐
The "locationURI" element holds a single Location URI. 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 dereferencing protocol details have to meet the location dereference protocol requirements in [RFC5808], and they're outside the scope of this base HELD spec 📚
Each Location URI the LIS allocates is unique to the Device requesting it. When the Location URI shows up in the response, it isn't bound to any specific location type. It's totally independent of whatever type of location it might point to. The specific location type gets decided at dereference time, so it's giving flexibility 💜
A "locationURI" SHOULD NOT contain any information that could be used to identify the Device or Target. So it's RECOMMENDED that the "locationURI" element contain a public address for the LIS and an anonymous identifier, like a local identifier or an unlinked pseudonym 🫣
When a LIS hands a "locationURI" element to a Device, the policy on that "locationURI" is set by the LIS alone. This spec has no mechanism for the HELD client to set access control policies on a "locationURI". And going the other way, this protocol has no mechanism for the LIS to tell the Device what access control policy applies to a "locationURI". Since the Device doesn't know which access controls apply to later dereference requests, the client SHOULD protect a "locationURI" as if it were a Location Object. In other words, the Device SHOULD send a "locationURI" over encrypted channels and only to entities that are authorized to have access to the location 🔒
Main character warning: a Location URI is basically a Location Object in disguise. Protect it like one, bestie. 🚨
Further guidelines to keep the information in the "locationResponse" message private and confidential, including the "locationURI", are 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. It tells you the date and time when the Location URIs from the LIS will expire. It does NOT define how long a location you get by dereferencing the Location URI stays valid, so don't mix those up 🙃 The "expires" attribute is RECOMMENDED not to exceed 24 hours, and it 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 lets you use time zone identifiers for offsets from the zero meridian, but this option MUST NOT be used with HELD. The extended date-time form, with upper case T and Z characters from [W3C.REC-xmlschema-2-20041028], MUST be used to represent date-time values. Strict, but iconic 💅
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. Expired means expired, babe 💀
6.6. "Presence" Parameter (PIDF-LO) 🧚
A single "presence" parameter MAY be included in the "locationResponse" message when specific locationTypes (like "geodetic" or "civic") are requested, or when a "locationType" of "any" is requested. The LIS MUST follow the subset of the rules about constructing the "location-info" element in the PIDF-LO Usage Clarification, Considerations, and Recommendations document [RFC5491] when it generates the PIDF-LO for the presence parameter 🎀
The LIS MUST NOT include any means of identifying the Device in the PIDF-LO, unless it can verify that the identifier is correct and a Rule Maker has expressly permitted including identity. So any PIDF parameters that contain identity are either left out 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 like the "contact" and "deviceID" elements [RFC4479] are not used 🫶
Heads up: the presence parameter isn't explicitly shown in the XML schema in Section 7 for a location response message. That's because of XML schema constraints, since PIDF is already defined and registered separately. So the "##other" namespace is just a placeholder for the presence parameter in the schema 🌸
7. XML Schema 💅
okay so this bit is the actual XML Schema Definition for the application/held+xml format, and it's giving "official spec, no cap" 🎀 [W3C.REC-xmlschema-1-20041028] [W3C.REC-xmlschema-2-20041028] 🌸 It's presented as the formal definition of the format, so implementers should treat it as the real thing ✨ Heads up: it's not meant for on-the-fly validation of the presence XML document, so don't try that bestie 🙈 The whitespace got added so the lines fit the RFC line length limits without hurting readability, and any conforming processor should remove leading and trailing white spaces 🫶
<?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>
<!-- 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>
<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>
<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 🦋
okay this section is where HELD gets its ride, bestie 🚗 It describes using HTTP [RFC2616] and HTTP over TLS [RFC2818] as the transport mechanisms for HELD, and a conforming LIS and Device MUST support both 💖
Here's the tea: HELD uses HTTP, but only a strict subset of its features 🍓 Because some features are restricted, a LIS is not a fully compliant HTTP server, and that's intentional! The idea is that a LIS can be built easily on an HTTP server with extensibility mechanisms, and a HELD Device can trivially use existing HTTP libraries 🧚 Keeping the subset small helps implementors avoid ambiguity with all the options full HTTP offers. Iconic. 👑
A conforming Device MAY choose not to support HTTP authentication [RFC2617] or cookies [RFC2965] 🌈 The Device and the LIS might not have a prior relationship, so the LIS SHOULD NOT require a Device to authenticate, whether with those HTTP authentication methods or with TLS client authentication. Unless every Device that accesses a LIS can be expected to authenticate in a certain fashion, denying access to location information could stop a Device from using location-dependent services, like emergency calling 😭 Future extensions might add request parameters that a LIS could 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 🎀
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 doesn't receive the right Content-Type and Accept header fields, the LIS SHOULD fail the request and return 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 is used. If the LIS gets 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 POST, a GET or HEAD MUST be either an escaped URL (like somebody who found a URL in protocol traces or log files and pasted it into their browser) or somebody doing testing or debugging 🕵️ The LIS could put information in the HELD response saying the URL belongs to a LIS that only responds to HELD POST requests. Or the LIS could avoid leaking info by returning a super generic HTTP error like 404 (not found) 🙈
The LIS populates the HTTP headers of responses so they match 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's a risk of stale locations and/or unauthorized disclosure of the LI, which is a whole mess 💀 This also lets the LIS 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 the server provides 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 the 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 🦋
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 one 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, so "f*.example.com" is not a valid name and doesn't match any domain name 🙃
The Device uses the URI it got during LIS discovery to authenticate the server 💖 The details of this authentication method are 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 🔐
okay bestie, this is the serious part, so let's be real for a sec 🫶 HELD is a location acquisition protocol, which means the client asks its LIS for its own location. The specific requirements and security considerations for location acquisition protocols live in [RFC5687]. For a deep dive on Location URIs and the by-reference provision of LI, check out [RFC5808].
When you use HELD, the client and the LIS are exposed to two kinds of risk:
Accuracy: The client receives incorrect location information.
Privacy: An unauthorized entity receives location information.
Getting an accurate, privacy- and confidentiality-protected location to the requestor depends on five steps all going right 💅
- The client must determine the proper LIS.
- The client must connect to the proper LIS.
- The LIS must be able to identify the Device by its identifier (IP address).
- The LIS must be able to return the desired location.
- HELD messages must be transmitted unmodified between the LIS and the client.
Only steps 2, 3, and 5 are in scope for this document ✨ Step 1 is based on either manual configuration or on the LIS discovery defined in [RFC5986], which already talks about its own security considerations. Step 4 depends on the specific positioning capabilities of the LIS, so it's 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, which 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 to the client, either as a domain name or as an IP address, by presenting a certificate that contains that identifier as a subjectAltName (that is, as an iPAddress or dNSName, respectively). For the HTTP binding described above, this is exactly the authentication described by TLS [RFC2818] 🦋
If the client has external information about the expected identity or credentials of the proper LIS (for example, 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. Also, note that 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
To stop the response from being modified en route, messages must be transmitted over an integrity-protected channel 🛡️ When the transaction is conducted over TLS (a required feature per Section 9.1), the channel is integrity protected by appropriate ciphersuites. When TLS is not used, this protection varies 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. On the flip side, in most cases, when not conducted over TLS, the response will be accessible while en route from the LIS to the requestor 💀
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. 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, so 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. Also, if a Device drops off the network for various reasons, re-using 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:
- 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.
- 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 depend 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 🎀
10. Examples 🍓
The following sections give 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 the important bits of messages, the examples in Sections 10.2 and 10.3 do not show HTTP/HTTPS headers or the XML prologue. Sections of XML that aren't relevant to the example are replaced with comments too 🧚
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">
<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 below doesn't specify any location types or response time, so it's giving minimal vibes 🦋
<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
</locationURI>
</locationUriSet>
</locationResponse>An error response to this location request looks like this:
<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
okay bestie, this is the combo example 🎀✨ one request asking for geodetic, civic, and any Location URIs all at once. so iconic 💅
<locationRequest xmlns="urn:ietf:params:xml:ns:geopriv:held">
<locationType exact="true">
geodetic
civic
locationURI
</locationType>
</locationRequest>the matching Location Response hands back the requested location info, and that includes two Location URIs 🦋 it's giving generous 😭
<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>
<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. this is the paperwork part, but it's still kind of a vibe 📋
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, following 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).
the XML content for the registration is below 💖
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>
END11.2. XML Schema Registration
this section registers an XML schema following 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 is the entirety of Section 7 of this document. go look at Section 7 if you want the full schema, it's all there ✨
11.3. MIME Media Type Registration for 'application/held+xml'
this section registers the application/held+xml MIME type. this one's a whole form, so here it is in full 💅
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.
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.the security bit is the important bit: this content can carry location info that might be private, so precautions should be taken to limit who sees it 🔒😭
11.4. Error Code Registry
okay so IANA made a brand new registry for the HELD protocol, and it includes an initial set of error codes 🚨 these codes show up in HELD error messages as described in Section 6.3, and they're defined by the codeType token in the XML schema in Section 7. 💜
here's the summary of the registry:
- Related Registry: Geopriv HELD Registries, Error codes for HELD
- Defining RFC: RFC 5985
- Registration/Assignment Procedures: following the policies in [RFC5226], the IANA policy for assigning new 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. let's meet them 🥹
requestError: this code means the request was badly formed in some fashion. 🙈xmlError: this code means the XML content of the request was either badly formed or invalid. 💀generalLisError: this code means an unspecified error occurred at the LIS. 🌈locationUnknown: this code means the LIS could not determine the location of the Device. 🫶unsupportedMessage: this code means the request was not supported or understood by the LIS. this one gets used when a HELD request contains a document element that the receiver doesn't support. 🔥timeout: this code means the LIS could not satisfy the request within the time specified in theresponseTimeparameter. ⭐cannotProvideLiType: this code means the LIS was unable to provide LI of the type or types requested. this one gets used when theexactattribute on thelocationTypeparameter is set totrue. 🍓notLocatable: this code means the LIS is unable to locate the Device, and the Device MUST NOT make further attempts to retrieve LI from this LIS. this one signals 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. 🚫🦋
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 info is below. they also made additional contributions to the WG document, including the XML schema. so grateful 🥹💖
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.com13. 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, 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. everyone on this list is a legend 🌈👑
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>.
[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. 💅
[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. 🫶
Appendix A. HELD Compliance to IETF LCP Requirements 🌈
This appendix is the big checklist moment, bestie. It describes how HELD stacks up against the requirements 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 ✅
Okay so HELD uses the IP address of the location request message as the main source of identity for the requesting Device or target. 🦋 That identity can be paired with other contextual network information to give a physical location for the Target in lots of network deployments. There may be deployments where an IP address alone isn't enough to identify a Target in a network. However, any identity extensions those networks need are 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 basically a characteristic of the access network technology, and HELD is designed to be access network agnostic, so it's giving compliance. 💜 On top of that, HELD gives mobile environments extra help with an optional responseTime attribute in location request messages. Wireless networks often have several ways to figure out position (for example, assisted GPS versus working out the location from the identity of the serving base station). Each one has different accuracy and takes a different amount of time to give a result. The responseTime parameter gives the LIS a criterion it can use to pick a location determination technique. ⭐
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 HELD context, the LIS sits within the Access Network. So HELD doesn't depend on any business or trust relationship between the Application Service Provider (ASP) and the Access Network Provider. 🫶 Location acquisition using HELD is still 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 built with exactly this model in mind, and it can chain requests between operators without needing any protocol change. 🔗 HELD is a webservices protocol that can be bound to transports other than HTTP, such as BEEP. BEEP gives you high request throughput over a dedicated connection between an L3 provider and an L2 provider, without the serial restriction HTTP imposes. That's way harder to pull off with protocols that don't 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."
COMPLY ✅
HELD is an application protocol that runs on top of IP. A HELD request from a host behind a residential NAT goes through the NAT and picks up the external address of the home router. So in this case, the location given to the host will be the address of the home router. 🏡 No changes are needed on the home router to support this, because HELD was designed specifically for 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 doesn't stop a LIS on the far end of a VPN tunnel from knowing that the client's request is coming over that tunnel. 🦋 It also doesn't stop a client Device from reaching a LIS that serves the local physical network and then using that location information with an application 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 using TLS with server-side certificates for communication between the endpoint and the LIS. 🔐 There's 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."
COMPLY ✅
HELD makes no assumption about the network topology. 🌐 HELD doesn't require the Device to know its external IP address, except where that's needed to discover 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 ✅
The HELD protocol overview (Section 4) describes the requirements on the LIS when it creates the PIDF-LO, and it spells out that the PIDF-LO generated by the LIS MUST conform to [RFC5491]. 👑 Periodt. 💅
Author's Address 🖋️
Mary Barnes (editor)
Polycom
EMail: mary.ietf.barnes@gmail.com📦 where this page comes from
- ietf: rfc5985 2010-09
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms