时间戳授权（TSA）

★ Pro — Commercial License Required

时间戳授权功能需要 Pro 包。

时间戳授权（Time Stamping Authority）提供可信的时间证明，证明文件在特定时间点已经存在。Pro 包的 TsaClient 完整实现 RFC 3161 协议，支持 nonce 验证、DNS 固定与 mTLS 双向认证。

核心类

类	说明
TsaClient	RFC 3161 时间戳请求客户端
DocumentTimestamp	文档级时间戳签名

基本用法

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

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

// 直接取得时间戳响应
$token = $tsa->stamp(data: $signatureHash);

echo "时间戳：{$token->time()->format('Y-m-d H:i:s')}\n";
echo "TSA 名称：{$token->tsaName()}\n";
echo "序号：{$token->serialNumber()}\n";

RFC 3161 协议

TsaClient 实现完整的 RFC 3161 时间戳协议：

1. 生成 TimeStampReq，包含数据哈希与 nonce。
2. 通过 HTTP POST 将请求送至 TSA 服务器。
3. 接收并验证 TimeStampResp。
4. 验证 nonce 是否匹配以防止重放攻击。
5. 返回 TimeStampToken。

配置哈希算法

$tsa->hashAlgorithm('sha256');   // 默认值
$tsa->hashAlgorithm('sha384');
$tsa->hashAlgorithm('sha512');

Nonce 验证

Nonce（一次性随机数）用于防止重放攻击。TsaClient 默认启用 nonce 验证：

$tsa = new TsaClient('https://tsa.example.com');
$tsa->useNonce(true);       // 默认启用
$tsa->nonceLength(8);       // nonce 字节长度（默认 8）

如果 TSA 服务器返回的 nonce 与请求中的不一致，TsaClient 会抛出 TimestampVerificationException。

DNS 固定

DNS 固定可防止中间人攻击，确保连接到正确的 TSA 服务器：

$tsa->dnsPinning([
    'tsa.example.com' => '93.184.216.34',
]);

当 DNS 解析结果与固定的 IP 地址不一致时，连接会被拒绝。

mTLS 双向认证

部分企业级 TSA 服务器要求客户端证书认证（mutual TLS）：

$tsa = new TsaClient('https://tsa.enterprise.com');
$tsa->clientCertificate(
    cert: '/certs/client.pem',
    key: '/certs/client-key.pem',
    password: 'key-password'
);

超时与重试

$tsa->timeout(seconds: 15);     // 连接超时
$tsa->retryCount(3);            // 重试次数
$tsa->retryDelay(seconds: 2);   // 重试间隔

DocumentTimestamp

DocumentTimestamp 用于加入文档级时间戳，这是 PAdES B-LTA 的必要组成部分。文档级时间戳保护整个文件（包括所有先前的签名与验证数据）。

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

$docTs = new DocumentTimestamp($tsa);
$docTs->apply($pdf);

// 文档级时间戳会以增量更新方式附加
$pdf->save('/output/timestamped.pdf');

常用 TSA 服务器

服务	URL	备注
FreeTSA	https://freetsa.org/tsr	免费，适合开发测试
DigiCert	http://timestamp.digicert.com	商用，高可用性
Sectigo	http://timestamp.sectigo.com	商用
GlobalSign	http://timestamp.globalsign.com/tsa/r6advanced1	商用
Entrust	http://timestamp.entrust.net/TSS/RFC3161sha2TS	商用
台湾时间戳中心	依机构提供	政府机关专用

建议

开发阶段可使用 FreeTSA 测试，正式环境请使用商用 TSA 服务以确保可用性与服务等级。

搭配 PAdES 签名

$tsa = new TsaClient('https://timestamp.digicert.com');

$signer = new DigitalSigner($cert);
$signer->level(SignatureLevel::PAdES_B_LTA);
$signer->timestampAuthority($tsa);

LtvManager::embed($pdf, $signer);

下一步

• PAdES 数字签名 — 签名等级与时间戳的角色。
• 长期验证 — 文档时间戳在归档循环中的作用。
• HSM 集成 — 结合 HSM 签署与 TSA 时间戳。