Enterprise 版本

Security — HSM、PKCS#11 與 FIPS 模式

速覽

NextPDF Enterprise 在 Core 與 Pro 安全範圍之上，新增一條 PKCS#11 硬體 token 簽署路徑與一套 FIPS 模式密碼學原則。本頁陳述行為、邊界，以及明確的 FIPS 認證與金鑰保管立場。

可用性與授權

此功能隨附於 NextPDF Enterprise（nextpdf/enterprise），並以一個 Enterprise 層級授權封套啟用。沒有該授權的部署不會載入此功能的類別。比較各版本並取得授權。

概念總覽

Enterprise 安全範圍有三個部分：一個硬體 token 簽署器、一套 FIPS 模式密碼學原則，以及一個開機自我測試守衛。

硬體 token 簽署器配接一個 PKCS#11 token——一張智慧卡、一個 USB 裝置，或一個網路型 HSM。簽署器依標籤在 token 上定位憑證與私鑰。接著它請 token 計算簽章。私鑰不會離開 token 邊界；該操作在 token 內部執行。token 簽署操作、工作階段與使用者登入遵循 PKCS#11 v3.1 §5。HSM 路徑需要 ext-pkcs11 PHP 擴充。該擴充不是標準 PHP 的一部分。請另外安裝它。請在建構簽署器之前先使用可用性檢查。

FIPS 模式密碼學原則將密碼學選擇限制在一個已核准的集合內。它有兩個預設。strict 預設允許 SHA-256、SHA-384 與 SHA-512 雜湊；搭配那些雜湊的 RSA 與 ECDSA 簽章 OID；AES-256-CBC 加密；以及最小金鑰大小 RSA 2048 與 EC 256。standard 預設相同，但另允許 AES-128-CBC 以利較舊的互通。一個執行階段守衛包覆該原則。守衛會在操作執行之前檢查每個雜湊、簽章 OID、加密演算法與金鑰強度。不被允許的選擇會引發一個具型別的違規並停止該操作。該路徑為 fail-closed：原則絕不放鬆自己，也絕不以較弱的演算法替代。最小 RSA 金鑰長度遵循 NIST SP 800-131A Rev.2 §3。ECDSA 曲線與雜湊配對遵循 FIPS 186-5 §6.1.1。

開機自我測試守衛會在程序啟動時執行一次已知答案測試電池。該電池涵蓋已核准的雜湊、MAC、加密、簽章與隨機位元函式。若任一測試失敗，Enterprise FIPS 守衛會進入錯誤狀態，並在重設之前拒絕提供密碼學服務。結果會快取至程序生命週期結束；提供隨選重跑。自我測試類別與條件式測試觸發遵循 ISO/IEC 19790:2025 §7.10 與 §7.10.3。

為何如此設計

承載性的決策是將私鑰保留在 token 邊界內，並使密碼學原則為 fail-closed。一個能匯出金鑰、或會默默回退至較弱演算法的簽署器，會摧毀 HSM 存在所要提供的保證。因此簽署器請 token 就地計算簽章，而 FIPS 模式守衛會在操作執行之前，拒絕任何位於已核准預設之外的雜湊、OID 或金鑰強度。開機自我測試將同樣的姿態延伸至啟動：一個未經驗證的模組會拒絕服務，而非在未經測試的原語上簽署。其結果是一個你能夠推理的邊界，其中金鑰保管由操作者與 token 擁有，而非由本軟體擁有。

設計背景：HSM 後援簽署。

API 介面

Public surface	Type	Purpose	Stability	Since
PKCS#11 token signer	class (implements the Core `HsmSignerInterface`)	以一個 PKCS#11 token 簽署；金鑰留在 token 上	stable	1.0.0
FIPS crypto-policy	class (implements the Core `CryptoPolicyInterface`)	一個允許演算法與金鑰強度的預設	stable	1.9.0
FIPS-mode guard	class	斷言某個雜湊、簽章 OID、加密演算法或金鑰強度是被允許的	stable	1.9.0
FIPS boot guard	class	執行並快取開機自我測試；斷言模組可運作	stable	3.2.0
OpenSSL CLI / engine signer	class (implements `HsmSignerInterface`)	為 engine 後援的 token，透過 OpenSSL engine 或 OpenSSL CLI 簽署	stable	1.0.0

token 簽署器建構子取用 PKCS#11 函式庫路徑、slot 號碼、token PIN、憑證標籤，以及一個選用的獨立金鑰標籤。PIN 參數標記為敏感；它不會被記錄，也不會被序列化。簽署器也以 DER 形式公開簽署者憑證與憑證鏈。權威的參數與型別合約是 nextpdf/enterprise 套件已發布的 API 參考；請將該參考——而非本頁——視為合約。

程式碼範例 — 快速上手

composer require nextpdf/core
composer require nextpdf/enterprise:^3

use NextPDF\Enterprise\Security\Fips\FipsCryptoPolicy;
use NextPDF\Enterprise\Security\Fips\FipsModeGuard;

$guard = new FipsModeGuard(FipsCryptoPolicy::strict());

// Throws a typed FIPS violation if the algorithm is not approved.
$guard->assertHashAllowed('sha256');
$guard->assertKeyStrengthAllowed('rsa', 2048);

程式碼範例 — 正式環境

use NextPDF\Enterprise\Security\Fips\FipsBootGuard;
use NextPDF\Enterprise\Security\Fips\FipsSelfTest;

// At application bootstrap (one self-test cycle per worker process):
$bootGuard = new FipsBootGuard(new FipsSelfTest());
$bootGuard->assertOperational(); // throws on a known-answer-test failure
$container->set(FipsBootGuard::class, $bootGuard);

// The PKCS#11 token signer is only available when ext-pkcs11 is loaded.
// Check availability before you construct the signer. The PIN is a secret;
// supply it from your secret manager, never from source or logs.

完整的建構子引數清單、例外型別，以及 PKCS#11 token 簽署器的建構，記載於 Enterprise 安全深入參考。

邊界案例與陷阱

PKCS#11 token 簽署器建構子會在 ext-pkcs11 未載入時擲出一個具型別的操作例外。請先檢查可用性。
token 簽署器會為每個程序、每個函式庫路徑快取一個 PKCS#11 模組。這滿足 token 介面「每個模組初始化一次」的規則。
ECDSA token 機制回傳原始簽章。簽署器會將其轉換為 DER 編碼形式，以利 PDF 與 OpenSSL 互通。
FIPS 守衛預設拒絕未知的金鑰型別。不被辨識的金鑰型別不會被默默接受。
後量子簽署路徑是實驗性的、選用的，且預設停用。標準 PAdES 長期封存設定檔尚未承認後量子套件。請勿為正式的 AdES 簽章啟用它。

效能

FIPS 守衛檢查是常數時間的雜湊表查詢。開機自我測試每個程序執行一次；其成本攤提至整個程序生命週期，而非逐次簽署呼叫。一次 PKCS#11 簽署操作會增加一次往返 token。一個網路型 HSM 會增加那次往返的網路延遲。

安全注意事項

簽署路徑為 fail-closed。原語失敗或原則缺口會引發一個具型別的例外。該路徑絕不默默降級為較弱的演算法。
token PIN 參數標記為敏感。它不會被記錄，也不會被序列化。
PKCS#11 token 的私鑰留在 token 上。簽署操作在 token 邊界內部執行。
開機自我測試在已知答案測試不符時，將 Enterprise FIPS 守衛置入錯誤狀態，並在重設之前拒絕提供密碼學服務。
AES-GCM 的使用要求每把金鑰有一個唯一的初始化向量，依 NIST SP 800-38D §5。

資料落地與 PII 緩解措施

簽署與 FIPS 原則程式碼在行程內執行。FIPS 原則檢查或開機自我測試不會讓任何文件內容離開主機。一個 PKCS#11 token 接收待簽署的資料，而非無關的文件內容。一個網路型 HSM 會透過你所設定的網路通道接收該資料。金鑰材料留在 token 或 HSM 邊界內部。

安全遙測與日誌清洗

token PIN 是一個敏感的建構子參數，並被排除於日誌與序列化之外。請勿將 PIN、token 標籤或金鑰材料加入你自己的應用程式日誌。請在你的日誌與追蹤政策中將所有 token 憑證視為密碼。

威脅模型

這是一個密碼學邊界，因此威脅模型是明確的。待簽署的資料被交給 token；token 持有金鑰。token 或 HSM 錯誤會引發一個具型別的例外；簽署器不會產生未簽署或部分簽署的結果。金鑰保護取決於 token 或 HSM、取決於部署，以及取決於操作者——而非單靠本軟體。請參閱部署邊界。

一致性

開機與條件式自我測試模型與 ISO/IEC 19790:2025 §7.10 與 §7.10.3 對齊。
最小 RSA 簽章金鑰長度與 NIST SP 800-131A Rev.2 §3 對齊。
已核准的 ECDSA 曲線與雜湊配對與 FIPS 186-5 §6.1.1 對齊。
PKCS#11 token 簽署操作與工作階段登入與 PKCS#11 v3.1 §5 對齊。
金鑰保護責任與 NIST SP 800-57 Part 1 Rev.5 §5.5.2 對齊。
AES-GCM 初始化向量唯一性與 NIST SP 800-38D §5 對齊。

每個規範性來源皆為改寫。本頁不重現任何規範性文字。本頁涉及密碼學簽署。

FIPS 模式行為

FIPS 模式原則將密碼學選擇限制在上述已核准的集合內。當設定為搭配一個經 FIPS 驗證的 OpenSSL 供應者時，底層原語在該已驗證邊界內執行。NextPDF Enterprise 本身執行結構性組裝、摘要計算與原則強制。

NextPDF Enterprise 不是經 FIPS 驗證的密碼學模組，亦不做任何 FIPS 認證聲明。 NextPDF Enterprise 只有在被設定為搭配一個經 FIPS 驗證的密碼學供應者——例如一個經 FIPS 驗證的 OpenSSL 供應者——或一個經 FIPS 驗證的 HSM 時，才以 FIPS 相容模式運作。FIPS 模式原則協助合規；它不是認證。

版本邊界

NextPDF Core 隨附軟體簽署器、RFC 3161 時間戳記取用、RFC 5280 路徑驗證，以及 OCSP 與 CRL 撤銷檢查。Core 產生 PAdES B-B 與 B-T 層級。NextPDF Pro 新增遮罩、文字層 PII 偵測、多方循序簽署，以及遠端與雲端 KMS 簽署策略（AWS KMS、GCP Cloud KMS、Azure Key Vault）。NextPDF Pro 不提供 PKCS#11 硬體 token 路徑，也不提供 FIPS 模式密碼學原則設定檔。PKCS#11 硬體 token 簽署器、FIPS 模式密碼學原則設定檔、開機自我測試守衛，以及 PAdES B-LT 與 B-LTA 產生器僅隨附於 nextpdf/enterprise 套件。沒有 Enterprise 授權的部署不會載入 Enterprise 類別。

Pro 回退

在僅有 Pro 的部署中，受支援的硬體後援與雲端後援簽署路徑是 Pro 雲端 KMS 策略：一個雲端 KMS 或 HSM 後援的 KMS 持有金鑰，而 Pro 將已簽署屬性的摘要（而非文件）送往供應商。Pro 提供 KMS 整合，而非 Enterprise PKCS#11 token 工廠或 FIPS 模式設定檔。在僅有 Pro 的部署中，請求 B-LT、B-LTA、一個 PKCS#11 token 或 FIPS 模式設定檔的設定會 fail closed，並附上指名缺少之 Enterprise 元件的訊息。Pro 簽署介面請參閱 Security — NextPDF Pro。

Core 回退

在僅有 Core 的部署中，軟體簽署器以本機金鑰，或透過 Core 簽署策略合約提供的金鑰，產生 PAdES B-B 與 B-T。Core 沒有硬體 token 路徑，也沒有 FIPS 模式設定檔。請參閱 Security — NextPDF Core。

Enterprise 邊界註記

PKCS#11 token 整合、其機制對應，以及其工作階段處理皆僅以行為層級描述。內部機制對應表、內部工作階段復原邏輯，以及後量子遷移材料不在公開介面的範圍內，此處不予重現。

部署邊界

NextPDF Enterprise 整合一個 PKCS#11 token、一個 HSM，或一個 KMS。它本身不儲存、不產生，也不保證簽署金鑰的安全。**金鑰安全取決於 token、HSM 或 KMS、取決於部署，以及取決於操作者——而非單靠 NextPDF Enterprise。**操作者負責 token 配置、PIN 處理、slot 設定、網路型 HSM 的網路保護，以及信任設定。金鑰保護責任遵循 NIST SP 800-57 Part 1 Rev.5 §5.5.2。NextPDF Enterprise 不在本文件中揭露 token PIN 處理、slot 設定內部實作，或廠商憑證材料。

法律合規邊界

本頁涉及密碼學簽署與硬體安全模組整合。FIPS 模式原則是一項合規協助功能。它不是法律意見，也不是認證。關於你的法規義務，請諮詢你自己的合規與法律顧問。

發布邊界

本頁僅記載外部可觀察的行為與受支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表、runbook 檔名，以及工單前綴皆不在範圍內。

行為合約

FIPS 守衛會針對作用中的預設斷言每個雜湊、簽章 OID、加密演算法與金鑰強度，並在不被允許的選擇時引發一個具型別的違規。
開機自我測試每個程序執行一次，並在已知答案測試失敗時拒絕提供密碼學服務直到重設。
PKCS#11 token 簽署器需要 ext-pkcs11；它在該擴充缺席時引發一個具型別的操作例外。
簽署路徑為 fail-closed，且絕不以較弱的演算法替代。

另請參閱

Security — NextPDF Enterprise（深入參考）
Security — NextPDF Pro
Signature — NextPDF Enterprise
Accelerator — NextPDF Enterprise
Security — NextPDF Core
PAdES · HSM · PKCS#11 · FIPS mode · KMS — 詞彙表條目。