Bug 1103120 - Part 1: Add WiFi auth design doc. r=past
authorJ. Ryan Stinnett <jryans@gmail.com>
Mon, 26 Jan 2015 12:47:12 -0600
changeset 225843 3a36bc50398e17f761cb9914f5a2389c3c2220aa
parent 225842 9bfda2f52e8221dc85112f7a9117e7e55428cc44
child 225844 c3b4fc516509a3b0cb1fca2e7b4a1673720b89c9
push id28176
push userryanvm@gmail.com
push dateMon, 26 Jan 2015 21:48:45 +0000
treeherdermozilla-central@38e4719e71af [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerspast
bugs1103120
milestone38.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1103120 - Part 1: Add WiFi auth design doc. r=past
toolkit/devtools/security/docs/wifi.md
new file mode 100644
--- /dev/null
+++ b/toolkit/devtools/security/docs/wifi.md
@@ -0,0 +1,154 @@
+Overview
+--------
+
+### Remote Debugging Today
+
+Connecting to the Dev Tools debugging server on a remote device (like
+B2G) via USB (which requires ADB) is too complex to setup and use.
+Dealing with ADB is confusing, especially on Windows and Linux where
+there are driver issues / udev rules to set up first. We have made
+various attempts to simplify this and probably will continue to try our
+best, but it doesn't seem like the UX will ever be great with ADB
+involved.
+
+### Wi-Fi
+
+We're interested in making the debugging server available over Wi-Fi,
+mainly in an attempt to simplify the UX. This of course presents new
+security challenges to address, but we must also keep in mind that **if
+our plan to address security results in a complex UX, then it may not be
+a net gain over the USB & ADB route**.
+
+To be clear, we are not trying to expose ADB over Wi-Fi at all, only the
+Dev Tools debugging server.
+
+### Security
+
+TLS is used to provide encryption of the data in transit. Both parties
+use self-signed certs to identify themselves. There is a one-time setup
+process to authenticate a new device. This is explained in many more
+details later on in this document.
+
+Definitions
+-----------
+
+-   **Device / Server**: Firefox OS phone (or Fennec, remote Firefox,
+    etc.)
+-   **Computer / Client**: Machine running desktop Firefox w/ WebIDE
+
+Proposal
+--------
+
+This proposal uses TLS with self-signed certs to allow Clients to
+connect to Servers through an encrypted, authenticated channel. After the
+first connection from a new Client, the Client is saved on the Server
+(if the user wants to always allow) and can connect freely in the future
+(assuming Wi-Fi debugging is still enabled).
+
+### Default State
+
+The device does not listen over Wi-Fi at all by default.
+
+### Part A: Enabling Wi-Fi Debugging
+
+1.  User goes to Developer menu on Device
+2.  User checks "DevTools over Wi-Fi" to enable the feature
+    -   Persistent notification displayed in notification bar reminding
+        user that this is enabled
+
+3.  Device begins listening on random TCP socket via Wi-Fi only
+4.  Device announces itself via service discovery
+    -   Announcements only go to the local LAN / same subnet
+    -   The announcement contains hash(DeviceCert) as additional data
+
+The Device remains listening as long as the feature is enabled.
+
+### Part B: Using Wi-Fi Debugging (new computer)
+
+Here are the details of connecting from a new computer to the device:
+
+1.  Computer detects Device as available for connection via service
+    discovery
+2.  User chooses device to start connection on Computer
+3.  TLS connection established, authentication begins
+4.  Device sees that ComputerCert is from an unknown client (since it is
+    new)
+5.  User is shown an Allow / Deny / Always Allow prompt on the Device
+    with Computer name and hash(ComputerCert)
+    -   If Deny is chosen, the connection is terminated and exponential
+        backoff begins (larger with each successive Deny)
+    -   If Allow is chosen, the connection proceeds, but nothing is
+        stored for the future
+    -   If Always Allow is chosen, the connection proceeds, and
+        hash(ComputerCert) is saved for future attempts
+
+6.  Device waits for out-of-band data
+7.  Computer verifies that Device's cert matches hash(DeviceCert) from
+    the advertisement
+8.  Computer creates hash(ComputerCert) and K(random 128-bit number)
+9.  Out-of-band channel is used to move result of step 8 from Computer
+    to Device
+    -   For Firefox Desktop -\> Firefox OS, Desktop will make a QR code,
+        and FxOS will scan it
+    -   For non-mobile servers, some other approach is likely needed,
+        perhaps a short code form for the user to transfer
+
+10. Device verifies that Computer's cert matches hash(ComputerCert) from
+    out-of-band channel
+11. Device sends K to Computer over the TLS connection
+12. Computer verifies received value matches K
+13. Debugging begins
+
+### Part C: Using Wi-Fi Debugging (known computer)
+
+Here are the details of connecting from a known computer (saved via
+Always Allow) to the device:
+
+1.  Computer detects Device as available for connection via service
+    discovery
+2.  User choose device to start connection on Computer
+3.  TLS connection established, authentication begins
+4.  Device sees that ComputerCert is from a known client via
+    hash(ComputerCert)
+5.  Debugging begins
+
+### Other Details
+
+-   When there is a socket listening for connections, they will only be
+    accepted via Wi-Fi
+    -   The socket will only listen on the external, Wi-Fi interface
+    -   This is to ensure local apps can't connect to the socket
+-   Socket remains listening as long as the feature is enabled
+
+### UX
+
+This design seems convenient and of relatively low burden on the user.
+If they choose to save the Computer for future connections, it becomes a
+one click connection from Computer to Device, as it is over USB today.
+
+### Possible Attacks
+
+Someone could try to DoS the phone via many connection attempts. The
+exponential backoff should mitigate this concern. ([bug
+1022692](https://bugzilla.mozilla.org/show_bug.cgi?id=1022692))
+
+### Comparison to ADB
+
+While it would be nice if we could instead leverage ADB here, that
+doesn’t seem viable because:
+
+-   ADB comes with a lot of setup / troubleshooting pain
+    -   Users don’t understand it or why it is needed for us
+    -   Each OS has several UX issues with ADB that make it annoying to
+        use
+-   ADB has a much larger attack surface area, simply because it has
+    many more lower level functions than the Developer Tools protocol we
+    are exposing here
+
+Acknowledgments
+---------------
+
+-   J. Ryan Stinnett started this project from the DevTools team
+-   Brian Warner created many of the specific details of the authentication
+    protocol
+-   Trevor Perrin helped vet the authentication protocol