Manager ADB Wireless Pairing
Overview
The manager app implements two related ADB flows under manager/src/main/java/moe/shizuku/manager/adb: a low-level ADB client for talking to an already-enabled daemon, and the Android 11+ wireless debugging pairing flow that authorizes the app's ADB key.
manager/…/AdbProtocol.kt defines the ADB command and auth constants used by both the message encoder and client. manager/…/AdbMessage.kt serializes/deserializes 24-byte little-endian ADB packet headers, appends NUL terminators for string payloads, computes ADB's additive payload checksum, and validates incoming command magic/checksum before callers act on a packet.
manager/…/AdbKey.kt owns the local ADB identity. It stores the RSA private key bytes through PreferenceAdbKeyStore, where the stored blob is Base64 in SharedPreferences but encrypted/decrypted with an Android Keystore AES-GCM key named _adbkey_encryption_key_. If no stored private key can be recovered, it generates a 2048-bit RSA key, persists it, derives the matching public key, and exposes two protocol-specific views: sign() for legacy A_AUTH token signing with the ADB RSA padding block, and adbPublicKey for the Android RSAPublicKey wire format plus the key name. The same key object also builds a TLS 1.3 SSLContext with a client certificate chain for Android 11+ ADB TLS connections.
manager/…/AdbClient.kt connects to an ADB endpoint by opening a TCP socket, sending A_CNXN host::, then handling either modern TLS upgrade (A_STLS) or legacy A_AUTH token signing/public-key submission before requiring a final A_CNXN. After connection, shellCommand() opens a single shell:<command> stream with local id 1, forwards A_WRTE payload bytes to its listener, acknowledges writes with A_OKAY, and closes when it receives A_CLSE.
Wireless debugging discovery is handled by manager/…/AdbMdns.kt on Android R+. It wraps NsdManager.discoverServices() for _adb-tls-pairing._tcp or _adb-tls-connect._tcp, resolves found services, and only reports a port when the resolved host address is one of the device's own network-interface addresses and binding 127.0.0.1:<port> fails. In this app's flow, that makes the observer receive a loopback port for the local wireless debugging service rather than an arbitrary device on the network.
The pairing UI starts at manager/…/AdbPairingTutorialActivity.kt, which is registered as .adb.AdbPairingTutorialActivity in manager/…/AndroidManifest.xml. The activity inflates manager/…/adb_pairing_tutorial_activity.xml, checks whether app notifications and the AdbPairingService.notificationChannel are enabled, hides the tutorial steps when notifications are blocked, and opens either app notification settings or Android developer settings (ACTION_APPLICATION_DEVELOPMENT_SETTINGS with toggle_adb_wireless) from the on-screen buttons. When notifications are allowed, it starts AdbPairingService as a foreground service; on Android S+ it catches ForegroundServiceStartNotAllowedException and falls back to startService() after checking the android:start_foreground app-op.
manager/…/AdbPairingService.kt is the foreground notification-driven pairing orchestrator registered as a non-exported shortService in manager/…/AndroidManifest.xml. On start, it creates the adb_pairing notification channel and starts AdbMdns for _adb-tls-pairing._tcp. When discovery reports a valid port, the service replaces the searching notification with an input notification carrying a RemoteInput for the pairing code and a pending intent that stores the discovered port in the service intent; the port is copied into the intent because the service can be killed while the user is typing. On reply, it creates AdbKey(PreferenceAdbKeyStore(ShizukuSettings.getPreferences()), "shizuku"), connects to 127.0.0.1:<port> with AdbPairingClient, and posts a success/failure notification based on the result or exception class.
manager/…/AdbPairingClient.kt implements the Android wireless pairing protocol. It first opens a TCP socket to the discovered port, wraps it in an SSLSocket from AdbKey.sslContext, exports 64 bytes of TLS keying material with Conscrypt label adb-label�, and concatenates that material with the user-entered pairing code. That derived password initializes the private PairingContext, whose native methods are provided by manager/…/adb_pairing.cpp. The client then sends and receives a version-1 big-endian pairing header plus a SPAKE2 message, initializes the cipher from the peer SPAKE2 message, encrypts its 8192-byte PeerInfo containing the app's ADB public key, and decrypts the peer info response. A decrypt failure is surfaced as AdbInvalidPairingCodeException, which AdbPairingService.kt maps to the pairing-code error notification text.
The native bridge in manager/…/adb_pairing.cpp backs PairingContext by registering JNI methods for the Kotlin class moe/shizuku/manager/adb/PairingContext during JNI_OnLoad. It uses BoringSSL SPAKE2 with the ADB client/server role names (adb pair client, adb pair server), derives a 16-byte AES-128-GCM key via HKDF-SHA256 with info string adb pairing_auth aes-128-gcm key, and seals/opens payloads with monotonically increasing little-endian sequence numbers copied into the AEAD nonce. manager/…/adb_pairing.h is only an include guard used by this bridge.
Coupling
- If manager/…/AdbPairingClient.kt changes the
PairingContextKotlin class name, native method names, or JNI signatures, also update manager/…/adb_pairing.cpp;JNI_OnLoadregisters against the hard-coded class pathmoe/shizuku/manager/adb/PairingContextand exact descriptors. - If the pairing packet header or peer-info sizes in manager/…/AdbPairingClient.kt change, verify byte order and limits against both the Java/Kotlin reader/writer and manager/…/adb_pairing.cpp; pairing headers are big-endian in Kotlin, while ADB protocol messages in manager/…/AdbMessage.kt are little-endian.
- If manager/…/AdbKey.kt changes ADB public-key encoding, verify both manager/…/AdbClient.kt and manager/…/AdbPairingClient.kt; the same
adbPublicKeybytes are sent as legacyA_AUTH_RSAPUBLICKEYdata and as encrypted pairingPeerInfo. - If manager/…/AdbMdns.kt changes how it reports ports, verify manager/…/AdbPairingService.kt; the service assumes reported ports are local loopback pairing ports and unconditionally connects to host
127.0.0.1. - If notification channel IDs, pending-intent request codes, or remote-input keys in manager/…/AdbPairingService.kt change, verify manager/…/AdbPairingTutorialActivity.kt; the activity gates tutorial visibility and service startup on
AdbPairingService.notificationChannel, and the service relies on the reply intent carrying both the code and the discovered port. - If the
AdbPairingServicemanifest declaration in manager/…/AndroidManifest.xml changes, verify manager/…/AdbPairingTutorialActivity.kt; the activity uses foreground-service startup APIs and the service currently declaresforegroundServiceType="shortService".
Risks
- manager/…/AdbPairingService.kt has churn around foreground-service notification state and lifecycle: history includes
627acd2 Fix onStartCommand,b21ae24 Fix update foreground service notification,7514f61 Avoid "searching" notification shows after succeed,a58b9ae Service could be killed when the user is typing pairing code,892309e Don't let ForegroundServiceStartNotAllowedException crash the app, and2d56a5a Stop service. If start/reply/stop handling is changed, pairing can leave a stale notification, lose the discovered port while the user types, or fail to start on Android S+. - manager/…/AdbPairingClient.kt and manager/…/adb_pairing.cpp are sensitive to protocol constants and byte layout. History includes early fixes such as
c374e4c fix bug,70a85e4 fix print type,094c86a add missing memset 0, ande88de6a Fix first time of pairing always fail since recent versions; if SPAKE2 message exchange, exported key label/length, nonce sequencing, or peer-info padding drift from Android's pairing protocol, the user will see pairing failure or an invalid-code error even with a correct code. - manager/…/AdbMdns.kt filters services by matching the resolved host to a local network interface and by probing whether
127.0.0.1:<port>is already bound. History includes3785c20 Support AdbMdns,6729a19 Use mdns only on Android 11, andbc29dd1 Replace "InetAddress.getLoopbackAddress()" with hardcoded "127.0.0.1"; if this local-port heuristic is relaxed or broken, AdbPairingService.kt may prompt for a code for the wrong endpoint or fail withConnectException.