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 或空——都被当作关闭。
逐签章者可选开关。 向 Pkcs11Signer 构造器传入 $enablePostQuantum: true。

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”/“generally available”。
“AdES”/“PAdES-compliant”——没有 ETSI 套件为长期归档注册一个后量子签章。
“FIPS-validated”——尚未为此路径确立任何经 FIPS-140-3 验证的后量子 HSM 往返。
针对 FIPS、OASIS PKCS#11 v3.1 或 ETSI 的“certified”或“conformant”。
“production-ready”。

该接口诚实地是什么：一个可选启用、默认关闭、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 的、经由 PKCS#11 的 HSM 委托后量子签章。在被禁用时、密钥缺失时，或在签章长度不匹配时抛出 `HsmOperationException`。
`Pkcs11Signer::isPostQuantumEnabled()`	逐签章者的 `$enablePostQuantum` 可选开关是否被设置。
`Pkcs11PqsAlgorithm`	ML-DSA（FIPS 204）与 SLH-DSA（FIPS 205）参数集的枚举；把每个映射到一个临时性机制 id 与 FIPS 强制签章长度。
`PqsPreviewFeature`	进程级、默认关闭的环境变量门控（`NEXTPDF_FEATURE_PREVIEW_PQS_HSM`）。
`PqsCapabilityStatus`	诚实、机器可读的状态：每个正向主张布尔值（generally-available、AdES、verification、conformance）无论预览标志如何都被硬编码为 `false`。
`HsmOperationException`	在 fail-closed 路径上抛出的带类型异常。

发布边界

本页仅记录外部可观察的行为与受支持的公开 API 接口。内部命名空间路径、辅助类、机制表、运维手册文件名以及工单前缀均不在范围内。