libadb 0.6.0

Low-level ADB protocol library for direct TCP and USB communication
Documentation
use alloc::vec::Vec;
use bytes::{Bytes, BytesMut};
use embedded_io::ErrorType;
use embedded_io_async::{Read, Write};

use super::{Connection, ConnectionConfig};
use crate::base::auth::Authenticator;
use crate::base::device_banner::DeviceBanner;
use crate::base::error::{AuthError, Error, ProtocolError};
use crate::base::protocol::command::{self, Command};
use crate::base::protocol::features::{self, Feature};
use crate::base::protocol::Checksum;
use crate::base::protocol::Packet;
use crate::base::wire::{recv_pkt, send_pkt, DesyncFlag};

pub(super) fn build_host_banner(features: &[Feature]) -> Vec<u8> {
    let mut banner = Vec::from(b"host::features=".as_ref());
    for (i, f) in features.iter().enumerate() {
        if i > 0 {
            banner.push(b',');
        }
        banner.extend_from_slice(f.wire_name().as_bytes());
    }
    banner
}

// adbd may emit stream-level packets (CLSE/OKAY/WRTE/OPEN) for channels
// left over from a previous session, typically right after host
// re-attach on USB. Drain them until a handshake packet arrives: CNXN,
// AUTH or STLS.
pub(crate) async fn recv_handshake_pkt<T: Read>(
    t: &mut T,
    buf: &mut BytesMut,
    max_payload: u32,
) -> Result<Packet, Error<T::Error>> {
    loop {
        let pkt = recv_pkt(t, buf, max_payload).await?;
        match pkt.command {
            Command::Connect | Command::Auth | Command::StartTls => return Ok(pkt),
            Command::Close | Command::Ready | Command::Write | Command::Open => {
                log::debug!("dropping stale {:?} during handshake", pkt.command);
            }
            other => return Err(ProtocolError::UnexpectedCommand(other).into()),
        }
    }
}

impl<T, const MAX_CHANNELS: usize, const MAX_PROPERTIES: usize, const MAX_FEATURES: usize>
    Connection<T, MAX_CHANNELS, MAX_PROPERTIES, MAX_FEATURES>
where
    T: Read + Write,
{
    /// Connect to an ADB device, performing the CNXN/AUTH handshake.
    ///
    /// * `transport` — an async read/write stream (TCP, USB, etc.)
    /// * `auth` — authenticator providing RSA signing and public key
    /// * `features` — features this host advertises; use
    ///   [`DEFAULT_HOST_FEATURES`](crate::protocol::features::DEFAULT_HOST_FEATURES)
    ///   for the conservative set of features this library implements.
    ///
    /// Builds the identity banner as `host::features=<csv>` from the
    /// supplied list, then delegates to [`connect_with_raw_banner`].
    /// Delayed ACK (credit-based flow control) is enabled only when
    /// [`Feature::DelayedAck`] is in `features` and the device also advertises it.
    ///
    /// A device that answers with `STLS`, as Android 11+ wireless
    /// debugging does, fails this with [`ProtocolError::TlsRequired`];
    /// with the `tls` feature, `connect_tls` serves both kinds.
    ///
    /// [`connect_with_raw_banner`]: Self::connect_with_raw_banner
    pub async fn connect<A: Authenticator>(
        transport: T,
        auth: A,
        features: &[Feature],
    ) -> Result<Self, Error<<T as ErrorType>::Error>> {
        Self::connect_with_config(transport, auth, features, ConnectionConfig::new()).await
    }

    /// Like [`connect`](Self::connect), but with explicit resource
    /// limits instead of the desktop defaults.
    ///
    /// `config.max_payload()` is what this host advertises to the device
    /// in CNXN, so it directly bounds how large an inbound packet — and
    /// therefore the receive buffer — can get. Use
    /// [`ConnectionConfig::embedded`] as a starting point on memory-tight
    /// targets.
    pub async fn connect_with_config<A: Authenticator>(
        transport: T,
        auth: A,
        features: &[Feature],
        config: ConnectionConfig,
    ) -> Result<Self, Error<<T as ErrorType>::Error>> {
        let banner = build_host_banner(features);
        Self::connect_with_raw_banner_and_config(transport, auth, banner.as_slice(), config).await
    }

    /// Connect to an ADB device with a caller-supplied raw identity
    /// banner (e.g. `b"host::features=shell_v2,delayed_ack"`).
    ///
    /// Escape hatch for callers that need properties beyond a plain
    /// feature list; prefer [`connect`](Self::connect) for the common
    /// case. A device that wants TLS fails this with
    /// [`ProtocolError::TlsRequired`], as it fails `connect`.
    pub async fn connect_with_raw_banner<A: Authenticator>(
        transport: T,
        auth: A,
        banner: &[u8],
    ) -> Result<Self, Error<<T as ErrorType>::Error>> {
        Self::connect_with_raw_banner_and_config(transport, auth, banner, ConnectionConfig::new())
            .await
    }

    /// [`connect_with_raw_banner`](Self::connect_with_raw_banner) with
    /// explicit resource limits.
    pub async fn connect_with_raw_banner_and_config<A: Authenticator>(
        mut transport: T,
        mut auth: A,
        banner: &[u8],
        config: ConnectionConfig,
    ) -> Result<Self, Error<<T as ErrorType>::Error>> {
        // The flag outlives the handshake: it moves into the
        // `Connection` that this builds, carrying over an abandoned
        // write from the handshake itself.
        let desync = DesyncFlag::new();
        let mut recv_buf = BytesMut::new();
        let verdict = open(
            &mut transport,
            &mut auth,
            banner,
            &config,
            &desync,
            &mut recv_buf,
        )
        .await?;

        match verdict {
            Verdict::Connected(cnxn) => {
                Self::assemble(transport, desync, recv_buf, banner, config, cnxn)
            }
            Verdict::StartTls(offer) => {
                log::debug!("device demands TLS: STLS version {:#010x}", offer.arg0);
                Err(ProtocolError::TlsRequired.into())
            }
        }
    }

    /// Everything after the device's CNXN: negotiate, parse the banner
    /// and build the connection.
    ///
    /// Split out so the TLS path, which reads its CNXN from inside the
    /// session, ends the same way.
    pub(crate) fn assemble(
        transport: T,
        desync: DesyncFlag,
        recv_buf: BytesMut,
        banner: &[u8],
        config: ConnectionConfig,
        cnxn: Packet,
    ) -> Result<Self, Error<<T as ErrorType>::Error>> {
        let delayed_ack = features::has_feature(banner, features::DELAYED_ACK)
            && features::has_feature(&cnxn.data, features::DELAYED_ACK);

        let device_banner = Some(DeviceBanner::from_bytes(cnxn.data)?);

        Ok(Self {
            transport,
            channels: core::array::from_fn(|_| None),
            // Bounded by our own encoder, not just by the device's offer.
            max_payload: cnxn.arg1.min(command::MAX_PAYLOAD),
            protocol_version: cnxn.arg0.min(command::ADB_VERSION),
            config,
            device_banner,
            local_id_counter: 1,
            incoming: alloc::collections::VecDeque::new(),
            delayed_ack,
            recv_buf,
            desync,
        })
    }
}

/// How the device ended the opening exchange.
pub(crate) enum Verdict {
    /// Its own CNXN: it is satisfied.
    Connected(Packet),
    /// STLS: it will only go on inside TLS.
    StartTls(Packet),
}

impl Verdict {
    /// The verdict `pkt` carries, or `pkt` back if it carries none.
    fn of(pkt: Packet) -> Result<Self, Packet> {
        match pkt.command {
            Command::Connect => Ok(Self::Connected(pkt)),
            Command::StartTls => Ok(Self::StartTls(pkt)),
            _ => Err(pkt),
        }
    }
}

/// The half of the handshake both entry points share: send our CNXN
/// and bring back the device's verdict.
///
/// Authentication happens in here when the device asks for it. A
/// first answer that is none of CNXN, STLS and AUTH fails here, as a
/// protocol error.
pub(crate) async fn open<T: Read + Write, A: Authenticator>(
    transport: &mut T,
    auth: &mut A,
    banner: &[u8],
    config: &ConnectionConfig,
    desync: &DesyncFlag,
    recv_buf: &mut BytesMut,
) -> Result<Verdict, Error<<T as ErrorType>::Error>> {
    let hello = Packet::new(
        Command::Connect,
        command::ADB_VERSION,
        config.max_payload(),
        banner.to_vec(),
    );
    // The device has not told us its version yet, so stay on the
    // conservative side: a pre-0x0100_0001 peer verifies this packet.
    send_pkt(transport, desync, &hello, Checksum::Compute).await?;

    let pkt = recv_handshake_pkt(transport, recv_buf, config.max_payload()).await?;
    let pkt = match Verdict::of(pkt) {
        Ok(verdict) => return Ok(verdict),
        Err(pkt) => pkt,
    };
    match pkt.command {
        Command::Auth if pkt.arg0 == command::AUTH_TOKEN => {
            do_auth(transport, desync, auth, recv_buf, pkt.data, config).await
        }
        other => Err(ProtocolError::UnexpectedCommand(other).into()),
    }
}

/// Answer the device's AUTH challenge.
///
/// Returns the verdict the exchange ended on: CNXN once the key is
/// accepted, or STLS if the device switches to TLS midway. Any AUTH but
/// the one token that asks for the key is [`AuthError::Rejected`]; that
/// token is [`AuthError::KeyNotTrusted`] when the authenticator will not
/// offer the key; a command with no place in the handshake, such as
/// SYNC, fails as [`ProtocolError::UnexpectedCommand`].
pub(crate) async fn do_auth<T: Read + Write, A: Authenticator>(
    transport: &mut T,
    desync: &DesyncFlag,
    auth: &mut A,
    recv_buf: &mut BytesMut,
    token: Bytes,
    config: &ConnectionConfig,
) -> Result<Verdict, Error<<T as ErrorType>::Error>> {
    // Checked here rather than in each authenticator: a stray
    // length must not reach a signer that may be someone else's.
    if token.len() != command::AUTH_TOKEN_LEN {
        return Err(ProtocolError::InvalidAuthToken(token.len()).into());
    }

    let signature = auth
        .sign(&token)
        .await
        .map_err(|e| Error::Auth(AuthError::SignFailed(alloc::format!("{e}"))))?;

    send_pkt(
        transport,
        desync,
        &Packet::auth_signature(signature),
        Checksum::Compute,
    )
    .await?;

    let resp = recv_handshake_pkt(transport, recv_buf, config.max_payload()).await?;
    let resp = match Verdict::of(resp) {
        Ok(verdict) => return Ok(verdict),
        Err(resp) => resp,
    };
    match resp.command {
        // A second token: the signature was not enough, offer the key.
        Command::Auth if resp.arg0 == command::AUTH_TOKEN => {}
        _ => return Err(AuthError::Rejected.into()),
    }

    // The key is what brings up the dialog on the device; an
    // authenticator that only asks whether it is trusted stops here.
    if !auth.offer_public_key() {
        return Err(AuthError::KeyNotTrusted.into());
    }

    {
        let pubkey = auth.public_key();
        send_pkt(
            transport,
            desync,
            &Packet::auth_public_key(pubkey.to_vec()),
            Checksum::Compute,
        )
        .await?;

        let resp = recv_handshake_pkt(transport, recv_buf, config.max_payload()).await?;
        if let Ok(verdict) = Verdict::of(resp) {
            return Ok(verdict);
        }
    }

    Err(AuthError::Rejected.into())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn build_host_banner_empty_features() {
        assert_eq!(build_host_banner(&[]), b"host::features=");
    }

    #[test]
    fn build_host_banner_single_feature() {
        assert_eq!(
            build_host_banner(&[Feature::ShellV2]),
            b"host::features=shell_v2",
        );
    }

    #[test]
    fn build_host_banner_multiple_features_preserves_order() {
        assert_eq!(
            build_host_banner(&[Feature::ShellV2, Feature::Cmd, Feature::DelayedAck]),
            b"host::features=shell_v2,cmd,delayed_ack",
        );
    }

    #[test]
    fn build_host_banner_matches_default_host_features() {
        let banner = build_host_banner(features::DEFAULT_HOST_FEATURES);
        assert!(banner.starts_with(b"host::features="));
        for f in features::DEFAULT_HOST_FEATURES {
            assert!(
                features::has_feature(banner.as_slice(), f.wire_name().as_bytes()),
                "banner does not advertise {:?}",
                f,
            );
        }
    }
}