Pro 版本
Security — 深度参考
这是面向 NextPDF Pro 安全范围的深度参考：生成期遮罩、文本层 PII 检测、远程与云 KMS 签名会话、多方顺序签名、CAdES 与 XAdES 接入路径、PAdES B-B 基线级别，以及 PAdES B-T 签名支持（一个 B-B 签名加上对签名值的一个 RFC 3161 signature-time-stamp）。它陈述公开 API 契约、外部可观测行为，以及 Enterprise B-LT/B-LTA 边界。它是行为层面的；它不引用任何内部实现路径。
可用性与授权
标题为“可用性与授权”的章节此能力随 NextPDF Pro（nextpdf/pro）交付，并以一个 Pro 级别的授权信封激活。没有该权益的部署不会加载此能力的类。比较各版本并获取授权。
Core 提供软件 CMS 签名器、RFC 3161 时间戳客户端、RFC 5280 路径验证，以及 OCSP 与 CRL 吊销检查。Pro 增加此处所述的遮罩、PII 检测、远程与云 KMS 签名范围，以及 PAdES B-T 签名支持（它组合 Core 的 RFC 3161 栈以添加一个 signature-time-stamp）。此范围的能力标志为 pro：没有有效 Pro 权益的部署不会加载这些类，Core 签名契约会继续保持不变地工作，且当权益缺失时，依赖 Core 契约的代码不会被破坏。
composer require nextpdf/pro:^3行为契约
标题为“行为契约”的章节遮罩引擎在页面被写出之前，对文本应用一个有序的规则列表。一条规则匹配一个 PCRE 模式，并以三种模式之一替换一个匹配：
- BlackBox —— 从内容流中移除匹配到的文本，并保留一个填充区域。如经测试，此模式会移除底层的文本对象。
- Asterisks —— 将每个匹配到的字符替换为一个星号，保留字符数。
- FixedLabel —— 将整个匹配替换为一个可配置的标签，默认为
[REDACTED]。
一条规则可由通过 MaskingRule::exactMatch 提供的精确字面量构建（该字面量会被正则转义），或由通过 MaskingRule::regex 提供的自定义 PCRE 模式构建。MaskingConfig 持有有序规则列表、一个默认模式，以及填充颜色。MaskingConfig::fromArray 解析一个配置映射，并会静默丢弃没有可用字符串模式的规则条目，而不会令整个导入失败。
PII 范围提取 PDF 文本层，然后对电子邮件地址、电话号码、美国社会安全号码与信用卡号应用内置模式。它返回一个结构化结果：一个表示是否找到任何匹配的布尔值、一个匹配计数、遮罩后的文本视图，以及已扫描类型的列表。调用方可以将扫描限定为这四种类型的子集。该范围不会覆写已渲染的页面字形；没有文本层的被扫描页面不会产生匹配。请把结果视为对所配置类型的文本层模式检测，而非完整的个人数据移除，也不是一份合规声明。
签名会话是两阶段的。RemoteSigningSession::create 打开一个会话。prepare 在两个 ByteRange 区域上计算文档摘要，然后构建 CMS 签名属性。complete 调用策略并嵌入结果；suspend 序列化会话，以便一个 worker 稍后能用 resume 与 completeWithRawSignature 恢复它。会话组装一个 CMS SignedData，并将其以 DER 编码形式存储在签名字典的 Contents 条目中 —— ISO 32000-2 §12.8.1。当提供了一个可解析的 X.509 证书时，会话会发出完整的 PAdES B-B 强制签名属性集：content-type、message-digest、signing-time、signing-certificate-v2，以及一个 algorithm-protection 属性 —— RFC 5652 §5.3 与 RFC 5652 §5。验证方重新计算内容摘要并将其与 message-digest 属性比较；该比较必须匹配，签名才有效 —— RFC 5652 §5.4。
当配置的 PAdES 级别为 B-T（RemoteSigningConfig::default->withLevel(SignatureLevel::PAdES_B_T)，或经由 SequentialSigner::withTimestamping），且已接入一个时间戳提供方时，会话会额外在第一个 SignerInfo 上嵌入恰好一个 RFC 3161 signature-time-stamp，作为一个 CMS unsigned 属性。一个 signature-time-stamp 是一个 unsigned 属性，承载对某个签名者的数字签名值计算得到的一个 time-stamp token —— ETSI EN 319 122-1 §5.3；其 MessageImprint 是 SignerInfo signature 字段值的哈希，排除 ASN.1 tag 与 length —— ETSI EN 319 122-1 §5.3 与 RFC 3161 Appendix A（OID id-aa-timeStampToken = 1.2.840.113549.1.9.16.2.14）。由于该时间戳是一个 unsigned 属性，B-B 签名属性、message-digest、SignerInfo 签名值，以及 PDF /ByteRange 都与 B-B 输出字节一致；只有 CMS 因该 unsigned 属性而增长，且 B-T 预留的 /Contents 空间被提高以容纳它。该 token 从所配置的时间戳提供方请求（默认的 Core RFC 3161 客户端，或调用方提供的提供方）。在默认提供方路径上，imprint 摘要为 SHA-256；与 SHA-1 绑定的遗留 ESSCertID v1 形式被拒绝，且要求 ESSCertIDv2 —— RFC 5816 §1。TSA 故障、被拒绝的请求、错误的 nonce 或 message-imprint 回显、格式错误或算法不受支持的 token，或一个未能通过密码学验证的 token，都会以一个有类型的 PadesBt 异常呈现，并将发起的 Core 异常作为前一个可抛出对象（previous throwable）保留。NextPDF Pro 依据 ETSI EN 319 122-1 §5.3、RFC 3161、RFC 5652 与 RFC 5816 实现 PAdES B-T 签名支持，且经 fixture 验证；它不主张独立的 ETSI EN 319 142-1 认证，也不主张文档的法律效力。
SequentialSigner 协调多方签名。每个签名者是一个单独的增量更新修订（incremental-update revision）。第一个签名者可以是一个带有通过 certifyFirst 设置的 DocMDP 限制的认证签名（certification signature）。PadesWrapper 接入一个既有签名：fromCades 直接嵌入一个 CMS 结构，fromXades 解析一个 XAdES 文档并复用其核心签名材料，detect 按格式自动选择。XAdES 路径复用证书、链、签名值与算法；它不会转移 XAdES qualifying properties。
公开 API 范围
标题为“公开 API 范围”的章节composer require nextpdf/pro:^3| Type | Kind | Role | Stability | Since |
|---|---|---|---|---|
RemoteSigningSession | class | 两阶段远程或异步签名会话 | stable | 1.9.0 |
RemoteSigningConfig | class | 不可变的会话配置，包含 PAdES 级别与算法 | stable | 1.9.0 |
SequentialSigner | class | 带 DocMDP 支持的多方顺序签名 | stable | 1.9.0 |
SequentialSigningResult | class | 一次顺序运行的结果：PDF 字节、链、计数、完整性 | stable | 1.9.0 |
SigningStrategy | interface | 会话所调用的签名机制契约 | stable | 1.9.0 |
PadesWrapper | class | 包装一个既有 CAdES 或 XAdES 签名以用于 PAdES 嵌入 | stable | 1.9.0 |
KmsSignerInterface | interface (SPI) | 第三方 HSM 与 KMS 驱动契约；扩展 Core HSM 签名器契约 | stable | 2.1.0 |
SignatureAlgorithm | enum | Pro 签名算法 OID 与摘要名称 | stable | 2.1.0 |
GenerationTimeMasker | class | 在页面被写出之前应用的规则驱动遮罩 | stable | 1.9.0 |
MaskingConfig | class | 不可变的遮罩配置 | stable | 1.9.0 |
MaskingRule | class | 单条遮罩规则（字面量或 PCRE） | stable | 1.9.0 |
MaskingMode | enum | BlackBox、Asterisks、FixedLabel | stable | 1.9.0 |
SigningStrategy 契约
标题为“SigningStrategy 契约”的章节一个策略在 DER 编码的签名属性上操作，并返回原始签名字节。组装 CMS SignedData 的是会话，而非策略。一个策略暴露签名者证书 DER、按叶到根排序的链 DER、签名算法 OID、摘要算法名称，以及一个标记某策略其会话可被序列化并恢复的 isAsync 标志。
KmsSignerInterface SPI
标题为“KmsSignerInterface SPI”的章节KmsSignerInterface 扩展 Core HSM 签名器契约。它增加一个用于注册表查找的稳定 providerId、一个带显式每次调用密钥版本参数的 signWithVersion 方法，以及 supportsAlgorithm 与 supportedAlgorithms，以便调用方在签名调用前发现算法兼容性。预留的内置提供方标识为 aws-kms、azure-keyvault、gcp-kms、pkcs11、openssl-cli 与 openssl-engine。第三方驱动必须为其标识加上命名空间以避免冲突。默认密钥版本语义因提供方而异：一个解析别名的提供方在版本为 null 时从别名解析出活跃密钥；一个选择最新已启用版本的提供方通过其传输层这样做；一个没有服务端活跃版本概念的提供方必须使用在其配置中固定的版本，且当调用与配置都未固定版本时必须引发一个密钥管理错误。一个非空版本会固定该版本，且当版本未知、被禁用或被吊销时，提供方必须引发一个密钥管理错误。
边界情况与注意事项
标题为“边界情况与注意事项”的章节- 已产出的签名不是已验证的签名。路径验证在验证方处运行，使用该验证方的信任锚与 basic-constraint 检查 —— RFC 5280 §6.1。生产方无法主张该结果。
- 会话为非 X.509 的合成证书字节保留了一个遗留的三属性回退。生产策略总是提供真实的 X.509 DER，因此完整的 B-B 属性集才是生产路径。该回退仅为历史性的 DER 机制测试范围而存在。
- CMS 结构必须适配预留的
Contents空间。带完整证书链的 B-B SignedData 有一个大小；当组装出的 CMS 超过预留的十六进制空间时，会话会引发一个溢出错误。请据此设定预留空间的大小。对于 B-T，嵌入的 RFC 3161 token（其大小由 TSA 证书链主导）会增大 CMS；B-T 预留空间会被自动提高，而一个尺寸不足的已配置空间会以一个有类型的配置错误失败关闭（fail closed），而非截断。 MaskingConfig::fromArray会丢弃没有可用字符串模式的条目，而非令导入失败。如果静默丢弃不可接受，请验证配置来源。- 遮罩的 black-box 模式对匹配到的运行（run）发出一个空替换，并移除底层文本。一条不匹配某个值的规则不会遮罩它；引擎不会主张所有敏感内容都被找到。
- B-T 需要一个已接入的时间戳提供方。在默认的 Core RFC 3161 提供方路径上，imprint 摘要为 SHA-256；该路径上一个非 SHA-256 的 imprint 摘要会以一个有类型的配置错误被拒绝，而非静默降级，而一个调用方提供的自定义提供方可以合法地使用另一种被批准的摘要。一个时间戳
serialNumber在来自给定时间戳机构（Time-Stamping Authority）的每个 token 中唯一，而genTime是 token 被创建时的 UTC 时刻 —— RFC 3161 §2.4.1、§2.4.2。B-LT/B-LTA 的长期验证材料仍属 Enterprise 边界范畴；Pro 不产生 DSS、不产生 VRI，也不产生文档时间戳。 - OCSP
unknown不等于good，且状态新鲜度由thisUpdate与nextUpdate限定 —— RFC 6960 §2.2、§4.2。
FIPS-mode 行为
标题为“FIPS-mode 行为”的章节Pro 从所配置的签名算法与策略中选择算法。当配置为针对一个经 FIPS 验证的 KMS 或 HSM 时，密码学操作在该已验证边界内运行，且算法集合是该边界所允许的任意集合。NextPDF Pro 执行结构性的 CMS 组装与摘要计算；它不是一个经 FIPS 验证的密码学模块，也不作出任何 FIPS 认证声明。一个要求 FIPS 态势的部署必须配置一个经 FIPS 验证的 KMS 或 HSM，而 FIPS 140-3 密码学策略预设是一项 Enterprise 能力。
出口管制态势
标题为“出口管制态势”的章节本模块涉及密码学功能；请在你自己的审查中把它视为安全敏感。
Enterprise 边界
标题为“Enterprise 边界”的章节NextPDF Pro 产生 B-B 基线与 B-T 级别。对于 B-B，会话组装一个带 B-B 签名属性集的 CMS SignedData，且不应用时间戳。对于 B-T，它添加恰好一个 RFC 3161 signature-time-stamp，作为一个对某个签名者的数字签名值计算得到的 CMS unsigned 属性 —— ETSI EN 319 122-1 §5.3。NextPDF Pro 依据 ETSI EN 319 122-1 §5.3、RFC 3161、RFC 5652 与 RFC 5816 实现这一点，且经 fixture 验证；它不主张独立的 ETSI EN 319 142-1 认证、符合性或合规，也不主张文档的法律效力。
B-LT 与 B-LTA 级别是 Enterprise 能力，且不由 Pro 产生。B-LT 与 B-LTA 为长期归档验证添加一个 Document Security Store 与文档时间戳 —— ETSI EN 319 142-2 §5.5。一个产生这些级别的签名处理器（signature handler）支持 DSS 条目与文档时间戳 —— ETSI EN 319 142-2 §6.3.3.3。Pro 的 RemoteSigningConfig 可以携带一个高于 B-T 的级别（B-LT 或 B-LTA），它请求一个 Document Security Store，但 Pro 既不交付该生产者，也不据此采取行动；这样的级别是一个前向声明（forward-declared）的值。Core 签名流程在运行时通过 Core 契约解析长期验证生产者，而该生产者随 nextpdf/enterprise 包交付。在仅有 Pro 的部署中，对 B-LT 或 B-LTA 的请求会失败关闭（fail closed），并给出指明缺失 Enterprise 组件的消息。Pro 不产生 DSS、不产生 VRI 字典、不产生文档时间戳，也不产生归档循环，且不作出任何长期验证（LTV）声明。经由 PKCS#11 的硬件密钥保管，以及 FIPS 140-3 密码学策略预设，同样是 Enterprise 能力。本页不记录 Enterprise 的长期验证实现；它只陈述边界与公开包名。
| PAdES level | Adds | Producer edition |
|---|---|---|
| B-B | 带签名属性的 CMS 签名 | Core, Pro |
| B-T | 对签名值的一个 RFC 3161 signature-time-stamp unsigned 属性 | Core, Pro |
| B-LT | 带验证材料的 Document Security Store | Enterprise (nextpdf/enterprise) |
| B-LTA | 用于归档有效性的文档时间戳 | Enterprise (nextpdf/enterprise) |
发布边界
标题为“发布边界”的章节本页仅记录外部可观测行为与所支持的公开 API 范围。内部命名空间路径、辅助类、机制表、runbook 文件名与工单前缀均不在范围内。
Core 回退
标题为“Core 回退”的章节没有 Pro 权益的部署保留 Core 签名契约。依赖 Core SignerInterface 契约的代码会继续以软件 CMS 签名器在 B-B 基线签名。没有 Pro 包时，遮罩、PII 检测，以及远程与云 KMS 策略不存在，且对这些类型的调用是一个硬依赖错误，而非静默的 no-op。
数据驻留与 PII 缓解
标题为“数据驻留与 PII 缓解”的章节遮罩与 PII 范围在进程内运行。文档内容不会为了遮罩或 PII 检测而离开主机。一个云 KMS 策略将签名属性摘要（而非文档）发送给提供方以执行签名操作。PII 检测对所配置的类型进行模式匹配，并如经测试地为 black-box 模式移除底层文本对象。它不是完整的个人数据移除保证，也不是一份合规声明。
安全遥测与日志清洗
标题为“安全遥测与日志清洗”的章节库引发带结构性消息的有类型异常。它不会把文档内容或检测到的 PII 值写入异常消息或日志。一个在签名路径周围记录日志的部署应记录结构性字段，而非文档字节。
一致性
标题为“一致性”的章节| Claim | Standard | Clause |
|---|---|---|
CMS 签名以 DER 编码形式存储在签名字典的 Contents 条目中。 | ISO 32000-2 | §12.8.1 |
| message digest 计算过程；签名属性承载 content-type 与 message-digest。 | RFC 5652 | §5.4 |
| 验证方不得依赖发起方计算的摘要；它独立地重新计算并比较（签名验证过程）。 | RFC 5652 | §5.6 |
| SignerInfo 承载摘要算法标识符与签名属性块。 | RFC 5652 | §5 |
| 一个时间戳请求返回一个 TSTInfo 结构。 | RFC 3161 | §2.4.1 |
| 一个时间戳 serialNumber 在来自给定 TSA 的每个 token 中唯一。 | RFC 3161 | §2.4.2 |
| 时间戳 genTime 是 token 被创建时的 UTC 时刻。 | RFC 3161 | §2.4.2 |
| 一个 PAdES B-T signature-time-stamp 是一个 unsigned 属性，承载对某个签名者的数字签名值计算得到的一个 time-stamp token（Pro 产生 B-T）。 | ETSI EN 319 122-1 | §5.3 |
| signature-time-stamp imprint 是 SignerInfo signature 字段值的哈希，排除 ASN.1 tag 与 length。 | ETSI EN 319 122-1 | §5.3 |
signature-time-stamp token 使用 id-aa-timeStampToken OID；其 MessageImprint 是 SignerInfo signature 字段值的哈希。 | RFC 3161 | Appendix A |
| 在验证侧，NextPDF 将一个 signature-time-stamp 的 MessageImprint 绑定到 SignerInfo 签名值，并在出现不匹配、token 缺失/重复，或 SHA-1 imprint 时失败关闭（fail closed）（严格验证，而非认证）。 | RFC 3161 | Appendix A |
| ESSCertIDv2 取代与 SHA-1 绑定的遗留 ESSCertID；严格的 B-T 路径要求 ESSCertIDv2。 | RFC 5816 | §1 |
| 认证路径验证检查 basic constraints 与到信任锚的路径输入。 | RFC 5280 | §6.1 |
| OCSP 将 certStatus 报告为 good、revoked 或 unknown。 | RFC 6960 | §2.2 |
| OCSP 状态新鲜度由 thisUpdate 与 nextUpdate 限定。 | RFC 6960 | §4.2 |
| B-LT 与 B-LTA 为长期验证添加一个 Document Security Store 与文档时间戳（Enterprise 边界）。 | ETSI EN 319 142-2 | §5.5 |
| 一个产生长期级别的签名处理器支持 DSS 条目与文档时间戳（Enterprise 边界）。 | ETSI EN 319 142-2 | §6.3.3.3 |
所有条款均为转述。NextPDF 不复制规范性文本。请查阅已发布的标准以获取权威措辞。NextPDF Pro 依据 ETSI EN 319 122-1 §5.3（signature-time-stamp）、RFC 3161、RFC 5652 与 RFC 5816 实现 PAdES B-T 签名支持，且经 fixture 验证。ETSI EN 319 142-1（PAdES 基线级别部分）不在所引证据集之内；因此 NextPDF Pro 不主张独立的 ETSI EN 319 142-1 认证、符合性或合规，也不主张文档的法律效力。本页陈述所产生的结构、B-T 支持所实现的标准，以及 Enterprise B-LT/B-LTA 边界，而非一个经认证的一致性级别。
另请参阅
标题为“另请参阅”的章节- Core signing —— CMS 签名器、RFC 3161 时间戳、RFC 5280 路径验证、OCSP 与 CRL。
- PAdES clause map —— 跨版本的 B-B、B-T、B-LT、B-LTA。
- Security（能力概览） —— 公开的 Pro 安全能力页面。
- CMS · PAdES · RFC 3161 timestamp · KMS · DSS —— 术语表词条。