[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

Network Working Group                                         L. Barguno
Internet-Draft                                                    Google
Intended status: Informational                           August 08, 2017
Expires: February 9, 2018

           Geolocation Header for HTTP over a Secure Context


   The Geolocation header introduces a mechanism to send a device
   location over an HTTP Secure Context from a user agent to a server.

   The Geolocation-Request header is used by a server to inform the user
   agent when a Geolocation header is requested to be sent.

   This mechanism, through persistent Geolocation-Requests, provides a
   single-roundtrip solution to obtain location-aware responses for
   location-aware services, as oposed to existing JS-based Geolocation
   API that require two round trips.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on February 9, 2018.

Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents

Barguno                 Expires February 9, 2018                [Page 1]

Internet-Draft              GeolocationHeader                August 2017

   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   4.  Geolocation Header  . . . . . . . . . . . . . . . . . . . . .   3
     4.1.  Attributes  . . . . . . . . . . . . . . . . . . . . . . .   4
   5.  Geolocation-Request Header  . . . . . . . . . . . . . . . . .   5
     5.1.  Attributes  . . . . . . . . . . . . . . . . . . . . . . .   5
     5.2.  Handling multiple headers . . . . . . . . . . . . . . . .   6
     5.3.  Best effort . . . . . . . . . . . . . . . . . . . . . . .   6
   6.  Negotiation, Privacy and Security . . . . . . . . . . . . . .   7
     6.1.  User agent Considerations . . . . . . . . . . . . . . . .   7
     6.2.  Server considerations . . . . . . . . . . . . . . . . . .   8
   7.  Header field registration . . . . . . . . . . . . . . . . . .   8
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     8.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
     8.2.  Informative References  . . . . . . . . . . . . . . . . .   9
     8.3.  URIs  . . . . . . . . . . . . . . . . . . . . . . . . . .   9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   Geolocation headers provide a mechanism to request and share the
   device location in an HTTP Secure Context.

   The Javascript W3C Geolocation API [1] is the only existing mechanism
   to share a location with a host.  This leads to some limitations.
   First, in order to have the server know the client's location there
   are two full roundtrips required (one roundtrip to load the page with
   Javascript code, and a second roundtrip to actually send the location
   to the server and get back a location-aware response).  While not as
   significant as the first limitation, the second limitation is that
   the client must execute Javascript in order to acquire location.

   Having a performant and safe mechanism to share a fresh device
   location, with and without a client being able to run Javascript, is
   increasingly necessary, especially on mobile devices.

   The proposal detailed in this document is purely based on HTTP
   headers, and guarantees a single roundtrip with hosts that already
   have permission to access the device location.

Barguno                 Expires February 9, 2018                [Page 2]

Internet-Draft              GeolocationHeader                August 2017

2.  Example

   Header sent from the server to the user agent when a host is
   compatible with the Geolocation Header and is requesting geolocation
   to be attached in subsequent requests.

       Geolocation-Request: Path="/localService"; Type=IfAlreadyGranted;
       Expires=Thu, 18 Dec 2017 12:00:00 UTC

   Header sent from user agent to server to share a location over a Full
   Secure Context [2] when permissions are granted, and the request Path
   matches a valid previously requested Geolocation-Request.

         Geolocation: Position=[47.368684, 8.535741, 345]; Accuracy=10;
         Timestamp=1495804846156; AltitudeAccuracy=20; Speed=1.5;

3.  Terminology

   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
   and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119
   [RFC2119] and indicate requirement levels for compliant STuPiD

4.  Geolocation Header

   A user agent request MAY include a Geolocation header.

   The header identifier used for this purpose is "Geolocation", and the
   content of the header MUST include the attributes Position, Accuracy
   and Timestamp (in this order).  After the required attributes, it MAY
   also include optional attributes AltitudeAccuracy, Speed and Heading
   (in this order).

   All attributes are separated by semicolon.  Each attribute MUST be
   specified as Attribute=Value.

   These attributes match the data exposed through the Javascript
   Geolocation API [3].

   This header is used to send geolocation data from the user agent to
   the server.

Barguno                 Expires February 9, 2018                [Page 3]

Internet-Draft              GeolocationHeader                August 2017

4.1.  Attributes

   o  Position

   A position is an array of numbers and MUST always be provided.  There
   MUST be two or three elements.  The first two elements are longitude
   and latitude, in that order and using decimal numbers.  Altitude or
   elevation in meters above sea level MAY be included as an optional
   third element.  This position format is based on RFC 7946 [RFC7946]

   o  Accuracy

   Accuracy MUST always be provided and represents the level of accuracy
   of the latitude and longitude components of the Position.  It is
   specified in meters.  The value of the accuracy attribute must be a
   non-negative decimal number.

   o  Timestamp

   Time when Position was computed.  It is a positive value,
   representing milliseconds since the UNIX epoch of 1 January 1970 at
   00:00 UTC.

   Optional attributes that MAY be included:

   o  AltitudeAccuracy

   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.

   o  Speed

   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.

   o  Heading

   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.

Barguno                 Expires February 9, 2018                [Page 4]

Internet-Draft              GeolocationHeader                August 2017

5.  Geolocation-Request Header

   A server response MAY include one or more Geolocation-Request headers
   in a single response.

   The header identifier used for this purpose is "Geolocation-Request",
   and the content of the header MUST include the attributes Path and
   Type.  It MAY also include the optional attribute Expires.

   All attributes are separated by semicolon.  Each attribute MUST be
   specified as Attribute=Value.

   This header is used to send a geolocation request from the server to
   the user agent.  A geolocation request will be scoped to a particular
   Path on the server, and this geolocation request state per-Path MAY
   be persisted and maintained by the user agent.

5.1.  Attributes

   o  Path

   The scope of a Geolocation request is limited to a particular path,
   controlled by the Path attribute, mimicking the Path attribute in
   Set-cookie RFC 6265 [RFC6265].  However, in the Geolocation-Request
   case, the Path attribute MUST always be provided.

   The user agent will include the Geolocation Header in a request only
   if the Path portion of the request-uri matches (or is a subdirectory
   of) the Geolocation-Request Path attribute, where the %x2F ("/")
   character is interpreted as a directory separator.

   Permission to access geolocation is granted or denied to an entire
   origin, rather than individual paths within an origin (see
   "Negotiation, Privacy and Security" section).

   o  Type

   There are two possible values for this attribute: "IfAlreadyGranted"
   or "MayPrompt".

   "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.

   "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

Barguno                 Expires February 9, 2018                [Page 5]

Internet-Draft              GeolocationHeader                August 2017

   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.

   Optional attribute that MAY be included:

   o  Expires

   This mimics the Expires attribute in Set-cookie RFC 6265 [RFC6265],
   and follows the same format and semantics.  The Expires attribute
   indicates the maximum lifetime of the Geolocation Request,
   represented as the date and time at which the request expires.

   This attribute is optional, and when this attribute is not provided,
   the lifetime of the request will be undefined and decided by the user

5.2.  Handling multiple headers

   If a server response contains multiple Geolocation-Request headers,
   each MUST be handled independently by the user agent.

   The scope of a Geolocation-Request is the Path attribute, so the
   latest Geolocation-Request for a given Path MUST always overwrite any
   older Geolocation-Request for that particular Path (regardless of

5.3.  Best effort

   A Geolocation-Request should follow a best effort approach from the
   user agent.  Computing location can be expensive, and it is
   recommended that the user agent does not block a request only because
   Geolocation is missing.  It is recommended that Geolocation is only
   attached when it is already available to the user agent.

   However, the user agent MAY internally precompute, cache, and keep
   geolocation information available and fresh, so when it is required
   to be attached in a server request, it is already available.

Barguno                 Expires February 9, 2018                [Page 6]

Internet-Draft              GeolocationHeader                August 2017

6.  Negotiation, Privacy and Security

   The data exposed in the Geolocation header is very sensitive
   information, and thereby potentially compromises the user's privacy.
   Any implementation of this technology must include the following
   mechanisms to guarantee the privacy of the user is protected.

6.1.  User agent Considerations

   o  Ensure that no location information is made available through this
      header without the user's permission.

   Permission must be acquired by the user agents through a user
   interface, which MUST expose at least the host name and include
   "Location" as the key piece of data being shared with that origin.
   The user agent MAY persist the user response and follow up requests
   MAY rely on older responses from the user for that particular origin,
   but before sending the Geolocation header, the user agent MUST
   guarantee that the latest response from the user for that origin was
   granting Location permission.  When these decisions are persisted,
   the user agent MUST provide another user interface to change the
   decision later on.

   Given that the data exposed through the Geolocation Header matches
   the data exposed through the W3C Javascript geolocation API, the user
   agent MAY use a consistent and unified permission-control mechanism
   for both location-sharing technologies, which is recommended for user
   clarity.  In particular, it is recommended to rely on the state of
   the geolocation permission [4].

   Since different paths within a single origin can access each other's'
   data, the permission to get location MUST be granted to the origin
   (domain+port+scheme, not a specific Path).

   o  Ensure that location information is only sent when the Path
      matches a valid Geolocation-Request.

   A user agent MUST only include a Geolocation header when permission
   has been granted and the server registered a Geolocation-Request in
   the past that has a matching Path and is still valid (not expired).

   o  Only send Geolocation header on Secure Contexts.

   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.

   o  Be transparent that the location information is sent

Barguno                 Expires February 9, 2018                [Page 7]

Internet-Draft              GeolocationHeader                August 2017

   Due to the sensitivity of the data, the user agent MUST include a
   visual indicator informing the user that a location information was
   shared.  The nature of the indicator is not mandated.

6.2.  Server considerations

   o  Location information MUST be requested only when necessary.

   The server MUST only send a Geolocation-Request header when it offers
   location-aware services, and the Path attribute must be used to limit
   the scope of the request, to only relevant services.

   o  Location data MUST be handled responsibly and transparently.

   The server MUST only use location information for the service for
   which it was provided by the user agent.  Location data MUST be
   protected from unauthorized access by third parties.  It MUST also be
   disposed once the task is completed, or retained according to terms
   of service acknowledged by the user.  When this data is stored, users
   should have access to it and the right to delete it at anytime.

   The server MUST disclose the following: The fact that they are
   collecting location data, why they are collection location data,
   security policy for location data, retention policy of location data,
   whether this location data is shared and how, and explain to the user
   how to access and delete this data on the server.

7.  Header field registration

   The message header fields should be added to the permanent registry
   RFC 3864 [RFC3864]: Geolocation and Geolocation-Request.

   The applicable protocol is HTTP.  Format specification is detailed in
   this document.

   Geolocation and Geolocation-Request are defined using US-ASCII.

8.  References

8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
              RFC2119, March 1997,

Barguno                 Expires February 9, 2018                [Page 8]

Internet-Draft              GeolocationHeader                August 2017

8.2.  Informative References

   [RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration
              Procedures for Message Header Fields", BCP 90, RFC 3864,
              DOI 10.17487/RFC3864, September 2004,

   [RFC6265]  Barth, A., "HTTP State Management Mechanism", RFC 6265,
              DOI 10.17487/RFC6265, April 2011,

   [RFC7946]  Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S.,
              and T. Schaub, "The GeoJSON Format", RFC 7946, DOI 10
              .17487/RFC7946, August 2016,

8.3.  URIs

   [1] https://www.w3.org/TR/geolocation-API/

   [2] https://w3c.github.io/webappsec-secure-contexts/

   [3] https://www.w3.org/TR/geolocation-API/

   [4] https://w3c.github.io/permissions/#reading-current-states

Author's Address

   Luis Barguno Jane
   Brandschenkestrasse 110
   Zurich  8002

   Email: lbargu@google.com

Barguno                 Expires February 9, 2018                [Page 9]

Html markup produced by rfcmarkup 1.123, available from https://tools.ietf.org/tools/rfcmarkup/