Tích hợp HSM

★ Pro — Commercial License Required

Tích hợp HSM yêu cầu package Pro và thiết bị phần cứng tương thích PKCS#11.

TCPDF-Next Pro hỗ trợ ký với Hardware Security Module (HSM), smart card và USB token qua PKCS#11. Private key không bao giờ rời thiết bị phần cứng.

Class HSM

Class	Mục đích
HsmSigner	Implement SignerInterface cho ký dựa trên HSM
Pkcs11Bridge	Giao tiếp thư viện PKCS#11 cấp thấp

Pkcs11Bridge

Quản lý kết nối đến thư viện PKCS#11.

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

$bridge = new Pkcs11Bridge(
    libraryPath: '/usr/lib/softhsm/libsofthsm2.so',
    slotId:      0,
    pin:         $_ENV['PKCS11_PIN'], // không bao giờ hardcode PIN
);

// Liệt kê key có sẵn
$keys = $bridge->listPrivateKeys();
foreach ($keys as $key) {
    echo $key->label(); // "signing-key-2026"
    echo $key->type();  // 'RSA', 'EC'
}

HsmSigner

Thay thế trực tiếp cho ký dựa trên phần mềm trong workflow DigitalSigner.

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('Chữ ký lưu trữ cho production');

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

HSM được hỗ trợ

Bất kỳ thiết bị tương thích PKCS#11 đều hoạt động. Ví dụ phổ biến:

Thiết bị	Đường dẫn thư viện (thông thường)
SoftHSM 2 (testing)	/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

Thuật toán chữ ký

$hsm->algorithm('sha256WithRSAEncryption');  // mặc định
$hsm->algorithm('sha256WithRSAPSS');         // RSASSA-PSS
$hsm->algorithm('ecdsaWithSHA256');          // ECDSA P-256

Thuật toán	Ghi chú
RSA PKCS#1 v1.5 (SHA-256/384/512)	Tương thích rộng nhất
RSASSA-PSS (SHA-256)	Khuyên dùng cho triển khai mới
ECDSA (P-256 / P-384)	Chữ ký nhỏ hơn, nhanh hơn

Test với SoftHSM 2

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

Xử lý lỗi

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

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

PKCS#11 Code	Ý nghĩa
CKR_PIN_INCORRECT	PIN sai
CKR_PIN_LOCKED	PIN bị khóa sau quá nhiều lần thử
CKR_TOKEN_NOT_PRESENT	Thiết bị HSM chưa kết nối
CKR_KEY_HANDLE_INVALID	Không tìm thấy key trên token

Bước tiếp theo

• Chữ ký số PAdES -- Pipeline chữ ký đầy đủ từ B-B đến B-LTA.
• Long-Term Validation -- DSS, OCSP, CRL và archival timestamp.
• Tổng quan Pro -- Danh sách module đầy đủ và thông tin license.