1# Architecture of *ADB Wifi* 2 3ADB has always had the capability to communicate with a device over TCP. However 4the process involved is convoluted and results in an insecure channel. 5The steps are as follows. 6 71. Connect device via USB cable. 82. Accept host's public key in the device UI dialog (pairing). 93. Request adbd to open a TCP server socket 10``` 11$ adb tcpip 5555 12``` 134. Retrieve device's Wi-Fi IP address 14``` 15IP=`adb shell ip route | awk '{print $9}'` 16``` 175. Finally, connect over TCP 18``` 19$ adb connect $IP:5555 20``` 21 22After all these steps, adb server is communicating 23with adbd over TCP unencrypted. 24This means all traffic can be eavesdropped and open to MITM attacks. 25 26## The two problems *ADB Wifi* solves 27 28*ADB Wifi* allows a user to pair a device and a host in a single step, without 29requiring prior USB connection. 30 31Moreover, *ADB Wifi* uses TLS which allows for secure authentication and 32a secure connection after authentication. 33 34## How *ADB Wifi* works 35 36*ADB Wifi* revolves around four capabilities. 37 38- Pair without the user having to click "Allow debugging". 39- Encrypt ADB traffic. 40- Advertise services over the network. 41- Auto-connect to paired devices. 42 43### Pairing 44 45A host and a device are considered *paired* if the host's public key 46is in the device's `/data/misc/adb/adb_keys` or `/adb_keys` files (keystore). After pairing, the 47host can be trusted by the device because the host 48can use its private key to answer the challenges from the device (and the device can verify 49answer using keys from the keystore until a matching public key is found). 50 51To pair, *ADB Wifi* uses a Pairing Server running on the device. 52The Pairing Server communicates using RSA 2048-bit encryption (in a x509 certificate). 53Trust is bootstrapped using a shared secret, seeded either by a six-digit number (pairing code) 54or a 10-digit number (QR code pairing). 55 56### Encrypted traffic 57 58After pairing, and if the user has enabled "Wireless debugging", adbd listens on 59a TCP server socket (port picked at random). This is not the same as the legacy `tcpip` socket. The 60legacy socket greets all communication attempts with an A_AUTH packet whereas 61this socket opens communication with A_STLS which means all traffic will be 62TLS encrypted (and [authentication](../../protocol.txt) is different as well). 63 64All this traffic is handled by the TLSServer which is forwarded to adbd's fdevent. 65When users toggle "Wireless Debugging", they start and stop the TLSServer. 66 67### Network Advertising (mDNS) 68 69All of the elements previously mentioned advertise their presence on the network 70via mDNS. Three service types are used. 71 72- `_adb._tcp`: This is the legacy TCP service started via `adb tcpip <PORT>`. 73- `_adb-tls-pairing._tcp`: The service advertised when the device pairing server is active. 74- `_adb-tls-connect._tcp`: The service advertised when the device TLSServer is active. 75 76Note that all services' instances are published by the device (adb server is merely a consumer 77of mDNS packets). Both `_adb._tcp` and `_adb-tls-connect._tcp` are published directly 78by adbd while `_adb-tls-pairing._tcp` is published via NsdServiceInfo. 79 80#### mDNS Service Instance names 81 82An instance name prefix is usually `adb-` followed by the value of the property `ro.serialno` plus a random suffix added 83by the mdns backend. 84 85The Pairing Server is special. Its service instance name changes whether it is intended 86to be used with a pairing code or a QR code. 87 88- Pairing code: `adb-`<`prop(persist.adb.wifi.guid)`> 89- QR code: `studio-`< RANDOM-10> (e.g: `studio-58m*7E2fq4`) 90 91### Auto-connect 92 93When the host starts, it also starts mDNS service discovery for all three service types. 94Any service instance of type `_adb-tls-connect` being published by the device results in a connection attempt 95by the host (if the device's GUID is known to the host from pairing). If the device was previously paired, 96TLS authentication will automatically succeed and the device is made available to the host. 97 98There is one exception. When the pairing client finishes on the host, it also attempts to connect to the device 99it just paired with. This is because `_adb-tls-connect` was already published before pairing even began, which 100means the host cannot rely on the mDNS `_adb-tls-connect` "Create" event being published. 101 102### Device components communication 103 104On the device, three components must communicate. There is adbd, Framework (AdbDebuggingManager) 105and the mDNS daemon. 106 107The Pairing Server and the TLS server are part of the adbd apex API. 108These two libraries are linked into system_server (AdbDebuggingManager). 109The rest of the communication works via system properties. 110 111- `persist.adb.tls_server.enable`: Set when the Developer Settings UI checkbox "Use wireless debugging" is changed. 112adbd listens for these changes and manages the TLSServer lifecycle accordingly. 113- `service.adb.tls.port`: Set by adbd. Retrieved by Framework so it can publish `_adb-tls-connect`. 114- `ctl.start`: Set to `mdnsd` by adbd to make sure the mDNS daemon is up and running. 115- `persist.adb.wifi.guid`: Where the device GUID (used to build service instance name) comes from. Both adbd 116and Framework retrieve this property to build `_adb-tls-connect` and `_adb-tls-pairing` service instance 117names. 118 119# CLI tools 120 121*ADB Wifi* can be set up and monitored with the command line. 122 123### mdns check 124`$ adb mdns check` tells the user the name of adb's mDNS stack and its version. 125 126``` 127$ adb mdns check 128mdns daemon version [Openscreen discovery 0.0.0] 129``` 130 131### mdns services 132`$ adb mdns services` lists all supported mdns services' instances discovered and still active, 133followed by their service type and their resolved IPv4 address/port. 134``` 135$ adb mdns services 136List of discovered mdns services 137adb-14141FDF600081 _adb._tcp 192.168.86.38:5555 138adb-14141FDF600081-QXjCrW _adb-tls-pairing._tcp 192.168.86.38:33861 139adb-14141FDF600081-TnSdi9 _adb-tls-connect._tcp 192.168.86.38:33015 140studio-g@<xeYnap/ _adb-tls-pairing._tcp 192.168.86.39:55861 141``` 142 143Note: At the moment, IPv6 addresses are resolved but not output by the command. 144 145### pair 146 147If a user starts a Pairing Server on the device (via 148`Settings > System > Developer options > Wireless debugging > Pair device with pairing code`), they 149are presented with both a pairing code and the IPv4:port of the Wi-fi interface. In this case 150the vector to exchange the TLS secret is the user who reads it on the device then types the pairing code on the host. 151 152 153 154With the Pairing Server active, *ADB Wifi* is entirely configurable from the command-line, as follows. 155 156``` 157$ adb pair 192.168.86.38:43811 158Enter pairing code: 515109 159$ adb connect 192.168.86.34:44643 160$ adb devices 161List of devices attached 162adb-43081FDAS000VS-QXjCrW._adb-tls-connect._tcp device 163``` 164 165# Android Studio 166 167## Pair with code 168Android Studio automates pairing with a pairing code thanks to its GUI. 169The advantage compared to the CLI method 170is that it relies on mDNS to detect devices with an active Pairing Server. 171To this effect, Studio polls adb server for service instances of type `_adb-tls-pairing`. 172 173## Pair with QR code 174Studio also introduces a QR code system which is just an easy way to share 175the pairing code between the host and the device. 176 177When a user clicks on "Pair device Using Wi-Fi", they are shown a QR code. 178 179 180 181In the example code above Studio generated a QR code containing the string `WIFI:T:ADB;S:studio-g@<xeYnap/;P:(Aq+v9>Cx>!/;;`. 182The QR code piggyback on [WPA3 Specification](https://www.wi-fi.org/system/files/WPA3%20Specification%20v3.2.pdf#page=25) 183which specifies the format as follows. 184 185``` 186“WIFI:” [type “;”] [trdisable “;”] ssid “;” [hidden “;”] [id “;”] [password “;”] [publickey “;”] “;” 187``` 188 189Tokens are `;` separated. The QR Code contains three tokens 190 1911. Type (marked by `T:` prefix) indicates this is an `ADB` special string. 192 1931. The `ssid` field (marked by `S:` prefix) is repurposed to request a specific service instance name for `_adb-tls-pairing._tcp`. 194The device has a special Camera QR code handler which when it sees 195type `T:ADB` starts a Pairing Server with the requested instance name. Note that the part after `studio-` is randomized. 196This is done so Studio can tell which phone just scanned the QR code (here the instance name requested is `studio-g@<xeYnap/`). 197 1983. The password (marked by `P:` prefix) to use with the Pairing Server (here: `(Aq+v9>Cx>!/`). 199This is the second shared secret vector we mentioned earlier. Here the code is generated 200by Studio and read by the device's camera. 201
