idnits 2.17.1 draft-luisbarguno-geolocation-header-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). == 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: It represents the accuracy level of the altitude, and it is specified in meters. When altitude is not provided as part of the Position, this attribute MUST not be included. Otherwise, the value of this attribute MUST be a non-negative decimal number. == 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: Denotes the device's current speed, in meters per second. When provided, the value of the speed attribute MUST be a non-negative decimal number. If the device is not moving, the speed attribute MUST not be included. == 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: Represents the bearing, that is the direction of the device and is specified in degrees. The value MUST be a decimal number between 0 and 360, as the clockwise direction relative to the north. If the device is not moving, the heading attribute MUST not be included. == 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: "IfAlreadyGranted" is used to specify that the user agent MUST not prompt the user for permission, and MUST only include a Geolocation header in requests matching the Path if the user already granted permission to share location with that origin in the past. == 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: "MayPrompt" is used to specify that the user agent MAY actively prompt the user for permission to share the geolocation with the server's origin. When this Type of request is specified, the server is telling the user agent that it is acceptable to prompt the user, but the user agent is not forced to do so. For example if the user agent already prompted the user for that origin in a recent request and the user denied sharing geolocation with the origin, the user agent can decide not to prompt this user for the same origin again. Also note that this option should never block the browser from working without Geolocation with the origin, since "MayPrompt" MUST not be interpreted as Geolocation is a requirement, but just as the browser MAY prompt the user if possible. == 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: The Geolocation header will only be included in Full Secure Contexts with the authorized origin, and MUST not be sent in a non-encrypted connection, so the user privacy is protected. -- The document date (August 08, 2017) is 2451 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 393 -- Looks like a reference, but probably isn't: '2' on line 395 -- Looks like a reference, but probably isn't: '3' on line 397 -- Looks like a reference, but probably isn't: '4' on line 399 Summary: 2 errors (**), 0 flaws (~~), 8 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group L. Barguno 3 Internet-Draft Google 4 Intended status: Informational August 08, 2017 5 Expires: February 9, 2018 7 Geolocation Header for HTTP over a Secure Context 8 draft-luisbarguno-geolocation-header-00 10 Abstract 12 The Geolocation header introduces a mechanism to send a device 13 location over an HTTP Secure Context from a user agent to a server. 15 The Geolocation-Request header is used by a server to inform the user 16 agent when a Geolocation header is requested to be sent. 18 This mechanism, through persistent Geolocation-Requests, provides a 19 single-roundtrip solution to obtain location-aware responses for 20 location-aware services, as oposed to existing JS-based Geolocation 21 API that require two round trips. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on February 9, 2018. 40 Copyright Notice 42 Copyright (c) 2017 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 58 2. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 4. Geolocation Header . . . . . . . . . . . . . . . . . . . . . 3 61 4.1. Attributes . . . . . . . . . . . . . . . . . . . . . . . 4 62 5. Geolocation-Request Header . . . . . . . . . . . . . . . . . 5 63 5.1. Attributes . . . . . . . . . . . . . . . . . . . . . . . 5 64 5.2. Handling multiple headers . . . . . . . . . . . . . . . . 6 65 5.3. Best effort . . . . . . . . . . . . . . . . . . . . . . . 6 66 6. Negotiation, Privacy and Security . . . . . . . . . . . . . . 7 67 6.1. User agent Considerations . . . . . . . . . . . . . . . . 7 68 6.2. Server considerations . . . . . . . . . . . . . . . . . . 8 69 7. Header field registration . . . . . . . . . . . . . . . . . . 8 70 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 8.1. Normative References . . . . . . . . . . . . . . . . . . 8 72 8.2. Informative References . . . . . . . . . . . . . . . . . 9 73 8.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 76 1. Introduction 78 Geolocation headers provide a mechanism to request and share the 79 device location in an HTTP Secure Context. 81 The Javascript W3C Geolocation API [1] is the only existing mechanism 82 to share a location with a host. This leads to some limitations. 83 First, in order to have the server know the client's location there 84 are two full roundtrips required (one roundtrip to load the page with 85 Javascript code, and a second roundtrip to actually send the location 86 to the server and get back a location-aware response). While not as 87 significant as the first limitation, the second limitation is that 88 the client must execute Javascript in order to acquire location. 90 Having a performant and safe mechanism to share a fresh device 91 location, with and without a client being able to run Javascript, is 92 increasingly necessary, especially on mobile devices. 94 The proposal detailed in this document is purely based on HTTP 95 headers, and guarantees a single roundtrip with hosts that already 96 have permission to access the device location. 98 2. Example 100 Header sent from the server to the user agent when a host is 101 compatible with the Geolocation Header and is requesting geolocation 102 to be attached in subsequent requests. 104 Geolocation-Request: Path="/localService"; Type=IfAlreadyGranted; 105 Expires=Thu, 18 Dec 2017 12:00:00 UTC 107 Header sent from user agent to server to share a location over a Full 108 Secure Context [2] when permissions are granted, and the request Path 109 matches a valid previously requested Geolocation-Request. 111 Geolocation: Position=[47.368684, 8.535741, 345]; Accuracy=10; 112 Timestamp=1495804846156; AltitudeAccuracy=20; Speed=1.5; 113 Heading=27.53; 115 3. Terminology 117 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 118 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 119 and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 120 [RFC2119] and indicate requirement levels for compliant STuPiD 121 implementations. 123 4. Geolocation Header 125 A user agent request MAY include a Geolocation header. 127 The header identifier used for this purpose is "Geolocation", and the 128 content of the header MUST include the attributes Position, Accuracy 129 and Timestamp (in this order). After the required attributes, it MAY 130 also include optional attributes AltitudeAccuracy, Speed and Heading 131 (in this order). 133 All attributes are separated by semicolon. Each attribute MUST be 134 specified as Attribute=Value. 136 These attributes match the data exposed through the Javascript 137 Geolocation API [3]. 139 This header is used to send geolocation data from the user agent to 140 the server. 142 4.1. Attributes 144 o Position 146 A position is an array of numbers and MUST always be provided. There 147 MUST be two or three elements. The first two elements are longitude 148 and latitude, in that order and using decimal numbers. Altitude or 149 elevation in meters above sea level MAY be included as an optional 150 third element. This position format is based on RFC 7946 [RFC7946] 152 o Accuracy 154 Accuracy MUST always be provided and represents the level of accuracy 155 of the latitude and longitude components of the Position. It is 156 specified in meters. The value of the accuracy attribute must be a 157 non-negative decimal number. 159 o Timestamp 161 Time when Position was computed. It is a positive value, 162 representing milliseconds since the UNIX epoch of 1 January 1970 at 163 00:00 UTC. 165 Optional attributes that MAY be included: 167 o AltitudeAccuracy 169 It represents the accuracy level of the altitude, and it is specified 170 in meters. When altitude is not provided as part of the Position, 171 this attribute MUST not be included. Otherwise, the value of this 172 attribute MUST be a non-negative decimal number. 174 o Speed 176 Denotes the device's current speed, in meters per second. When 177 provided, the value of the speed attribute MUST be a non-negative 178 decimal number. If the device is not moving, the speed attribute 179 MUST not be included. 181 o Heading 183 Represents the bearing, that is the direction of the device and is 184 specified in degrees. The value MUST be a decimal number between 0 185 and 360, as the clockwise direction relative to the north. If the 186 device is not moving, the heading attribute MUST not be included. 188 5. Geolocation-Request Header 190 A server response MAY include one or more Geolocation-Request headers 191 in a single response. 193 The header identifier used for this purpose is "Geolocation-Request", 194 and the content of the header MUST include the attributes Path and 195 Type. It MAY also include the optional attribute Expires. 197 All attributes are separated by semicolon. Each attribute MUST be 198 specified as Attribute=Value. 200 This header is used to send a geolocation request from the server to 201 the user agent. A geolocation request will be scoped to a particular 202 Path on the server, and this geolocation request state per-Path MAY 203 be persisted and maintained by the user agent. 205 5.1. Attributes 207 o Path 209 The scope of a Geolocation request is limited to a particular path, 210 controlled by the Path attribute, mimicking the Path attribute in 211 Set-cookie RFC 6265 [RFC6265]. However, in the Geolocation-Request 212 case, the Path attribute MUST always be provided. 214 The user agent will include the Geolocation Header in a request only 215 if the Path portion of the request-uri matches (or is a subdirectory 216 of) the Geolocation-Request Path attribute, where the %x2F ("/") 217 character is interpreted as a directory separator. 219 Permission to access geolocation is granted or denied to an entire 220 origin, rather than individual paths within an origin (see 221 "Negotiation, Privacy and Security" section). 223 o Type 225 There are two possible values for this attribute: "IfAlreadyGranted" 226 or "MayPrompt". 228 "IfAlreadyGranted" is used to specify that the user agent MUST not 229 prompt the user for permission, and MUST only include a Geolocation 230 header in requests matching the Path if the user already granted 231 permission to share location with that origin in the past. 233 "MayPrompt" is used to specify that the user agent MAY actively 234 prompt the user for permission to share the geolocation with the 235 server's origin. When this Type of request is specified, the server 236 is telling the user agent that it is acceptable to prompt the user, 237 but the user agent is not forced to do so. For example if the user 238 agent already prompted the user for that origin in a recent request 239 and the user denied sharing geolocation with the origin, the user 240 agent can decide not to prompt this user for the same origin again. 241 Also note that this option should never block the browser from 242 working without Geolocation with the origin, since "MayPrompt" MUST 243 not be interpreted as Geolocation is a requirement, but just as the 244 browser MAY prompt the user if possible. 246 Optional attribute that MAY be included: 248 o Expires 250 This mimics the Expires attribute in Set-cookie RFC 6265 [RFC6265], 251 and follows the same format and semantics. The Expires attribute 252 indicates the maximum lifetime of the Geolocation Request, 253 represented as the date and time at which the request expires. 255 This attribute is optional, and when this attribute is not provided, 256 the lifetime of the request will be undefined and decided by the user 257 agent. 259 5.2. Handling multiple headers 261 If a server response contains multiple Geolocation-Request headers, 262 each MUST be handled independently by the user agent. 264 The scope of a Geolocation-Request is the Path attribute, so the 265 latest Geolocation-Request for a given Path MUST always overwrite any 266 older Geolocation-Request for that particular Path (regardless of 267 Type). 269 5.3. Best effort 271 A Geolocation-Request should follow a best effort approach from the 272 user agent. Computing location can be expensive, and it is 273 recommended that the user agent does not block a request only because 274 Geolocation is missing. It is recommended that Geolocation is only 275 attached when it is already available to the user agent. 277 However, the user agent MAY internally precompute, cache, and keep 278 geolocation information available and fresh, so when it is required 279 to be attached in a server request, it is already available. 281 6. Negotiation, Privacy and Security 283 The data exposed in the Geolocation header is very sensitive 284 information, and thereby potentially compromises the user's privacy. 285 Any implementation of this technology must include the following 286 mechanisms to guarantee the privacy of the user is protected. 288 6.1. User agent Considerations 290 o Ensure that no location information is made available through this 291 header without the user's permission. 293 Permission must be acquired by the user agents through a user 294 interface, which MUST expose at least the host name and include 295 "Location" as the key piece of data being shared with that origin. 296 The user agent MAY persist the user response and follow up requests 297 MAY rely on older responses from the user for that particular origin, 298 but before sending the Geolocation header, the user agent MUST 299 guarantee that the latest response from the user for that origin was 300 granting Location permission. When these decisions are persisted, 301 the user agent MUST provide another user interface to change the 302 decision later on. 304 Given that the data exposed through the Geolocation Header matches 305 the data exposed through the W3C Javascript geolocation API, the user 306 agent MAY use a consistent and unified permission-control mechanism 307 for both location-sharing technologies, which is recommended for user 308 clarity. In particular, it is recommended to rely on the state of 309 the geolocation permission [4]. 311 Since different paths within a single origin can access each other's' 312 data, the permission to get location MUST be granted to the origin 313 (domain+port+scheme, not a specific Path). 315 o Ensure that location information is only sent when the Path 316 matches a valid Geolocation-Request. 318 A user agent MUST only include a Geolocation header when permission 319 has been granted and the server registered a Geolocation-Request in 320 the past that has a matching Path and is still valid (not expired). 322 o Only send Geolocation header on Secure Contexts. 324 The Geolocation header will only be included in Full Secure Contexts 325 with the authorized origin, and MUST not be sent in a non-encrypted 326 connection, so the user privacy is protected. 328 o Be transparent that the location information is sent 329 Due to the sensitivity of the data, the user agent MUST include a 330 visual indicator informing the user that a location information was 331 shared. The nature of the indicator is not mandated. 333 6.2. Server considerations 335 o Location information MUST be requested only when necessary. 337 The server MUST only send a Geolocation-Request header when it offers 338 location-aware services, and the Path attribute must be used to limit 339 the scope of the request, to only relevant services. 341 o Location data MUST be handled responsibly and transparently. 343 The server MUST only use location information for the service for 344 which it was provided by the user agent. Location data MUST be 345 protected from unauthorized access by third parties. It MUST also be 346 disposed once the task is completed, or retained according to terms 347 of service acknowledged by the user. When this data is stored, users 348 should have access to it and the right to delete it at anytime. 350 The server MUST disclose the following: The fact that they are 351 collecting location data, why they are collection location data, 352 security policy for location data, retention policy of location data, 353 whether this location data is shared and how, and explain to the user 354 how to access and delete this data on the server. 356 7. Header field registration 358 The message header fields should be added to the permanent registry 359 RFC 3864 [RFC3864]: Geolocation and Geolocation-Request. 361 The applicable protocol is HTTP. Format specification is detailed in 362 this document. 364 Geolocation and Geolocation-Request are defined using US-ASCII. 366 8. References 368 8.1. Normative References 370 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 371 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 372 RFC2119, March 1997, 373 . 375 8.2. Informative References 377 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 378 Procedures for Message Header Fields", BCP 90, RFC 3864, 379 DOI 10.17487/RFC3864, September 2004, 380 . 382 [RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265, 383 DOI 10.17487/RFC6265, April 2011, 384 . 386 [RFC7946] Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., 387 and T. Schaub, "The GeoJSON Format", RFC 7946, DOI 10 388 .17487/RFC7946, August 2016, 389 . 391 8.3. URIs 393 [1] https://www.w3.org/TR/geolocation-API/ 395 [2] https://w3c.github.io/webappsec-secure-contexts/ 397 [3] https://www.w3.org/TR/geolocation-API/ 399 [4] https://w3c.github.io/permissions/#reading-current-states 401 Author's Address 403 Luis Barguno Jane 404 Google 405 Brandschenkestrasse 110 406 Zurich 8002 407 Switzerland 409 Email: lbargu@google.com