跳转到内容
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 界面”的章节
符号参数默认行为返回值抛出或失败于说明
Pkcs11PqsAlgorithm以 string 为底层类型的枚举，15 个 case每个 case 命名一个 FIPS 204 / FIPS 205 参数集枚举 case访问 case 时不抛出任何异常Case 值即参数集名称，例如 ML-DSA-65。
Pkcs11PqsAlgorithm::isMlDsa()无族别判定bool不抛出对 MlDsa44、MlDsa65、MlDsa87 返回 true。
Pkcs11PqsAlgorithm::isSlhDsa()无isMlDsa() 的取反bool不抛出对十二个 SLH-DSA case 返回 true。
Pkcs11PqsAlgorithm::mechanismId()无将族别映射到候选的 PKCS#11 v3.1 PQ 机制 idint当运行时缺少临时 Pkcs11 PQ 常量时抛出 PHP ErrorCKM_ML_DSA 或 CKM_SLH_DSA；两个 id 均为临时性质。
Pkcs11PqsAlgorithm::parameterSetId()无将 case 映射到 OASIS 参数集判别符int当运行时缺少临时 Pkcs11 PQ 常量时抛出 PHP ErrorCKP_* 值；临时性质。
Pkcs11PqsAlgorithm::signatureLength()无该 case 由 FIPS 强制规定的签名字节长度int（正数）不抛出由签名路径消费，用于拒绝返回的意外长度签名。
Pkcs11PqsAlgorithm::nistCategory()无所声称的 NIST 安全强度类别int不抛出返回 1、2、3 或 5。
PqsPreviewFeature以 string 为底层类型的枚举，1 个 case单个 case PREVIEW_PQS_HSM；常量 ENV_PREVIEW_PQS_HSM枚举 case访问 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）。每个 case 映射到一个临时机制 id、一个参数集判别符、一个由 FIPS 强制规定的签名字节长度，以及一个所声称的 NIST 类别。
  • 签名长度。 依据 FIPS 204 §4.p15（Table 2），signatureLength() 对 MlDsa44、MlDsa65 和 MlDsa87 分别返回 2420、3309 和 4627 字节。依据 FIPS 205 §11（Table 2），SLH-DSA 各 case 按级别与变体返回 7856、17088、16224、35664、29792 和 49856 字节。当返回的签名长度不同时，使用该界面的签名者会抛出 HsmOperationException，与 FIPS 204 §x34 的长度拒绝原则相呼应。
  • 类别。 依据 FIPS 204 §4.p9，nistCategory() 对各 ML-DSA case 返回 2、3 和 5。SLH-DSA 各 case 按安全参数级别返回 1、3 和 5。
  • 进程门控。 PqsPreviewFeature::PREVIEW_PQS_HSM 默认关闭。仅当环境变量 NEXTPDF_FEATURE_PREVIEW_PQS_HSM 恰好等于字符串 1 时，isEnabled() 才返回 true。每次调用都是实时读取；不做任何记忆化。
  • 互补门控。 进程门控与 Pkcs11Signer 上按签名者设置的 $enablePostQuantum 构造函数显式启用彼此独立。若缺少按签名者的显式启用，签名调用会失败关闭（fail closed）。进程门控作为一个可审计的单一边界存在，用于任何未来的往返或归档行为。
  • 诚实不变量。 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 和参数集 id 均为临时性质。OASIS 尚未定稿 PKCS#11 v3.1 后量子注册表。若某令牌的固件分配了不同的 id，将在 PKCS#11 层失败；运营方必须在启用预览前确认固件 id。
  • 使用该界面的签名者所接受的签名上下文以 255 字节为上限，与 FIPS 204 的签名输入契约（§x43.p2）一致。更长的上下文会在任何令牌调用之前抛出 InvalidArgumentException。
  • PqsCapabilityStatus::__construct() 是 public 的，因此手工构建的实例可以携带任意布尔值。这样的实例只是一个值对象。它不会改变任何签名行为。current() 才是规范化的、硬编码的构造函数。
  • 使用该界面的签名者在随机化与确定性之间的选择遵循 FIPS 205 §x65.p7 语义：对冲签名（hedged signing）为默认。该标志对 ML-DSA 被忽略，后者始终通过其自身的 nonce 进行随机化。

FIPS 模式行为

标题为“FIPS 模式行为”的章节

ML-DSA 和 SLH-DSA 是 FIPS 204 和 FIPS 205 算法，但此预览不携带任何 FIPS 140-3 验证声明。此路径尚未建立任何经过 FIPS 验证的后量子 HSM 往返。记录在安全深度参考上的 Enterprise FIPS 模式加密策略配置，对经典签名算法进行门控；它不会将 PQS 界面纳入某个已验证集合。启用 FIPS 模式并不会使后量子签名成为经 FIPS 验证的签名。请勿在需要经 FIPS 验证签名的场景中部署此预览。

合规性

标题为“合规性”的章节
声明标准条款
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.1以产品源码为依据

所有条款均为转述。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 文件名以及工单前缀均不在范围之内。