Add m-esr52 at 52.6.0

1 files changed, 154 insertions, 0 deletions

diff --git a/devtools/shared/security/docs/wifi.md b/devtools/shared/security/docs/wifi.md
new file mode 100644
index 000000000..9ba94fc82
--- /dev/null
+++ b/devtools/shared/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