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 簽章附加時間戳記。