YuerKey

深色模式

HSM 硬件安全模块 ​

概述 ​

YuerKey 实现了 SmartCard-HSM 规范，提供 PKCS#15 兼容的硬件安全模块功能。HSM 的核心价值是让密钥的生命周期（生成、存储、使用、销毁）全部在安全硬件内完成，私钥永远不以明文形式暴露在设备之外。

YuerKey 支持最多 16 个独立的密钥域，每个域使用独立的保护密钥（DKEK），实现多租户密钥隔离。

基本概念 ​

密钥层次 ​

YuerKey HSM 使用分层密钥架构保护用户密钥：

设备主密钥 —— 由设备内部的硬件密钥派生，不可导出
  └── DKEK[0..15]（域密钥加密密钥）—— 每个域独立，由管理员导入
        └── 用户密钥 —— 在各自域内受 DKEK 保护
  • 设备主密钥：设备级主密钥，由设备内部的硬件密钥派生。硬件密钥采用物理熔断型存储，写入后不可逆转，也无法被读取。
  • DKEK：域级保护密钥，用于加密包裹域内的用户密钥。DKEK 由管理员在外部生成后导入设备。
  • 用户密钥：实际用于签名、加密等操作的密钥，始终以 DKEK 加密的形式存储。

密钥域 ​

密钥域是 YuerKey HSM 的核心管理单元：

  • 最多支持 16 个独立域（编号 0-15）。
  • 每个域有自己独立的 DKEK 保护，域之间完全隔离。
  • 一个域内的密钥无法被另一个域访问。
  • 适合多项目、多团队或多租户场景——每个项目/团队使用独立的域。

初始化 ​

设置 SO PIN ​

SmartCard-HSM 的 SO（Security Officer）PIN 用于管理级操作，如初始化设备、创建/删除密钥域等。

  1. 将 YuerKey 通过 USB 连接到电脑。
  2. 在设备上进入「HSM 管理」界面。
  3. 选择「初始化」，按照提示设置 SO PIN。
  4. SO PIN 需满足最低长度要求，建议使用 8 位以上。

重要：SO PIN 丢失将无法执行管理操作。请妥善记录。

导入 DKEK ​

为密钥域导入保护密钥（DKEK）。DKEK 支持 Shamir 秘密分享方案，可以将一个 DKEK 拆分为多份，由多人分别保管：

  1. 在管理工具中生成 DKEK（可选择直接使用或拆分为 N 份）。
  2. 如果使用 Shamir 分享方案，需要至少 t 个持有人到场，依次输入各自的 DKEK 分片。
  3. 设备收集到足够的分片后，自动重建完整的 DKEK。
  4. DKEK 被安全存储在设备中对应的密钥域内。

DKEK 分享方案示例 ​

以 3-of-5 方案为例：

  • 生成 DKEK 并拆分为 5 份，分发给 5 位管理员。
  • 任意 3 位管理员到场即可恢复 DKEK。
  • 任何少于 3 份的组合无法恢复，防止单点风险。

密钥管理 ​

生成密钥对 ​

通过 PKCS#11 工具或设备界面生成密钥对：

支持的算法：

算法密钥长度适用场景
RSA2048 / 3072 / 4096 位签名、加密，兼容性最好
ECDSAP-256 / P-384签名，性能优于同等安全级别的 RSA
EdDSAEd25519签名，高性能
ECDHX25519密钥协商

生成的密钥对中，私钥始终留在设备内部，只有公钥可以导出。

导入和导出密钥 ​

  • 导入密钥：外部生成的密钥可以通过 DKEK 加密包裹后导入到设备中。导入过程中，明文私钥不会暴露——密钥在外部先用 DKEK 加密，设备接收到加密包裹后在内部解密存储。
  • 导出密钥：密钥可以以 DKEK 加密的形式导出（用于备份或迁移到另一台设备）。明文私钥永远不会离开设备。

注意：密钥的导入/导出必须使用对应域的 DKEK 加密。没有 DKEK 就无法操作。

使用场景 ​

CA 证书签发 ​

使用 HSM 中的密钥签发 X.509 证书，根密钥安全存储在硬件中：

  1. 在 HSM 中生成 CA 根密钥对。
  2. 使用根密钥签署 CA 证书。
  3. 用 CA 密钥签发终端证书。
  4. 所有签名操作都在 YuerKey 内部完成，根私钥永远不暴露。

这种方案适合小型 PKI 基础设施，或作为离线根 CA 使用。

代码签名 ​

将代码签名密钥存储在 HSM 域中，集成到 CI/CD 流程：

  1. 在 HSM 中生成代码签名密钥对。
  2. 导出公钥，注册到代码签名服务（如 Microsoft Authenticode、Apple 公证）。
  3. CI/CD 服务器通过 PKCS#11 接口调用 HSM 签名。
  4. 即使 CI/CD 服务器被入侵，签名密钥仍然安全。

数据库加密 ​

将数据库的主加密密钥（Master Key）存储在 HSM 中：

  1. 在 HSM 中生成或导入数据库主密钥。
  2. 应用通过 PKCS#11 接口请求加密/解密操作。
  3. 数据库的数据加密密钥（DEK）由主密钥包裹保护。
  4. 主密钥永远不离开 HSM，即使数据库文件泄露也无法解密。

密钥托管与灾备 ​

利用 DKEK 的导入/导出机制实现密钥备份：

  1. 备份设备上的密钥：以 DKEK 加密形式导出。
  2. 导入到备用 YuerKey 设备中（需要相同的 DKEK）。
  3. 实现双设备冗余，防止单设备故障导致密钥丢失。

管理界面 ​

在 YuerKey 设备上可以进行以下管理操作：

  • 查看域状态：查看各密钥域的使用状态（已用/可用密钥槽数量）。
  • 查看密钥列表：浏览域内的密钥列表，包括密钥类型、算法和用途标签。
  • 创建密钥域：新建一个密钥域并导入 DKEK。
  • 删除密钥域：销毁一个密钥域及其中所有密钥（需要 SO PIN 确认，屏幕会显示警告提示）。

注意事项 ​

  • DKEK 丢失不可恢复：DKEK 丢失将导致对应域中所有密钥永久不可用。设备无法恢复 DKEK，也无法解密没有 DKEK 的密钥。
  • 建议使用 Shamir 秘密分享：使用 t-of-n 阈值方案备份 DKEK（如 3-of-5），避免单点故障。将 DKEK 分片交给不同的可信人员保管。
  • 密钥域删除不可恢复：删除密钥域会永久销毁域内所有密钥和 DKEK。此操作不可撤销。
  • 物理安全：虽然 HSM 提供了强大的逻辑安全保护，但物理安全同样重要。请将 YuerKey 存放在安全的位置，防止未授权的物理接触。
  • SO PIN 管理：SO PIN 连续输错超过最大重试次数后会被锁定。锁定后需要重置设备才能恢复，重置会清除所有数据。

OpenSC 兼容 ​

YuerKey 的 HSM 模块完整兼容 OpenSC，可以使用标准的 pkcs11-tool 和 pkcs15-tool 进行密钥管理操作。

支持的 OpenSC 操作 ​

  • 密钥生成：通过 pkcs11-tool 在设备上生成 RSA/ECC 密钥对
  • 密钥导入/导出：标准 DKEK 密钥包装格式，兼容 SmartCard-HSM 生态
  • 证书管理：导入和管理 X.509 证书
  • 签名和解密：使用设备上的私钥进行 PKCS#11 操作

快速验证 ​

bash
# 检测设备
pkcs15-tool --list-pins

# 列出密钥
pkcs15-tool --list-keys

# 列出证书
pkcs15-tool --list-certificates

TIP

OpenSC 兼容性基于 SmartCard-HSM 标准实现，完整支持 PKCS#15 文件结构。详细的 OpenSC 使用方法请参阅 OpenSC 官方文档。