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로 테스트 ​

오류 처리 ​

다음 단계 ​