HSM統合

★ Pro — Commercial License Required

HSM統合にはProパッケージとPKCS#11互換のハードウェアデバイスが必要です。

TCPDF-Next Proは、PKCS#11経由でハードウェアセキュリティモジュール（HSM）、スマートカード、USBトークンによる署名をサポートしています。秘密鍵がハードウェアデバイスの外に出ることはありません。

HSMクラス

クラス	用途
`HsmSigner`	HSMベースの署名のための`SignerInterface`を実装
`Pkcs11Bridge`	低レベルPKCS#11ライブラリ通信

Pkcs11Bridge

PKCS#11ライブラリへの接続を管理します。

php

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

$bridge = new Pkcs11Bridge(
    libraryPath: '/usr/lib/softhsm/libsofthsm2.so',
    slotId:      0,
    pin:         $_ENV['PKCS11_PIN'], // PINをハードコードしないでください
);

// 利用可能な鍵を一覧表示
$keys = $bridge->listPrivateKeys();
foreach ($keys as $key) {
    echo $key->label(); // "signing-key-2026"
    echo $key->type();  // 'RSA', 'EC'
}

HsmSigner

DigitalSignerワークフローでソフトウェアベース署名のドロップイン代替として使用できます。

php

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Pro\Security\Hsm\{HsmSigner, Pkcs11Bridge};
use Yeeefang\TcpdfNext\Pro\Security\Signature\DigitalSigner;
use Yeeefang\TcpdfNext\Pro\Security\Timestamp\TsaClient;
use Yeeefang\TcpdfNext\Contracts\Enums\SignatureLevel;

$pdf = Document::create()->addPage()->text('HSM-signed document.');

$bridge = new Pkcs11Bridge(
    libraryPath: $_ENV['PKCS11_LIBRARY'],
    slotId:      (int) $_ENV['PKCS11_SLOT'],
    pin:         $_ENV['PKCS11_PIN'],
);

$hsm = new HsmSigner($bridge);
$hsm->selectKey(label: 'signing-key-2026');
$hsm->certificate('/certs/hsm-signing.pem');
$hsm->chain(['/certs/intermediate.pem', '/certs/root.pem']);

$signer = new DigitalSigner($hsm);
$signer->level(SignatureLevel::PAdES_B_LTA);
$signer->timestampAuthority(new TsaClient('https://tsa.example.com/timestamp'));
$signer->reason('Enterprise archival signature');

$signer->sign($pdf);
$pdf->save('/output/hsm-signed.pdf');

対応HSM

PKCS#11互換のデバイスであれば動作します。一般的な例：

デバイス	ライブラリパス（一般的）
SoftHSM 2（テスト用）	`/usr/lib/softhsm/libsofthsm2.so`
Thales Luna	`/usr/lib/libCryptoki2_64.so`
AWS CloudHSM	`/opt/cloudhsm/lib/libcloudhsm_pkcs11.so`
YubiKey（PIV）	`/usr/lib/libykcs11.so`
SafeNet eToken	`C:\Windows\System32\eTPKCS11.dll`

署名アルゴリズム

php

$hsm->algorithm('sha256WithRSAEncryption');  // デフォルト
$hsm->algorithm('sha256WithRSAPSS');         // RSASSA-PSS
$hsm->algorithm('ecdsaWithSHA256');          // ECDSA P-256

アルゴリズム	備考
RSA PKCS#1 v1.5（SHA-256/384/512）	最も広い互換性
RSASSA-PSS（SHA-256）	新規デプロイに推奨
ECDSA（P-256 / P-384）	よりコンパクトで高速な署名

SoftHSM 2によるテスト

bash

apt-get install softhsm2
softhsm2-util --init-token --slot 0 --label "test-token" \
  --so-pin 87654321 --pin 12345678
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login --pin 12345678 \
  --keypairgen --key-type rsa:2048 --label "signing-key-2026" --id 01

エラーハンドリング

php

use Yeeefang\TcpdfNext\Pro\Security\Hsm\HsmException;

try {
    $bridge->openSession();
} catch (HsmException $e) {
    echo $e->getMessage(); // "PKCS#11 error: CKR_PIN_INCORRECT"
}

PKCS#11コード	意味
`CKR_PIN_INCORRECT`	PINが間違っている
`CKR_PIN_LOCKED`	試行回数超過によりPINがロック
`CKR_TOKEN_NOT_PRESENT`	HSMデバイスが接続されていない
`CKR_KEY_HANDLE_INVALID`	トークン上に鍵が見つからない

次のステップ

PAdES デジタル署名 -- B-BからB-LTAまでの完全な署名パイプライン。
長期検証 -- DSS、OCSP、CRL、およびアーカイブタイムスタンプ。
Proパッケージ概要 -- 全モジュール一覧とライセンス情報。

HSM統合 ​

HSMクラス ​

Pkcs11Bridge ​

HsmSigner ​

対応HSM ​

署名アルゴリズム ​

SoftHSM 2によるテスト ​

エラーハンドリング ​

次のステップ ​