yubikey.rs

Yubico的YubiKey设备纯Rust跨平台主机端驱动程序，支持使用YubiKey设备从Yubico使用个人身份验证(PIV)应用进行公钥加密和数字签名。

使用个人计算机/智能卡(PC/SC)接口，通过pcsccrate提供跨平台访问。

文档

关于

YubiKey是一种多功能的设备，通过其PIV支持，您可以使用它存储多种RSA（2048/1024）和ECC（NIST P-256/P-384）私钥，并具有可配置的访问控制策略。支持对任何密钥类型进行签名（RSASSA/ECDSA）和加密（PKCS#1v1.5/ECIES）的用例。

有关支持PIV的设备以及可用功能的信息，请参阅Yubico的PIV启用YubiKey指南。

如果您一直想使用Rust来使用在YubiKey（可选基于PIN的访问）上生成和存储的私钥对数据进行签名和/或加密，那么这正是您需要的crate！

请注意，虽然该项目最初是从Yubico项目分叉而来，但这个分叉不是官方的Yubico项目，并且以任何方式都未得到Yubico的支持或认可。

功能

个人身份验证 (PIV)

PIV 是一种由 NIST 标准化的技术，用于使用智能卡和基于智能卡的安全令牌（如 YubiKey）进行签名和加密。

与 PIV 相关的功能可以在 [piv] 模块中找到。

此库原生实现用于管理和利用 PIV 加密和签名密钥的协议，这些密钥可以在 YubiKey 设备上生成、导入和存储。

有关支持PIV的设备以及可用功能的信息，请参阅Yubico的PIV启用YubiKey指南。

支持的算法

• 认证： 3DES
• 加密:
  • RSA： RSA1024，RSA2048
  • ECC： ECCP256，ECCP384（NIST 曲线：P-256，P-384）
• 签名:
  • RSASSA-PKCS#1v1.5： RSA1024，RSA2048
  • ECDSA： ECCP256，ECCP384（NIST 曲线：P-256，P-384）

注意：RSASSA-PSS 签名和 RSA-OAEP 加密可能支持（待定）

最低支持的 Rust 版本

Rust 1.60 或更高版本。

支持的 YubiKey

• YubiKey 4 系列
• YubiKey 5 系列

注意：上述产品的 Nano 和 USB-C 版本也支持。预 YK4 YubiKey NEO 系列不支持（参见 #18）。

支持的操作系统

• Linux
• macOS
• Windows

安全警告

此 crate 从未进行过安全审计。目前处于实验阶段，可能仍存在严重问题。

自行承担风险！

状态

已成功测试的功能默认可用。

受 untested 功能限制的功能尚未经过适当测试，且其正确性未知。

请参阅 untested 功能跟踪问题 了解当前状态。我们非常感谢任何帮助测试此功能以及移除 untested 限制以及编写更多自动化测试的人。

测试

要运行完整的测试套件，您需要一个连接的 YubiKey NEO/4/5 设备，并处于默认状态（即默认 PIN/PUK）。

默认情况下，针对 YubiKey 设备的运行测试被标记为 #[ignore]，以便在 CI 环境中运行时通过。要本地运行这些测试，请调用以下命令

cargo test -- --ignored

此 crate 广泛使用 log 模块以提供关于正在发生的事情的详细信息。如果您想在运行测试时打印此日志信息，请将 RUST_LOG 环境变量设置为一个相关的日志级别（例如 error、warn、info、debug、trace）

RUST_LOG=info cargo test -- --ignored

要跟踪发送到/从卡的消息，即原始应用协议数据单元（APDU）消息，请使用 trace 日志级别

running 1 test
[INFO  yubikey::yubikey] trying to connect to reader 'Yubico YubiKey OTP+FIDO+CCID'
[INFO  yubikey::yubikey] connected to 'Yubico YubiKey OTP+FIDO+CCID' successfully
[TRACE yubikey::apdu] >>> Apdu { cla: 0, ins: SelectApplication, p1: 4, p2: 0, data: [160, 0, 0, 3, 8] }
[TRACE yubikey::transaction] >>> [0, 164, 4, 0, 5, 160, 0, 0, 3, 8]
[TRACE yubikey::apdu] <<< Response { status_words: Success, data: [97, 17, 79, 6, 0, 0, 16, 0, 1, 0, 121, 7, 79, 5, 160, 0, 0, 3, 8] }
[TRACE yubikey::apdu] >>> Apdu { cla: 0, ins: GetVersion, p1: 0, p2: 0, data: [] }
[TRACE yubikey::transaction] >>> [0, 253, 0, 0, 0]
[TRACE yubikey::apdu] <<< Response { status_words: Success, data: [5, 1, 2] }
[TRACE yubikey::apdu] >>> Apdu { cla: 0, ins: GetSerial, p1: 0, p2: 0, data: [] }
[TRACE yubikey::transaction] >>> [0, 248, 0, 0, 0]
[TRACE yubikey::apdu] <<< Response { status_words: Success, data: [0, 115, 0, 178] }
test connect ... ok

标记为 >>> 的 APDU 消息正在发送到 YubiKey 的内部智能卡，标记为 <<< 的消息是响应。

历史

这个库是Yubico的C语言编写的yubico-piv-tool工具的Rust翻译版本。它最初是用C编写的，通过Corrode从C机械翻译成Rust，然后经过大量重构，使其更安全、更符合Rust习惯。

有关yubico-piv-tool的更多信息以及关于YubiKey实现PIV的一般背景信息，请参阅[Yubico PIV工具命令行指南][piv-tool-guide]。

⚠️ 安全警告

从未对这个crate进行过安全审计。

行为准则

我们遵守贡献者公约，并要求您也这样做。

有关更多信息，请参阅CODE_OF_CONDUCT.md。

许可证

yubikey.rs是从Yubico的yubico-piv-tool（一个C语言库/CLI程序）分支出来的，最初是从C机械翻译过来的。原始库在2-Clause BSD许可证下许可，该许可证作为派生作品被此库继承。

版权（c）2014-2023 Yubico AB，Tony Arcieri。保留所有权利。

在满足以下条件的情况下，允许重新分发和使用源代码和二进制代码，无论是否修改：

• 源代码重新分发必须保留上述版权声明、本条件列表和以下免责声明。

• 二进制形式的重新分发必须复制上述版权声明、本条件列表和以下免责声明在随分发提供的文档和其他材料中。

本软件按“原样”提供，版权所有者和贡献者不提供任何明示或暗示的保证，包括但不限于适销性和适用于特定目的的隐含保证。在任何情况下，版权所有者或贡献者不应对任何直接、间接、偶然、特殊、示范性或后果性的损害（包括但不限于替代商品或服务的采购；使用、数据或利润的损失；或业务中断）承担责任，无论这种损害是否由使用本软件引起，即使已被告知此类损害的可能性。

贡献

除非您明确声明，否则您提交的任何有意包含在作品中的贡献都应按照上述所示2-Clause BSD许可证许可，没有其他附加条款或条件。