CloudServices/FindMyDevice

From MozillaWiki
Jump to: navigation, search
Draft-template-image.png THIS PAGE IS A WORKING DRAFT Pencil-emoji U270F-gray.png
The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly.
If you have any questions or ideas, please add them as a new topic on the discussion page.

Find My Device

(aka "Where's My Fox")

To provide a means for users to locate, track and purge devices remotely. We are targeting version 1.4 which is FC on March 17, 2014 (and based on Gecko 30).

v1.4 Important Dates

  • [ON TRACK] 12/09/13 - Scoping Complete/User Story Freeze
  • [ON TRACK] 12/11/13 - Demo Day for WMF working prototype
  • [PROPOSED] 01/17/14 - UX Interaction Evaluation
  • [ON TRACK] 01/21/14 - Naming/Identity Brainstorm
  • [AT RISK] 02/04/14 - Convert from Persona to FxA
  • [AT RISK] 02/10/14 - MWC Demo Freeze <== this has changed from 02/14
  • [ON TRACK] 02/24-02/27/14 - MWC
  • [ON TRACK] 03/17/14 - Functional Complete
  • [ON TRACK] 06/09/14 - Code Freeze

Important People

For a list of DRIs and what they own, visit: https://wiki.mozilla.org/FirefoxOS/functionalteams#Find_My_Device

Example Use Cases, MVP User Stories

1) Albert can't remember the location of his phone. Going to a nearby computer, he logs into WheresMyFox and requests the phone to report it's location. The phone reports that it is nearby, so Albert requests the device to ring. Albert quickly finds that his phone is in his coat pocket.

2) Bea discovers that her phone is missing. Using a friends phone, she logs into WheresMyFox and requests the phone to report it's location. She discovers that the phone is currently headed down Broadway, and realizes she has left it in the cab. Realizing that she may never see her phone again, she requests the phone to remotely wipe itself, before calling the cab agency to see if she can recover her device.

WMF Setup Via Firefox Accounts from a Firefox OS Phone

No results.

0 Total; 0 Open (0%); 0 Resolved (0%); 0 Verified (0%);

"Where's My fox" website for Desktop (and Mobile?)

No results.

0 Total; 0 Open (0%); 0 Resolved (0%); 0 Verified (0%);


Requirements

  1. The user must use a secure credentialing and authorization system to identify self and associate to a device.
    1. The login system is currently Out of Scope of these requirements, but should be or substantially similar to Firefox Accounts.
    2. A user may have one or more devices.
    3. A device shall have a Globally Unique Identifier (WTFID).
    4. A device shall be associated with a single user.
  2. Data exchanged between client and server shall be via JSON Web Signature format
    1. The secret shall be generated and stored on the client, and sent to the server ONLY on initialization.
      1. The secret shall be a 128bit value.
      2. The secret shall be stored on the device as long as the WTFID remains unchanged.
      3. A new WTFID shall require a new secret to be generated and the device to reconnect as if new.
      4. No data shall be preserved in the case of a WTFID changing.
    2. Data signatures shall use HMAC SHA-256 or any more secure signing method for any exchange EXCEPT for Initialization.
  3. A remote wipe operation will format any additional storage (e.g. SD card) on the phone and reset the phone to initial Factory conditions.
  4. Only allow registered user to display and remotely control devices.
    1. Login and user authorization is delegated to Persona/FirefoxAccounts
    2. Control panel is secured by https and session cookie.
  5. Control panel shall securely send commands to:
    1. report location on a regular interval (for motion tracking)
      1. record tracking information keeping latest location for device
      2. Tracking records expire after 10 minutes, with the exception of the last reported location.
        1. Last reported location does not expire.
    2. play a default audio alarm.
      1. Alarm will repeatedly play for a user specified period of seconds
    3. lock a device
      1. Allow a user to specify a key code if not already present on the device.
    4. display an optional message
      1. Messages shall be less than 100 non-control ASCII characters
    5. remove all user information from a device by performing a factory reset
  6. Securely display web based UI for device including
    1. current location
    2. previously recv'd locations, provided they are different than latest location.
  7. Allow multiple devices per user.
    1. How long to store data?

Tracking

No results.

0 Total; 0 Open (0%); 0 Resolved (0%); 0 Verified (0%);


Cloud Services Back-End Design

Discussions

https://etherpad.mozilla.org/wheresmyfox-2013-10-28

https://etherpad.mozilla.org/wmf

Client API Reference/Documentation

Client UX was presented by Epic:

https://www.dropbox.com/sh/uaxlhzz211br438/rH2UA0Tf6_/WIMF_3.0.pdf

Client module owners

Owner: :ggp

Peers: :mgoodwin, :gerard-majax :6a68?

https://wiki.mozilla.org/Modules/FirefoxOS#Find_My_Device

Server API Reference/Documentation

API calls will be a combination of REST calls and BOSH where possible. This avoids some of the issues with the fragility of websockets in areas where connectivity is sub-optimal or sporadic.

In addition, packet identifiers have been reduced as much as possible. This is to both reduce bandwidth costs as well as require less time to exchange data.

To reduce risk of injection attacks, calls will use Hawk to sign requests (unless otherwise specified).

Data Schema

Since each server system will be unique, it does not make sense to strictly specify the data storage method. Instead an example storage mechanism will be offered to illustrate how the server would manage data.

A simple storage object would be keyed off of the ID returned in the /$v/init call. 

   key => {"lastPosition":{"lat":lat,             // The last position reported by track
                           "lon":lon, 
                           "alt":altitude?,       // Optional "altitude", if provided
                           "tim":UTC},            // UTC Timestamp
           "previousPositions":[{position},...],  // the last 5? position reports for the device
           "state":"(rtn)",                       // the state the server thinks the device is in
           "lockable"1:True|False,                // does the device have a user supplied key code1
           "lastExchange":UTC,                     // last time an exchange happened
           "secret":HawkSecret,
           "pendingCommand": {outboundCommand}
           }
   
    user => ["key:name",...]               // A list of known keys & user friendly names for devices

1Note: this should be queried on device. User might set a passcode while the device is active or between updates.

API

Unless otherwise specified, all exchanged blocks are in JSON format and signed using HAWK (not shown here for simplicity).

Standard HTTP responses apply (401, 500, 301)

POST /<version>/register

Registers the existence of a device.

The POSTed JSON payload contains the following fields:

keyvalue
assertA Firefox Accounts user assertion
pushurlThe SimplePush channel URL that the server should use to notify the device that it has a new instruction. See <some simplepush link> for more details on acquiring a SimplePush channel.
deviceidThe previous deviceid returned by the server from a register call. Used to overwrite a previous pushurl for this device if the SimplePush channel has changed.
acceptsThe list of commands that this device will accept (e.g. ["t","r","e"] If this is missing or empty, it is assumed that the device accepts all commands.


reply from server:

keyvalue
deviceidThe unique id for this device. This id should be used in all future requests to the server, including any needed reregistration.
secreta HAWK valid secret hash key for the device. This is used to sign the JSON responses.


After a device has registered for the first time, it should immediately call POST /$v/cmd/$deviceUniqueId with a response as though it had just received a tracking call of: 

   {"t":{"p":1,"d":1}}

POST /<version>/cmd/<deviceid>

A request to the server for any new commands. If the device has just completed a command, the POST body will contain the appropriate information with the results from the last command (see below).

The server response consists of a list of commands, of the format 

"<command name/short code>":{<command parameters>}

Multiple commands may be combined into a single server response.


Command NameShort CodeAdditional parametersDetails
lockl"c": <lock code>, "m": <message>Specify the lock code to use, if no device lock code is present. If a lock code already exists on the device, lock the device with the device's lock code. Messages are limited to 100 standard (non-control) ASCII characters.
messagem"m": <message>
"n": <phone number>		Displays <message> on the device including the contact <phone number>. Contact numbers are limited to 25 characters in the set 0123456789 +-(). Messages are limited to 100 standard (non-control) ASCII characters
ringr"d": <duration>
"p": <period>		Cause the device to ring every <period> seconds for the specified duration. Specifying a duration of 0 cancels any previous ring commands.
trackt"d": <duration>
"p": <period>		Begin active location tracking on the device, reporting the devices position every <period> seconds for <duration> seconds. See below for the response format for this report. Specifying a duration of 0 stops the device from reporting its location.
eraseeErase the device. This performs a factory reset.


Client Responses

A successful client payload will, for each command in the previous request, be formatted: 

{"<device command>":{"ok": "true", <additional response values>},...}

If one of the commands results in an error, the response for that command is 

{"<device command>":{"ok": "false", "error": "<error details>"},...}

At this time, the only additional response values are defined for the track command, and are as follows:

KeyValue
laThe current latitude of the device
loThe current longitude of the device
tiThe current UTC time
has_passcodeA boolean defining whether or not a lock key is currently set on the phone.

If, for whatever reason, the user has not activated or authorized geo-location for a device, the "la"/"lo" values may be specified as 0.

Response Codes

If the <deviceid> in the URL or payload is unknown, or the HAWK wrapper fails, the URL will return a 401, requiring the device to re-register. Other HTTP response codes (500, 301, 200, etc) perform as per normal.

Platform Requirements

Find My Device uses the following AWS products:

  • RDS: Postgres DB (note, stand alone Postgres may be used)

In addition the development system requires:

  • node.js (for some front end build/install requirements)

Code Repository

https://github.com/mozilla-services/FindMyDevice

Release Schedule

Refer to [Releases] for a list of the releases and dates.

QA

Points of Contact

Engineer - Ed Wong edwong@

Test Framework

Security and Privacy

Tracking bug: 935724

  • Bug 935725 - Security Review: Where's My Fox
  • Bug 935726 - Legal Review: Where's My Fox
  • Bug 935727 - Privacy-Technical Review: Where's My Fox
  • Bug 935728 - Privacy-Policy Review: Where's My Fox


No results.

0 Total; 0 Open (0%); 0 Resolved (0%); 0 Verified (0%);


Points of Contact

Legal - udevi@

Privacy Review

https://wiki.mozilla.org/Privacy/Reviews/Wheres_My_Fox

Security Review

https://wiki.mozilla.org/Where%27s_My_Fox_Security_Review

Review Status

https://bugzilla.mozilla.org/show_bug.cgi?id=935725

2014-04-16 Review https://wiki.mozilla.org/Where%27s_My_Fox_Security_Review

Issues and Resolutions

Operations

Points of Contact

Deployment Architecture

Bugzilla Tracking # -

https://bugzilla.mozilla.org/show_bug.cgi?id=963163

Escalation Paths

Lifespan Support Plans

Logging and Metrics

Points of Contact

kparlante@

Tracking Element Definitions

Data Retention Plans

Dashboard URL

Kibana logging page

Customer Support

Points of Contact

Sumo Tags

https://bugzilla.mozilla.org/show_bug.cgi?id=1026791

Review Meeting

Retrieved from "https://wiki.mozilla.org/index.php?title=CloudServices/FindMyDevice&oldid=1039402"