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('[email protected]');

$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 客户端的高级配置。