簽章與加密安全模型

重點摘要

本頁說明核心引擎提供的兩種密碼學介面的安全模型：文件加密（AES-256）與文件簽署（CMS/PAdES），並釐清每種機制保護什麼、不保護什麼，以及信任邊界落在哪裡。

邊界。 支援某項密碼學機制，並不保證它在你的部署環境中安全。已加密文件的強度取決於你選用的密碼與金鑰保管方式。一份簽章的意義取決於憑證、信任錨點、時間戳記授權單位，以及驗證者的政策。憑證、信任錨點、時間戳記授權單位與驗證者政策，全都位於本函式庫之外。本頁描述的是機制；它並不為結果背書。

安裝

composer require nextpdf/core:^3

ext-openssl 是簽署與 CMS 路徑所需的擴充。

概念總覽

加密在核心引擎中指的是 ISO 32000-2 §7.6 的 AES-256 安全處理器（AESV3，Revision 6）（iso32000_2_sec7#x1.x65.p29）。它提供機密性：沒有密碼的一方無法讀取字串與串流內容。它不提供完整性或真確性。密文仍可能遭到截斷或替換。偵測遭截斷或替換的密文，是簽章或文件 MAC 的職責，而不是加密處理器的職責。

權限（列印、複製、修改）是另一個概念，也是常見的信任陷阱。ISO 32000-2 的權限旗標屬於讀取器配合性質（iso32000_2_sec7#x1.x71.p27）。符合規範的讀取器會遵守這些旗標，但它們是諮詢性的中繼資料，而不是密碼學上的存取控制。不配合的工具可以忽略它們。引擎會忠實寫出這些旗標；但無法強制執行。

簽署是一個依 ISO 32000-2 §12.8 內嵌的 CMS SignedData 結構。被簽署的位元組範圍是一個直接物件，而摘要刻意排除簽章的 Contents 值（iso32000_2_sec12#x1.x121.p45），因此簽章涵蓋文件，但不涵蓋簽章本身。

API 介面

本頁不重複說明簽章 API。加密的進入點與簽署協調器，分別記錄於 /modules/core/security/ 與 /modules/core/security/signing/。這裡的模型聚焦於意義與邊界，而不是方法形式。

程式碼範例 — 快速上手

加密只保護內容對沒有密碼者的機密性 —— 僅此而已：

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = new Document();
// AES-256 (AESV3 R6). The owner/user passwords gate read access only.
// Permission flags below are advisory: a conforming reader honors them.
$doc->encrypt(
    userPassword: 'open-secret',
    ownerPassword: 'owner-secret',
);
$doc->save('confidential.pdf');

程式碼範例 — 正式環境

正式環境的簽署流程會使用軟體持有的金鑰，套用 CMS/PAdES 基準簽章。Core 版會產生 PAdES B-B 等級。設定時間戳記授權單位後，Core 版會產生 PAdES B-T，也就是在 B-B 上再加上一個 RFC 3161 signature-time-stamp 未簽署屬性：

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Security\Signature\CertificateInfo;
use NextPDF\Security\Signature\SignatureLevel;

$cert = CertificateInfo::fromPkcs12('signer.p12', 'pin');

$doc = new Document();
// B-B is the default. B-T adds a trusted timestamp over the signature value.
$doc->setSignature($cert, SignatureLevel::PAdES_B_B);
$doc->save('signed.pdf');

PAdES B-T 正是 B-B 再加上一個 RFC 3161 signature-time-stamp 未簽署屬性，並承載於 CMS 的 SignerInfo 之中（rfc5652#p603）。這個時間戳記會把簽章值繫結到從時間戳記授權單位取得的可信時間（rfc3161#p208）。它不會加入驗證資料字典、撤銷資訊結構或封存時間戳記迴圈。那些屬於各自獨立、範圍分開的長期等級，並非 B-B/B-T 介面的一部分，也不在本頁範圍內。

U-1。 NextPDF 並未主張任何針對 PAdES B-T 的獨立 ETSI EN 319 142-1 認證。EN 319 142-1 並不在此處使用的驗證語料庫中。B-T 的 signature-time-stamp 要求，是對照 ETSI EN 319 122-1 §5.3 —— 也就是 EN 319 142 針對 PAdES 系列以引用方式匯入的 CAdES 基礎（etsi_en_319_122_1#6.x40.p96）—— 連同 RFC 3161、RFC 5652，以及 ISO 32000-2 §12.8 一併驗證。支援 B-T 設定檔，並不構成符合性，也不是法律效力認證。這項判定要由獨立的驗證者作出。

邊界情況與陷阱

加密 ≠ 完整性。 即使讀取器能開啟文件，仍可能讀到一份遭竄改的副本。只有簽章（或文件 MAC）才能偵測這種情況。「防竄改」並不是加密處理器所提供的性質，本產品也不以此詞作為宣稱。
簽章存在不等於簽章有效。 文件帶有簽章字典，並不能說明憑證是否受信任、是否未過期，或是否未被撤銷。確立有效性是驗證端的作業，受信賴方政策管轄，而不是由簽署者決定。
時間戳記的信任在外部。 一個 B-T 時間戳記的意義，只取決於驗證者對發行該時間戳記的時間戳記授權單位所賦予的信任。函式庫負責取得並內嵌該權杖；它並不為該 TSA 背書。
FIPS 態勢屬於環境層面。 在通過 FIPS 驗證的密碼學模組上執行，是作業環境與模組本身的性質（fips_140_3#x12），不是 PHP 函式庫可以替呼叫端主張的事項。

效能

簽章路徑會計算一個位元組範圍摘要與一個 CMS 結構。B-T 延伸會對時間戳記授權單位增加一次同步往返。加密是一種 per-string/per-stream 對稱運算。兩者都不會主導一次典型的繪製。B-T 的網路往返才是變動成本，且取決於呼叫端選擇的 TSA。

安全注意事項

以下將邊界陳述整理成審查者可執行的規則：

僅限機密性。 AES-256 加密保護內容，避免被沒有密碼的一方讀取。它不是完整性、不是真確性，也不是存取控制（iso32000_2_sec7#x1.x65.p29）。
權限屬諮詢性質。 權限旗標屬於讀取器配合性質，並未在密碼學上強制執行（iso32000_2_sec7#x1.x71.p27）。沒有任何產品用語宣稱它們能阻止某項動作。
本頁僅涵蓋 B-B 與 B-T。 此處記錄的 core/Pro 簽署介面涵蓋 B-B 及其 B-T 時間戳記延伸；每一處提及 B-T 的位置，都與上方的 U-1 警語並列。長期封存等級屬於另一個付費版本的介面，此處刻意不描述。本頁並未主張任何驗證資料、撤銷資訊或封存時間戳記能力。
不主張法律效力。 所產生的簽章是一項密碼學產物。它是否具法律效力，取決於管轄區、憑證政策與信賴方 —— 而不取決於本函式庫。

符合性

支援不等於符合。引擎產生的輸出使用所引用的 ISO 32000-2、RFC 3161、RFC 5652 與 ETSI EN 319 122-1 結構。引擎並不主張 PAdES、CAdES 或 eIDAS 符合性。FIPS 140-3 驗證是 module/environment 的性質（fips_140_3#x12），而不是函式庫的主張。任何符合性或法律效力的判定，皆由獨立的驗證者或評鑑者作出。