Enterprise 版本穩定性: 實驗性

後量子 HSM 簽章（PQS）預覽能力狀態

概覽

預覽能力狀態。可選擇啟用、預設關閉、fail-closed。 這是一個 HSM 委派後量子簽章的預覽。它不是一般可用、它不是 AdES 相容、它未經 FIPS 驗證，且它不作任何認證或一致性主張。在你選擇啟用之前，預覽是關閉的；當它關閉時，簽章呼叫會以一個具型別例外 fail closed。

NextPDF Enterprise 公開一個實驗性的後量子簽章（PQS）介面，會透過一個 PKCS#11 硬體權杖驅動 ML-DSA（FIPS 204）與 SLH-DSA（FIPS 205）簽章。其路徑為 Pkcs11Signer::signPqs()，受一個明確的逐簽署者選擇性啟用（$enablePostQuantum），以及另外一個程序層級的環境旗標（NEXTPDF_FEATURE_PREVIEW_PQS_HSM）所控制。兩者皆預設為關閉。

本頁是誠實的邊界。它陳述此預覽做什麼——它將一個真正的後量子簽章操作委派給權杖——並以同等的誠實陳述它不是什麼：它不是 GA、不是 AdES、未經 FIPS 驗證，也不是一個對照 FIPS、OASIS 或 ETSI 的一致性主張。能讓一個後量子 PDF 簽章在長期封存上可互通的標準尚未落地（請參閱標準邊界）。

版次與授權

此能力隨 NextPDF Enterprise（nextpdf/enterprise）出貨，並以一個 Enterprise 層級的授權封套啟用。一個不具該權利的部署不會載入此能力的類別。比較版次並取得授權。

它建立在 Enterprise 的 PKCS#11 硬體權杖簽署者之上——請參閱 HSM 簽章。傳統（RSA / ECDSA）PKCS#11 簽章路徑是受支援、穩定的 Enterprise 能力；此處所述的後量子路徑是一個疊加於其上的實驗性預覽。NextPDF Enterprise 包含 Pro 功能集。

預覽能力狀態

此預覽驅動一個真正的簽章操作：啟用時，signPqs() 會派送到權杖上的候選 PKCS#11 v3.1 後量子機制，私鑰絕不離開權杖邊界，而回傳的位元組在被接受之前會對照所選參數集的 FIPS 規定簽章長度進行長度檢查。

它同時是一個預覽，而非一個一般可用的產品能力：

PKCS#11 後量子機制與參數集識別碼是臨時的——OASIS PKCS#11 v3.1 尚未定案一個後量子機制註冊表，因此所用的值被追蹤為臨時值，且 HSM 操作者必須在啟用之前確認其權杖的 PQ 韌體與它們相符。
NextPDF 中不存在後量子驗證路徑，且沒有任何 ETSI 套件為 AdES 長期封存註冊一個後量子簽章，因此在此處產生的一個簽章尚不可互通，且大多數 PDF 檢視器會在驗證時拒絕它。
一個配套的描述器 PqsCapabilityStatus 會以機器可讀的形式回報這些事實。每一個正面主張布林值——generallyAvailable、adesCompliant、verificationAvailable、conformanceClaimed——都硬式編碼為 false，並且即使在預覽旗標開啟時仍維持 false，沒有任何設定可以將其中一個翻為開啟。（它也帶有一個 recognitionOnly 旗標，硬式編碼為 true，記錄演算法辨識絕非一致性裁決；它不代表此介面無法簽章——簽章如上所述透過 signPqs() 進行。）

為何如此運作

NextPDF 已經能透過權杖計算一個真正的 ML-DSA 或 SLH-DSA 簽章。即便如此，每一個一致性布林值仍硬式編碼為 false，位於兩個預設關閉的閘門之後。一個簽章的價值僅在於日後能夠驗證它。對於後量子，尚不存在驗證路徑、沒有已註冊的 ETSI AdES 套件，也還沒有經 FIPS 驗證的 HSM 往返。將此以一般可用的形式出貨，會發出沒有任何檢視器能驗證、也沒有任何封存能信任的簽章。因此，此設計將產生位元組與主張任何人可以依賴它們分離開來，且沒有任何預覽旗標可以模糊那條界線。

設計背景：長期驗證。

演算法參數集

signPqs() 透過 Pkcs11PqsAlgorithm 列舉選擇演算法與參數集。每一個 case 都將一個 NIST 參數集對映到一個臨時的 PKCS#11 機制/參數集識別碼，以及用於縱深防禦長度檢查的 FIPS 規定簽章位元組長度。

ML-DSA——FIPS 204（模格）。 三個參數集，宣稱位於所示的 NIST 安全強度類別：

參數集	NIST 類別	簽章長度（位元組）
`ML-DSA-44`	2	2420
`ML-DSA-65`（建議的預設值）	3	3309
`ML-DSA-87`	5	4627

SLH-DSA——FIPS 205（無狀態雜湊式）。 十二個參數集，由 SHA2 / SHAKE x 128 / 192 / 256 x small（s）/ fast（f）構成。s 變體將簽章大小最小化；f 變體將簽章延遲最小化：

參數集系列	NIST 類別	簽章長度（位元組）
`SLH-DSA-{SHA2,SHAKE}-128s`	1	7856
`SLH-DSA-{SHA2,SHAKE}-128f`	1	17088
`SLH-DSA-{SHA2,SHAKE}-192s`	3	16224
`SLH-DSA-{SHA2,SHAKE}-192f`	3	35664
`SLH-DSA-{SHA2,SHAKE}-256s`	5	29792
`SLH-DSA-{SHA2,SHAKE}-256f`	5	49856

啟用預覽

兩個獨立的閘門都必須開啟。兩者皆預設為關閉。

程序閘門。 在程序啟動之前（或在狀態被讀取之前透過 putenv()）設定 NEXTPDF_FEATURE_PREVIEW_PQS_HSM=1。要求嚴格等於字串 1；任何其他值——包括 0、true、yes 或空值——都被視為關閉。
逐簽署者選擇性啟用。 將 $enablePostQuantum: true 傳給 Pkcs11Signer 建構函式。

use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11Signer;
use NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus;
use NextPDF\Enterprise\Security\Signature\Hsm\PqsPreviewFeature;

// 1. Open the process-level preview gate (default-off).
putenv(PqsPreviewFeature::ENV_PREVIEW_PQS_HSM . '=1');

// 2. The capability status is honest even with the gate open:
//    generallyAvailable / adesCompliant / verificationAvailable stay false.
$status = PqsCapabilityStatus::current();

// 3. Construct the PKCS#11 signer with the per-signer opt-in.
$signer = new Pkcs11Signer(
    libraryPath: '/usr/lib/softhsm/libsofthsm2.so',
    slotId: 0,
    pin: '1234',
    certLabel: 'my-pqc-signing-cert',
    enablePostQuantum: true,
);

// 4. Sign with a chosen parameter set. The returned bytes are length-checked
//    against Pkcs11PqsAlgorithm::signatureLength() before being accepted.
$signature = $signer->signPqs(
    data: $tbsBytes,
    algorithm: Pkcs11PqsAlgorithm::MlDsa65,
);

isPostQuantumEnabled() 回報逐簽署者選擇性啟用是否被設定，而 PqsCapabilityStatus::current() 回報程序層級的狀態加上誠實的主張布林值。

Fail-closed 邊界

此介面是 fail-closed 的，並透過具名、具型別的例外回報失敗，而非默默退回：

未選擇性啟用。 如果在 $enablePostQuantum 為 false 時呼叫 signPqs()，它會拋出 HsmOperationException。不會發生任何簽章。
情境過長。 一個長度超過 255 位元組的簽章情境八位元組字串，會在任何權杖呼叫之前拋出 InvalidArgumentException（依 FIPS 204 / FIPS 205 的情境上限）。
金鑰不存在。 如果權杖上沒有任何私鑰與所設定的標籤相符，signPqs() 會拋出 HsmOperationException。
長度不符。 如果權杖回傳一個其位元組長度不等於該參數集 FIPS 規定長度的簽章，signPqs() 會拋出 HsmOperationException——一個格式錯誤（被截斷或過大）的簽章會在抵達 CMS SignedData 編碼之前被拒絕。
權杖錯誤。 任何底層的 PKCS#11 錯誤都會被包裝為 HsmOperationException。

程序層級的環境旗標不會改變此邊界的任何部分：即使旗標開啟，能力布林值仍維持 false，而簽章路徑仍維持經過長度檢查且 fail-closed。

誠實邊界

以下主張不為此介面而作，且不得出現在由它衍生的任何文件、UI 或行銷中：

「GA」/「一般可用」。
「AdES」/「PAdES 相容」——沒有任何 ETSI 套件為長期封存註冊一個後量子簽章。
「FIPS 已驗證」——尚未為此路徑建立任何經 FIPS-140-3 驗證的後量子 HSM 往返。
對照 FIPS、OASIS PKCS#11 v3.1 或 ETSI 的「已認證」或「一致」。
「正式環境就緒」。

此介面誠實地是什麼：一個可選擇啟用、預設關閉、fail-closed 的 HSM 委派後量子簽章預覽，會透過一個 PKCS#11 權杖驅動 ML-DSA / SLH-DSA 並對結果進行長度檢查。它不是什麼：一個一般可用、AdES 相容、FIPS 已驗證或已認證的簽章能力。

標準邊界

所涉及的標準由外部機構維護，而此預覽對於是否符合其中任何一者不採取任何立場：

演算法參數集與簽章長度遵循 FIPS 204（ML-DSA）與 FIPS 205（SLH-DSA）。
權杖機制識別碼遵循 OASIS PKCS#11；PKCS#11 v3.1 中的後量子機制註冊表尚未定案，因此 NextPDF 使用臨時識別碼。
PDF 簽章長期封存設定檔為 ETSI EN 319 142-2（PAdES 延伸設定檔，建立在 CMS SignerInfo 之上）與密碼套件目錄 ETSI TS 119 312，後者目前僅為 RSA 與 ECDSA 制定設定檔——沒有任何後量子套件為 CAdES/PAdES 註冊。因此今日所產生的一個後量子 PDF 簽章在封存上尚不是 AdES 相容。

本頁未重現任何規範文字。

安全性注意事項

一個預覽不是一項安全控制。一個由此路徑所產生之後量子簽章的存在，並不建立 AdES 有效性、不蘊含一把受信任的金鑰，且無法被 NextPDF 驗證（不存在後量子驗證路徑）。請勿在簽章保證上依賴此預覽，亦請勿在需要一個 AdES 相容或 FIPS 已驗證簽章之處部署它。在標準落地之前，請在正式環境中保持兩個閘門皆關閉。

API 介面

符號	角色
`Pkcs11Signer::signPqs()`	可選擇啟用、fail-closed 的 HSM 委派後量子簽章，透過 PKCS#11 進行。在停用、金鑰不存在，或簽章長度不符時拋出 `HsmOperationException`。
`Pkcs11Signer::isPostQuantumEnabled()`	逐簽署者的 `$enablePostQuantum` 選擇性啟用是否被設定。
`Pkcs11PqsAlgorithm`	ML-DSA（FIPS 204）與 SLH-DSA（FIPS 205）參數集的列舉；將每一個對映到一個臨時機制 id 與 FIPS 規定的簽章長度。
`PqsPreviewFeature`	程序層級、預設關閉的環境閘門（`NEXTPDF_FEATURE_PREVIEW_PQS_HSM`）。
`PqsCapabilityStatus`	誠實、機器可讀的狀態：每一個正面主張布林值（一般可用、AdES、驗證、一致性）無論預覽旗標如何都硬式編碼為 `false`。
`HsmOperationException`	在 fail-closed 路徑上引發的具型別例外。

出版邊界

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