diff options
Diffstat (limited to 'devtools/shared/security/docs/wifi.md')
| -rw-r--r-- | devtools/shared/security/docs/wifi.md | 154 |
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 |