HSM 集成

★ Pro — Commercial License Required

HSM 集成功能需要 Pro 包。

硬件安全模块（Hardware Security Module，HSM）是专门用于保护加密密钥的物理设备。私钥永远不离开 HSM，所有签名运算都在模块内部完成，提供最高等级的密钥安全性。Pro 包通过 PKCS#11 接口与 HSM 集成。

核心类

类	说明
HsmSigner	HSM 签名器，取代软件签名的 DigitalSigner
Pkcs11Bridge	PKCS#11 库桥接器

系统需求

• 已安装 HSM 的 PKCS#11 驱动程序（.so / .dll）
• PHP pkcs11 扩展模块，或通过 FFI 桥接
• HSM 设备或云端 HSM 服务

配置设置

use Yeeefang\TcpdfNext\Pro\Security\Hsm\Pkcs11Bridge;
use Yeeefang\TcpdfNext\Pro\Security\Hsm\HsmSigner;

$bridge = Pkcs11Bridge::create([
    'library'  => '/usr/lib/softhsm/libsofthsm2.so',  // PKCS#11 驱动程序路径
    'slot'     => 0,                                     // HSM 插槽编号
    'pin'      => env('HSM_PIN'),                        // 用户 PIN
    'keyLabel' => 'my-signing-key',                      // 密钥标签
]);

环境变量配置

建议将敏感信息存放在环境变量中：

# .env
HSM_PKCS11_LIBRARY=/usr/lib/softhsm/libsofthsm2.so
HSM_SLOT=0
HSM_PIN=your-secure-pin
HSM_KEY_LABEL=my-signing-key

使用 HsmSigner 签署文件

HsmSigner 的接口与 DigitalSigner 完全兼容，只是底层签名运算改由 HSM 执行：

$hsm = new HsmSigner($bridge);
$hsm->level(SignatureLevel::PAdES_B_LTA);
$hsm->timestampAuthority($tsa);
$hsm->reason('高安全等级文件签署');
$hsm->location('台北市');

// 附加签署者证书（证书本身可存放在 HSM 或文件系统）
$hsm->certificate(CertificateInfo::fromPem('/certs/hsm-signer.pem'));

LtvManager::embed($pdf, $hsm);
$pdf->save('/output/hsm-signed.pdf');

支持的 HSM 设备与服务

设备/服务	PKCS#11 驱动程序	备注
SoftHSM2	libsofthsm2.so	软件模拟，适合开发测试
Thales Luna	libCryptoki2.so	企业级硬件 HSM
AWS CloudHSM	libcloudhsm_pkcs11.so	云端 HSM 服务
Azure Managed HSM	通过 REST API	需搭配自定义 Bridge
YubiHSM 2	libyubihsm_pkcs11.so	小型 USB HSM

应用场景

金融机构

银行与保险公司的文件签署需符合监管要求，私钥必须存放在 FIPS 140-2 Level 3 认证的 HSM 中。

政府机关

公文电子签章需使用经认证的硬件安全模块，确保密钥的不可导出性。

大量签署

HSM 提供硬件加速的签名运算，适合批处理数千份文件的签署需求。

foreach ($documents as $doc) {
    $hsm->sign($doc);   // 密钥始终保留在 HSM 内
    $doc->save("/output/{$doc->id()}.pdf");
}

下一步

• PAdES 数字签名 — 软件签名的完整流程。
• 长期验证 — 结合 HSM 签名与 LTV。
• 时间戳授权 — 为 HSM 签名附加时间戳。