Rust硬件安全模块库yubihsm的使用

yubihsm.rs是一个纯Rust客户端库，用于与Yubico的YubiHSM 2硬件安全模块通信。它实现了Yubico YubiHSM SDK中libyubihsm C库的大部分功能。

功能特性

yubihsm提供两种与YubiHSM通信的后端：

• HTTP：通过Yubico SDK中的yubihsm-connector进程通信
• USB：使用rusb crate直接通过USB与YubiHSM通信

yubihsm::Client类型提供了对HSM命令的访问。

安装

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

cargo add yubihsm

或在Cargo.toml中添加：

yubihsm = "0.42.1"

示例代码

以下是使用yubihsm库进行基本操作的完整示例：

use yubihsm::{Client, Connector, Credentials, ObjectId, ObjectType};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建HTTP连接器(默认连接localhost:12345)
    let connector = Connector::http("http://127.0.0.1:12345")?;
    
    // 认证凭据(默认authkey id为1,密码为"password")
    let credentials = Credentials::default();
    
    // 创建客户端
    let mut client = Client::open(connector, credentials, true)?;
    
    // 获取设备信息
    let device_info = client.device_info()?;
    println!("Device Info: {:?}", device_info);
    
    // 生成新的非对称密钥
    let key_id = ObjectId::from(1);
    let key_label = "example-key".to_string();
    
    client.generate_asymmetric_key(
        key_id,
        key_label.clone(),
        vec![], // domains
        yubihsm::Algorithm::Ed25519, // 算法
        yubihsm::Capability::SIGN_EDDSA, // 能力
    )?;
    
    println!("Generated Ed25519 key with ID: {}", key_id);
    
    // 获取公钥
    let public_key = client.get_pubkey(key_id)?;
    println!("Public key: {:?}", public_key);
    
    // 签名数据
    let data = b"test message";
    let signature = client.sign_ed25519(key_id, data)?;
    println!("Signature: {:?}", signature);
    
    // 列出所有对象
    let objects = client.list_objects(&[])?;
    println!("Objects in HSM: {}", objects.len());
    
    // 删除密钥
    client.delete_object(key_id, ObjectType::AsymmetricKey)?;
    println!("Deleted key with ID: {}", key_id);
    
    Ok(())
}

完整示例代码

以下是一个更完整的示例，展示了更多yubihsm.rs的功能：

use yubihsm::{
    Algorithm, Capability, Client, Command, Connector, Credentials, 
    Domain, ObjectId, ObjectLabel, ObjectType, WrapKey
};
use std::time::Duration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. 设置连接器
    let connector = Connector::http("http://127.0.0.1:12345")?;
    
    // 2. 配置认证凭据
    let credentials = Credentials::builder()
        .auth_key_id(1)  // 认证密钥ID
        .password("my_secure_password")  // 密码
        .build();
    
    // 3. 创建客户端并设置超时
    let mut client = Client::open(
        connector,
        credentials,
        true  // 启用自动会话续订
    )?;
    client.set_command_timeout(Some(Duration::from_secs(5)))?;
    
    // 4. 获取并打印设备信息
    let device_info = client.device_info()?;
    println!("设备序列号: {}", device_info.serial_number);
    println!("固件版本: {}", device_info.version);
    
    // 5. 创建新的RSA密钥对
    let rsa_key_id = ObjectId::from(100);
    println!("\n生成RSA密钥对...");
    client.generate_asymmetric_key(
        rsa_key_id,
        "rsa-encryption-key".into(),
        vec![Domain::DOM1],  // 域
        Algorithm::Rsa2048,  // 算法
        Capability::all(),   // 所有能力
    )?;
    
    // 6. 使用RSA密钥加密数据
    let plaintext = b"secret data to encrypt";
    println!("\n加密数据: {:?}", plaintext);
    let ciphertext = client.encrypt_pkcs1v15(rsa_key_id, plaintext)?;
    println!("加密结果: {:?}", ciphertext);
    
    // 7. 创建对称加密密钥
    let aes_key_id = ObjectId::from(101);
    println!("\n生成AES-256密钥...");
    client.generate_wrap_key(
        aes_key_id,
        "aes-wrapping-key".into(),
        vec![Domain::DOM1],
        WrapKey::Aes256,
        Capability::all(),
    )?;
    
    // 8. 导出公钥
    println!("\n导出RSA公钥...");
    let public_key = client.get_pubkey(rsa_key_id)?;
    println!("RSA公钥: {:?}", public_key);
    
    // 9. 列出HSM中的所有对象
    println!("\n列出所有对象...");
    let objects = client.list_objects(&[])?;
    for obj in objects.iter() {
        println!("ID: {}, 类型: {:?}, 标签: {}", obj.object_id, obj.object_type, obj.label);
    }
    
    // 10. 清理 - 删除创建的对象
    println!("\n清理资源...");
    client.delete_object(rsa_key_id, ObjectType::AsymmetricKey)?;
    client.delete_object(aes_key_id, ObjectType::WrapKey)?;
    println!("已删除所有测试对象");
    
    Ok(())
}

支持的命令

yubihsm.rs支持大多数YubiHSM 2命令，包括：

• 会话管理(创建/关闭会话)
• 密钥管理(生成/导入/导出/删除密钥)
• 加密操作(签名/验证/加密/解密)
• 设备管理(重置/获取信息)
• 审计日志

测试

yubihsm.rs提供三种测试方式：

1. 通过HTTP连接器对真实YubiHSM2设备进行测试
2. 通过USB直接连接YubiHSM2测试(需启用usb特性)
3. 使用MockHSM进行模拟测试(启用mockhsm特性)

许可证

yubihsm.rs采用双重许可：MIT许可证和Apache许可证(版本2.0)。