跳转到内容
NextPDF

使用 NextPDF Connect（Pro）应用 PAdES 数字签名

快速概览

标题为“快速概览”的章节

使用 NextPDF Connect 为 PDF 应用 PAdES 基线数字签名。此工具为 sign_pdf，已针对 Pro 工具提供方重新验证：该提供方会注册 new SignPdfTool()，其协议名称为 sign_pdf。**sign_pdf 是 Pro 级工具。**服务器会在启动时通过 class_exists() 探测它，并且仅在安装了 Pro 套件时注册。

此工具默认生成 PAdES B-B。只有主机已为此工具接入时间戳提供方时，它才能生成 PAdES B-T（B-B 加上一个 RFC 3161 signature-time-stamp）；请求无法指向某个 TSA。长期保存级别（B-LT、B-LTA）及其验证材料（DSS、VRI、LTV）并非此工具的一部分，也不在本页范围内。

U-1 注意事项。 NextPDF 并未声明任何独立的 ETSI EN 319 142-1 PAdES B-T 认证。EN 319 142-1 不在验证语料库中。B-T 的 signature-time-stamp 要求是依据 ETSI EN 319 122-1 §5.3（EN 319 142-1/-2 通过引用纳入的 CAdES 基础规范），并结合 RFC 3161、RFC 5652、RFC 5816 以及 ISO 32000-2 §12.8 进行验证。对 B-T 配置文件的支持并非一致性或法律效力认证；该判断由独立验证器作出。

安装

标题为“安装”的章节
Terminal window
composer require nextpdf/server
composer require nextpdf/pro

绑定一个传输。通过 diagnostic.capabilities 确认 sign_pdf 可用。若需 B-T，主机必须使用时间戳提供方来构建此工具。如果没有提供方，pades_b_t: true 的请求会以类型明确的错误失败，而不会默默降级。

概念总览

标题为“概念总览”的章节

sign_pdf 会计算文件的字节范围摘要，并排除签名值预留位置（ISO 32000-2 §12.8.1）。随后，它会将 DER 编码的 CMS SignedData 写入签名字典 Contents（ISO 32000-2 §12.8.1）。支持的算法包括：RSA-SHA256（默认）、RSA + SHA-3（256/384/512）以及 Ed25519。对于并非端对端机密的传输，可选的 AES-GCM 封装可以保护传入的 private_key 载荷。

**B-T 升级。**当 pades_b_t: true 且主机已接入时间戳提供方时，签名会升级为 PAdES B-T：字节范围哈希会发送到 TSA，并嵌入一个 TimeStampToken（ISO 32000-2 §12.8.5）。B-T 本质上就是在 B-B 基础上增加 一个作为 CMS SignerInfo 未签署属性携带的 RFC 3161 signature-time-stamp（RFC 5652 §5.3）。未签署属性不在签名覆盖范围内，因此 B-B 已签署摘要及其有效性保持不变（RFC 5652 §5.3）。该属性值为 SignatureTimeStampToken（ETSI EN 319 122-1 §5.3）。B-T 不会新增 DSS 字典、不会新增 VRI、不会新增验证材料，也没有封存时间戳循环——这些属于 B-LT/B-LTA Enterprise 增量，不在此工具的范围内。

U-1 注意事项（在 B-T 主张处重述）。 此处的 B-T 支持并非 EN 319 142-1 一致性或法律效力认证；由独立验证器决定。EN 319 142-1 不在验证语料库中。B-T 的依据是 ETSI EN 319 122-1 §5.3、RFC 3161、RFC 5652、RFC 5816 以及 ISO 32000-2 §12.8。

此工具流程如下所示，其中包含由主机把关的 TSA 接口（请求无法指向 TSA），以及失败即关闭的 B-T 分支（绝不会默默降级）。

Host-wired RFC 3161 TSAPro SignPdfToolNextPDF Connect serverHost-wired RFC 3161 TSAPro SignPdfToolNextPDF Connect serveralt[host wired a TSA provider][no provider wired]alt[pades_b_t == true]MCP callercreate_pdf then add_text — build content1sign_pdf — certificate, private_key, pades_b_t?2dispatch — Pro tool, class_exists-probed at boot3Byte-range digest, build CMS SignedData — B-B4byte-range hash — request-unconfigurable endpoint5TimeStampToken6Embed token in unsignedAttrs — B-T7Typed error — NOT downgraded to B-B8signed PDF — level B-B or B-T9output_pdf — Approval Required gate10result — pdf, level, timestamped11MCP caller
Diagram

API 接口

标题为“API 接口”的章节
工具级别角色风险级别
create_pdf、add_textCore创建内容安全 / 注意
sign_pdfPro应用 PAdES B-B（或主机把关的 B-T）需要批准
output_pdfCore渲染并返回 PDF需要批准 / 审查（base64）

工具名称就是注册表中的协议名称；工具目录 是正式目录。可用工具取决于已安装的级别，且 Pro 中没有长期保存级别的工具。

代码示例——快速上手

标题为“代码示例——快速上手”的章节
  1. create_pdf → 使用 add_text 创建内容。
  2. sign_pdf，传入 certificate（PEM）、private_key（PKCS#8 PEM）、可选的 signer_name、reason 以及 algorithm。如果需要 B-B，请省略 pades_b_t（或将其设为 false）。
  3. output_pdf。

此工具会返回以下结果封装：

{
  "pdf": "<base64 of the signed PDF>",
  "signature_count": 1,
  "is_complete": true,
  "algorithm": "RSA_SHA256",
  "oid": "<algorithm OID>",
  "digest": "<digest algorithm>",
  "level": "PAdES-B-B",
  "timestamped": false
}

若要使用主机把关的 B-T 签名，请传入 pades_b_t: true；level 会变成 "PAdES-B-T"，而 timestamped 会变成 true。

代码示例——正式环境

标题为“代码示例——正式环境”的章节

将签署作为最后一个内容操作。在 sign_pdf 之后执行任何 add_text/add_image 都会使签名失效。在非机密传输上，请使用 AES-GCM transport_encryption 封装 private_key（12 字节 nonce；16/24/32 字节密钥）。确认结果中的 level 与你的请求一致。对没有提供方的工具发出 pades_b_t: true 请求会明确失败：请处理该错误，不要默默改用 B-B 重试。

边界情况与陷阱

标题为“边界情况与陷阱”的章节
  • 证书/密钥不匹配。 会以明确错误拒绝；私钥必须与证书的公钥匹配。
  • 格式错误的 PEM / 过期的证书。 会被拒绝；此工具默认不会使用无法解析或已过期的证书签署。
  • 签署后新增内容。 会被拒绝——请在最后签署。
  • 已请求 B-T，但无提供方。 会返回类型明确的错误：签名不会生成，也不会默默降级为 B-B。
  • 自签名证书。 签名会应用，但阅读器会显示信任未知——这是预期行为，而非工具缺陷。
  • 未安装 Pro。 仅安装 Core 时，sign_pdf 不会被注册。

效能

标题为“效能”的章节

签署会增加 CMS 构建；对于 B-T，还会增加一次 TSA 往返；预算已涵盖这部分。此配置文件属于 semantic：RFC 3161 令牌本质上不可重现，而 §12.8.1 字节范围摘要会排除签名值，因此只有比较 AST 以及签名中继数据才是如实的做法。

安全注意事项

标题为“安全注意事项”的章节

签名提供相对于签署密钥的完整性与身份验证。它本身并不会让文件变得「安全」或「具有法律效力」，也不会保证不可否认性——这取决于证书、其信任锚点、密钥保管，以及验证者的政策，这些全都在此工具之外。密钥载荷的加密（AES-GCM 封装）保护的是传输中的机密性，而非完整性。请将私钥视为机密，并在任何非机密通道上优先使用传输加密封装。

一致性

标题为“一致性”的章节
陈述规范条款reference_id
字节范围摘要涵盖整个文件，并排除签名值。ISO 32000-2§12.8.1
Contents 持有 DER 编码的 CMS SignedData。ISO 32000-2§12.8.1
使用时间戳时，字节范围哈希会送往 TSA，且令牌会放入 Contents。ISO 32000-2§12.8.5
B-T 时间戳是 SignerInfo 上的未签署属性。RFC 5652§5.3
未签署属性不会改变 B-B 已签署的 digest/validity。RFC 5652§5.3
signature-time-stamp 值为 SignatureTimeStampToken。ETSI EN 319 122-1§5.3

NextPDF 生成签名结构。它并未声明任何最终签名具有一致性或法律效力——这由独立验证器决定。B-LT/B-LTA 不由此工具生成。

商业背景

标题为“商业背景”的章节

sign_pdf 是 Pro 级工具，只有在服务器启动时能够解析 Pro 套件时才会注册。PAdES 长期保存级别（B-LT、B-LTA）及其验证材料（DSS、VRI、LTV）为 Enterprise 专属，不会通过此工具或本指南提供。

数据驻留与 PII 缓解

标题为“数据驻留与 PII 缓解”的章节

证书与私钥会随请求传输。在任何并非端对端机密的通道上，请使用 AES-GCM transport_encryption 封装。已签署的 PDF 与签署者身份（signer_name、reason）属于文件内容，因此请将它们保留在你的数据驻留边界内。部署层面的驻留由集成者负责。

安全遥测与日志清理

标题为“安全遥测与日志清理”的章节

切勿记录 private_key 载荷、AES-GCM key/nonce，或确认令牌。记录算法、最终的 level 以及 signature_count——而非密钥材料。此工具不会在其结果中输出密钥字节。

威胁模型

标题为“威胁模型”的章节

考虑的威胁：传输中的密钥泄露（由 AES-GCM 封装以及主机注入、请求无法配置的 TSA 提供方缓解）；MCP 调用者把时间戳指向任意端点（已防止——提供方由主机注入，无法通过请求配置）；以及签署后的篡改（字节范围摘要可检测修改）。威胁模型记录已考虑的威胁与缓解措施；它并不声明不存在漏洞。

FIPS 模式行为

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

算法选择（RSA-SHA256、RSA + SHA-3、Ed25519）由请求驱动；密码学原语由主机的 OpenSSL 提供。在受 FIPS 限制的部署中，请在政策层限制算法，并依赖主机已验证的模块。此工具本身并不声明 FIPS 验证。

传输可用性

标题为“传输可用性”的章节
传输可用备注
MCP（stdio）是（Pro）在 stdio 上使用 AES-GCM 密钥封装。
REST是（Pro）优先使用 TLS 加上密钥封装。
gRPC是（Pro）优先使用 TLS 加上密钥封装。

HITL 风险级别

标题为“HITL 风险级别”的章节

sign_pdf 属于「需要批准」（一项破坏性、不可逆的操作——此工具会声明破坏性提示）。确认关卡的应用方式，与任何「需要批准」工具相同。output_pdf 输出至文件同样属于「需要批准」；base64 模式则为「审查」（HITL 风险级别）。

确认关卡 JSON 封装

标题为“确认关卡 JSON 封装”的章节

没有有效令牌的 sign_pdf 会返回挑战封装：

{
  "allowed": false,
  "challenge": "⚠️ CONFIRMATION REQUIRED\n\nOperation: sign_pdf\nDescription: <tool description>\n\nTo proceed, call sign_pdf again with parameter _confirmation_token: \"confirm_<single-use-hex>\"\nExpires in 300 seconds.",
  "token": "confirm_<single-use-hex>"
}

将 _confirmation_token 设为该令牌并重新调用 → { "allowed": true }。完整流程：输出批准。

另见

标题为“另见”的章节