Document Overview

Timeline:

Architecture

In this section, the product's architecture is described. Any individual components or actors are identified, their "knowledge" or what data they store is identified, and data flow between components and external entities is described.

The main objective of this feature/product is: To make changes to the existing geolocation WebAPI in order to allow web developers to convert an arbitrary location (given in latitude and longitude) into civic mailing address for increased user readability.

Design Documents:

http://arreth.wordpress.com/2012/03/14/ch-ch-ch-ch-changes-to-geolocation-api-specifcations-2-2/

http://arreth.wordpress.com/2012/03/13/proposed-changes-to-geolocation-api-specification/

Components

Describe any major components in the system and how they interact. Also include any third-party APIs (those Mozilla does not control) and what type of data is sent or received via those APIs.

There are three components:

1. The content (untrusted) page requesting the location
2. The Geolocation API (Gecko)
3. The Reverse Geocoding service (e.g., Google)

NOTE:

• All Location data mentioned in this section may pertain to the user's location data (retrieved by another function), or to any arbitrary location data.
• Location data in this context is equivalent to the coordinates interface as described in the W3C Geolocation API documentation here: http://dev.w3.org/geo/api/spec-source.html#coordinates_interface

Page Holding Location Request

A web page requests help from our API to convert a location to a civic address. This request is sent to our Geolocation API, which brokers communication with a third party geocoder and then returns the resulting civic address to this page.

Stored Data: None relevant.

Communication with Geolocation API:

Mozilla Geolocation API

This is a browser component in privileged code that brokers communication between the page requesting the location information and the third party location services. This component begins to handle the request by asking the user for permission to use geolocation.

This API will prompt the user for permission even if website is not requesting the user's location (ie. just converting an arbitrary location into a civic address). This is because it calls a third-party API with arbitrary data. We are planning to have the implementation only ask permission if the user has not currently authorized other geolocation activity on the page.

If permission is given, this request is processed, and the location's lat/long is then sent to the platform's reverse geocoding API (if available). If not, the request is not performed, and the interaction stops here.

Stored Data:

The civic addresses are not stored in this component, and are only retrieved and passed as parameter arguments to/from the third party geocoding API. No actual civic address object is being stored in this component. The location data stored in this component are provided by the page holding location request and may or may not have been obtained through the other geolocation API.

Communication with page requesting location data:

(See "Page Holding Location Request" component for communications with that component.)

Communication with 3rd Party Geocoding API:

The 3rd party APIs vary from platform to platform, but we would only ever be handing over the latitude and longitude to these 3rd party APIs. For example, on the Android platform, we use a call to getFromLocation(double, double, int) (documented here: http://developer.android.com/reference/android/location/Geocoder.html).

This call would return a list of Address objects, which should be of the general form that is documented here: http://arreth.wordpress.com/2012/03/13/proposed-changes-to-geolocation-api-specification/

On the Android platform, the Address objects are of the form documented here: http://developer.android.com/reference/android/location/Address.html

Platform Reverse Geocoding API (3rd-Party)

On request, the 3rd party reverse geocoding API reverse geocodes lat/long into a civic address and passes it back to the Mozilla Geolocation API.

NOTE: 3rd party API should be from a trusted source to ensure that IF we are actually using the user's location data, then it is not compromised

Stored Data: Unknown -- this third party is out of Mozilla's control. Potentially they could store any data we send them via the Mozilla Geolocation API.

Communication with Mozilla Geolocation API:

(See "Mozilla Geolocation API" component for communications with this component.)

User Data Risk Minimization

Location Disclosure

The Geocoding API service provider may be different than the location provider, and potentially may learn the location of Firefox users who encounter pages using this API.

The Risk is that, since this feature is sending longitude and latitude to the Geocoding service, the user may be leaking his location to an unknown third party.

Recommendation: If possible, make sure the location is obtained from the same service provider that is used for geocoding. This way, the same entity is used for both operations, reducing any surprise when users identify with whom their coordinates are shared.

Requirement: Ensure the user is aware when this Geocoding API is activated.

Geographical Tracking

As the user physically changes location (with a mobile device, laptop, etc), he may also frequently visit sites that use geocoding. As a result, the geocoding service is exposed to the user's location at multiple points in time and space.

The Risk is that the geocoding service will be able to tie multiple requests together into a trail of locations corresponding to an individual's movements. This problem is present also in other geolocation services, not just geocoding.

Requirement: Ensure no other client-state data are transmitted to the geocoding service (cookies, etags/cache tags, last-access timestamps, etc).

Local Traces

Calls to and from the geocoding API may be cached locally. The side-effect of this are that these data could form a "tracking record" of everywhere the users' browser activated geocoding -- a series of addresses where the user probably physically sat.

The Risk is that the locations will be persisted longer than necessary and may become discoverable by others who access the device; this leaks the user's physical location history to another person, probably without consent.

Requirement: store addresses and longitude/latitude coordinates in volatile memory only (not on disk or in cache).

Confused Origin

Web pages are often composed of objects and frames from many different web sites. An iframe or subordinate resource on a page may trigger access to the geocoding API. Consider a map widget in an iframe; it may want location information geocoded into an address for display, but might be served by "thirdpartymaps.com" instead of the main page.

The Risk is that it will not be clear to the user which part of the page (which origin) caused the geolocation request.

Requirement: make it obvious who is requesting the call to the API.

Recommendation: allow only script running in the context of the top-level document (the one displayed in the address bar) to make requests to this API.

Alignment with Privacy Operating Principles

In this section, the privacy champion will identify how the feature lines up with Mozilla's privacy operating principles.

See Also: Privacy/Roadmap_2011#Operating_Principles:

Principle: Transparency / No Surprises

This feature prompts users before giving content access to the geocoding API. Users who have allowed the current page to obtain their location through the other geolocation API will not be prompted, though they have already authorized location services on the current page.

Recommendations: Let the user know that this function MAY involve the data associated with their location(s) (ie. from geo-tagged photos, etc.) Update the prompt message to say this.

Principle: Real Choice

This feature will prompt the user for permission for use of this feature through use of an on-screen prompt. The prompt is simple and allows the user to continue using the current web site without granting access to this service.

Recommendations: None.

Principle: Sensible Defaults

This feature is disabled by default and when a site requests access, the user will be asked for permission. The prompt is tied into other geolocation services too -- the user will be prompted only once per site per session (so there will not be a flood of prompts for each call to this API). The effect is that the user will be prompted once to allow a site to access location services, then not again for that session on that site.

Recommendations: None.

Principle: Limited Data

The data being shared to 3rd party platforms is only the bare minimum data that can be shared for the services requested. All other location data being stored in the browser is stored only in memory (not on disk).

Requirement: store addresses and longitude/latitude coordinates in volatile memory only (not on disk or in cache).

Follow-up Tasks and tracking