安全性總覽
TCPDF-Next 以安全優先的哲學進行設計。作為一套處理數位簽章、加密與機敏文件的函式庫，安全不是事後補強，而是核心架構原則。
安全優先設計
每一個元件在設計時都將安全納入考量：
1. 全面淘汰過時密碼學
TCPDF-Next 在編譯期與執行期均拒絕所有已棄用和不安全的演算法：
- RC4 — 禁止使用（已知多種攻擊手法的破損加密法）
- MD5 — 禁止使用（自 2004 年以來已展示碰撞攻擊）
- SHA-1 — 拒絕用於所有簽章操作（自 2017 年以來已展示碰撞攻擊）
- RSA 金鑰 < 2048 位元 — 拒絕（1024 位元金鑰已可被分解）
- DES / 3DES — 未實作
2. 記憶體安全
- 所有機敏資料（私鑰、密碼、解密內容）儲存於
SensitiveString物件中，不再使用時自動從記憶體歸零 - 在可用的情況下使用 PHP 的
sodium_memzero()進行安全的記憶體清除 - 含有機敏資料的暫存檔案會透過覆寫方式安全刪除
3. 輸入驗證
- 所有 PDF 輸入在處理前均經過嚴格驗證
- 畸形的 PDF 結構會被拒絕，而非以「盡力解析」方式處理
- 所有大小計算均包含整數溢位檢查
- 嵌入式檔案處理具備路徑遍歷防護
4. 常數時間操作
- HMAC 驗證使用常數時間比較（
hash_equals()） - 密碼驗證使用常數時間比較
- 密碼學操作不會產生基於計時的資訊洩漏
加密
TCPDF-Next 支援使用 AES-256 的 PDF 2.0 加密：
php
use YeeeFang\TcpdfNext\Encryption\EncryptionAlgorithm;
use YeeeFang\TcpdfNext\Encryption\Permissions;
$pdf->setEncryption()
->setAlgorithm(EncryptionAlgorithm::AES256)
->setUserPassword('reader-password')
->setOwnerPassword('admin-password')
->setPermissions(
Permissions::PRINT_HIGH_QUALITY
| Permissions::COPY
| Permissions::ACCESSIBILITY
)
->apply();加密功能
| 功能 | 說明 |
|---|---|
| AES-256-CBC | 依據 PDF 2.0（Revision 6）的預設加密 |
| 公鑰加密 | 針對多個收件者的憑證式加密 |
| 細粒度權限 | 控制列印、複製、修改、註解、填寫表單、擷取、組合 |
| 中繼資料加密 | 文件中繼資料可選擇性加密 |
WARNING
加密保護的是文件機密性，但無法保證完整性或不可否認性。如需完整性與不可否認性，請同時搭配使用數位簽章與加密。
數位簽章
TCPDF-Next 完整實作了 PAdES 基準設定檔（ETSI EN 319 142-1）的數位簽章：
| 等級 | 說明 | 驗證有效期 |
|---|---|---|
| PAdES B-B | 基礎 CMS 簽章 | 憑證有效期（約 1-3 年） |
| PAdES B-T | + RFC 3161 時間戳記 | TSA 憑證有效期（約 10-15 年） |
| PAdES B-LT | + DSS 含 OCSP/CRL 資料 | 演算法安全壽命（約 15-30 年） |
| PAdES B-LTA | + 歸檔時間戳記 | 無限期（搭配重新戳記） |
詳細資訊請參閱 PAdES B-LTA 簽章。
安全架構
┌─────────────────────────────────────────────────────┐
│ 應用程式層 │
│ （您使用 TCPDF-Next API 的程式碼） │
├─────────────────────────────────────────────────────┤
│ 驗證層 │
│ • 輸入淨化 • PDF 結構驗證 │
│ • 參數驗證 • 憑證鏈檢查 │
├─────────────────────────────────────────────────────┤
│ 密碼學層 │
│ • AES-256 加密 • CMS 簽章建構 │
│ • RSA/ECDSA/EdDSA • 雜湊計算 │
│ • HMAC 驗證 • 金鑰衍生 │
├─────────────────────────────────────────────────────┤
│ 核心 PDF 層 │
│ • 物件序列化 • 串流壓縮 │
│ • 交叉引用產生 • 增量更新 │
├─────────────────────────────────────────────────────┤
│ PHP 執行環境與擴充套件 │
│ • OpenSSL • Sodium • mbstring • zlib │
└─────────────────────────────────────────────────────┘相依性安全
TCPDF-Next 將外部相依性降至最低，以縮小攻擊面：
- 零執行期相依 — 核心 PDF 產生不依賴任何第三方 Composer 套件
- OpenSSL 擴充 — 密碼學操作所需（使用 PHP 內建綁定）
- Sodium 擴充 — 選用，用於安全記憶體清除及 Ed25519/Ed448（PHP 8.5+ 已內建）
- zlib 擴充 — 串流壓縮所需（PHP 已內建）
- mbstring 擴充 — Unicode 文字處理所需（PHP 已內建）
TIP
TCPDF-Next 刻意避免依賴外部 PHP 密碼學函式庫。所有密碼學操作均使用 PHP 內建的 OpenSSL 與 Sodium 擴充套件，它們是經過充分審計之 C 函式庫的薄封裝。
負責任揭露政策
我們嚴肅對待安全漏洞。若您發現 TCPDF-Next 的安全問題，請依照以下負責任揭露流程進行：
回報漏洞
- 請勿在公開的 GitHub Issue 中回報安全漏洞
- 電子郵件：[email protected]（PGP 金鑰如下）
- 請包含：
- 漏洞描述
- 重現步驟
- 潛在影響評估
- 建議修復方式（如有）
回應時程
| 階段 | 時程 |
|---|---|
| 確認收到 | 24 小時內 |
| 初步評估 | 72 小時內 |
| 修復開發 | 14 天內（重大）、30 天內（高） |
| 公開揭露 | 回報後 90 天，或修復釋出時 |
安全設定
建議的 php.ini 設定
ini
; 確保載入 OpenSSL
extension=openssl
; 確保載入 Sodium（PHP 8.5+ 已內建）
extension=sodium
; 停用 PDF 產生不需要的危險函式
disable_functions = exec,passthru,shell_exec,system,proc_open,popen
; 為 PDF 產生設定合理的記憶體限制
memory_limit = 256M
; 若接受 PDF 上傳，設定合理的檔案大小限制
upload_max_filesize = 50M
post_max_size = 50MTCPDF-Next 安全組態
php
use YeeeFang\TcpdfNext\Security\SecurityConfig;
SecurityConfig::global()
->setMinRsaKeySize(2048)
->setMinEcKeySize(256)
->setRejectSha1(true)
->setRejectRc4(true)
->setSecureMemoryWipe(true)
->setStrictPdfParsing(true)
->setMaxPdfFileSize(100 * 1024 * 1024) // 100 MB
->setMaxEmbeddedFileSize(50 * 1024 * 1024); // 50 MB安全文件
- 安全稽核報告 — 第三方稽核發現與修復
- TCPDF CVE 修復對照 — 已知 TCPDF 漏洞的處置方式
- 威脅模型 — PDF 簽章攻擊向量與緩解措施
- 安全最佳實踐 — 安全部署建議