View source for DevTools/WiFi Debugging/Design

== 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 ===
Thus far, we’ve come to basic agreement that we should encrypt data in transit (via TLS or similar). However, the authentication mechanism is not yet decided. The UX flows here will need to be updated once a final authentication scheme has been determined. Current options under consideration include:
* Self-signed client & server certs via TLS
* Short code method, such as TLS-SRP
* Integration with Firefox Accounts

== Definitions ==
* '''Device / Server''': Firefox OS phone (or Fennec, remote Firefox, etc.)
* '''Computer / Client''': Machine running desktop Firefox w/ WebIDE

== Proposal ==
This proposal uses a public / private key signature authentication scheme to accept connections from devices. After first connection from a new Client, the Client is saved on the Device (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.

=== Enabling Wi-Fi Debugging ===
# User goes to Developer menu on Device
# User checks "Remote Debugger over Wi-Fi" to enable the feature
#* Persistent notification displayed in notification bar reminding user that this is enabled
# Device begins listening on random TCP socket via Wi-Fi only
# Device announces itself via service discovery
#* Announcements only go to the local LAN / same subnet

The Device remains listening as long as the feature is enabled.

=== Using Wi-Fi Debugging (new computer) ===
Here are the details of connecting from a new computer to the device:

# Computer detects Device as available for connection via service discovery
# User presses "Connect to device Foo" on computer
# Initial connection established, authentication begins
# Device sends a random number to Computer
# Computer signs the number using its private key, sends to Device
# Since the Computer is new, Device will fail to verify the signature
# Computer presents it public key to the Device
# Computer displays hash of public key for visual verification during step 9
# User is shown a Allow / Deny / Always Allow prompt on the Device with Computer name and hash of the public key
#* 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 the Computer’s public key is saved for future attempts

=== Using Wi-Fi Debugging (known computer) ===
Here are the details of connecting from a known computer (saved via Always Allow) to the device:

# Computer detects Device as available for connection via service discovery
# User presses "Connect to device Foo" on computer
# Initial connection established, authentication begins
# Device sends a random number to Computer
# Computer signs the number using its private key, sends to Device
# Since the Computer is known, Device can verify signature using matching public key
# Connection proceeds

=== Other Details ===
* When there is a socket listening for connections, they will only be accepted via Wi-Fi
** 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.

All of the data is unencrypted, so it can be overheard in transit. The main cases I can think of where potentially private data would go over the wire is the Network tab's view of request data, but there may be other concerns depending on the apps being debugged. Even then, I don't know that this is a large concern, assuming we loudly announce this case when enabling Wi-Fi debugging.

=== Encryption ===
(Note: This section is in flux and still being discussed. See also the Security section in the overview.)

This proposal could be strengthened against overhearing data by using TLS to encrypt the data in transit. If that decision is made, it seems logical to the replace the RSA key exchange for authentication with a self-signed client auth certificate, so that TLS would then handle both the authentication and encryption. In slightly more detail:

* The listening socket on the Device would only accept TLS connections
* User would approve a hash of a new client auth certificate on first connection

=== Comparison to ADB ===
This proposal (at least in unencrypted form) is quite similar to secure debugging with ADB. In fact it would be nice to just use this ADB feature, but 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