跳到內容
NextPDF
getnextpdf.com

TSA 設定

一覽

標題為「一覽」的區段

NextPDF 只有在你以 PAdES B-T 或更高等級簽章時，才會聯絡時間戳記機構（TSA）。在 B-B 下不會有時間戳記、也不會有網路呼叫，因此本頁不適用於 B-B 簽章。

為了讓 B-T 開箱即用，NextPDF 隨附一個內建的預設 TSA。這個預設值是一種便利設計：它讓帶有時間戳記的簽章在不需任何額外設定的情況下就能成功。它並非 公開受信任，也並非 eIDAS 合格，因此在未經審慎抉擇之前，並不適合用於正式環境或符合性用途。本頁會明確說明這個預設值究竟是什麼、如何讓 NextPDF 指向你自己的 TSA、如何關閉時間戳記，以及那兩條升級路徑。

有三項性質彼此獨立，切勿混為一談：

  • 自架（self-hosted）——由誰營運該伺服器，以及其憑證鏈接到哪個根憑證；
  • 公開受信任（publicly-trusted）——你的依賴方所使用的驗證生態系（其信任儲存區或信任清單）是否在無需手動設定的情況下就已信任該根憑證，而不必由人工安裝私有根憑證。這關乎的是依賴方的信任錨點，而非任何單一方案（例如 Web PKI）；
  • eIDAS 合格（eIDAS-qualified）——該時間戳記在歐盟是否具備合格的法律效力。

隨附的預設值僅止於自架。公開受信任的 TSA 會再加上第二項性質。eIDAS 合格的 TSA 則額外帶有合格的法律地位，並透過歐盟信任清單（EU Trusted Lists）加以驗證，且可能由第三方 QTSP 營運。這三項性質彼此獨立——其中一項並不蘊含另一項。

內建的預設 TSA

標題為「內建的預設 TSA」的區段

預設端點為 https://timestamp.pateon.com.tw，這是 NextPDF 自有的 RFC 3161 時間戳記伺服器。它屬於自架：其時間戳記單元憑證鏈接到一個私有的 PATEON 根憑證，而非某個公開信任方案。因此，除非依賴方已在帶外（out of band）安裝並信任該 PATEON 根憑證，否則無法驗證由此預設值所發出的時間戳記。

由於 RFC 3161 權杖並未帶有任何外部證據能證明所主張的時間正確無誤，因此對任何此類時間戳記的信任，完全建立在信任發行該權杖的 TSA 之上（ISO/IEC 18014-2 §7.3）。 對隨附的預設值而言，該信任錨點是私有的，這正是為何此預設值是一種便利與開發用途的預設值，而**非符合性等級（compliance-grade）**的預設值。

當使用預設端點且你的框架已設定記錄器（logger）時，NextPDF 會在程序啟動時發出 一次性警告，指出該預設值並非公開受信任，並指向本設定頁。此警告僅供參考；簽章仍會成功。

覆寫預設值

標題為「覆寫預設值」的區段

在你的框架轉接器（adapter）設定中設定 TSA 端點。確切的鍵會因轉接器而異（請參閱 各框架設定表）：在 Laravel 中為 NEXTPDF_TSA_URL 環境變數，在 Symfony 中為 nextpdf.tsa.url bundle 節點，在 CodeIgniter 中則為 nextPdf.tsa.url env 鍵。

有效的 TSA 會依下列優先順序解析，最高者在前：

  1. 由你自行建構並注入的明確 TsaClient——這一向勝出。
  2. 在你的轉接器中設定的 URL——當你未注入用戶端時採用。
  3. 內建的預設值——只有在以上兩者皆未設定時才採用。
Terminal window
# Laravel (.env): use your own publicly-trusted TSA instead of the shipped default.
NEXTPDF_TSA_URL=http://timestamp.digicert.com

停用時間戳記

標題為「停用時間戳記」的區段

將轉接器的 TSA url 保留在其預設（未設定）狀態，會沿用內建的預設端點。將該 url 設為空值則屬另一回事：它會停用時間戳記。在未設定任何 TSA 的情況下，於 B-T 或更高等級提出的簽章請求會以「TSA required」錯誤 fail closed（失敗即關閉），而不會無聲地降級為 B-B。

Terminal window
# Laravel (.env):
# NEXTPDF_TSA_URL unset -> use the built-in default (timestamp succeeds against pateon).
# NEXTPDF_TSA_URL empty -> no TSA; a B-T+ request fails closed.
NEXTPDF_TSA_URL=

選擇 messageImprint 摘要演算法

標題為「選擇 messageImprint 摘要演算法」的區段

RFC 3161 時間戳記請求會攜帶一個 messageImprint——即被加上時間戳記之資料的雜湊值——而 NextPDF 預設會以 SHA-256 計算該 imprint。此預設值是一項刻意且具互通性的選擇；你鮮少需要變更它。

當你親手建構 TsaClient 時，可透過 imprintHashAlgorithm 建構子參數選擇不同的 imprint 摘要，該參數接受一個 TsaImprintHashAlgorithm case：Sha256（預設值）、 Sha384、Sha512、Sha3_256、Sha3_384 或 Sha3_512。此預設值會讓每一個發出的請求都與先前版本維持位元組相同（byte-identical），因此除非你主動選擇啟用，否則升級不會改變任何行為。

use NextPDF\Security\Timestamp\TsaClient;
use NextPDF\Security\Timestamp\TsaImprintHashAlgorithm;


// Default — SHA-256 imprint, unchanged from earlier releases:
$tsa = new TsaClient('https://timestamp.example.com/tsa');


// Opt in to a stronger imprint digest:
$tsa = new TsaClient(
    'https://timestamp.example.com/tsa',
    imprintHashAlgorithm: TsaImprintHashAlgorithm::Sha512,
);

在離開預設值之前，有兩項限制值得了解：

  • 目前生態系僅支援 SHA-256。 非 SHA-256 的 imprint 能與 Core 權杖驗證器互通， 但 nextpdf-server 的 PAdES B-T 證明關卡（proof gate）以及 Premium 的驗證摘要對應表（digest map）目前僅辨識 SHA-256 imprint。因此，以不同 imprint 摘要建立的簽章時間戳記，在那些環節上尚無法證明達到 B-T。除非你確知每一個時間戳記的取用方都接受你所選的摘要，否則請沿用預設值。
  • 預先計算的摘要必須與演算法相符。 getDocumentTimestamp() 接受一個已計算完成的文件雜湊；當該雜湊的長度與所設定的 imprint 演算法不符時，它會在任何網路呼叫之前就 fail closed（失敗即關閉），而不會送出不相符的請求。

升級路徑

標題為「升級路徑」的區段

凡是超出開發或內部用途的情境，都應以下列兩個更強的選項之一取代預設值。

公開受信任的 TSA

標題為「公開受信任的 TSA」的區段

將轉接器的 TSA url 指向一個其憑證鏈接到你的依賴方已信任之公開根憑證的 TSA——例如 http://timestamp.digicert.com。無須散布任何私有根憑證。正式環境等級的 TSA 通常會聲明符合某項時間戳記政策，例如 ETSI EN 319 421 §5，並遵循 ETSI EN 319 422 §7 所述的 RFC 3161 協定設定檔；請對照營運者已發布的政策加以確認，而不要僅憑公開信任便逕行假設。

eIDAS 合格的 TSA

標題為「eIDAS 合格的 TSA」的區段

對於必須在歐盟具備合格法律效力的時間戳記，請使用列於某份歐盟信任清單上的合格信任服務提供者（QTSP）所提供的合格時間戳記服務。合格電子時間戳記會將時間綁定到資料，以合理防止無法察覺的竄改，並以連結至協調世界時（UTC）的精確時間來源為基礎，且受到 QTSP 的進階電子簽章或進階電子印章、或等效方法所保護（Regulation (EU) 910/2014, Art 42）。這是最強的選項，也是當某項法規明確指名合格時間戳記時應選擇的選項。

各框架設定

標題為「各框架設定」的區段

預設值存在於各框架轉接器的設定之中，而非核心引擎裡。Core 從不自行發明 URL：你親手建構的 TsaClient 必須帶有明確端點，若端點為空便會擲出例外。長期等級（B-LT 與 B-LTA）會重用與 B-T 相同的已設定 TSA。

IntegrationWhere the default livesHow to override
Laravelconfig/nextpdf.php -> tsa.url在 .env 中設定 NEXTPDF_TSA_URL
Symfonybundle 設定 nextpdf.tsa.url設定該節點，或將其繫結到某個 env 變數
CodeIgniterConfig\NextPdf::$tsa['url']透過 nextPdf.tsa.url env 鍵覆寫
Plain core無隱含預設值以明確 URL 加上一個強化過的 PSR-18 用戶端建構 TsaClient

在每個轉接器中，B-B 從不建構 TSA 用戶端，因此未帶時間戳記的簽章完全不受以上任何設定影響。

信任模型與標準

標題為「信任模型與標準」的區段

時間戳記的價值在於其背後的信任鏈，而非位元組本身。RFC 3161 權杖只主張一個時間；該主張是否可信，是簽署它的那個 TSA 的性質（RFC 3161 §2；ISO/IEC 18014-2 §7.3）。當你沿用隨附的預設值時，你正選擇一個自架、私有信任的錨點——對於每個依賴方都能安裝 PATEON 根憑證的開發與內部工作流程而言這沒有問題，但不適用於由第三方驗證的文件。對於那些文件，請改用公開受信任的 TSA；當需要合格法律效力時，則改用 eIDAS 合格的 TSA。

如果你自行營運這個預設值，你可以在自己注入的 PSR-18 用戶端中釘選該 TSA 的公開金鑰。 請勿在共用程式碼中釘選隨附的預設值：營運者一旦輪換金鑰，便會同時讓每一位預設值使用者中斷。時間戳記的信任在於憑證鏈與 PATEON 根憑證，而非某個傳輸層釘選。

另請參閱

標題為「另請參閱」的區段