ledger_lib/transport/

usb.rs

//! USB HID transport implementation

use std::{ffi::CString, fmt::Display, io::ErrorKind, marker::PhantomData, time::Duration};

use hidapi::{HidApi, HidDevice, HidError};
use tracing::{debug, error, trace, warn};

use crate::{
    info::{LedgerInfo, Model},
    transport::PhantomNonSend,
    Error, NonSendExchange, Transport,
};

/// Basic USB device information
#[derive(Clone, PartialEq, Debug)]
#[cfg_attr(feature = "clap", derive(clap::Parser))]
pub struct UsbInfo {
    #[cfg_attr(feature = "clap", clap(long, value_parser=u16_parse_hex))]
    /// USB Device Vendor ID (VID) in hex
    pub vid: u16,

    #[cfg_attr(feature = "clap", clap(long, value_parser=u16_parse_hex))]
    /// USB Device Product ID (PID) in hex
    pub pid: u16,

    #[cfg_attr(feature = "clap", clap(long))]
    /// Device path
    pub path: Option<String>,
}

impl Display for UsbInfo {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:04x}:{:04x}", self.vid, self.pid)
    }
}

/// Helper to pass VID/PID pairs from hex values
#[cfg(feature = "clap")]
fn u16_parse_hex(s: &str) -> Result<u16, std::num::ParseIntError> {
    u16::from_str_radix(s, 16)
}

/// USB HID based transport
///
/// This type is deliberately non-`Send` to avoid potential quirks that might happen when
/// the underlying `hidapi` type changes threads.
/// If you don't need low-level control, see [LedgerProvider](crate::LedgerProvider) for a tokio-based wrapper.
pub struct UsbTransport {
    hid_api: HidApi,
    _phantom: PhantomNonSend,
}

/// USB HID based device
///
/// This type is deliberately non-`Send` to avoid potential quirks that might happen when
/// the underlying `hidapi` type changes threads.
pub struct UsbDevice {
    pub info: UsbInfo,
    device: HidDevice,
    _phantom: PhantomNonSend,
}

/// Ledger USB VID
pub const LEDGER_VID: u16 = 0x2c97;

/// HID usage page used by Ledger for its APDU interface.
#[allow(unused)]
const LEDGER_APDU_USAGE_PAGE: u16 = 0xffa0;
/// The value of "interface_number" that Ledger's APDU interface will have.
#[allow(unused)]
const LEDGER_APDU_INTREFACE_NUMBER: i32 = 0;

fn is_apdu_interface(device_info: &hidapi::DeviceInfo) -> bool {
    // A Ledger device has two USB HID interfaces, one of which is the "APDU" interface
    // and the other one FIDO/U2F; we need to select the former and ignore the latter.

    // The more reliable way of selecting the APDU interface is to look for the corresponding
    // "usage_page"; however, it's not available on Linux libusb backends, in which case
    // we select the interface based on its interface number. This is similar to how it's done in Ledger Live -
    // https://github.com/LedgerHQ/ledger-live/blob/4b73b3b61f07bc44fe4a04606e3cf1e610e7eb51/libs/ledgerjs/packages/hw-transport-node-hid-noevents/src/TransportNodeHid.ts#L19-L22
    // except that in Ledger Live they always resort to using the interface number on Linux, but
    // here it's done only for Linux/libusb.
    // Note: on Windows, the FIDO interface is never returned by `hidapi::HidApi::devices_list`
    // for some reason; presumably it's because the interface is held by the OS. But it's still
    // better to do the filtering "just in case" and also for consistency with Ledger Live.

    #[cfg(all(feature = "transport_usb_libusb", target_os = "linux"))]
    {
        let is_apdu = device_info.interface_number() == LEDGER_APDU_INTREFACE_NUMBER;
        debug!(
            "(PID={pid:#x}) USB interface #{inum} is APDU: {is_apdu}",
            pid = device_info.product_id(),
            inum = device_info.interface_number()
        );
        is_apdu
    }

    #[cfg(not(all(feature = "transport_usb_libusb", target_os = "linux")))]
    {
        let is_apdu = device_info.usage_page() == LEDGER_APDU_USAGE_PAGE;
        debug!(
            "(PID={pid:#x}) USB interface #{inum} (usage page = {uspg:#x}) is APDU: {is_apdu}",
            pid = device_info.product_id(),
            inum = device_info.interface_number(),
            uspg = device_info.usage_page(),
        );
        is_apdu
    }
}

impl UsbTransport {
    /// Create a new [UsbTransport]
    pub fn new() -> Result<Self, Error> {
        #[cfg(feature = "transport_usb_libusb")]
        debug!("Feature transport_usb_libusb is enabled");

        #[cfg(feature = "transport_usb_hidraw")]
        debug!("Feature transport_usb_hidraw is enabled");

        Ok(Self {
            hid_api: HidApi::new()?,
            _phantom: PhantomData,
        })
    }
}

impl Transport for UsbTransport {
    type Filters = ();
    type Info = UsbInfo;
    type Device = UsbDevice;

    /// List available devices using the [UsbTransport]
    async fn list(&mut self, _filters: Self::Filters) -> Result<Vec<LedgerInfo>, Error> {
        debug!("Listing USB devices");

        // Refresh available devices
        // TODO: determine whether the refresh call is critical (or, useful?)
        if let Err(e) = self.hid_api.refresh_devices() {
            warn!("Failed to refresh devices: {e:?}");
        }

        tokio::time::sleep(Duration::from_millis(200)).await;

        // Fetch list of devices, filtering for ledgers
        let devices: Vec<_> = self
            .hid_api
            .device_list()
            .filter(|d| d.vendor_id() == LEDGER_VID && is_apdu_interface(d))
            .map(|d| LedgerInfo {
                model: Model::from_usb_pid(d.product_id()),
                conn: UsbInfo {
                    vid: d.vendor_id(),
                    pid: d.product_id(),
                    path: Some(d.path().to_string_lossy().to_string()),
                }
                .into(),
            })
            .collect();

        debug!("devices: {:?}", devices);

        Ok(devices)
    }

    /// Connect to a device using the usb transport
    async fn connect(&mut self, info: UsbInfo) -> Result<UsbDevice, Error> {
        debug!("Connecting to USB device: {:?}", info);

        // If we have a path, use this to connect
        let d = if let Some(p) = &info.path {
            let p = CString::new(p.clone()).unwrap();
            self.hid_api.open_path(&p)

        // Otherwise, fallback to (non unique!) vid:pid
        } else {
            self.hid_api.open(info.vid, info.pid)
        };

        match d {
            Ok(d) => {
                debug!("Connected to USB device: {:?}", info);
                Ok(UsbDevice {
                    device: d,
                    info,
                    _phantom: PhantomData,
                })
            }
            Err(e) => {
                debug!("Failed to connect to USB device: {:?}", e);
                Err(e.into())
            }
        }
    }
}

// HID packet length (header + data)
const HID_PACKET_LEN: usize = 64;

// Five bytes: channel (0x101), tag (0x05), sequence index
const HID_HEADER_LEN: usize = 5;

impl UsbDevice {
    /// Write an APDU to the device
    pub fn write(&mut self, apdu: &[u8]) -> Result<(), Error> {
        debug!("Write APDU");

        // Setup outgoing data buffer with length prefix
        let mut data = Vec::with_capacity(apdu.len() + 2);
        data.extend_from_slice(&(apdu.len() as u16).to_be_bytes());
        data.extend_from_slice(apdu);

        debug!("TX: {:02x?}", data);

        // Write data in 64 byte chunks
        for (i, c) in data.chunks(HID_PACKET_LEN - HID_HEADER_LEN).enumerate() {
            trace!("Writing chunk {} of {} bytes", i, c.len());

            // Setup HID packet with header and data
            let mut packet = Vec::with_capacity(HID_PACKET_LEN + 1);

            // Zero prefix for unknown reasons
            packet.push(0x00);

            // Header channel (0x101), tag (0x05), sequence index
            packet.extend_from_slice(&[0x01, 0x01, 0x05]);
            packet.extend_from_slice(&(i as u16).to_be_bytes());
            // Remaining data
            packet.extend_from_slice(c);

            trace!("Write: 0x{:02x?}", packet);

            // Write HID packet
            self.device.write(&packet)?;
        }

        Ok(())
    }

    /// Read an APDU from the device
    pub fn read(&mut self, timeout: Duration) -> Result<Vec<u8>, Error> {
        debug!("Read APDU");

        let mut buff = [0u8; HID_PACKET_LEN + 1];

        // Read first chunk of response
        // Timeout argument applied here as once the reply has started timeout bounds should be more consistent
        let n = match self
            .device
            .read_timeout(&mut buff, timeout.as_millis() as i32)
        {
            Ok(n) => n,
            Err(HidError::IoError { error }) if error.kind() == ErrorKind::TimedOut => {
                return Err(Error::Timeout)
            }
            Err(e) => return Err(e.into()),
        };

        // Check read length is valid for following operations
        if n == 0 {
            error!("Empty response");
            return Err(Error::EmptyResponse);
        } else if n < 7 {
            error!("Unexpected read length {n}");
            return Err(Error::UnexpectedResponse);
        }

        // Check header matches expectations
        if buff[..5] != [0x01, 0x01, 0x05, 0x00, 0x00] {
            error!("Unexpected response header: {:02x?}", &buff[..5]);
            return Err(Error::UnexpectedResponse);
        }

        trace!("initial read: {buff:02x?}");

        // Parse response length
        let len = u16::from_be_bytes([buff[5], buff[6]]) as usize;

        trace!("Read len: {len}");

        // Setup response buffer and add any remaining data
        let mut resp = Vec::with_capacity(len);

        let data_len = len.min(n - 7);
        resp.extend_from_slice(&buff[7..][..data_len]);

        // Read following chunks if required
        let mut seq_idx = 1;
        while resp.len() < len {
            let rem = len - resp.len();

            trace!("Read chunk {seq_idx} ({rem} bytes remaining)");

            // Read next chunk, constant timeout as chunks should be sent end-to-end
            let n = self.device.read_timeout(&mut buff, 500)?;

            if n < 5 {
                error!("Invalid chunk length {n}");
                return Err(Error::UnexpectedResponse);
            }

            // Check header and sequence index
            if buff[..3] != [0x01, 0x01, 0x05] {
                error!("Unexpected response header: {:02x?}", &buff[..5]);
                return Err(Error::UnexpectedResponse);
            }
            if u16::from_be_bytes([buff[3], buff[4]]) != seq_idx {
                error!("Unexpected sequence index: {:02x?}", &buff[5..7]);
                return Err(Error::UnexpectedResponse);
            }

            // Add to response buffer
            let data_len = rem.min(n - 5);
            resp.extend_from_slice(&buff[5..][..data_len]);
            seq_idx += 1;
        }

        debug!("RX: {:02x?}", resp);

        Ok(resp)
    }

    pub(crate) async fn is_connected(&self) -> Result<bool, Error> {
        Ok(self.device.get_device_info().is_ok())
    }
}

/// [NonSendExchange] impl for sending APDUs to a [UsbDevice]
impl NonSendExchange for UsbDevice {
    async fn exchange(&mut self, command: &[u8], timeout: Duration) -> Result<Vec<u8>, Error> {
        // Write APDU command, chunked for HID transport
        self.write(command)?;
        // Read APDU response, chunked for HID transport
        self.read(timeout)
    }
}