Rust智能卡通信库pcsc-sys使用指南

概述

pcsc-sys是Rust中用于与智能卡和读卡器交互的低级绑定库，实现了PC/SC (Personal Computer/Smart Card)标准接口。它提供了与Windows PC/SC和Linux/Unix PCSC-lite API的直接绑定。

主要功能

• 与智能卡读卡器建立连接
• 发送APDU命令到智能卡
• 接收智能卡响应
• 管理读卡器状态和上下文
• 处理智能卡插入/移除事件

基本使用方法

添加依赖

首先在Cargo.toml中添加依赖：

[dependencies]
pcsc-sys = "1.0"

基本示例

use pcsc_sys::*;
use std::ptr;
use std::ffi::CString;

fn main() {
    // 1. 建立上下文
    let mut ctx: SCARDCONTEXT = ptr::null_mut();
    let result = unsafe {
        SCardEstablishContext(
            SCARD_SCOPE_SYSTEM,
            ptr::null_mut(),
            ptr::null_mut(),
            &mut ctx,
        )
    };
    
    if result != SCARD_S_SUCCESS {
        eprintln!("Failed to establish context: {:?}", result);
        return;
    }

    // 2. 列出读卡器
    let mut readers_len: DWORD = 0;
    unsafe {
        SCardListReaders(ctx, ptr::null(), ptr::null_mut(), &mut readers_len);
    }
    
    let mut readers_buf = vec![0u8; readers_len as usize];
    let result = unsafe {
        SCardListReaders(
            ctx,
            ptr::null(),
            readers_buf.as_mut_ptr() as *mut i8,
            &mut readers_len,
        )
    };
    
    if result != SCARD_S_SUCCESS {
        eprintln!("Failed to list readers: {:?}", result);
        unsafe { SCardReleaseContext(ctx) };
        return;
    }

    // 3. 连接读卡器
    let reader_name = unsafe { CString::from_vec_unchecked(readers_buf) };
    let mut card: SCARDHANDLE = ptr::null_mut();
    let mut active_protocol: DWORD = 0;
    
    let result = unsafe {
        SCardConnect(
            ctx,
            reader_name.as_ptr(),
            SCARD_SHARE_SHARED,
            SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
            &mut card,
            &mut active_protocol,
        )
    };
    
    if result != SCARD_S_SUCCESS {
        eprintln!("Failed to connect to card: {:?}", result);
        unsafe { SCardReleaseContext(ctx) };
        return;
    }

    println!("Connected to card successfully!");

    // 4. 发送APDU命令 (示例: SELECT命令)
    let apdu = [0x00, 0xA4, 0x04, 0x00, 0x00]; // SELECT命令
    let mut response = [0u8; 256];
    let mut response_len = response.len() as DWORD;
    
    let result = unsafe {
        SCardTransmit(
            card,
            ptr::null(),
            apdu.as_ptr(),
            apdu.len() as DWORD,
            ptr::null_mut(),
            response.as_mut_ptr(),
            &mut response_len,
        )
    };
    
    if result != SCARD_S_SUCCESS {
        eprintln!("Failed to transmit APDU: {:?}", result);
    } else {
        println!("Response: {:?}", &response[..response_len as usize]);
    }

    // 5. 断开连接并释放资源
    unsafe {
        SCardDisconnect(card, SCARD_LEAVE_CARD);
        SCardReleaseContext(ctx);
    }
}

高级用法

事件监控

use std::thread;
use std::time::Duration;

// 在连接读卡器后...
let mut reader_states = vec![
    SCARD_READERSTATE {
        szReader: reader_name.as_ptr() as *mut i8,
        pvUserData: ptr::null_mut(),
        dwCurrentState: SCARD_STATE_UNAWARE,
        dwEventState: 0,
        cbAtr: 0,
        rgbAtr: [0; 36],
    }
];

loop {
    let result = unsafe {
        SCardGetStatusChange(
            ctx,
            1000, // 超时1秒
            reader_states.as_mut_ptr(),
            reader_states.len() as DWORD,
        )
    };
    
    if result == SCARD_S_SUCCESS {
        let state = reader_states[0].dwEventState;
        if state & SCARD_STATE_PRESENT != 0 {
            println!("Card inserted!");
        } else if state & SCARD_STATE_EMPTY != 0 {
            println!("Card removed!");
        }
    }
    
    thread::sleep(Duration::from_millis(500));
}

错误处理

fn check(result: DWORD) -> Result<(), String> {
    if result != SCARD_S_SUCCESS {
        let error_msg = match result {
            SCARD_E_NO_READERS_AVAILABLE => "No readers available",
            SCARD_E_NO_SMARTCARD => "No smartcard inserted",
            SCARD_E_PROTO_MISMATCH => "Protocol mismatch",
            SCARD_E_NOT_READY => "Reader not ready",
            _ => "Unknown error",
        };
        return Err(error_msg.to_string());
    }
    Ok(())
}

// 使用示例
check(unsafe { SCardEstablishContext(SCARD_SCOPE_SYSTEM, ptr::null_mut(), ptr::null_mut(), &mut ctx) })?;

注意事项

1. pcsc-sys是低级绑定，使用时需要大量unsafe代码
2. 考虑使用更高级的封装库如pcsc(基于pcsc-sys)
3. 在Windows和Linux上的行为可能略有不同
4. 确保系统已安装PC/SC服务(Windows自带，Linux需要pcsc-lite)
5. 处理多线程时需要小心，某些PC/SC实现不是线程安全的

替代方案

如果觉得pcsc-sys太底层，可以考虑使用pcsc crate，它提供了更友好的Rust接口：

[dependencies]
pcsc = "2.0"

示例：

use pcsc::*;

fn main() {
    let ctx = Context::establish(Scope::User).unwrap();
    let readers = ctx.list_readers().unwrap();
    
    for reader in readers {
        println!("Found reader: {:?}", reader);
        
        let card = ctx.connect(&reader, ShareMode::Shared, Protocols::ANY).unwrap();
        let apdu = [0x00, 0xA4, 0x04, 0x00, 0x00];
        let mut response = [0; 256];
        let response_len = card.transmit(&apdu, &mut response).unwrap();
        
        println!("Response: {:?}", &response[..response_len]);
    }
}

完整示例代码

以下是一个完整的智能卡交互示例，包含错误处理和事件监控：

use pcsc_sys::*;
use std::ptr;
use std::ffi::CString;
use std::thread;
use std::time::Duration;

fn main() -> Result<(), String> {
    // 1. 建立上下文
    let mut ctx: SCARDCONTEXT = ptr::null_mut();
    check(unsafe {
        SCardEstablishContext(
            SCARD_SCOPE_SYSTEM,
            ptr::null_mut(),
            ptr::null_mut(),
            &mut ctx,
        )
    })?;

    // 2. 列出读卡器
    let mut readers_len: DWORD = 0;
    unsafe {
        SCardListReaders(ctx, ptr::null(), ptr::null_mut(), &mut readers_len);
    }
    
    let mut readers_buf = vec![0u8; readers_len as usize];
    check(unsafe {
        SCardListReaders(
            ctx,
            ptr::null(),
            readers_buf.as_mut_ptr() as *mut i8,
            &mut readers_len,
        )
    })?;

    // 3. 连接读卡器
    let reader_name = unsafe { CString::from_vec_unchecked(readers_buf) };
    let mut card: SCARDHANDLE = ptr::null_mut();
    let mut active_protocol: DWORD = 0;
    
    check(unsafe {
        SCardConnect(
            ctx,
            reader_name.as_ptr(),
            SCARD_SHARE_SHARED,
            SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
            &mut card,
            &mut active_protocol,
        )
    })?;

    println!("Connected to card successfully!");

    // 4. 发送APDU命令 (示例: SELECT命令)
    let apdu = [0x00, 0xA4, 0x04, 0x00, 0x00]; // SELECT命令
    let mut response = [0u8; 256];
    let mut response_len = response.len() as DWORD;
    
    check(unsafe {
        SCardTransmit(
            card,
            ptr::null(),
            apdu.as_ptr(),
            apdu.len() as DWORD,
            ptr::null_mut(),
            response.as_mut_ptr(),
            &mut response_len,
        )
    })?;
    
    println!("Response: {:?}", &response[..response_len as usize]);

    // 5. 事件监控线程
    let event_thread = thread::spawn(move || {
        let mut reader_states = vec![
            SCARD_READERSTATE {
                szReader: reader_name.as_ptr() as *mut i8,
                pvUserData: ptr::null_mut(),
                dwCurrentState: SCARD_STATE_UNAWARE,
                dwEventState: 0,
                cbAtr: 0,
                rgbAtr: [0; 36],
            }
        ];

        loop {
            let result = unsafe {
                SCardGetStatusChange(
                    ctx,
                    1000, // 超时1秒
                    reader_states.as_mut_ptr(),
                    reader_states.len() as DWORD,
                )
            };
            
            if result == SCARD_S_SUCCESS {
                let state = reader_states[0].dwEventState;
                if state & SCARD_STATE_PRESENT != 0 {
                    println!("Card inserted!");
                } else if state & SCARD_STATE_EMPTY != 0 {
                    println!("Card removed!");
                }
            }
            
            thread::sleep(Duration::from_millis(500));
        }
    });

    // 主线程等待用户输入退出
    println!("Press Enter to exit...");
    let mut input = String::new();
    std::io::stdin().read_line(&mut input).unwrap();

    // 6. 断开连接并释放资源
    unsafe {
        SCardDisconnect(card, SCARD_LEAVE_CARD);
        SCardReleaseContext(ctx);
    }

    Ok(())
}

fn check(result: DWORD) -> Result<(), String> {
    if result != SCARD_S_SUCCESS {
        let error_msg = match result {
            SCARD_E_NO_READERS_AVAILABLE => "No readers available",
            SCARD_E_NO_SMARTCARD => "No smartcard inserted",
            SCARD_E_PROTO_MISMATCH => "Protocol mismatch",
            SCARD_E_NOT_READY => "Reader not ready",
            _ => format!("Unknown error: 0x{:X}", result),
        };
        return Err(error_msg);
    }
    Ok(())
}

这个完整示例包含了：

1. 上下文建立
2. 读卡器列表获取
3. 智能卡连接
4. APDU命令发送
5. 事件监控线程
6. 完善的错误处理
7. 资源清理

使用时可以根据实际需求修改APDU命令和响应处理逻辑。