CloudServices/WheresMyFox: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Redirected page to CloudServices/FindMyDevice)
 
(76 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{draft}}
#REDIRECT [[CloudServices/FindMyDevice]]
<h1><i>Where's My Fox</i></h1>
==Overview==
To provide a means for users to locate, track and purge devices remotely.
 
==Project Contacts==
''Principal Point of Contact'' - <i>Doug Turner</i> <i>dougt@mozilla.com</i>
 
''Product'' - vishy@, elancaster@
 
''IRC'' - #<i>services-dev</i>
 
''Group Email'' - TBD
 
==Goals==
* Be able to provide a simple, secure means for FirefoxOS users to remotely locate, track and purge their devices.
==Use Cases==
 
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.
 
==Requirements==
# The user must use a secure credentialing and authorization system to identify self and associate to a device.
## The login system is currently Out of Scope of these requirements, but should be or substantially similar to Firefox Accounts.
## A user may have one or more devices.
## A device shall have a Globally Unique Identifier (WTFID).
## A device shall be associated with a single user.
# Data exchanged between client and server shall be via [http://datatracker.ietf.org/doc/draft-ietf-jose-json-web-signature/ JSON Web Signature format]
## The secret shall be generated and stored on the client, and sent to the server ONLY on initialization.
### The secret shall be a 128bit value.
### The secret shall be stored on the device as long as the WTFID remains unchanged.
### A new WTFID shall require a new secret to be generated and the device to reconnect as if new.
### No data shall be preserved in the case of a WTFID changing.
## Data signatures shall use HMAC SHA-256 or any more secure signing method for any exchange EXCEPT for Initialization.
# A remote wipe operation will format any additional storage (e.g. SD card) on the phone and reset the phone to initial Factory conditions.
* Only allow registered user to display and remotely control devices.
** login page?
** secured by session cookie
* Securely send commands to:
** report location on a regular interval (for motion tracking)
*** record tracking information keeping latest location for device
*** older records expired after ? period ?
** play a default audio alarm.
*** For known period? Forever? What happens if multiple of these commands sent?
** lock a device
*** to a key code (if not present? Override?)
*** display an optional message
** remove all user information from a device
*** Factory reset
*** Display message and contact phone
*** lock to a key code
* Securely display UI for phone including
** current location
** previous recent locations
* store user & device information (multiple devices)
** How long to store data?
** How reliable does storage need to be?
 
==Get Involved==
<i>Call to action for folks who want to help.</i>
=Design=
==Points of Contact==
Engineer - <i>Name</i> <i>jr@</i>
==Discussions==
https://etherpad.mozilla.org/wheresmyfox-2013-10-28
==Client API Reference/Documentation==
Client UX was presented by Epic:
 
https://www.dropbox.com/sh/uaxlhzz211br438/rH2UA0Tf6_/WIMF_3.0.pdf
 
==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 [https://github.com/hueniverse/hawk 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 <i>ID</i> returned in the <code>/$v/init</code> call.
 
    <i>key</i> => {"lastPosition":{"lat":<i>lat</i>,            // The last position reported by track
                            "lon":<i>lon</i>,
                            "alt":<i>altitude?</i>,      // Optional "altitude", if provided
                            "tim":<i>UTC</i>},            // UTC Timestamp
            "previousPositions":[{<i>position</i>},...],  // the last 5? position reports for the device
            "state":"<i>(rtn)</i>",                      // the state the server thinks the device is in
            "lockable"<sup>1</sup>:True|False,                // does the device have a user supplied key code<sup>1</sup>
            "lastExchange":<i>UTC</i>                    // last time an exchange happened.
            "pendingCommand": {<i>outboundCommand</i>}
            }
   
    <i>user</i> => ["<i>key</i>:<i>name</i>",...]              // A list of known keys & user friendly names for devices
 
<sup>1</sup>Note: this should be queried on device. User might set a passcode while the device is active or between updates.
 
=== API ===
For this API discussion:
 
<i>$v</i> - API Version (currently 1)
 
<i>$id</i> - Globally unique ID for a device
 
Unless otherwise specified, all exchanged JSON blocks are signed using
[https://github.com/hueniverse/hawk HAWK] (not shown here for simplicity).
Standard HTTP responses apply (401, 500, 301)
 
==== POST /$v/register ====
from device:
    {"assert":$assertion,
    "pushurl":$simplePushURL,
    "deviceid":$deviceUniqueId,
    "secret":$HawkSecretHashKey}
 
arguments:<br>
<b>$assertion</b> - this is the Firefox Accounts/Persona user assertion.<br>
<b>$SimplePushURL</b> - this is the SimplePush registration URL. If this
changes the device must call register again, specifying the device_id. <br>
<b>$deviceUniqeId</b> - the existing $deviceUniqueId returned by previous
registration. If this is the first time the device is registering, no
value should be set. If the $deviceUniqueId is not recognized by the server
as belonging to the $UUID, it is ignored and a new $deviceUniqueId is
returned.<br>
<b>$HawkSecretHashKey</b> - a HAWK valid secret hash key for the device.<br>
 
reply from server:
    {"id":$deviceUniqueId}
 
arguments:<br>
<b>$deviceUniqueId</b> - A unique designator for the device. All
 
After device registration, a device should immediately call
POST /$v/cmd/$deviceUniqueId as if it had just received the following
command:
 
    {"t":{"p":1,"d":1}}
 
This should return the devices current location.
 
==== POST /$v/cmd/$deviceUniqueId====
A device may acknowledge the last commands received and additional
information as appropriate. See <i>Device commands</i> for
details about these commands. If a given $deviceUniqueId 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.
 
<b>Replies for the "l", "r", "m", or "e" command:</b><br>
the device shall return an object containing a "status" and optionally an
"error" string.<br>
For example, a successful lock and ring would return:
    {"l":{"ok":true},"r":{"ok":true}}
In the case of an error with the ringer:
    {"l":{"ok":true},"r":{"ok":false,"error":"no ringtone found"}}
 
<b>For the "t" command:</b><br>
the device shall return an object that includes the "ok" status, <b>la</b>titude,
<b>lo</b>ongitude, device <b>ti</b>me as UTC and other related positional
information, and lock <b>k</b>ey code present boolean.<br>
If the tracking information is not available, it will also report "ok" as
false and optionally include an "error" string.<br>
For example, a successful tracking request would return:
    {"t":{"ok":true, "la":37.388017, "lo":-122.0833, "ti":1234567890, "k":true}}
Periodic updates for "t" commands do not need to include other commands. 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.
 
The body of the POST reply shall optionally contain further commands from the
server. The following section describes these commands.
 
===== Device commands =====
 
<b>Commands</b> consist of a JSON object containing zero or more of the following:
 
    {"<i>command</i>": {<i>arguments</i>},... }
 
<dl>
<dt><b>l</b>ock
<dd>Specify the lock <b>c</b>ode 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.<br>
Example:<br>
    {"l":{"c":1234}}
<dt><b>r</b>ing
<dd>Cause the device to ring every <b>p</b>eriod seconds for a
<b>d</b>uration of seconds. Specifying a duration of "0" stops the device
from ringing.<br>
Example:<br>
    {"r":{"p":10,"d":60}}
<dt><b>m</b>essage
<dd>Display a message on the device consisting of a contact <b>n</b>umber
and text <b>m</b>essage. <br>
contact numbers may only consist of the following: <code>0123456789 +-()</code>,
and is limited to 25 characters.<br>
message text may only be 100 or less standard ASCII, non-control
characters.<br>
Example:<br>
    {"m":{"n":"+1 (408) 555-555", "m":"Help, I'm lost. Please return me!"}}
<dt><b>t</b>rack
<dd>Begin active location tracking on the device, reporting the devices
position every <b>p</b>eriod second for a <b>d</b>uration of seconds.
See POST /$v/cmd/$deviceUniqueId for how the device reports this
information. Specifying a duration of 0 stops the device from reporting
its location.<br>
Example:<br>
    {"t":{"p":10,"d":300}}
<dt><b>e</b>rase
<dd>Erase the device. This performs a factory reset.<br>
Example:<br>
    {"e":{}}
</dl>
 
Any of the above commands may be combined into a single command. For
example, to lock a phone, display a message with contact number and cause
the device to ring ever 30 seconds for 5 minutes:
 
    {"l":{"c":1111},
    "m":{"n":"555-555-5555","m":"Please return me!"},
    "r":{"p":30,"d":300}}
 
==Platform Requirements==
<i>What are the things this needs (OS, language, databases, etc.)?</i>
 
==Libraries Required==
<i>List of external project dependencies. (Stuff that's not pulled in via the installation script)</i>
* http://godoc.org/github.com/tent/hawk-go
 
==Code Repository==
<i>Links to the published code bases</i>
==Release Schedule==
<i>Predicted code delivery dates</i>
 
=QA=
==Points of Contact==
Engineer - <i>Ed Wong</i> <i>edwong@</i>
 
==Test Framework==
=Security and Privacy=
Tracking bug: [https://bugzilla.mozilla.org/show_bug.cgi?id=935724 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
==Points of Contact==
Legal - udevi@
 
 
==Questionnaire Answers==
===1.1 Goal of Feature ===
===2. Potential Threat Vectors and Mitigation Points===
==Review Status==
https://bugzilla.mozilla.org/show_bug.cgi?id=935725
 
see https://wiki.mozilla.org/Security/Reviews
==Issues and Resolutions==
 
=Operations=
 
==Points of Contact==
==Deployment Architecture==
''Bugzilla Tracking # '' -
==Escalation Paths==
==Lifespan Support Plans==
=Logging and Metrics=
==Points of Contact==
==Tracking Element Definitions==
==Data Retention Plans==
==Dashboard URL==
=Customer Support=
==Points of Contact==
==Sumo Tags==
==Review Meeting==

Latest revision as of 20:42, 11 August 2014

Redirect to:

Retrieved from "https://wiki.allizom.org/index.php?title=CloudServices/WheresMyFox&oldid=1004702"