Rust YubiKey安全认证库yubico的使用指南

介绍

yubico是一个Rust库，用于与YubiKey硬件安全设备交互，支持硬件密钥管理和双因素身份验证(2FA)。它提供了与YubiKey设备通信的接口，可以用于生成OTP(一次性密码)、管理PIV功能等安全操作。

主要功能

• YubiKey OTP验证
• PIV(智能卡)功能管理
• HMAC-SHA1挑战/响应
• 设备状态检测和管理

使用方法

添加依赖

在Cargo.toml中添加：

[dependencies]
yubico = "0.10"

基本示例：验证YubiKey OTP

use yubico::config::{Config, Slot};
use yubico::verify;

fn main() {
    let config = Config::default()
        .set_client_id("CLIENT_ID")  // 从Yubico获取
        .set_key("API_KEY")          // 从Yubico获取
        .set_api_hosts(vec!["api.yubico.com".into()]);

    let otp = "ccccccbcgklhfvftjfnhfchvthvuitvkllkcudkic"; // 从YubiKey获取的OTP
    
    match verify(otp, config) {
        Ok(answer) => println!("验证成功: {:?}", answer),
        Err(e) => println!("验证失败: {:?}", e),
    }
}

使用PIV功能管理密钥

use yubico::piv::{AlgorithmId, SlotId, YubiKey};
use yubico::management::Device;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 查找连接的YubiKey
    let mut yk = YubiKey::open()?;
    
    // 生成新密钥对
    yk.generate(
        AlgorithmId::Rsa2048,
        SlotId::Authentication,
        None, // 可选PIN策略
    )?;
    
    // 导出公钥
    let public_key = yk.fetch_certificate(SlotId::Authentication)?;
    println!("公钥: {:?}", public_key);
    
    Ok(())
}

HMAC-SHA1挑战/响应示例

use yubico::hmacmode::{Config, Slot};
use yubico::configure;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 配置HMAC-SHA1
    let config = Config::default()
        .set_vendor_id(0x1050)
        .set_product_id(0x0030)
        .set_variable_size(true)
        .set_challenge("my_challenge".to_string())
        .set_slot(Slot::Slot2);
    
    // 连接到YubiKey
    let mut device = configure::find_yubikey()?;
    
    // 发送挑战并获取响应
    let result = configure::challenge_response_hmac(&mut device, &config)?;
    println!("HMAC响应: {:?}", result);
    
    Ok(())
}

高级用法

枚举所有连接的YubiKey设备

use yubico::manager::get_yubikeys;

fn main() {
    match get_yubikeys() {
        Ok(devices) => {
            println!("找到 {} 个YubiKey设备:", devices.len());
            for (i, device) in devices.iter().enumerate() {
                println!("{}: {:?}", i+1, device);
            }
        }
        Err(e) => println!("错误: {:?}", e),
    }
}

双因素认证集成示例

use yubico::config::Config;
use yubico::verify;

struct User {
    username: String,
    password: String,
    yubikey_id: Option<String>,
}

fn two_factor_auth(user: &User, otp: Option<&str>) -> bool {
    // 第一步：验证用户名和密码
    if user.username != "admin" || user.password != "secure123" {
        return false;
    }
    
    // 第二步：如果用户有YubiKey，验证OTP
    if let Some(id) = &user.yubikey_id {
        if let Some(otp_code) = otp {
            let config = Config::default()
                .set_client_id("CLIENT_ID")
                .set_key("API_KEY");
            
            return verify(otp_code, config).is_ok();
        }
        return false;
    }
    
    true // 没有YubiKey的用户只需要用户名/密码
}

fn main() {
    let user_with_yubikey = User {
        username: "admin".to_string(),
        password: "secure123".to_string(),
        yubikey_id: Some("ccccccbcgklh".to_string()),
    };
    
    let otp = "ccccccbcgklhfvftjfnhfchvthvuitvkllkcudkic";
    println!("认证结果: {}", two_factor_auth(&user_with_yubikey, Some(otp)));
}

完整示例：YubiKey综合使用

use yubico::{
    config::Config,
    verify,
    piv::{AlgorithmId, SlotId, YubiKey},
    hmacmode::{Config as HmacConfig, Slot},
    configure,
    manager::get_yubikeys
};
use std::error::Error;

fn main() -> Result<(), Box<dyn Error>> {
    // 1. 枚举所有连接的YubiKey设备
    println!("=== 枚举YubiKey设备 ===");
    let devices = get_yubikeys()?;
    println!("找到 {} 个YubiKey设备:", devices.len());
    for (i, device) in devices.iter().enumerate() {
        println!("{}: {:?}", i+1, device);
    }

    // 2. OTP验证示例
    println!("\n=== OTP验证示例 ===");
    let otp_config = Config::default()
        .set_client_id("CLIENT_ID")
        .set_key("API_KEY");
    
    let otp = "ccccccbcgklhfvftjfnhfchvthvuitvkllkcudkic";
    match verify(otp, otp_config) {
        Ok(answer) => println!("OTP验证成功: {:?}", answer),
        Err(e) => println!("OTP验证失败: {:?}", e),
    }

    // 3. PIV功能管理
    println!("\n=== PIV功能管理 ===");
    let mut yk = YubiKey::open()?;
    
    // 生成RSA2048密钥对
    yk.generate(AlgorithmId::Rsa2048, SlotId::Authentication, None)?;
    
    // 获取证书
    let cert = yk.fetch_certificate(SlotId::Authentication)?;
    println!("认证槽证书: {:?}", cert);

    // 4. HMAC-SHA1挑战/响应
    println!("\n=== HMAC-SHA1挑战/响应 ===");
    let hmac_config = HmacConfig::default()
        .set_vendor_id(0x1050)
        .set_product_id(0x0030)
        .set_variable_size(true)
        .set_challenge("secure_challenge".to_string())
        .set_slot(Slot::Slot2);
    
    let mut device = configure::find_yubikey()?;
    let hmac_result = configure::challenge_response_hmac(&mut device, &hmac_config)?;
    println!("HMAC响应: {:?}", hmac_result);

    Ok(())
}

注意事项

1. 使用OTP验证功能需要从Yubico获取API密钥
2. 某些功能需要YubiKey设备支持特定功能
3. 生产环境中应考虑错误处理和重试机制
4. 密钥管理操作需要适当的权限和PIN码

通过这个库，Rust开发者可以轻松地将YubiKey硬件安全功能集成到他们的应用程序中，增强安全性并支持双因素认证。