跳到內容
NextPDF
getnextpdf.com

Enterprise 版本穩定性: 實驗性

後量子簽章預覽 — 深入參考

概覽

標題為「概覽」的區段

本頁是 NextPDF Enterprise 中後量子簽章（PQS）預覽介面的合約層級參考。它涵蓋三個公開符號：Pkcs11PqsAlgorithm 參數集列舉、PqsPreviewFeature 行程閘門，以及 PqsCapabilityStatus 描述子。本頁也說明 NEXTPDF_FEATURE_PREVIEW_PQS_HSM 環境閘門。

此介面屬於實驗性且預設關閉。它能辨識 ML-DSA（FIPS 204）與 SLH-DSA（FIPS 205）的演算法識別碼、參數集及簽章長度。辨識並不等於驗證裁決。此處沒有後量子驗證路徑。本預覽不做任何 AdES、FIPS 驗證或符合性宣告，且預覽旗標無法憑空造出一個。消費端的簽章進入點 Pkcs11Signer::signPqs() 記載於能力頁面。

供應與授權

標題為「供應與授權」的區段

此能力隨附於 NextPDF Enterprise（nextpdf/enterprise），並以 Enterprise 級授權封套啟用。缺少該權利的部署不會載入此能力的類別。比較版本並取得授權。

授權啟用的是整體 Enterprise PKCS#11 介面。其中的後量子路徑無論授權級別為何，始終維持在預覽狀態。仍需兩道彼此獨立的選擇性啟用：本頁記載的行程閘門，以及 Pkcs11Signer 上的每簽章者建構子旗標。

公開 API 介面

標題為「公開 API 介面」的區段
SymbolParametersDefault behaviorReturnsThrows or fails withNotes
Pkcs11PqsAlgorithmstring 型別列舉，15 個案例每個案例命名一個 FIPS 204 / FIPS 205 參數集enum case存取案例時不發生案例值即為參數集名稱，例如 ML-DSA-65。
Pkcs11PqsAlgorithm::isMlDsa()無家族判定bool不擲出例外對 MlDsa44、MlDsa65、MlDsa87 為 true。
Pkcs11PqsAlgorithm::isSlhDsa()無isMlDsa() 的反向bool不擲出例外對十二個 SLH-DSA 案例為 true。
Pkcs11PqsAlgorithm::mechanismId()無將家族對應到候選的 PKCS#11 v3.1 PQ 機制 idint當執行環境缺少臨時性 Pkcs11 PQ 常數時擲出 PHP ErrorCKM_ML_DSA 或 CKM_SLH_DSA；兩個 id 皆為臨時性。
Pkcs11PqsAlgorithm::parameterSetId()無將案例對應到 OASIS 參數集判別碼int當執行環境缺少臨時性 Pkcs11 PQ 常數時擲出 PHP ErrorCKP_* 值；臨時性。
Pkcs11PqsAlgorithm::signatureLength()無該案例經 FIPS 規定的簽章位元組長度int（正值）不擲出例外由簽章路徑消費，用以拒絕長度異常的回傳簽章。
Pkcs11PqsAlgorithm::nistCategory()無所宣稱的 NIST 安全強度類別int不擲出例外回傳 1、2、3 或 5。
PqsPreviewFeaturestring 型別列舉，1 個案例單一案例 PREVIEW_PQS_HSM；常數 ENV_PREVIEW_PQS_HSMenum case存取案例時不發生行程層級的預覽閘門。
PqsPreviewFeature::isEnabled()無即時讀取 getenv()；對字串 1 做嚴格比較bool不擲出例外變數不存在或為任何其他值（含 0、true、yes）皆為關閉。
PqsCapabilityStatus::__construct()九個具名 readonly 欄位建立任意的描述子實例PqsCapabilityStatus不擲出例外current() 才是正規建構子。
PqsCapabilityStatus::current()無為所處行程建立描述子PqsCapabilityStatus不擲出例外每個宣告布林值皆固定；只有 hsmRoundtripPreviewEnabled 隨閘門變動。
PqsCapabilityStatus::summary()無單行狀態文字string不擲出例外用詞不帶任何供應、封存或驗證宣告。
enum Pkcs11PqsAlgorithm: string


case MlDsa44 = 'ML-DSA-44';
case MlDsa65 = 'ML-DSA-65';
case MlDsa87 = 'ML-DSA-87';


case SlhDsaSha2_128s = 'SLH-DSA-SHA2-128s';
case SlhDsaShake_128s = 'SLH-DSA-SHAKE-128s';
case SlhDsaSha2_128f = 'SLH-DSA-SHA2-128f';
case SlhDsaShake_128f = 'SLH-DSA-SHAKE-128f';


case SlhDsaSha2_192s = 'SLH-DSA-SHA2-192s';
case SlhDsaShake_192s = 'SLH-DSA-SHAKE-192s';
case SlhDsaSha2_192f = 'SLH-DSA-SHA2-192f';
case SlhDsaShake_192f = 'SLH-DSA-SHAKE-192f';


case SlhDsaSha2_256s = 'SLH-DSA-SHA2-256s';
case SlhDsaShake_256s = 'SLH-DSA-SHAKE-256s';
case SlhDsaSha2_256f = 'SLH-DSA-SHA2-256f';
case SlhDsaShake_256f = 'SLH-DSA-SHAKE-256f';


public function isMlDsa(): bool
public function isSlhDsa(): bool
public function mechanismId(): int
public function parameterSetId(): int
public function signatureLength(): int
public function nistCategory(): int
enum PqsPreviewFeature: string


case PREVIEW_PQS_HSM = 'preview_pqs_hsm';


public const string ENV_PREVIEW_PQS_HSM = 'NEXTPDF_FEATURE_PREVIEW_PQS_HSM';


public function isEnabled(): bool
final readonly class PqsCapabilityStatus


public const string MATURITY_PREVIEW_EXPERIMENTAL = 'preview-experimental';
public const string MECHANISM_STATUS_PROVISIONAL = 'provisional';


public function __construct(
    public bool $hsmRoundtripPreviewEnabled,
    public bool $generallyAvailable,
    public bool $adesCompliant,
    public bool $verificationAvailable,
    public bool $conformanceClaimed,
    public bool $recognitionOnly,
    public string $maturity,
    public string $mechanismIdStatus,
    public string $envGate,
)


public static function current(): self
public function summary(): string

行為合約

標題為「行為合約」的區段
  • 參數集目錄。 NextPDF\Enterprise\Security\Signature\Hsm\Pkcs11PqsAlgorithm 列舉三個 ML-DSA 集（FIPS 204）與十二個 SLH-DSA 集（FIPS 205 §11.p12，Table 2）。每個案例對應到一個臨時性機制 id、一個參數集判別碼、一個經 FIPS 規定的簽章位元組長度，以及一個所宣稱的 NIST 類別。
  • 簽章長度。 signatureLength() 對 MlDsa44、MlDsa65、MlDsa87 分別回傳 2420、3309、4627 位元組，依 FIPS 204 §4.p15（Table 2）。SLH-DSA 案例依級別與變體回傳 7856、17088、16224、35664、29792、49856 位元組，依 FIPS 205 §11（Table 2）。當回傳簽章長度不符時，消費端簽章者會擲出 HsmOperationException，對映 FIPS 204 §x34 的長度拒絕紀律。
  • 類別。 nistCategory() 對 ML-DSA 案例回傳 2、3、5，依 FIPS 204 §4.p9。SLH-DSA 案例依安全參數級別回傳 1、3、5。
  • 行程閘門。 PqsPreviewFeature::PREVIEW_PQS_HSM 預設關閉。isEnabled() 只有在環境變數 NEXTPDF_FEATURE_PREVIEW_PQS_HSM 恰好等於字串 1 時才回傳 true。每次呼叫都即時讀取；不做任何記憶化。
  • 互補閘控。 行程閘門與 Pkcs11Signer 上每簽章者的 $enablePostQuantum 建構子選擇性啟用彼此分離。缺少每簽章者的選擇性啟用時，簽章呼叫會失敗關閉。行程閘門的存在，是為任何未來的往返或封存行為提供單一可稽核的邊界。
  • 誠實不變量。 NextPDF\Enterprise\Security\Signature\Hsm\PqsCapabilityStatus::current() 將 generallyAvailable、adesCompliant、verificationAvailable、conformanceClaimed 硬編碼為 false，並將 recognitionOnly 硬編碼為 true。沒有任何設定、建構子選項或環境旗標能把某個宣告翻成開啟。只有 hsmRoundtripPreviewEnabled 反映閘門狀態。
  • 無驗證路徑。 NextPDF 沒有後量子驗證路徑。一個被辨識的演算法識別碼或一個格式正確的簽章長度，永遠不是接受裁決。

邊界情形與失效模式

標題為「邊界情形與失效模式」的區段
  • 將閘門變數設為 0、true、yes、on 或空字串,都會使閘門維持關閉。只有恰好的字串 1 才會啟用它。
  • 由於讀取是即時的，putenv() 的變更會在下一次 isEnabled() 呼叫時生效。行程中途切換的閘門會立即被觀察到。
  • mechanismId() 與 parameterSetId() 從 Pkcs11 擴充命名空間解析常數。缺少臨時性後量子擴充常數的執行環境，會在呼叫時以 PHP Error（未定義常數）失敗。
  • 機制與參數集 id 皆為臨時性。OASIS 尚未定案 PKCS#11 v3.1 後量子登錄。若某權杖的韌體指派了不同的 id,將在 PKCS#11 層失敗；操作人員必須在啟用預覽前確認韌體 id。
  • 消費端簽章者所接受的簽章脈絡以 255 位元組為上限,對映 FIPS 204 的簽章輸入合約（§x43.p2）。較長的脈絡會在任何權杖呼叫之前擲出 InvalidArgumentException。
  • PqsCapabilityStatus::__construct() 為公開,因此手工建構的實例可攜帶任意布林值。這樣的實例只是一個值物件。它不會改變任何簽章行為。current() 才是正規且硬編碼的建構子。
  • 消費端簽章者上的隨機化對確定性選擇,遵循 FIPS 205 §x65.p7 語意:對沖式簽章為預設。此旗標對 ML-DSA 被忽略,ML-DSA 一律透過自身的 nonce 進行隨機化。

FIPS 模式行為

標題為「FIPS 模式行為」的區段

ML-DSA 與 SLH-DSA 是 FIPS 204 與 FIPS 205 演算法,但本預覽不帶任何 FIPS 140-3 驗證宣告。此路徑尚未建立任何經 FIPS 驗證的後量子 HSM 往返。Enterprise FIPS 模式加密政策設定檔（記載於 Security 深度參考）閘控的是傳統簽章演算法;它不會把 PQS 介面納入一個已驗證的集合。啟用 FIPS 模式並不會讓後量子簽章成為經 FIPS 驗證。切勿在需要經 FIPS 驗證簽章之處部署本預覽。

符合性

標題為「符合性」的區段
ClaimStandardClause
ML-DSA-44/65/87 所宣稱的 NIST 類別為 2、3、5。FIPS 204§4.p9
ML-DSA 簽章大小為 2420、3309、4627 位元組。FIPS 204§4.p15 (Table 2)
簽章脈絡位元組字串以 255 位元組為上限。FIPS 204§x43.p2
長度錯誤的簽章或金鑰必須被拒絕。FIPS 204§x34
核准十二個 SLH-DSA 參數集。FIPS 205§11.p12 (Table 2)
SLH-DSA 簽章大小依循 Table 2（128s 為 7856 位元組）。FIPS 205§11.p6
對沖式簽章為預設;另有確定性變體存在。FIPS 205§x65.p7
CAdES/PAdES 套件目錄僅描繪 RSA 與 EC-DSA。ETSI TS 119 312 V1.5.1§7.x7.p10 (Table A.1)
PKCS#11 PQ 機制 id 為臨時性。OASIS PKCS#11 v3.1product-source grounded

所有條款皆為改述。NextPDF 不重製規範性文本。NextPDF 不持有任何認證,也不授予任何認證。 上述陳述是關於識別碼、長度與邊界的結構性對齊陳述。它們不是符合性測試結果、不是第三方鑑證,也不是 FIPS、OASIS 或 ETSI 的符合性宣告。PqsCapabilityStatus 在程式碼中編碼了這個立場:在每一種設定下,conformanceClaimed 為 false、adesCompliant 為 false、verificationAvailable 為 false。由本預覽產生的簽章不符合長期封存所需的 AdES,且多數 PDF 檢視器會在驗證時拒絕它。

開發備註

標題為「開發備註」的區段

  • OASIS PKCS#11 後量子機制登錄尚未定案;此處使用的 CKM_ML_DSA / CKM_SLH_DSA id 與參數集常數皆為臨時性,並以產品原始碼為據,而非規格引用。

  • 目前的里程碑是模擬測試就緒。尚未驗證任何真實後量子韌體 HSM 的往返。

  • 在正式環境中請保持兩道閘門皆關閉。本預覽並未新增傳統 RSA/ECDSA PKCS#11 路徑所欠缺的任何正式環境能力。

  • 在以真實硬體進行任何評估之前,請對照臨時性數值確認權杖韌體的機制與參數集 id。不相符會在 PKCS#11 層失敗,而非在 NextPDF 內部。

  • 在工具或 UI 中呈現 PQS 狀態時,請將 PqsCapabilityStatus::current() 視為唯一真實來源。切勿以手動方式覆述其布林值。

  • summary() 輸出可安全用於日誌與狀態端點;它的措辭刻意不帶任何供應或驗證宣告。

另請參閱

標題為「另請參閱」的區段

發佈邊界

標題為「發佈邊界」的區段

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