進階加密

★ Pro — Commercial License Required

進階加密功能需要 Pro 套件。

TCPDF-Next 僅支援 AES-256 加密（AESV3 加密處理器，Revision 6），這是 PDF 2.0 標準中唯一推薦的加密方式。Pro 套件提供底層加密機制的完整控制，包括金鑰推導、密碼正規化與權限編碼。

安全策略

項目	策略
支援的加密	AES-256（AESV3，Revision 6）
不支援的加密	RC4 40-bit、RC4 128-bit、AES-128
金鑰推導	基於密碼的金鑰推導（PDF 2.0 規範）
密碼正規化	SASLprep（RFC 4013）
密碼最大長度	127 位元組（UTF-8 編碼後）

TCPDF-Next 刻意不支援 RC4 與 AES-128，因為這些演算法已被視為不安全。如果需要開啟使用舊加密方式的既有文件，請使用專門的 PDF 處理工具。

AES-256 AESV3 詳解

加密架構

密碼 → SASLprep 正規化 → 金鑰推導 → 256-bit 加密金鑰
                                        ↓
                              AES-256-CBC 加密每個串流與字串

基本加密

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->font('Helvetica', size: 12)
    ->text('此文件使用 AES-256 加密保護。');

$pdf->encrypt(
    userPassword: 'reader-pass',
    ownerPassword: 'owner-pass'
);

$pdf->save('/output/encrypted.pdf');

金鑰推導

PDF 2.0 的金鑰推導流程基於以下步驟：

1. 密碼正規化：使用 SASLprep 將密碼轉為標準形式。
2. 雜湊計算：使用 SHA-256 計算密碼雜湊。
3. 金鑰加密金鑰：產生隨機的 Key Encryption Key（KEK）。
4. 檔案加密金鑰：產生隨機的 File Encryption Key（FEK）。
5. 金鑰包裝：使用 KEK 包裝 FEK，儲存在加密字典中。

use Yeeefang\TcpdfNext\Pro\Security\Encryption\Aes256Encryptor;

$encryptor = new Aes256Encryptor();

// 底層金鑰推導（通常不需手動呼叫）
$keys = $encryptor->deriveKeys(
    userPassword: 'reader-pass',
    ownerPassword: 'owner-pass'
);

SASLprep 密碼正規化

SASLprep（RFC 4013）確保不同平台、不同輸入法輸入的相同密碼會被統一處理：

use Yeeefang\TcpdfNext\Pro\Security\Encryption\SaslPrep;

$normalized = SaslPrep::prepare('Ｐａｓｓｗｏｒｄ');  // 全形轉半形
// 結果：'Password'

$normalized = SaslPrep::prepare("caf\u{00E9}");       // NFC 正規化
// 結果：'caf' + U+00E9

SASLprep 處理規則

步驟	說明
對應	移除不列印字元，全形轉半形
正規化	Unicode NFKC 正規化
禁止字元	拒絕控制字元、私用區字元等
雙向檢查	驗證混合方向文字的正確性

權限編碼

PDF 2.0 使用 32-bit 旗標編碼文件權限。Pro 套件提供型別安全的權限設定：

use Yeeefang\TcpdfNext\Contracts\Enums\Permission;

$pdf->encrypt(
    userPassword: '',               // 空字串 = 開啟不需密碼
    ownerPassword: 'admin-pass',
    permissions: [
        Permission::Print,
        Permission::PrintHighQuality,
    ]
);

權限旗標對應

權限	位元位置	說明
Print	3	列印（可能為低解析度）
Modify	4	修改文件內容
Copy	5	複製或擷取文字
Annotate	6	新增或修改註解
FillForms	9	填寫表單欄位
ExtractForAccessibility	10	為輔助技術擷取內容
Assemble	11	組裝文件
PrintHighQuality	12	高品質列印

不設權限限制

$pdf->encrypt(
    userPassword: 'secure-pass',
    ownerPassword: 'admin-pass',
    permissions: Permission::all()   // 授予所有權限
);

與 PDF/A 的關係

PDF/A 標準明確禁止加密。如果同時啟用加密與 PDF/A 合規，PdfAManager 會在驗證階段回報錯誤。數位簽章不屬於加密，PDF/A 文件可以正常使用數位簽章。

下一步

• PAdES 數位簽章 — 數位簽章與加密是獨立功能。
• PDF/A-4 歸檔 — 瞭解為何 PDF/A 禁止加密。
• 授權 — Pro 套件的商業授權條款。