compat-legacy 安全性與維運

概覽

此轉接器沿用 NextPDF 引擎的安全模型，並在舊版 TCPDF 6.2.13 之上加入少數刻意的強化。本頁會精確說明哪些功能可用、哪些不可用，且不誇大能力。請仔細閱讀簽署一節，該範圍刻意設計得很狹窄。

強化後的舊版行為

基於安全考量，三項 TCPDF 6.2.13 歷史行為已變更，且無法設定回不安全的形式：

考量項目	舊版 TCPDF 6.2.13	轉接器
錯誤處理	`Error()` 會呼叫 `die()` 並終止行程	`Error()` 會擲出 `RuntimeException`。可觀察、可攔截，且不會無聲地終止行程。
HTML 執行	某個逃脫機制可能會從標記執行 PHP	`K_TCPDF_CALLS_IN_HTML` 常數固定為 `false`；標記無法觸發 PHP 執行。
直接輸出	`Output()` 會回顯到目前作用中的輸出緩衝區	輸出會透過安全的目的地橋接器路由。它不會污染由呼叫端控制的輸出緩衝區。

錯誤處理的變更遵循一項原則：呼叫端必須能夠觀察到失敗，而不是讓行程憑空消失。OWASP ASVS 5.0 §16.5.3 指出，應用程式應優雅且安全地失敗，並防止 fail-open 情形。改為擲出而非 die 的變更，正是套用該原則。HTML 強化則移除了一處程式碼執行匯點。請將任何依賴舊行為的舊程式碼視為待修正的缺陷，並依 /integrations/tcpdf-compat/migration/ 的指引修正。釘選的條款摘要位於頁面前置資料的 citations 中。

加密

此轉接器公開 TCPDF 的 SetProtection()。它會委派給 NextPDF 引擎的標準安全處理器。

標準處理器使用 AES-256。舊版的 $mode 參數為了方法簽章相容性而被接受，但會被忽略；無法透過此方法選用較弱的密碼演算法。嚴格模式開啟時，非預設的 $mode 會擲出例外，以強制移轉過程必須正視它（在 tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php 中加以斷言）。
若未提供擁有者密碼，此轉接器會產生一組具密碼學強度的隨機擁有者密碼，而非重複使用使用者密碼。這可防止僅具使用者層級存取權者取得文件的擁有者層級控制權。
以憑證為基礎（公開金鑰）的加密並非透過 SetProtection() 完成；其 $pubkeys 參數會被忽略。請改用轉接器公開的現代公開金鑰加密進入點（setPublicKeyEncryption()），它會委派給引擎。

加密行為對應 ISO 32000-2 §7 所述的標準安全處理器。該條款定義了加密字典項目，以及引擎所使用的 AES-256 標準處理器。本文件並未聲稱輸出「預設即安全」或「防竄改」。它說明的是所使用的密碼演算法與擁有者密碼行為，也就是程式碼實際的作為。釘選的條款摘要位於頁面前置資料的 citations 中。

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Encrypted document');

// User password set; owner password auto-generated (strong, random).
$pdf->SetProtection([], 'user-secret');

$pdf->Output(__DIR__ . '/encrypted.pdf', 'F');

數位簽章：範圍聲明

請按字面閱讀本節。它刻意採取保守的立場。

TCPDF 舊版的 setSignature() 與 addEmptySignatureAppearance() 方法在核心引擎上的轉接器中未實作。它們在預設模式下不執行任何動作，並在嚴格模式下擲出 TcpdfNotImplementedException。
核心發行版並不透過此轉接器提供數位簽署能力。 基準簽章支援由商業版 NextPDF 版本閘控。
使用商業版時，此轉接器會公開一個現代簽章進入點（setSignatureV2()），它會委派給引擎。其預設設定檔為**基準（B-B）**設定檔。
本文件並未聲稱任何版本可透過此轉接器產生具時間戳記、長期驗證或封存能力的簽章設定檔。具體而言，它並未主張 B-T、B-LT 或 B-LTA 的行為。PAdES 基準規格 §6.1 定義了四個不同的基準層級：B-B、B-T、B-LT 與 B-LTA；各自有其要求。B-B 是基準層級，而較高的層級（時間戳記、長期驗證、封存）則是各自獨立、要求更高的設定檔。此相容層的文件僅涵蓋 B-B 基準層級。較高的層級明確不在範圍內，此處不宣稱任何版本支援這些層級。釘選的條款摘要位於頁面前置資料的 citations 中。
本文件任何地方都未做出「已認證」、「保證」、「具法律效力」或「符合 eIDAS 資格」的簽章主張。簽署正確性、信任錨點政策與法律效力，是簽署版本與呼叫端 PKI 的責任，而非此相容層的責任。

若你的移轉作業需要簽署，請將其視為獨立的工作項：在商業版上採用現代簽章 API，並以獨立的驗證器驗證所產生的簽章。請勿仰賴 TCPDF 的 setSignature() 呼叫；在此處它是無作用（no-op）。

舊版的 setTimeStamp() 方法會為了簽章相容性而被接受，並發出一則通知；它不會透過此轉接器產生加蓋時間戳記的簽章。

PDF/A 與符合性

建構函式的 pdfa 旗標為了方法簽章相容性而被接受。PDF/A 封存符合性需要商業版 NextPDF 版本。此轉接器公開 enablePdfA()，它會委派給引擎；當所需版本不存在時，引擎會回傳一則可據以處理的組態錯誤。此轉接器不會在聲稱符合 PDF/A 的同時，無聲地產生不符合的檔案。

輸出一律為 PDF 2.0（ISO 32000-2）。ISO 32000-2 §7.5.2 規定，符合規範的寫入器會將文件版本標示為 2.0，且不會在儲存時將其降回較舊的版本。因此 setPDFVersion() 無法將目標降至較舊的版本（參見 /integrations/tcpdf-compat/method-coverage/ §4）。釘選的條款摘要位於頁面前置資料的 citations 中。

維運指引

不會終止行程。 由於 Error() 會擲出例外而非呼叫 die()，請以 try/catch 包覆轉譯進入點，並將失敗對應到你的應用程式錯誤契約。請勿假設轉譯失敗就會結束請求。
輸出緩衝區安全。 Output() 搭配 S 會回傳位元組；搭配 F 會寫入檔案；搭配 E 會回傳 base64 MIME 主體；搭配 I/D 則會透過引擎輸出路徑路由。在工作行程與 HTTP 處理常式中，請優先使用 S 或 F，以便由你自行掌控回應；參見 /integrations/tcpdf-compat/production-usage/.
嚴格模式不是正式環境設定。 請將其保留給 CI/稽核作業使用。在正式環境的轉譯路徑中擲出例外，比讓參數無聲地降級更糟。
常數管理。 請在第一次建構轉接器之前定義 PDF_* / K_* 常數。這兩個強化旗標（K_TCPDF_CALLS_IN_HTML、K_TCPDF_THROW_EXCEPTION_ERROR）無法放寬；請勿嘗試這麼做。
隨機擁有者密碼。 若你仰賴確定性的擁有者密碼，請明確設定它。否則每份文件都會產生一組強隨機密碼，且無法復原。

威脅模型注意事項

針對影像方法，串流包裝器路徑會在任何檔案系統讀取之前遭拒。影像類型偵測（TcpdfImages::getImageFileType）會將任何 scheme:// 路徑——phar://、php:// 以及其他 PHP 串流包裝器——都視為包裝器，並略過 file_get_contents / getimagesize 探測，退回為僅根據副檔名推斷。這會在 PHP 7.4 回溯移植目標上封閉一個 phar 中繼資料反序列化向量；包裝器路徑嵌入本身則會被引擎拒絕。
除了引擎所做的處理之外，此轉接器不會另行驗證或清理傳入影像方法或輸出方法的檔案路徑。請在你的應用程式邊界將呼叫端提供的路徑與 URL 視為不受信任。
傳入 HTML 方法的 HTML 是由引擎轉譯，而不是由 TCPDF 的 HTML 剖析器處理。舊版的 PHP 執行匯點已被封閉，但呼叫端提供的 HTML 仍應被視為不受信任的輸入。
加密依標準處理器保護文件靜態保存時的機密性。它無法取代你應用程式中的傳輸安全或存取控制。

另請參閱

/integrations/tcpdf-compat/method-coverage/ —— SetProtection()、setSignature() 的確切行為
/integrations/tcpdf-compat/configuration/ —— 兩個強化、不可設定的旗標
/integrations/tcpdf-compat/production-usage/ —— 工作行程、緩衝區、失敗處理
docs/TCPDF_COVERAGE.md ——權威的涵蓋範圍矩陣
套件 NOTICE —— 獨立實作聲明