Rust硬件钱包通信库ledger-transport-hid的使用：支持Ledger设备的HID协议传输与交互

基本信息

• License: Apache-2.0
• 版本: 0.11.0
• 分类: 密码学, 认证
• 仓库: zondax/ledger-rs
• 文档: ledger-transport-hid 0.11.0文档

安装

在项目目录中运行以下Cargo命令：

cargo add ledger-transport-hid

或者在Cargo.toml中添加：

ledger-transport-hid = "0.11.0"

使用示例

以下是一个完整的示例代码，展示如何使用ledger-transport-hid库与Ledger设备进行交互：

use ledger_transport_hid::TransportNativeHID;
use ledger_transport::APDUCommand;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建HID传输实例
    let transport = TransportNativeHID::new()?;
    
    // 准备APDU命令
    let command = APDUCommand {
        cla: 0xE0,      // 指令类
        ins: 0x02,      // 指令码
        p1: 0x00,       // 参数1
        p2: 0x00,       // 参数2
        data: Vec::new(), // 数据字段
    };
    
    // 发送命令到设备
    let response = transport.exchange(&command).await?;
    
    // 处理响应
    println!("Response: {:?}", response);
    
    Ok(())
}

完整示例代码

下面是一个更完整的示例，包含错误处理和多个APDU命令交互：

use ledger_transport_hid::TransportNativeHID;
use ledger_transport::{APDUCommand, APDUError};
use tokio::runtime::Runtime;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建Tokio运行时
    let rt = Runtime::new()?;
    
    rt.block_on(async {
        // 创建HID传输实例
        let transport = match TransportNativeHID::new() {
            Ok(t) => t,
            Err(e) => {
                eprintln!("无法连接Ledger设备: {}", e);
                return Err(Box::new(e));
            }
        };
        
        // 示例1: 获取设备信息
        let get_info_cmd = APDUCommand {
            cla: 0xE0,
            ins: 0x01,  // GET_APP_INFO指令
            p1: 0x00,
            p2: 0x00,
            data: Vec::new(),
        };
        
        match transport.exchange(&get_info_cmd).await {
            Ok(response) => {
                println!("设备信息: {:?}", response);
            }
            Err(e) => {
                eprintln!("获取设备信息失败: {}", e);
                return Err(Box::new(e));
            }
        }
        
        // 示例2: 获取公钥
        let get_pubkey_cmd = APDUCommand {
            cla: 0xE0,
            ins: 0x02,  // GET_PUBLIC_KEY指令
            p1: 0x00,
            p2: 0x00,
            data: vec![0x01, 0x02, 0x03],  // 示例数据
        };
        
        match transport.exchange(&get_pubkey_cmd).await {
            Ok(response) => {
                println!("公钥响应: {:?}", response);
            }
            Err(e) => {
                eprintln!("获取公钥失败: {}", e);
                return Err(Box::new(e));
            }
        }
        
        Ok(())
    })
}

代码说明

1. TransportNativeHID - 提供与Ledger设备的HID连接功能
2. APDUCommand - 定义APDU协议命令结构:
   • cla: 指令类别
   • ins: 具体指令代码
   • p1/p2: 指令参数
   • data: 附加数据载荷
3. exchange方法 - 异步发送APDU命令并接收响应

注意事项

• 确保设备已通过USB连接且已解锁
• 不同Ledger应用(如比特币、以太坊等)使用不同的APDU指令集
• 需要处理设备可能返回的各种错误状态码
• 部分操作可能需要用户在设备上手动确认
• 建议为每个操作添加适当的超时处理

高级用法

对于需要更复杂交互的场景，可以结合使用多个APDU命令:

use ledger_transport_hid::TransportNativeHID;
use ledger_transport::APDUCommand;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let transport = TransportNativeHID::new()?;
    
    // 多步骤交互示例
    let commands = vec![
        APDUCommand { cla: 0xE0, ins: 0x10, p1: 0x00, p2: 0x00, data: vec![0x01] },
        APDUCommand { cla: 0xE0, ins: 0x11, p1: 0x00, p2: 0x00, data: vec![0x02] },
        APDUCommand { cla: 0xE0, ins: 0x12, p1: 0x00, p2: 0x00, data: vec![0x03] },
    ];
    
    for cmd in commands {
        let response = transport.exchange(&cmd).await?;
        println!("Command {:02X} response: {:?}", cmd.ins, response);
    }
    
    Ok(())
}

错误处理

建议实现自定义错误处理逻辑：

use thiserror::Error;

#[derive(Error, Debug)]
pub enum LedgerError {
    #[error("设备连接错误")]
    ConnectionError(#[from] std::io::Error),
    
    #[error("APDU通信错误")]
    ApduError(#[from] APDUError),
    
    #[error("设备拒绝操作")]
    RejectedByDevice,
    
    #[error("无效响应")]
    InvalidResponse,
}

fn handle_ledger_error(error: impl std::error::Error) {
    match error.downcast_ref::<APDUError>() {
        Some(APDUError::Io(e)) => eprintln!("IO错误: {}", e),
        Some(APDUError::Device(e)) => eprintln!("设备错误: {}", e),
        None => eprintln!("未知错误: {}", error),
    }
}

这个库为Rust开发者提供了与Ledger硬件钱包设备直接交互的能力，适合构建需要高安全性的加密货币应用。