PAdES 數位簽章

★ Pro — Commercial License Required

PAdES B-T 以上等級的數位簽章功能需要 Pro 套件。

Pro 套件提供完整的 PAdES（PDF Advanced Electronic Signatures）數位簽章管線，符合 ETSI EN 319 142 標準，涵蓋從基本簽章到長期保存簽章的完整生命週期。

簽章等級

等級	名稱	說明	包含內容
B-B	Basic	基本簽章	簽署者憑證
B-T	Timestamp	含時間戳記	B-B + RFC 3161 簽章時間戳記
B-LT	Long-Term	長期驗證	B-T + OCSP/CRL 驗證資料（DSS）
B-LTA	Long-Term Archival	長期保存	B-LT + 文件級時間戳記

每個等級都在前一個等級的基礎上逐層累加，確保更高的信任度與更長的驗證期限。

核心類別

類別	說明
CertificateInfo	解析與封裝 X.509 憑證資訊
DigitalSigner	簽章引擎，負責產生 CMS 簽章
ByteRangeCalculator	計算 PDF 位元組範圍以建立簽章雜湊
SignatureAppearance	管理簽章欄位的視覺外觀

憑證載入

從 PKCS#12 檔案載入

use Yeeefang\TcpdfNext\Pro\Security\Signature\CertificateInfo;

$cert = CertificateInfo::fromPkcs12(
    path: '/certs/signer.p12',
    password: 'my-passphrase'
);

echo $cert->subject();        // CN=John Doe, O=Example Corp
echo $cert->issuer();         // CN=Example CA
echo $cert->validFrom();      // 2025-01-01
echo $cert->validTo();        // 2027-12-31
echo $cert->serialNumber();   // 0A1B2C3D...

從 PEM 檔案載入

$cert = CertificateInfo::fromPem(
    certificate: '/certs/signer.pem',
    privateKey: '/certs/signer-key.pem',
    password: 'key-password'
);

附加中繼憑證鏈

$cert->addChainCertificate('/certs/intermediate-ca.pem');
$cert->addChainCertificate('/certs/root-ca.pem');

PAdES B-B 基本簽章

use Yeeefang\TcpdfNext\Core\Document;
use Yeeefang\TcpdfNext\Pro\Security\Signature\DigitalSigner;
use Yeeefang\TcpdfNext\Contracts\Enums\SignatureLevel;

$pdf = Document::create()
    ->addPage()
    ->font('Helvetica', size: 12)
    ->text('此文件已經過數位簽署。');

$signer = new DigitalSigner($cert);
$signer->level(SignatureLevel::PAdES_B_B);
$signer->reason('合約核准');
$signer->location('臺北市');
$signer->contactInfo('legal@example.com');

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

PAdES B-T 時間戳記簽章

B-T 等級在簽章上附加 RFC 3161 時間戳記，證明簽署時間的可靠性。

use Yeeefang\TcpdfNext\Pro\Security\Timestamp\TsaClient;

$tsa = new TsaClient('https://freetsa.org/tsr');

$signer = new DigitalSigner($cert);
$signer->level(SignatureLevel::PAdES_B_T);
$signer->timestampAuthority($tsa);
$signer->reason('採購單簽核');

$signer->sign($pdf);

PAdES B-LT 長期驗證簽章

B-LT 等級自動嵌入 OCSP 回應與 CRL，建立文件安全儲存區（DSS），使驗證資料自足於文件內。

$signer = new DigitalSigner($cert);
$signer->level(SignatureLevel::PAdES_B_LT);
$signer->timestampAuthority($tsa);
$signer->reason('法律文件簽署');

// OCSP/CRL 端點會自動從憑證的 AIA/CDP 擴充欄位擷取
$signer->sign($pdf);

手動指定 OCSP/CRL 端點

$signer->ocspResponder('http://ocsp.example.com');
$signer->crlDistributionPoint('http://crl.example.com/ca.crl');

PAdES B-LTA 長期保存簽章

B-LTA 是最高等級，在 B-LT 的基礎上再加入文件級時間戳記，保護所有已嵌入的驗證資料。

use Yeeefang\TcpdfNext\Pro\Security\Ltv\LtvManager;

$signer = new DigitalSigner($cert);
$signer->level(SignatureLevel::PAdES_B_LTA);
$signer->timestampAuthority($tsa);
$signer->reason('歸檔文件簽署');

// LtvManager 自動完成 DSS 建構與文件時間戳記
LtvManager::embed($pdf, $signer);
$pdf->save('/output/signed-blta.pdf');

B-LTA 簽章流程會自動執行：

1. 建立 CMS 簽章並嵌入簽署者憑證鏈。
2. 附加 RFC 3161 簽章時間戳記。
3. 查詢並嵌入 OCSP 回應或下載 CRL。
4. 建立 DSS（Document Security Store）。
5. 以增量更新方式加入文件級時間戳記。

ByteRangeCalculator

ByteRangeCalculator 負責計算 PDF 檔案中簽章的位元組範圍，確保雜湊值涵蓋檔案的正確區段。

use Yeeefang\TcpdfNext\Pro\Security\Signature\ByteRangeCalculator;

$calculator = new ByteRangeCalculator($pdfBytes);
$ranges = $calculator->calculate(signatureFieldOffset: 1024, signatureLength: 8192);

// $ranges = [0, 1024, 9216, totalLength - 9216]

此類別通常由 DigitalSigner 內部呼叫，一般不需手動使用。

SignatureAppearance 視覺外觀

use Yeeefang\TcpdfNext\Pro\Security\Signature\SignatureAppearance;

$appearance = SignatureAppearance::create()
    ->showName(true)
    ->showDate(true)
    ->showReason(true)
    ->showLocation(true)
    ->image('/path/to/signature-stamp.png')
    ->backgroundColor('#F0F0F0')
    ->borderColor('#333333')
    ->fontSize(8);

$signer->appearance($appearance);
$signer->fieldPosition(x: 15, y: 240, width: 80, height: 30);
$signer->sign($pdf);

下一步

• 長期驗證 — 深入了解 DSS、OCSP 與 CRL 嵌入機制。
• HSM 整合 — 將私鑰保存於硬體安全模組中進行簽署。
• 時間戳記授權 — RFC 3161 TSA 用戶端的進階設定。