libadb 0.9.0

Low-level ADB protocol library for direct TCP and USB communication
Documentation

libadb

CI coverage

Low-level ADB (Android Debug Bridge) wire-protocol library for Rust.

Talks to a device directly over TCP or USB — no adbd fork/exec, no adb binary, no platform-tools dependency. Supports devices running Android 9 or later. no_std + alloc core with optional async runtimes; a separate libadb-ffi crate exposes a C ABI.

Status: pre-1.0 — the public API may change in semver-breaking ways before 1.0.

English · Русский

Workspace

This repository is a Cargo workspace with two published crates:

Crate Type Purpose
libadb rlib no_std + alloc core protocol library
libadb-ffi cdylib / staticlib / rlib C ABI on top of libadb

libadb itself is rlib-only, so a pure no_std + alloc consumer never drags in cdylib / staticlib linkage requirements (allocator, panic handler). The libadb-ffi crate is where those live.

Feature flags (libadb)

Flag What it enables
tokio tokio::net::TcpStream transport (default)
smol smol::net::TcpStream transport; combinable with tokio
nusb USB transport via nusb (pure-Rust); combinable with rusb
rusb USB transport via rusb (libusb); combinable with nusb
usb Convenience alias — enables the default USB backend (nusb)
split Full-duplex Reader/Writer pair with no bundled runtime (pulls in std); implied by every feature above
runtime Set by tokio and smol, not by hand: it lets the examples say they need one of the two
keys Built-in RSA host key (keys::AdbKey): generation, PKCS#8 load/save, ADB public-key encoding; no_std + alloc
host-keys keys::store on top of keys: read ~/.android/adbkey, or generate and persist one; pulls in std
tls ADB over TLS — wireless debugging on Android 11+; implies keys and split, pulls in std
pairing adb pair: put a key on a device that has never seen it; implies tls

Features are additive: any combination compiles. Which runtime dials a socket and which backend opens a USB device are type arguments (transport::runtime::Runtime, transport::UsbBackend), not features, so an unrelated crate enabling smol or rusb cannot change what your code talks to. To use the libusb backend, disable defaults and enable rusb directly:

libadb = { version = "0.9", default-features = false, features = ["tokio", "rusb"] }

The core crate is no_std + alloc; any runtime feature pulls in std.

Quick start

[dependencies]
libadb = { version = "0.9", features = ["tokio"] }

One-shot command over shell::v2:

use libadb::shell::v2;
use libadb::{Connection, ConnectionConfig, Feature, HostBanner, TokioTcp};

let tcp = tokio::net::TcpStream::connect("127.0.0.1:5555").await?;
tcp.set_nodelay(true)?; // ADB is chatty; Nagle costs a round per exchange
let transport = TokioTcp::new(tcp);

let mut conn = Connection::connect(
    transport,
    auth, // your `libadb::auth::Authenticator` impl
    HostBanner::Features(&[Feature::ShellV2]),
    ConnectionConfig::new(),
).await?;

let mut rx = [0u8; 64 * 1024];
let out = v2::exec(&mut conn, "getprop ro.product.model", &mut rx).await?;
println!("{}", core::str::from_utf8(&out.stdout)?);

HostBanner is what the host announces in its CNXN: a feature list, as here, HostBanner::default() for everything the library implements, or HostBanner::Raw for bytes of your own. ConnectionConfig::new() keeps the desktop limits; "Memory budget" below shows how to tighten them.

Authenticator is a user-supplied trait, but the keys feature ships one: keys::AdbKey parses the key adb keeps in ~/.android/adbkey — reusing the identity the device already trusts — or generates one of its own, with no adb installation involved. With host-keys the crate also finds and writes those files for you:

use libadb::keys::{store, KeyName};

// `rng` is any `CryptoRngCore` — `OsRng` on a host, a hardware TRNG on
// a microcontroller. Loading draws from it once, to seed the generator
// the key then blinds each signature with; generating draws on it
// throughout the prime search as well, and seeds that generator after.
// Either way the borrow ends when the constructor returns.
// Reuse ~/.android/adbkey, or create it — the device asks the user to
// confirm a new key once, exactly as it does for adb itself.
let auth = store::load_or_generate(&dir, &mut rng, KeyName::new("user@host")?)?;

The directory is always a parameter: the library reads no environment and picks no path of its own. An existing key is reused untouched, and one that will not parse is an error rather than a reason to overwrite an identity a device may already trust.

Without std — on a microcontroller — keys::AdbKey does the same work directly, leaving the storing to you: generate takes any CSPRNG you hand it, to_pkcs8_der plus encode_key_record frame the key, checksum and all, for a flash region with no filesystem, and public_key_line() gives the adbkey.pub line. The rsa and zeroize crates this API speaks are re-exported as libadb::keys::{rsa, zeroize}, so there is one version to match rather than two manifests to guess at.

To learn whether a device already trusts a key without putting the "Allow USB debugging?" dialog on its screen, return false from Authenticator::offer_public_key: a device that does not know the key then ends the handshake with AuthError::KeyNotTrusted, and the key never leaves the host.

Memory budget

ConnectionConfig bounds everything the library allocates per connection:

Field Default (new()) embedded() Effect
max_payload 1 MiB 8 KiB advertised in CNXN — caps any single inbound packet
initial_ack_bytes 32 MiB 32 KiB delayed-ACK credit granted per channel
max_rx_per_channel unbounded 64 KiB fuse on data buffered for an unread channel
max_channels 32 32 slots in the channel table, allocated up front
max_banner_properties 64 64 properties the device banner may carry
use libadb::{Connection, ConnectionConfig, Feature, HostBanner};

let conn = Connection::connect(
    transport,
    auth,
    HostBanner::Features(&[Feature::ShellV2]),
    ConnectionConfig::embedded(),
).await?;

The default matches what adb does on a desktop. On a microcontroller it does not fit: a device that takes the advertised 1 MiB at face value can send a packet the receive buffer has to hold whole, and with only a few hundred KiB of RAM a single 64 KiB WRTE is already enough to exhaust the heap. Since adbd never exceeds the size the host advertised, embedded() (or new().with_max_payload(…)) is what keeps the footprint bounded.

Protocol version

The library offers 0x0100_0001 in its CNXN and then adopts min(mine, the device's), readable via Connection::protocol_version(). ADB retired payload checksums at exactly that version, so from there on outgoing packets leave data_check zero — the same thing adb does.

Two deliberate exceptions keep older peers working: handshake packets (CNXN, AUTH) are still checksummed, because the device has not announced its version yet, and an inbound non-zero data_check is always verified. A device reporting 0x0100_0000 gets checksummed traffic throughout.

The sum is a full pass over every payload. On a microcontroller that dominates the cost of a channel write: skipping it made a 32 KiB write_stdin roughly four times faster.

Supported services

Module Wire service Notes
shell::v1 shell: Interleaved stdout/stderr, no exit code
shell::v2 shell,v2,…: Framed stdout/stderr/exit, PTY + window-size
exec exec: Binary-clean stdout, raw PTY, no exit code
cmd abb_exec/abb/shell:cmd Auto-selects the best available service
abb abb_exec:, abb: Android 10+ Binder Bridge
logcat shell,v2,raw:logcat -B … Binary logcat entries, parsed
sync sync: STAT/LIST/SEND/RECV, v1 + v2
track_app track-app: Streaming debuggable-process snapshots
reverse reverse:… Reverse-forward rules; incoming channels via accept_incoming (Writer::listen_incoming under Reader::run)

See the libadb/examples/ directory for end-to-end programs (cargo run -p libadb --example shell_v2 -- 127.0.0.1:5555 …).

Limitations

  • Android 11+ wireless debugging needs the tls feature and Connection::connect_tls; in the C ABI, libadb-ffi's own tls feature and plain adb_connect. Without it the device answers the handshake with STLS and connect fails with ProtocolError::TlsRequired (ADB_ERR_TLS_REQUIRED from C).
  • adb pair needs the pairing feature — on libadb-ffi too, where it adds adb_pair. A key the device already trusts, one approved at a USB prompt, is accepted over TLS without it: adbd checks both against the same store.
  • The wireless-debugging port changes every time the setting is switched on, and this crate does no DNS-SD, so the caller supplies it.
  • With delayed ack negotiated, an OKAY must carry its 4-byte credit, as AOSP's adbd always does; the operation that received a creditless one fails with ShortReadyPayload rather than having a budget guessed for it.
  • USB reads cannot be cancelled safely mid-transfer on either backend: select takes effect between reads (see ReadCancelSafety), and aborting an in-flight read forfeits the connection. The rusb backend blocks the thread the transfer runs on — a runtime pool thread, or the caller itself under the Inline runtime and under Tokio outside an active Tokio runtime — until the device answers or detaches; nusb waits without parking an OS thread.

Transports

  • TokioTcp — wraps tokio::net::TcpStream
  • SmolTcp — wraps smol::net::TcpStream
  • transport::nusb::UsbTransport / transport::rusb::UsbTransport — USB transports with device discovery by VID:PID or serial, one per backend. Both implement embedded_io_async::{Read, Write} + libadb::Splittable and are reached through the same connect::<Runtime, Backend>("usb://…") entry point (enumeration is offloaded to the runtime's blocking pool so it never stalls the executor). They differ in trade-offs — pure-Rust nusb does async bulk transfers via its own IO backend, rusb/libusb wraps blocking ones — and in their error enums (UsbError, UsbConnectError have different variants and wrap different underlying types), so switching backends touches any code that names those types.
  • Any type implementing embedded_io_async::{Read, Write} + libadb::Splittable works as a custom transport; the service modules also need transport::ReadCancelSafety, which tells select whether a read may be dropped mid-way

Runtime and backend are chosen per call site, so a build may carry all of them at once:

use libadb::transport::{any, common::NoUsb, nusb::Nusb, rusb::Rusb};
use libadb::transport::runtime::{Smol, Tokio};

let a = any::connect::<Tokio, Nusb>("usb://18d1:4ee7").await?;
let b = any::connect::<Smol, Rusb>("usb://serial/ABC123").await?;

// `NoUsb` is a choice, not a statement about the build: both
// backends above are compiled in, and this call still fails at
// runtime because it asked for neither.
let Err(err) = any::connect::<Tokio, NoUsb>("usb://").await else {
    unreachable!("NoUsb cannot serve usb://")
};
// tcp:// works regardless of the backend parameter.
let tcp = any::connect::<Tokio, NoUsb>("tcp://127.0.0.1:5555").await?;

Connection::split() gives you a full-duplex Reader / Writer pair so that a reader task and a writer task can coexist on the same connection without locking each other out. Hand the Reader to Reader::run and the connection serves any number of channels at once: every service module takes a libadb::Session — a Connection or a Writer — so each task runs its own shell, logcat or sync over a clone of the Writer, and none waits on another's traffic. Over USB, where a device admits a single connection, this is how several services share it.

let (reader, writer) = conn.split()?;
tokio::spawn(reader.run());

let mut logs = writer.clone();
tokio::spawn(async move {
    let mut rx = vec![0; 64 * 1024];
    let mut logcat = logcat::open(&mut logs, &[], &mut rx).await?;
    loop {
        match logcat.read_entry().await {
            Ok(entry) => { /* … */ }
            Err(libadb::Error::ChannelClosed) => break, // logcat exited with 0
            Err(e) => return Err(e),
        }
    }
    Ok::<_, libadb::Error<_>>(())
});

let mut shell = writer.clone();
let mut rx = vec![0; 64 * 1024];
let out = shell::v2::exec(&mut shell, "getprop ro.product.model", &mut rx).await?;

C ABI (libadb-ffi)

libadb-ffi is a thin cdylib / staticlib wrapper over libadb with no async runtime of its own — a tiny internal executor drives the async transport so callers see a fully blocking API. The header lives at libadb-ffi/include/libadb.h and covers:

  • connection lifecycle and handshake
  • host keys (adb_key_load_or_generate) — reuse ~/.android/adbkey or create one on first run, no adb installation needed
  • caller-supplied authenticators (adb_connect_with_authenticator) — for private keys living outside the process (HSM, remote signer)
  • Android 11+ wireless debugging (--features tls) — adb_connect answers the device's STLS with TLS 1.3, presenting the same key; adb_connect_with_authenticator stays in the clear
  • adb pair (adb_pair, --features pairing, which implies tls) — put the key on a device that has never seen it, through its pairing dialog
  • channel open/read/write/close
  • shell_v2 session with framing, stdin, PTY resize
  • structured feature queries (adb_connection_has_feature, adb_feature_name, adb_connection_features)

Build (no async runtime is linked; add --features usb or --features rusb for USB transport support, --features tls for wireless debugging, --features pairing for adb_pair as well):

cargo build -p libadb-ffi --features pairing
cc -I libadb-ffi/include -o ffi_shell libadb-ffi/examples/ffi_shell.c \
   -L target/debug -ladb -lpthread -ldl -lm
cc -I libadb-ffi/include -o ffi_pair libadb-ffi/examples/ffi_pair.c \
   -L target/debug -ladb -lpthread -ldl -lm

A full interactive-shell C client is in libadb-ffi/examples/ffi_shell.c, and adb pair from C in libadb-ffi/examples/ffi_pair.c.

Layout

libadb/                    # core protocol library (rlib, no_std + alloc)
  src/base/                wire protocol, channels, banner, auth trait
  src/transport/           TCP (tokio/smol) and USB (nusb or rusb) transports
  src/shell/v{1,2}.rs      shell services
  src/{exec,cmd,abb}.rs    exec / cmd-fallback / Android Binder Bridge
  src/{logcat,sync}.rs     logcat stream and file-sync protocol
  src/track_app.rs         track-app snapshots
  src/split.rs             full-duplex Reader/Writer pair
  tests/                   integration tests via fake_device fixture
  examples/                Rust examples per service
libadb-ffi/                # C ABI (cdylib + staticlib + rlib)
  src/                     C entry points + RSA Authenticator
  include/libadb.h         C header
  examples/ffi_shell.c     interactive shell client in C
  examples/ffi_pair.c      adb pair in C
fuzz/                      cargo-fuzz targets (excluded from workspace)

Development

Tasks live in a justfile; CI drives the same recipes, so a green just ci locally means the same commands and feature sets the workflow runs.

just                      # list recipes
just ci                   # fmt, clippy, tests, docs, MSRV, no_std, all-features
just clippy-one tokio,smol   # one configuration
just doc                  # docs per narrow feature combination
just ffi-example          # build the C example against the cdylib
just fuzz packet_decode 60

License

MIT License.