時間戳記授權（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 時間戳記。