idnits 2.17.1
draft-winterbottom-http-location-delivery-04.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
** It looks like you're using RFC 3978 boilerplate. You should update this
to the boilerplate described in the IETF Trust License Policy document
(see https://trustee.ietf.org/license-info), which is required now.
-- Found old boilerplate from RFC 3978, Section 5.1 on line 17.
-- Found old boilerplate from RFC 3978, Section 5.5 on line 2287.
-- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2298.
-- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2305.
-- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2311.
** This document has an original RFC 3978 Section 5.4 Copyright Line,
instead of the newer IETF Trust Copyright according to RFC 4748.
** This document has an original RFC 3978 Section 5.5 Disclaimer, instead
of the newer disclaimer which includes the IETF Trust according to RFC
4748.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the RFC 3978 Section 5.4 Copyright Line does not
match the current year
== Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD',
or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please
use uppercase 'NOT' together with RFC 2119 keywords (if that is what you
mean).
Found 'MUST not' in this paragraph:
200 (Success): This code indicates that the request was
successful. This code MUST not be used for an error response.
-- The document seems to lack a disclaimer for pre-RFC5378 work, but may
have content which was first submitted before 10 November 2008. If you
have contacted all the original authors and they are all willing to grant
the BCP78 rights to the IETF Trust, then this is fine, and you can ignore
this comment. If not, you may need to add the pre-RFC5378 disclaimer.
(See the Legal Provisions document at
https://trustee.ietf.org/license-info for more information.)
-- The document date (October 23, 2006) is 6393 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Missing Reference: '0-5' is mentioned on line 1317, but not defined
== Missing Reference: '0-9' is mentioned on line 1317, but not defined
** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346)
** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231,
RFC 7232, RFC 7233, RFC 7234, RFC 7235)
** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110)
** Downref: Normative reference to an Informational RFC: RFC 3693
== Outdated reference: A later version (-07) exists of
draft-ietf-geopriv-revised-civic-lo-04
== Outdated reference: A later version (-14) exists of
draft-ietf-geopriv-pdif-lo-profile-04
-- Obsolete informational reference (is this intentional?): RFC 793
(Obsoleted by RFC 9293)
-- Obsolete informational reference (is this intentional?): RFC 2222
(Obsoleted by RFC 4422, RFC 4752)
-- Obsolete informational reference (is this intentional?): RFC 3023
(Obsoleted by RFC 7303)
Summary: 7 errors (**), 0 flaws (~~), 6 warnings (==), 10 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 GEOPRIV WG J. Winterbottom
3 Internet-Draft M. Thomson
4 Intended status: Standards Track Andrew
5 Expires: April 26, 2007 B. Stark
6 BellSouth
7 October 23, 2006
9 HTTP Enabled Location Delivery (HELD)
10 draft-winterbottom-http-location-delivery-04.txt
12 Status of this Memo
14 By submitting this Internet-Draft, each author represents that any
15 applicable patent or other IPR claims of which he or she is aware
16 have been or will be disclosed, and any of which he or she becomes
17 aware will be disclosed, in accordance with Section 6 of BCP 79.
19 Internet-Drafts are working documents of the Internet Engineering
20 Task Force (IETF), its areas, and its working groups. Note that
21 other groups may also distribute working documents as Internet-
22 Drafts.
24 Internet-Drafts are draft documents valid for a maximum of six months
25 and may be updated, replaced, or obsoleted by other documents at any
26 time. It is inappropriate to use Internet-Drafts as reference
27 material or to cite them other than as "work in progress."
29 The list of current Internet-Drafts can be accessed at
30 http://www.ietf.org/ietf/1id-abstracts.txt.
32 The list of Internet-Draft Shadow Directories can be accessed at
33 http://www.ietf.org/shadow.html.
35 This Internet-Draft will expire on April 26, 2007.
37 Copyright Notice
39 Copyright (C) The Internet Society (2006).
41 Abstract
43 A Geopriv using protocol is described that is used for retrieving
44 location information from a server within an access network. The
45 protocol includes options for retrieving location information either
46 by-value or by-reference. The protocol supports mobile and nomadic
47 devices through Location URIs. The protocol is an application-layer
48 protocol that is independent of session-layer; an HTTP, web services
49 binding is specified.
51 Table of Contents
53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
54 1.1. Exclusions . . . . . . . . . . . . . . . . . . . . . . . . 4
55 1.2. Device or Target . . . . . . . . . . . . . . . . . . . . . 5
56 1.3. The Bigger Picture . . . . . . . . . . . . . . . . . . . . 5
57 2. Conventions used in this document . . . . . . . . . . . . . . 7
58 2.1. GEOPRIV Terminology . . . . . . . . . . . . . . . . . . . 7
59 3. HELD Overview . . . . . . . . . . . . . . . . . . . . . . . . 9
60 3.1. Requesting Location Information Directly . . . . . . . . . 9
61 3.1.1. Shaping the PIDF-LO . . . . . . . . . . . . . . . . . 10
62 3.2. Requesting a Location URI . . . . . . . . . . . . . . . . 10
63 3.2.1. Establishing a Location Server Context . . . . . . . . 11
64 4. Protocol Description . . . . . . . . . . . . . . . . . . . . . 13
65 4.1. Protocol Binding . . . . . . . . . . . . . . . . . . . . . 14
66 4.2. Location Request . . . . . . . . . . . . . . . . . . . . . 14
67 4.3. Contexts . . . . . . . . . . . . . . . . . . . . . . . . . 15
68 4.3.1. Creating Contexts . . . . . . . . . . . . . . . . . . 15
69 4.3.2. Updating Contexts . . . . . . . . . . . . . . . . . . 16
70 4.3.3. Terminating Contexts . . . . . . . . . . . . . . . . . 16
71 4.4. Combined Context and Location Requests . . . . . . . . . . 17
72 4.5. Indicating Errors . . . . . . . . . . . . . . . . . . . . 17
73 5. Protocol Parameters . . . . . . . . . . . . . . . . . . . . . 18
74 5.1. "responseTime" Parameter . . . . . . . . . . . . . . . . . 19
75 5.2. "assert" Parameter . . . . . . . . . . . . . . . . . . . . 19
76 5.2.1. "method" Parameter . . . . . . . . . . . . . . . . . . 19
77 5.2.2. "timestamp" Parameter . . . . . . . . . . . . . . . . 19
78 5.2.3. "expires" Parameter . . . . . . . . . . . . . . . . . 20
79 5.2.4. "exact" Parameter . . . . . . . . . . . . . . . . . . 20
80 5.3. "locationType" Parameter . . . . . . . . . . . . . . . . . 20
81 5.3.1. "exact" Parameter . . . . . . . . . . . . . . . . . . 21
82 5.4. "profile" Parameter . . . . . . . . . . . . . . . . . . . 21
83 5.4.1. "presentity" Parameter . . . . . . . . . . . . . . . . 22
84 5.4.2. "retentionExpiry" Parameter . . . . . . . . . . . . . 22
85 5.4.3. "retentionInterval" Parameter . . . . . . . . . . . . 22
86 5.4.4. "retransmission" Parameter . . . . . . . . . . . . . . 23
87 5.4.5. "rulesetURI" Parameter . . . . . . . . . . . . . . . . 23
89 5.5. "signed" Parameter . . . . . . . . . . . . . . . . . . . . 23
90 5.6. "lifetime" Parameter . . . . . . . . . . . . . . . . . . . 23
91 5.7. "rules" Parameter . . . . . . . . . . . . . . . . . . . . 23
92 5.7.1. "rulesetURI" Parameter . . . . . . . . . . . . . . . . 24
93 5.7.2. Common Policy "ruleset" Parameter . . . . . . . . . . 24
94 5.8. "code" Parameter . . . . . . . . . . . . . . . . . . . . . 24
95 5.9. "message" Parameter . . . . . . . . . . . . . . . . . . . 26
96 5.10. "context" Parameter . . . . . . . . . . . . . . . . . . . 26
97 5.10.1. "locationURI" Parameter . . . . . . . . . . . . . . . 26
98 5.10.2. "password" Parameter . . . . . . . . . . . . . . . . . 26
99 5.10.3. "expires" Parameter . . . . . . . . . . . . . . . . . 27
100 5.11. "location" Parameter . . . . . . . . . . . . . . . . . . . 27
101 6. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . . 28
102 7. HTTP Binding . . . . . . . . . . . . . . . . . . . . . . . . . 34
103 7.1. HTTP Binding WSDL . . . . . . . . . . . . . . . . . . . . 34
104 8. Security Considerations . . . . . . . . . . . . . . . . . . . 37
105 8.1. Return Routability . . . . . . . . . . . . . . . . . . . . 37
106 8.2. Transaction Layer Security . . . . . . . . . . . . . . . . 38
107 8.3. Veracity of Asserted LI . . . . . . . . . . . . . . . . . 38
108 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
109 9.1. Simple HTTP Binding Example Messages . . . . . . . . . . . 39
110 9.2. Location Request Examples . . . . . . . . . . . . . . . . 41
111 9.3. Context Creation and Update Examples . . . . . . . . . . . 43
112 9.4. Sample LG WSDL Document . . . . . . . . . . . . . . . . . 47
113 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
114 10.1. IANA Registry for HELD Result Codes . . . . . . . . . . . 48
115 10.2. URN Sub-Namespace Registration for
116 urn:ietf:params:xml:ns:geopriv:held . . . . . . . . . . . 48
117 10.3. XML Schema Registration . . . . . . . . . . . . . . . . . 49
118 10.4. URN Sub-Namespace Registration for
119 urn:ietf:params:xml:ns:geopriv:held:http . . . . . . . . . 49
120 10.5. MIME Media Type Registration for 'application/held+xml' . 50
121 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 52
122 11.1. Normative References . . . . . . . . . . . . . . . . . . . 52
123 11.2. Informative References . . . . . . . . . . . . . . . . . . 53
124 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 55
125 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 56
126 Intellectual Property and Copyright Statements . . . . . . . . . . 57
128 1. Introduction
130 The location of a Device is information that is useful for a number
131 of applications. A Device might be able to determine this
132 information using its own resources, but more often than not, the
133 Device must rely on its access network to provide this information.
134 This document describes a protocol that can be used to acquire
135 Location Information (LI) from a service within an access network.
137 This specification identifies two methods for acquiring LI. Location
138 may be retrieved from a Location Generator (LG) by-value, that is,
139 the Device may acquire LI directly. Alternatively, the Device may
140 request that the LG provide a location URI so that LI can be
141 distributed by-reference. Both of these methods are compatible, and
142 both can be provided concurrently from the same LG so that
143 application needs can be addressed individually.
145 This specification defines an XML-based protocol that enables the
146 retrieval of LI from a LG. This protocol can be bound to any
147 session-layer protocol, particularly those capable of MIME transport;
148 an HTTP binding is included as a minimum requirement.
150 1.1. Exclusions
152 This document defines a protocol for configuration purposes; that is,
153 a protocol for requesting (and receiving) the information necessary
154 to use LI. This document does not define a Geopriv Using Protocol.
155 The LG is assumed to be present within the same administrative domain
156 as the Device (the access network), which limits the security threats
157 that this protocol is exposed to.
159 This document does not specify how LI is derived. Determination of
160 the physical location of a network termination point is dependent on
161 the type of access network and the capabilities of networking
162 equipment. The specific methods that could be used are innumerable,
163 therefore this is left to individual network and equipment
164 implementations.
166 Providing LI by-reference implies that a server is able to provide
167 the Device with a public, globally-routable URI. How this URI is
168 provided is not covered by this specification. This includes any
169 interactions between the LG and LS necessary to facilitate the
170 provision of a Location URI.
172 This document does not define how an LG is discovered or configured.
173 Service discovery techniques are described in two separate documents,
174 [I-D.winterbottom-geopriv-held-dhcp-discovery] describing a DHCP
175 discovery mechansim, and [I-D.thomson-geopriv-held-unaptr] describing
176 a DNS lookup mechanism.
178 1.2. Device or Target
180 LI provided for the Device is often represented as the location of a
181 user. However, in this document LI is attributed to a Device and not
182 a person. Primarily, this is because location determination
183 technologies are generally designed to locate a Device and not a
184 person. In addition to this, unless the Device requires active user
185 authentication, there is no guarantee that any particular individual
186 is using the Device at that instant. Thus, if any claim of veracity
187 is to be made for LI, the distinction between Target and Device must
188 be made explicit.
190 This distinction should not lead to the impression that the location
191 of the Device does not impact the privacy constraints required by
192 this protocol. Revealing the location of the Device almost
193 invariably reveals some information about the location of the user of
194 the Device, therefore the same level of privacy protection demanded
195 by a user is required for the Device.
197 It is expected that, for most applications, this distinction will be
198 unnecessary: LI for the Device will be used as an adequate substitute
199 for the user's LI. This requires either some additional assurances
200 about the link between Device and Target, or an acceptance of the
201 aforementioned limitations.
203 This document assumes that the Device is responsible for the protocol
204 interactions described and that it does so with the authority of the
205 Target and Rule Maker (RM).
207 1.3. The Bigger Picture
209 This document describes an interface between a Device and a Location
210 Generator (LG). Detailing the interactions between these two
211 entities requires a wider understanding of other interested parties.
213 For the Device, the most important consideration is the Target. In
214 some cases, this is the same as the Device, but it is more likely to
215 be a human user. The foundation of this protocol is that the Target
216 is able to direct the dissemination of LI, that is, the Target
217 provides authorization policies and otherwise controls how LI is
218 granted to Location Recipients (LRs). This extends to when a
219 Location Server (LS) is employed to provide a Location URI; the LS
220 cannot provide LI to an LR without express permission from the
221 Target.
223 The LG exists as an access network service. An Access Provider (AP)
224 operates this service so that Devices (and Targets) can retrieve LI.
225 The LG exists because not all Devices are capable of determining LI,
226 and because, even if a Device is able to determine its own LI, it may
227 be more efficient with assistance.
229 The following diagram shows one possible configuration of the roles
230 identified in [RFC3693] and where this protocol applies.
232 +-----------+ +-----------+
233 | Location | | Location |
234 | Generator | - - - - | Server |
235 | | | |
236 +-----------+ +-----------+
237 | |
238 HELD |
239 | |
240 Rule Maker - _ +-----------+ +-----------+
241 o - - | Device | | Location |
242 | (Target) |----Object--->| Recipient |
346 | | | (LS, RH) | | |
347 +-----------+ +----------+ +-----------+
349 Figure 2: Simple Location Request Model
351 In this model, the Device in this scenario acts as a Location Server
352 (LS) and Rule Holder (RH); it is responsible for making authorization
353 decisions about which Location Recipients are given LOs.
355 The LG needs to uniquely identify the Device within the access
356 network. The source address of the request message is sufficient in
357 most cases. Once the Device is identified, the LG uses network
358 domain-specific information to determine the location of the Device.
360 An LI request does not need to include any identification information
361 other than return addressing. In fact, the HTTP binding (Section 7)
362 includes the option for a GET request. Return routability also
363 addresses a number of security concerns, see Section 8.
365 The response from the LG is a PIDF-LO document [RFC4119], unless
366 there were errors in processing the request.
368 The interface between Device (acting as LS) and Location Recipient
369 (LR) is application-specific and outside the scope of this
370 specification.
372 3.1.1. Shaping the PIDF-LO
374 A Device can include additional information in an LI request that
375 controls how the LG populates the fields in a PIDF-LO document.
376 Related to privacy, a presentity URI and usage rules can be
377 specified. The Device can also include a location estimate, or
378 request a specific type of location information, including a request
379 for a signed PIDF-LO.
381 When requesting LI, the Device can include a presentity URI for the
382 Target and a ruleset reference. The LG incorporates this information
383 in the PIDF-LO document, or modifies the document accordingly.
385 LI contained within a PIDF-LO document can be either geodetic
386 (coordinates using latitude and longitude or some other coordinate
387 system) or civic (street or postal addresses). The Device can
388 request that the LG provide a specific type of LI, including whether
389 a jurisdictional or postal civic address is required.
391 If a Device is capable of providing its own location it can include
392 this in a request. The LG is then able to include this LI in the
393 returned PIDF-LO. The type of LI is inferred from the request when
394 LI is provided.
396 The PIDF-LO document generated by an LG MUST follow the rules in
397 [I-D.ietf-geopriv-pdif-lo-profile]. The LI sent in a request MUST
398 follow the subset of those rules relating to the construction of the
399 "location-info" element.
401 3.2. Requesting a Location URI
403 Requesting LI directly does not always address the requirements of an
404 application. A Location URI is a URI [RFC3986] of any scheme, which
405 a Location Recipient (LR) can use to retrieve LI. A Device can
406 request a Location URI instead of LI.
408 Figure 3 illustrates how this usage of HELD fits within the model
409 presented in [RFC3693]. The first aspect of the diagram shows how
410 the Device acts as an agent for the Target and retrieves a Location
411 URI, which it then provides to the Location Recipient. The second
412 aspect has the Device acting as an agent for the Rule Maker; the
413 Device forwards rules to the LG, which forwards them to the LS.
415 +-----------+ Location +--------------+
416 | Location |------URI------>| Device |
417 | Generator | | (Target) |
418 | |<-----Rules-----| (Rule Maker) |
419 +-----------+ +--------------+
420 | |
421 LO & Rules Location URI
422 | |
423 V V
424 +----------+ +------------+
425 | Location | Location | Location |
426 | Server |------Object----->| Recipient |
427 | | | |
428 +----------+ +------------+
430 Figure 3: Location URI Usage Model
432 Note that the Location Server takes the role of a (Private) Rule
433 Holder when the rules are provided by-value. The rules may also be
434 provided to the LG and LS by-reference, in which case, a Public Rule
435 Holder is required; the Public Rule Holder is not shown in this
436 diagram.
438 The interface between Device (acting as LS) and Location Recipient
439 (LR) is application-specific and outside the scope of this
440 specification. Also, any interface between Device (acting as RM) and
441 a Public Rule Holder is not relevant to this specification.
443 The merits and drawbacks of using a Location URI approach are
444 discussed in [I-D.winterbottom-location-uri].
446 3.2.1. Establishing a Location Server Context
448 A Location URI is allocated for a Device by the LS. If the LS is to
449 be able to service queries for location directed at the Location URI,
450 it must maintain certain information. When the LG receives a request
451 for a Location URI, it requests that the LS allocate a URI for a
452 particular Device. As a part of providing a Location URI, the LS
453 also creates a _context_, which contains the information that it
454 requires to properly service requests to the URI.
456 This document does not make any normative statements about the
457 interface between the LG and LS. Any assumptions that are made about
458 the nature of this interface are stated where necessary.
460 A context contains sufficient information for the LS to identify the
461 Device to the LG, so that LI can be generated as required, which
462 could be on a per-request basis. The context also includes
463 instructions from the Device on how the PIDF-LO is to be generated,
464 as described in Section 3.1.1.
466 The context contains an authorization policy that describes to whom,
467 and how, LI is granted. This is a common-policy document
468 [I-D.ietf-geopriv-common-policy] that is provided by the Device in
469 the context creation request, either directly, or by reference.
471 4. Protocol Description
473 As discussed in Section 3, this protocol provides two basic
474 functions: LI request and Location URI request. Messages are defined
475 as XML documents.
477 The Location Request message is described in Section 4.2. A Location
478 Request from a Device results in a PIDF-LO document in case of
479 success, or an error message.
481 In requesting a Location URI, the Device requests that a context be
482 created on the LS. The parameters for the create context request are
483 described in Section 4.3.1. The response to a context creation
484 request includes Location URIs and a password that can be used to
485 update the information contained in the context. The details stored
486 by the LS can be updated at any time after creation using the update
487 context request, described in Section 4.3.2.
489 Table 1 shows the basic set of messages supported by this protocol
490 and their respective responses, successful or otherwise.
492 +------------+------------------+-------------------+---------------+
493 | Operation | Request Message | Successful | Error |
494 | | | Response | Response |
495 +------------+------------------+-------------------+---------------+
496 | Request | locationRequest | PIDF-LO document | error |
497 | Location | (Section 4.2) | [RFC4119] | (Section 4.5) |
498 | | | | |
499 | Create | createContext | contextResponse | error |
500 | Context | (Section 4.3.1) | | (Section 4.5) |
501 | | | | |
502 | Update | updateContext | contextResponse | error |
503 | Context | (Section 4.3.2) | | (Section 4.5) |
504 +------------+------------------+-------------------+---------------+
506 Table 1: HELD Operations
508 A MIME type "application/held+xml" is registered in Section 10.5 to
509 distinguish HELD messages from other XML document bodies. This
510 specification follows the recommendations and conventions described
511 in [RFC3023], including the naming convention of the type ('+xml'
512 suffix) and the usage of the 'charset' parameter.
514 Section 5 contains a more thorough description of the protocol
515 parameters, valid values, and how each should be handled. Section 6
516 contains a more specific definition of the structure of these
517 messages in the form of an XML Schema [W3C.REC-xmlschema-1-20041028].
519 4.1. Protocol Binding
521 The HELD protocol is an application-layer protocol that is defined
522 independently of any lower layers. This means that any protocol can
523 be used to transport this protocol providing that it can provide a
524 few basic features:
526 o The protocol must have acknowledged delivery.
528 o The protocol must be able to correlate a response with a request.
530 o The protocol must provide authentication, privacy and protection
531 against modification.
533 Candidate protocols that could be used to address these purposes
534 include: TCP [RFC0793], TLS [RFC2246], SASL [RFC2222], HTTP
535 [RFC2616], SIP [RFC3261], BEEP [RFC3080] and SOAP
536 [W3C.REC-soap12-part1-20030624] [W3C.REC-soap12-part2-20030624].
537 This document includes a binding that uses a combination of HTTP, TLS
538 and TCP in Section 7.
540 4.2. Location Request
542 A location request is sent from the Device to the LG when it requires
543 LI. This request can be very simple, including no parameters; in
544 fact, the HTTP binding includes a GET request that does not include a
545 message body.
547 A Device MAY make an assertion about its own location as part of a
548 location request. Devices that have some means of acquiring LI,
549 either from embedded technology like Global Positioning System (GPS)
550 receivers or from user input, can use this to convey that information
551 to the LG. The "assert" element can be used to convey this
552 information.
554 The type of LI that a Device requests is determined by the type of LI
555 that is included in the "assert" element. When asserted LI is not
556 provided, the Device MAY specify the type of location requested using
557 the "locationType" element.
559 LI provided by the Device is potentially more precise than that
560 provided by the LG, therefore the LG MAY use this information to
561 create a response. The LG SHOULD validate the LI provided for
562 accuracy and precision before using this information.
564 The Device MAY specify a "profile" element that instructs the LG on
565 how to construct the LO. Alternatively, if the Device has created a
566 profile in an LS context, the Device can provide a "context" element
567 so that the LG can retrieve the profile from the LS.
569 The location request is made by sending a document formed of a
570 "locationRequest" element. The successful response to a location
571 request is a PIDF-LO document, unless the request fails, in which
572 case the LG SHOULD provide an error indication document.
574 4.3. Contexts
576 A context is established by the LS in order to provide a Location
577 URI. The context includes information necessary to identify the
578 Device and determine its location when an LR requests an LO using the
579 Location URI.
581 4.3.1. Creating Contexts
583 The Device uses the "createContext" message to request that the LG,
584 and the LS, assign a Location URI. This establishes a context at the
585 LS.
587 The LS MUST maintain the information provided in the create context
588 request. The create context request includes a time limit, which
589 sets the maximum time that this context can be maintained.
591 The response to a create context request contains information that
592 the Device can use to identify a context. A set of Location URIs are
593 included, each one MUST uniquely identify the context; that is, the
594 LS MUST be able to identify a context based on a single Location URI.
595 A Device can distribute a Location URI to an LR to allow it retrieve
596 LI from the LS.
598 A Location URI MUST NOT contain any information that could be used to
599 identify the Device or Target. It is RECOMMENDED that a Location URI
600 contain a public address for the LS and a random sequence of
601 characters that the LS can use to identify a particular context. The
602 presentity identifier included in a PIDF-LO document SHOULD NOT be
603 used for either part or the entirety of a Location URI.
605 The response to a create context request MUST include the time when
606 the LS will terminate the context. The LS MUST NOT respond to any
607 queries to the context beyond this time. A response to a context
608 creation also includes a password that the Device uses to identify
609 itself when updating the context at any time before the context
610 expiry time.
612 4.3.2. Updating Contexts
614 A Device can update any of the information it has provided for a
615 context at any time. The update context request includes the same
616 information as the create context request with the addition of
617 information that identifies an existing context.
619 A Device uses any one of the Location URIs provided to uniquely
620 identify a context when updating context information. The context
621 password MUST be provided when updating context information.
623 If a Device includes an authorization policy (or ruleset) in an
624 update context request, the LS MUST refresh any stored copy of the
625 authorization policy. This is especially important for authorization
626 policies that are provided by-reference; the LS MUST update the
627 authorization policy, even if the URI has not changed. Updated
628 authorization policies MUST be processed by the LG and LS before any
629 subsequent requests from LRs are accepted; the LG and LS MAY defer
630 processing of the authorization policy until after a response is sent
631 to the Device.
633 The update context request is constructed using the "updateContext"
634 element. A successful response is the "contextResponse" element,
635 which is the same as the response to a create context response.
637 The update context request can also indicate that data can be removed
638 by the context by specifying a _nil_ value for any of the parameters,
639 using the "xsi:nil" attribute. This applies to the profile
640 (Section 5.4) element.
642 The response to an update context request is identical in form to the
643 create context response, with updated information about the context.
644 The Location URIs MUST be the same as those in the response to the
645 initial create context request, but the password and expiry time MAY
646 be changed.
648 4.3.3. Terminating Contexts
650 The update context request can be used to instruct the LS to
651 terminate a context. The "lifetime" element in the request is set to
652 a zero duration. Once the context has been terminated, or it has
653 expired, Location URIs that reference that context can no longer be
654 used and the Device MUST NOT use the Location URIs or password
655 relating to that context.
657 The LS MAY terminate a context without notifying the Device. The LS
658 SHOULD terminate contexts if it, or the LG, detect that any
659 information relating to the Device changes in a way that invalidates
660 the context.
662 When the Device requests that a context be terminated, the LG
663 responds with a "contextResponse" message that does not include any
664 context information; this message MUST include the HELD "201"
665 response code.
667 4.4. Combined Context and Location Requests
669 HELD supports an optimization that allows for the creation or update
670 of a context while simultaneously requesting location information.
671 The optional "location" attribute on the "createContext" or
672 "updateContext" request can be used to request that the LG include a
673 PIDF-LO in the "contextResponse". This PIDF-LO is formed according
674 to the profile details associated with the context.
676 4.5. Indicating Errors
678 In the event of an error, the LG SHOULD respond to the Device with an
679 error document. The error response applies to all request types and
680 SHOULD also be sent in response to any unrecognized request.
682 An error indication document consists of an "error" element. The
683 "error" element MUST include a "code" attribute that indicates the
684 type of error. A set of predefined error codes are included in
685 Section 5.8.
687 Error responses MAY also include a "message" attribute that can
688 include additional information. This information SHOULD be for
689 diagnostic purposes only, and MAY be in any language. The language
690 of the message SHOULD be indicated with an "xml:lang" attribute.
692 5. Protocol Parameters
694 This section describes, in detail the parameters that are used for
695 this protocol. Table 2 lists the top-level components used within
696 the protocol and where they are used.
698 +------------------------+-------------+-------------+--------------+
699 | Parameter | Location | Create | Update |
700 | | Request | Context | Context |
701 +------------------------+-------------+-------------+--------------+
702 | responseTime | Request | Request | Request |
703 | (Section 5.1) | | | |
704 | | | | |
705 | assert (Section 5.2) | Request | | |
706 | | | | |
707 | exact (assert) | Request | | |
708 | (Section 5.2.4) | | | |
709 | | | | |
710 | locationType | Request | | |
711 | (Section 5.3) | | | |
712 | | | | |
713 | exact (locationType) | Request | | |
714 | (Section 5.3.1) | | | |
715 | | | | |
716 | profile (Section 5.4) | Request | Request | Request |
717 | | | | |
718 | signed (Section 5.5) | Request | | |
719 | | | | |
720 | lifetime (Section 5.6) | | Request | Request |
721 | | | | |
722 | rules (Section 5.7) | | Request | Request |
723 | | | | |
724 | code (Section 5.8) | Error | Error & | Error & |
725 | | | Response | Response |
726 | | | | |
727 | message (Section 5.9) | Error | Error & | Error & |
728 | | | Response | Response |
729 | | | | |
730 | context (Section 5.10) | Request | Response | Request & |
731 | | | | Response |
732 | | | | |
733 | location | | Request | Request |
734 | (Section 5.11) | | | |
735 +------------------------+-------------+-------------+--------------+
737 Table 2: Message Parameter Usage
739 5.1. "responseTime" Parameter
741 The "responseTime" attribute indicates to the LG how long the Device
742 is prepared to wait for a response. This attribute MAY be added to
743 any request message, although it is primarily used with the location
744 request. The value of this attribute is indicative only, the LG is
745 under no obligation to strictly adhere to the time limit implied; any
746 enforcement of the time limit is left to the Device.
748 This attribute MAY be either a duration value as defined in XML
749 Schema [W3C.REC-xmlschema-2-20041028], or a decimal seconds value,
750 which may include a decimal point. It is RECOMMENDED that systems
751 support millisecond precision for this parameter.
753 The LG SHOULD provide the most accurate LI that can be determined
754 within the specified interval. This parameter could be used as input
755 when selecting the method of location determination, where multiple
756 such methods exist. If this parameter is absent, then the LG SHOULD
757 return the most precise LI it is capable of determining.
759 5.2. "assert" Parameter
761 The "assert" element allows a Device to provide LI to the LG as part
762 of a location request. Two types of content are allowed: a geodetic
763 structure made up of a Geography Markup Language (GML) geometry
764 object, "_Geometry" as defined by [OGC.GML-3.1.1]; and a civic
765 address structure, "civicAddress" as defined by
766 [I-D.ietf-geopriv-revised-civic-lo]. The contents of this element
767 SHOULD follow the rules in [I-D.ietf-geopriv-pdif-lo-profile].
769 When used in combination with the "context" element, this LI MAY be
770 used by the LS for requests to Location URIs for that context.
772 This element is mutually exclusive with the "locationType" parameter,
773 defined in Section 5.3. The type of LI requested is implied by the
774 types included in the assertion.
776 5.2.1. "method" Parameter
778 The "method" attribute SHOULD be attached to the "assert" element to
779 indicate the means by which the LI was derived. This attribute
780 follows the rules of the similarly named method element of the
781 PIDF-LO.
783 5.2.2. "timestamp" Parameter
785 The "timestamp" attribute SHOULD be attached to the "assert" element
786 to indicate when the LI was generated.
788 5.2.3. "expires" Parameter
790 The "expires" attribute MAY be attached to the "assert" element to
791 indicate when the included LI is no longer valid. The LG SHOULD set
792 the "retention-expires" element in the returned PIDF-LO to no later
793 than this time if it uses the LI. This attribute SHOULD NOT be
794 included unless this time is definite.
796 5.2.4. "exact" Parameter
798 When the "exact" attribute is set to "true", it indicates to the LG
799 that the contents of the "assert" parameter MUST be strictly
800 followed. The default value of "false" allows the LG the option of
801 ignoring these values.
803 This attribute indicates that the asserted LI MUST be included in the
804 PIDF-LO response. If the LG cannot do this for any reason, which is
805 usually because it determines that the LI was inaccurate or
806 insufficiently precise, the LG MUST indicate an error.
808 5.3. "locationType" Parameter
810 The "locationType" element is included in a location request. It
811 contains a list of LI types that are requested by the Device. The
812 following list describes the possible values:
814 any: The LG SHOULD attempt to provide LI in all forms available to
815 it. This value MUST be assumed as the default if no
816 "locationType" is specified. The LG SHOULD return location
817 information in a form that is suited for routing and responding to
818 an emergency call in its jurisdiction.
820 geodetic: The LG SHOULD return a geodetic location for the Target.
822 civic: The LG SHOULD return a civic address for the Target. Any
823 type of civic address may be returned. The LG SHOULD ignore this
824 value if a request for jurisdictional or postal civic address has
825 been made and can be satisfied.
827 jurisdictionalCivic: The LG SHOULD return a jurisdictional civic
828 address for the Target.
830 postalCivic: The LG SHOULD return a postal civic address for the
831 Target.
833 The "locationType" element is mutually exclusive with the "assert"
834 element, defined in Section 5.2.
836 The LG SHOULD return the requested location type or types. The LG
837 MAY provide additional location types, or it MAY provide alternative
838 types if the request cannot be satisfied for a requested location
839 type. If the "exact" attribute is present and set to "true" in a
840 location request, then a successful LG response MUST provide the
841 requested location type only, with no additional location
842 information. The "exact" attribute has no effect when this element
843 is set to "any".
845 The "SHOULD"-strength requirement on this parameter is included to
846 allow for soft-failover. This enables a fixed client configuration
847 that prefers a specific location type without causing location
848 requests to fail when that location type is unavailable. Unless the
849 "exact" attribute is set, the LG MUST provide LI in any available
850 form if it is unable to comply with the request.
852 For example, a notebook computer could be configured to retrieve
853 civic addresses, which is usually available from typical home or work
854 situations. However, when using a wireless modem, the LG might be
855 unable to provide a civic address.
857 5.3.1. "exact" Parameter
859 When the "exact" attribute is set to "true", it indicates to the LG
860 that the contents of the "locationType" parameter MUST be strictly
861 followed. The default value of "false" allows the LG the option of
862 ignoring these values.
864 A value of "true" indicates that the LG MUST provide a PIDF-LO that
865 includes LI of the requested type or types. The LG MUST provide the
866 requested types only and these types SHOULD be specified in the same
867 order as they were requested. The LG SHOULD handle an exact request
868 that includes a "locationType" element set to "any" as if the "exact"
869 attribute were set to "false".
871 5.4. "profile" Parameter
873 The "profile" element contains a presentity identifier [RFC2778] and
874 GEOPRIV usage rules [RFC4119] information. All fields are optional
875 within this element, but when these fields are included, the LG MUST
876 use these parameters when constructing the PIDF-LO document.
878 This element MAY be included in location requests, create context
879 requests and update context requests. When included in a location
880 request, the profile is used immediately; when used in create context
881 or update context requests, the profile is stored on the LS and is
882 provided to the LG when the LS responds to requests from LRs.
884 5.4.1. "presentity" Parameter
886 The "presentity" element contains a presentity identifier that the LG
887 SHOULD include in the "pres" attribute of the PIDF-LO document.
889 The LG MAY require authentication of the presentity through any
890 means; the LG SHOULD ignore this parameter if authentication
891 information is not present or authentication information cannot be
892 verified.
894 5.4.2. "retentionExpiry" Parameter
896 The "retentionExpiry" element contains an absolute "dateTime"
897 [W3C.REC-xmlschema-2-20041028] value for the "retention-expires"
898 element of the PIDF-LO usage rules. This element is mutually
899 exclusive with the "retentionInterval" element.
901 The LG MAY use a different value than that specified (or the
902 suggested default) as circumstances dictate, but MUST NOT use a value
903 later than specified. If this value indicates a time that has
904 already passed, the request MUST be rejected with an error. See
905 retentionInterval (Section 5.4.3) for more details.
907 5.4.3. "retentionInterval" Parameter
909 The "retentionInterval" element contains a time duration value that
910 is specified in the same fashion as the responseTime attribute
911 (Section 5.1).
913 This value MUST be added to the time at which the PIDF-LO document is
914 created to set the value of the "retention-expires" element. This
915 element enables the Target to set an interval over which a LR can
916 retain a LO, rather than an absolute time. This element is mutually
917 exclusive with the "retentionExpires" element.
919 If neither "retentionExpiry" nor "retentionInterval" are specified,
920 the LG SHOULD provide a default value for the "retention-expires"
921 element of the generated PIDF-LO document. The default for this
922 value SHOULD be 24 hours from the receipt of the location request as
923 defined in [RFC4119].
925 The LG MAY use a different value than that specified (or the
926 suggested default) as circumstances dictate, but MUST NOT use a value
927 larger than specified.
929 5.4.4. "retransmission" Parameter
931 The "retransmission" element contains a boolean value that MUST be
932 included in the "retransmission-allowed" element of the generated
933 PIDF-LO usage rules. When this element is not provided, the LG MUST
934 set the "retransmission-allowed" element to "false".
936 5.4.5. "rulesetURI" Parameter
938 The "rulesetURI" element contains a URI value that MUST be included
939 in the "ruleset-reference" element of the generated PIDF-LO usage
940 rules.
942 This datum is only used to construct the usage rules in the PIDF-LO
943 document. Within the context of a profile, this ruleset is not
944 applied by either LG or LS, and the LS does not apply the rules found
945 at the URI.
947 5.5. "signed" Parameter
949 The "signed" attribute indicates whether the Device requires a
950 digitally signed PIDF-LO. When present and set to "true", the LG
951 MUST provide a PIDF-LO document that is signed according to XML-
952 Signature [RFC3275].
954 5.6. "lifetime" Parameter
956 The "lifetime" element specifies the maximum time that a context
957 should be maintained by the LS. This parameter MUST be included in
958 the context creation request to indicate to the LS the latest time
959 that the context is allowed to be retained. The parameter MAY be
960 included in context update requests to modify this time; when
961 included in an update request with a zero value, it indicates that
962 the context MUST be removed immediately.
964 The "lifetime" element is a duration value that is specified in the
965 same fashion as the "responseTime" attribute.
967 This value MUST be added to the current time when received by the LS
968 to determine the time at which the context expires. An LS MAY use
969 any value less than or equal to this value, but MUST NOT use a longer
970 value. The actual expiry time of the context MUST be indicated in
971 the context response.
973 5.7. "rules" Parameter
975 The "rules" element contains the authorization policy of the Target
976 that dictates how and to whom LI is provided by the LS. This policy
977 MUST be applied by the LS when providing LI to LRs.
979 Authorization policies MUST conform to
980 [I-D.ietf-geopriv-common-policy]. If the authorization policy is
981 invalid, cannot be retrieved, or is otherwise not understood by the
982 LS, the LG SHOULD fail the request. Note that this implies that the
983 LS SHOULD attempt to retrieve an authorization policy that is
984 provided by-reference at the time of a create context request;
985 however, an LS MAY choose to do this later, if the requested response
986 time might be exceeded.
988 In the absence of an authorization policy, the LS MUST NOT provide LI
989 to any LR. Note that in certain jurisdictions an LS might be
990 required to provide LI to specific parties irrespective of the
991 authorization policy, as mandated by legislation; for example,
992 emergency services in some countries.
994 5.7.1. "rulesetURI" Parameter
996 The "rulesetURI" element contains a URI that references the Target's
997 authorization policy. This URI should reference a document of type
998 "application/auth-policy+xml" as defined in
999 [I-D.ietf-geopriv-common-policy].
1001 It is RECOMMENDED that a ruleset URI use the "https" scheme. It is
1002 anticipated that, to improve responsiveness and reduce network usage,
1003 an LS could cache an authorization policy, consistent with the rules
1004 specified by the Rule Holder. For instance, the Rule Holder could
1005 specified retention times using the "Expires" header in HTTP
1006 [RFC2616]. The impact of changes to authorization policies are
1007 discussed in Section 4.3.2.
1009 5.7.2. Common Policy "ruleset" Parameter
1011 The "ruleset" element, which is in the
1012 "urn:ietf:params:xml:ns:common-policy" namespace
1013 [I-D.ietf-geopriv-common-policy], allows for providing an
1014 authorization policy directly as part of a request.
1016 5.8. "code" Parameter
1018 All responses, except a PIDF-LO document, MUST contain a response
1019 code. The "code" attribute applies to the "error" and
1020 "contextResponse" messages.
1022 The following response codes follow a three decimal form similar to
1023 that in HTTP [RFC2616] and SIP [RFC3261]:
1025 200 (Success): This code indicates that the request was successful.
1026 This code MUST not be used for an error response.
1028 201 (Context Terminated): This code indicates that the request to
1029 terminate a context was successful.
1031 400 (Request Error): This code indicates that the request was badly
1032 formed in some fashion.
1034 401 (XML Error): This code indicates that the XML content of the
1035 request was either badly formed or invalid.
1037 402 (Authentication Error): This code indicates that the request
1038 either did not contain authentication information, or the
1039 authentication provided was not accepted.
1041 403 (Asserted Location Error): This code indicates that the LI that
1042 was asserted in the request was not acceptable to the LG. This
1043 code is used when the "exact" attribute on the "assert" parameter
1044 is set to "true".
1046 404 (Context Not Found): This code indicates that the context
1047 identified in the request was not found. This code MAY also be
1048 used if the password provided was incorrect.
1050 500 (General LG Error): This code indicates that an unspecified
1051 error occurred at the LG.
1053 501 (Location Unknown): This code indicates that the LG could not
1054 determine the location of the Device.
1056 502 (Unsupported Message): This code indicates that the request was
1057 not supported or understood by the LG.
1059 503 (Timeout): This code indicates that the LG could not satisfy the
1060 request within the time specified in the "requestTime" parameter.
1062 504 (Cannot Provide LI Type): This code indicates that the LG was
1063 unable to provide LI of the type or types requested. This code is
1064 used when the "exact" attribute on the "locationType" parameter is
1065 set to "true".
1067 Additional response codes within the x00 to x79 range MUST be
1068 specified in published RFCs; the range from x80 to x99 is reserved
1069 for private usage.
1071 5.9. "message" Parameter
1073 The "contextResponse" and "error" messages MAY include a "message"
1074 attribute to convey some additional, human-readable information about
1075 the result of the request. This message MAY be included in any
1076 language, which SHOULD be indicated by the "xml:lang", attribute.
1078 5.10. "context" Parameter
1080 The "context" element includes information that is used to identify a
1081 context and control access to it. The context is identified by one
1082 or more Location URIs and a Device is granted a password which MUST
1083 be provided when accessing the context to update the information
1084 contained.
1086 When a context is created, the LG provides a "contextResponse"
1087 message that contains the "context" element. This element contains
1088 all of the Location URIs that can be used for the context, a
1089 password, and an expiry time.
1091 To update the details in a context, or reuse profile information
1092 stored in the context, the Device provides a "context" element. When
1093 identifying a context in this manner, the Device MUST provide only
1094 one Location URI and the password.
1096 5.10.1. "locationURI" Parameter
1098 The "locationURI" element includes a single Location URI. Each
1099 Location URI is allocated by the LS so that it is able to uniquely
1100 identify the context.
1102 A "contextResponse" message contains any number of "locationURI"
1103 elements. It is RECOMMENDED that the LS allocate a Location URI for
1104 all schemes that it supports and that no scheme is present twice.
1106 All "updateContext" request messages MUST contain only one
1107 "locationURI" element, which is all that is necessary to uniquely
1108 identify a context. The Device MAY select any of the Location URIs
1109 provided by the LS. Location URIs do not change over the lifetime of
1110 a context.
1112 5.10.2. "password" Parameter
1114 The "password" element carries a password that is used to access the
1115 context after it has been created. The LS generates this value when
1116 creating a context and the Device MUST use the exact same value when
1117 it wishes to access the context. This value acts as a shared secret
1118 between Device and LS.
1120 The value of the password MAY be updated in the response to any
1121 "updateContext" message.
1123 This element MAY contain any valid XML character data, within the
1124 constraints of the XML Schema "token" type.
1126 5.10.3. "expires" Parameter
1128 The "expires" attribute indicates the time at which the context
1129 created by the LS will expire. This attribute is included in the
1130 "contextResponse" message only.
1132 Responses to create and update context requests MUST include the
1133 expiry time of the context. If the LS has expired a context in
1134 response to an update context request, this value SHOULD include a
1135 time in the past to avoid problems that could be caused by a slow
1136 clock in the Device.
1138 5.11. "location" Parameter
1140 The "location" parameter is a boolean attribute associated with the
1141 "createContext" or "updateContext" message. The default for this
1142 attribute is "false".
1144 This parameter, when present and set to "true" indicates that the LG
1145 SHOULD include a PIDF-LO document in the "contextResponse" message.
1146 The success of any request that includes this parameter MUST NOT be
1147 affected by any error in providing a location; thus, if the LG is
1148 unable to include a PIDF-LO, it is only omitted from the response.
1149 If a "contextResponse" does not include a PIDF-LO, the Device can
1150 determine the reasons for failure by sending a separate
1151 "locationRequest".
1153 6. XML Schema
1155 This section gives the XML Schema Definition
1156 [W3C.REC-xmlschema-1-20041028] of the "application/held+xml" format.
1157 This is presented as a formal definition of the "application/
1158 held+xml" format. Note that the XML Schema definition is not
1159 intended to be used with on-the-fly validation of the presence XML
1160 document.
1162
1163 Namespace for HELD Messages
2000 urn:ietf:params:xml:ns:geopriv:held
2001 [[NOTE TO IANA/RFC-EDITOR: Please update RFC URL and replace XXXX
2002 with the RFC number for this specification.]]
2003
See RFCXXXX.
2004 2005 2006 END 2008 10.3. XML Schema Registration 2010 This section registers an XML schema as per the guidelines in 2011 [RFC3688]. 2013 URI: urn:ietf:params:xml:schema:geopriv:held 2015 Registrant Contact: IETF, GEOPRIV working group, (geopriv@ietf.org), 2016 Martin Thomson (martin.thomson@andrew.com). 2018 Schema: The XML for this schema can be found as the entirety of 2019 Section 6 of this document. 2021 10.4. URN Sub-Namespace Registration for 2022 urn:ietf:params:xml:ns:geopriv:held:http 2024 This section registers a new XML namespace, 2025 "urn:ietf:params:xml:ns:geopriv:held:http", as per the guidelines in 2026 [RFC3688]. 2028 URI: urn:ietf:params:xml:ns:geopriv:held:http 2030 Registrant Contact: IETF, GEOPRIV working group, 2031 (geopriv@ietf.org), Martin Thomson (martin.thomson@andrew.com). 2033 XML: 2035 BEGIN 2036 2037 2039 2040 2041See RFCXXXX.
2049 2050 2051 END 2053 10.5. MIME Media Type Registration for 'application/held+xml' 2055 This section registers the "application/held+xml" MIME type. 2057 To: ietf-types@iana.org 2059 Subject: Registration of MIME media type application/held+xml 2061 MIME media type name: application 2063 MIME subtype name: held+xml 2065 Required parameters: (none) 2067 Optional parameters: charset 2068 Indicates the character encoding of enclosed XML. Default is 2069 UTF-8. 2071 Encoding considerations: Uses XML, which can employ 8-bit 2072 characters, depending on the character encoding used. See RFC 2073 3023 [RFC3023], section 3.2. 2075 Security considerations: This content type is designed to carry 2076 protocol data related to the location of an entity, which could 2077 include information that is considered private. Appropriate 2078 precautions should be taken to limit disclosure of this 2079 information. 2081 Interoperability considerations: This content type provides a basis 2082 for a protocol 2084 Published specification: RFC XXXX [[NOTE TO IANA/RFC-EDITOR: Please 2085 replace XXXX with the RFC number for this specification.]] 2087 Applications which use this media type: Location information 2088 providers and consumers. 2090 Additional Information: Magic Number(s): (none) 2091 File extension(s): .xml 2092 Macintosh File Type Code(s): (none) 2094 Person & email address to contact for further information: Martin 2095 Thomson