Security — HSM、PKCS#11 与 FIPS-mode

概览

NextPDF Enterprise 在 Core 与 Pro 安全范围之上，增加了一条 PKCS#11 硬件 token 签名路径以及一项 FIPS-mode 密码学策略。本页陈述行为、边界，以及明确的 FIPS 认证立场与密钥保管立场。

可用性与授权

此能力随 NextPDF Enterprise（nextpdf/enterprise）交付，并通过一份 Enterprise 层级的授权信封激活。没有该权益的部署不会加载此能力的类。对比各版本并获取授权。

概念概览

Enterprise 安全范围有三个部分：一个硬件 token 签名器、一项 FIPS-mode 密码学策略，以及一个开机自检守卫。

硬件 token 签名器适配一个 PKCS#11 token——一张智能卡、一个 USB 设备，或一个网络连接式 HSM。签名器按 label 在 token 上定位证书与私钥。随后它请求 token 计算签名。私钥不离开 token 边界；操作在 token 内部运行。token 签名操作、会话与用户登录遵循 PKCS#11 v3.1 §5。HSM 路径需要 ext-pkcs11 PHP 扩展。该扩展不属于标准 PHP。请单独安装它。在构造签名器之前请使用可用性检查。

FIPS-mode 密码学策略将密码学选择限定在一个被批准的集合之内。它有两个预设。strict 预设允许 SHA-256、SHA-384 与 SHA-512 哈希；带这些哈希的 RSA 与 ECDSA 签名 OID；AES-256-CBC 加密；以及 RSA 2048 与 EC 256 的最小密钥尺寸。standard 预设与之相同，但还额外允许 AES-128-CBC 以兼容较旧的互操作。一个运行时守卫包裹该策略。守卫在操作运行之前检查每一个哈希、签名 OID、加密算法与密钥强度。不被允许的选择会引发一个有类型的违规并停止该操作。该路径以失败关闭：策略绝不放松自身，也绝不替换为更弱的算法。最小 RSA 密钥长度遵循 NIST SP 800-131A Rev.2 §3。ECDSA 曲线与哈希的配对遵循 FIPS 186-5 §6.1.1。

开机自检守卫在进程启动时运行一组已知答案测试（known-answer-test）套件一次。该套件覆盖被批准的哈希、MAC、加密、签名与随机比特函数。若任何测试失败，Enterprise FIPS 守卫进入错误状态，并在重置之前拒绝密码学服务。结果在进程生命周期内被缓存；可按需重新运行。自检类别与条件测试触发遵循 ISO/IEC 19790:2025 §7.10 与 §7.10.3。

为何如此设计

起决定作用的选择是：将私钥保留在 token 边界内部，并使密码学策略失败关闭。一个能导出密钥、或会静默回退到更弱算法的签名器，将会瓦解 HSM 本应提供的保证。因此签名器请求 token 就地计算签名，而 FIPS-mode 守卫在操作运行之前拒绝任何位于被批准预设之外的哈希、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、证书 label，以及一个可选的单独 key label。PIN 参数被标记为敏感；它不被记录到日志、不被序列化。签名器还以 DER 形式暴露签名器证书与证书链。权威的参数与类型契约是 nextpdf/enterprise 包已发布的 API 参考；请将那份参考——而非本页——视为契约。

代码示例 — 快速开始

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

Construct a FIPS-mode guard and assert a hash is allowed

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);

代码示例 — 生产

Run the power-on self-test at container boot, then gate signing

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 security 深度参考中。

边界情形与坑

• 当 ext-pkcs11 未加载时，PKCS#11 token 签名器构造函数会抛出一个有类型的操作异常。请先检查可用性。
• token 签名器在每个进程内为每个库路径缓存一个 PKCS#11 模块。这满足 token 接口“每个模块只初始化一次”的规则。
• ECDSA token 机制返回原始签名。签名器将其转换为 DER 编码形式，以便与 PDF 和 OpenSSL 互操作。
• FIPS 守卫默认拒绝未知密钥类型。无法识别的密钥类型不会被静默接受。
• 后量子签名路径是实验性的、需主动启用且默认禁用。标准 PAdES 长期归档配置文件尚未承认后量子套件。请勿为生产环境的 AdES 签名启用它。

性能

FIPS 守卫检查是恒定时间的哈希表查询。开机自检每个进程运行一次；其代价在进程生命周期内摊销，而非按每次签名调用计。一次 PKCS#11 签名操作会增加一次到 token 的往返。一个网络连接式 HSM 会增加该往返的网络延迟。

安全说明

• 签名路径以失败关闭。一次原语失败或一个策略缺口会引发一个有类型的异常。该路径绝不静默降级为更弱的算法。
• 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 label 或密钥材料加入你自己的应用日志。在你的日志与追踪策略中，请将所有 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-mode 行为

FIPS-mode 策略将密码学选择限定在上文所述被批准的集合之内。当配置为针对一个经 FIPS 验证的 OpenSSL 提供方时，底层原语在那个经验证的边界内运行。NextPDF Enterprise 自身执行结构性组装、摘要计算与策略强制。

NextPDF Enterprise 不是经 FIPS 验证的密码学模块，也不作出任何 FIPS 认证声明。 仅当 NextPDF Enterprise 配置了经 FIPS 验证的密码学提供方——例如一个经 FIPS 验证的 OpenSSL 提供方——或一个经 FIPS 验证的 HSM 时，它才以 FIPS 兼容模式运行。FIPS-mode 策略辅助合规；它不是一项认证。

版本边界

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-mode 密码学策略配置文件。PKCS#11 硬件 token 签名器、FIPS-mode 密码学策略配置文件、开机自检守卫，以及 PAdES B-LT 和 B-LTA 生产者，仅在 nextpdf/enterprise 包中提供。没有 Enterprise 权益的部署不会加载 Enterprise 类。

Pro 回退

在仅有 Pro 的部署中，受支持的硬件支撑与云支撑签名路径是 Pro 的云 KMS 策略：一个云 KMS 或 HSM 支撑的 KMS 持有密钥，而 Pro 将已签名属性的摘要、而非文件本身发送给提供方。Pro 提供 KMS 集成，而非 Enterprise 的 PKCS#11 token 工厂或 FIPS-mode 配置文件。在仅有 Pro 的部署中，请求 B-LT、B-LTA、PKCS#11 token 或 FIPS-mode 配置文件的配置会以失败关闭，并附一条命名了所缺失 Enterprise 组件的消息。Pro 签名范围请参阅 Security — NextPDF Pro。

Core 回退

在仅有 Core 的部署中，软件签名器用一个本地密钥或一个通过 Core 签名策略契约提供的密钥产出 PAdES B-B 与 B-T。Core 没有硬件 token 路径，也没有 FIPS-mode 配置文件。参见 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-mode 策略是一项合规辅助功能。它不是法律意见，也不是认证。请就你的监管义务咨询你自己的合规与法律顾问。

发布边界

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

行为契约

• FIPS 守卫针对活动预设断言每一个哈希、签名 OID、加密算法与密钥强度，并在不被允许的选择上引发一个有类型的违规。
• 开机自检每个进程运行一次，并在已知答案测试失败时拒绝密码学服务，直至重置。
• PKCS#11 token 签名器需要 ext-pkcs11；当该扩展缺失时它引发一个有类型的操作异常。
• 签名路径以失败关闭，绝不替换为更弱的算法。

另请参阅

• Security — NextPDF Enterprise (deep reference)
• Security — NextPDF Pro
• Signature — NextPDF Enterprise
• Accelerator — NextPDF Enterprise
• Security — NextPDF Core
• PAdES · HSM · PKCS#11 · FIPS mode · KMS — glossary terms.