技术文章

PDFium VCL 远程 PAdES 签名:HSM 与云端密钥

16,384 字节的 PAdES 签名占位符在文件里呈现为尖括号之间的 32,768 个 ASCII 零,而占位之外 PDF 的每一个字节都已进入签名者将要批准的哈希。这就是用一把你摸不到的密钥签名的尴尬之处:文档必须在 CMS 存在之前就敲定最终布局,然后等待——有时是几个小时——网络 HSM 或云签名服务在这期间还要等一个人在手机上确认。等待期间文件发生的任何事,都决定着签名能否通过校验

远程密钥为什么不能用 SignPadesBytes?

普通调用假定私钥在调用内部就能访问到。PDFium Component 的 SignPadesBytes 构建增量更新、对 ByteRange 计算哈希、用 Windows 证书存储里 CertificateThumbprint 指定的证书签名,并在返回前写完整个文件。对本地存储里的密钥来说,这正是你想要的形状

信任服务提供商运营的合格签名创建设备不是这样工作的;带第二因素步骤的云签名 API、排在队列后面的 HSM 也一样。整个交换是一场对话:你发出一个摘要,你进程之外的某个东西认证一个真人,CMS 稍后才到达——在不同的线程、不同的请求处理器,甚至不同的服务器上。同步调用想模拟这个过程,唯一的办法是阻塞一个线程,等某人的手机亮屏

所以远程路径拆成两次调用。PreparePadesRemoteSignature 产出准备好的 PDF 和一份小的请求记录;CompletePadesRemoteSignature 拿着准备好的 PDF、记录和返回的 DER CMS,写出签名后的文件。两次调用之间没有任何东西强制它们发生在同一个进程

用 PreparePadesRemoteSignature 准备文档

PreparePadesRemoteSignature 读取源 PDF,追加一次增量更新,在第一页放一个不可见的签名控件,并写出一个带 /Filter /Adobe.PPKLite 与 /SubFilter /ETSI.CAdES.detached 的签名字典。/Contents 条目用固定宽度的零填满,四个 ByteRange 数字围绕它打好补丁,这两段范围上的 SHA-256 就成为 Request.DocumentDigest。源文件的原始字节不动;更新只做追加

输出记录 TPadesRemoteSigningRequest 有六个字段:FormatVersion、PreparedFingerprint(整份准备文件的 SHA-256)、DocumentDigest、四元素 ByteRange、ContentsHexOffset(十六进制数字开始的位置)和 ContentsSize。只有摘要会交给签名服务;其余字段的存在,是为了让第二次调用能够证明它完成的正是这份摘要所来自的那份字节

三条选项规则影响准备出的文件,第四条影响你的构建。设置了 CommitmentTypeOid 时,字典不带 /Reason,因为 ETSI EN 319 142-1 把 CMS 里的承诺类型与 PDF 里的原因当作二选一;此时签名服务必须把 commitment-type-indication 写进 CMS 的签名属性。SigningTimeUtc 成为 /M 条目。加密源文件直接拒绝,请先解密。远程函数属于 Enterprise 版:必须链接 FPdfPadesRemote 单元,否则 FPdfPades 里的入口会抛 EPdfEnterpriseRequired

Delphi 中两阶段 PDFium 远程 PAdES 流程:PreparePadesRemoteSignature 预留 CMS 槽位并把文档摘要交给 HSM 或云服务;CompletePadesRemoteSignature 之后在任意进程或机器上嵌入返回的 CMS
第一阶段预留 CMS 槽位并移交文档摘要;第二阶段嵌入从 HSM 或云密钥返回的 CMS
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // 链接 Enterprise 版实现

var
  Options: TPadesRemoteSignOptions;
  Request: TPadesRemoteSigningRequest;
  Source, Prepared, Session: TFileStream;
begin
  Options := TPadesRemoteSignOptions.Default;   // ContentsSize = 16384
  Options.Reason := 'Approved by finance';
  Options.Location := 'Lisbon';
  Options.Name := 'A. Moreira';
  Options.SigningTimeUtc := TTimeZone.Local.ToUniversalTime(Now);

  Source := TFileStream.Create('contract.pdf', fmOpenRead or fmShareDenyWrite);
  Prepared := TFileStream.Create('contract.prepared.pdf', fmCreate);
  try
    PreparePadesRemoteSignature(Source, Prepared, Options, Request);
  finally
    Prepared.Free;
    Source.Free;
  end;

  Session := TFileStream.Create('contract.signreq', fmCreate);
  try
    SavePadesRemoteSigningRequest(Session, Request);
  finally
    Session.Free;
  end;

  // 你自己的代码:把 32 字节摘要交给 HSM 或签名 API
  SendDigestToSigningService(Request.DocumentDigest);
end;

如果文档已经打开在一个 TPdf 组件里,TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) 会保存当前状态并从它出发准备,没有活动文档时返回 False。完成函数和会话助手同样是 TPdf 的类方法,所以第二阶段完全不需要加载文档

签名服务必须返回什么

DocumentDigest 里的 32 字节,是 CMS 必须放进其 message-digest 签名属性的值。它们通常不是私钥直接签的字节。RFC 5652 §5.4 规定:存在签名属性时,签名是对属性集合的 DER 编码计算的。返回完整 CMS 的服务自己完成这一步;只签哈希的裸 HSM 则把它留给你。后一种情况下,你的代码要构建 SignedAttributes(content-type、message-digest、signing-certificate-v2),把它们按成员排序后 DER 编码成 SET OF,对它求哈希,再让 HSM 签这个哈希。排序搞错会得到一个看起来完好、密码学校验却失败的 CMS;CMS 签名属性中的 DER SET OF 排序专门拆解这个陷阱

无论 CMS 由谁组装,完成阶段只接受一种确定的形状:一个恰好含一个 SignerInfo 的 SignedData,detached(无封装内容),带 content-type 与 message-digest 签名属性,摘要算法不是 MD5 或 SHA-1,并且有有效的 signing-certificate-v2 属性。这些与 ETSI EN 319 142-1 对 PAdES baseline 签名的要求一致,所以已经在产出 PAdES 兼容 CAdES 的服务无需任何额外适配就能接入

CompletePadesRemoteSignature 拒绝什么?

CompletePadesRemoteSignature 在向目标流写出任何字节之前跑完每一项检查,每次拒绝都以 EPadesCrypto 抛出,消息里写明失败的检查。请求记录本身先查:格式版本 1、32 字节指纹与摘要、1024 字节到 64 MiB 之间的 ContentsSize、正的十六进制偏移。然后是准备文件:

  1. 记录的偏移量必须落在文件内,ByteRange 必须与占位符和文件长度严丝合缝
  2. /Contents 周围的 < 和 > 必须原位还在,其间每个十六进制数字必须仍是 0
  3. 整份文件的 SHA-256 必须等于 PreparedFingerprint,ByteRange 哈希必须等于 DocumentDigest

然后是 CMS:它必须是一个不带尾随字节的精确 DER 值,长度不超过 ContentsSize,具备受支持的 SignedData 形状,带 signing-certificate-v2,最后其 message-digest 属性必须等于 DocumentDigest

两个阶段之间被重新生成的准备文件,即使查看器里看起来一模一样,指纹也变了。占位符的全零检查抓住重复完成——重试把第二个 CMS 写到已有的签名上。message-digest 比较抓住最阴险的情况:一个来自你自己证书、格式完全正确的 CMS,签的却是另一份文档——队列把两个并发会话调换时就会发生这种事。那份文件会正常打开,携带的却是一份给别的合同的批准

signing-certificate-v2 检查更多关乎合规而非完整性。没有它的 CMS 可能通过密码学校验,却过不了 PAdES 校验器;在完成阶段就拒绝它,把发现问题的时机从客户的校验报告挪到你自己的日志里。校验器为什么拒绝 PAdES 签名覆盖了校验器寻找的其他属性

Delphi 中 PDFium 远程 PAdES 签名的完成闸门图:CompletePadesRemoteSignature 检查文件完整性、CMS 形态和 PAdES 合规性,所有检查都通过才写出已签名 PDF
CompletePadesRemoteSignature 在写入任何字节之前验证完整性、CMS 形状和 PAdES 合规性
var
  Request: TPadesRemoteSigningRequest;
  Session, Prepared, Dest: TFileStream;
  CmsDer: TBytes;
begin
  Session := TFileStream.Create('contract.signreq', fmOpenRead);
  try
    Request := LoadPadesRemoteSigningRequest(Session);
  finally
    Session.Free;
  end;

  CmsDer := FetchDetachedCmsFromService;   // 你自己的代码:DER 字节,不是 Base64

  Prepared := TFileStream.Create('contract.prepared.pdf', fmOpenRead);
  try
    Dest := TFileStream.Create('contract.signed.pdf', fmCreate);
    try
      try
        CompletePadesRemoteSignature(Prepared, Dest, Request, CmsDer);
      except
        on E: EPadesCrypto do
          FailSession(E.Message);   // 你自己的代码:保留原始错误消息
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

许多签名 API 把 CMS 以 Base64 形式放在 JSON 里返回,有时外面还套着 PEM 头。只传解码后的 DER。一个尾随换行或残留的头字节都会让"恰好一个 DER 值"检查失败——这正是设计意图:否则你面对的是一个解析完后面还挂着垃圾的 CMS

跨进程与机器的会话文件

SavePadesRemoteSigningRequest 写出固定 120 字节的二进制记录:8 字节 PDRSIG01 魔数、格式版本、十六进制偏移、ContentsSize、四个 ByteRange 值,然后是摘要和指纹。LoadPadesRemoteSigningRequest 拒绝大小不对、魔数不对、带尾随数据或格式版本不是 1 的任何东西。记录里没有密钥材料,也没有文档内容,把它和准备好的 PDF 一起放进数据库行或对象存储都没问题

Web 应用场景因此变得直白:一个请求处理器准备文件并保存两份产物,浏览器或手机应用批准摘要,另一个节点上的回调处理器加载会话并完成签名。约束落在准备好的 PDF 上:它必须逐字节回来。用 PDF 库重新保存、过一遍优化器、或让传输层碰行尾,都会改变指纹

按次计费的合格签名服务按操作收费,所以在请求签名之前先检查存储的文件是划算的。下面的草图用 Delphi RTL 的 System.Hash 把文件哈希与 PreparedFingerprint 比较;这是你自己加的检查,反正完成阶段还会再查一遍

uses
  System.SysUtils, System.Classes, System.Hash,
  FPdfPades, FPdfPadesRemote;

// 建议你自己加的预检;不属于组件
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // GetHashBytes 的 TStream 重载需要较新的 Delphi System.Hash;
    // Lazarus 没有 System.Hash,请在那里调用你自己的 SHA-256 例程
    H := THashSHA2.GetHashBytes(S);   // 默认就是 SHA-256
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

在 CMS 存在之前给 ContentsSize 定尺寸

ContentsSize 统计的是 DER CMS 的字节数。文件里的占位符是它两倍的十六进制字符,这就是开头那段 32,768 个零的来历。低于 1024 的值会被抬到 1024,超过 64 MiB 的值在准备阶段就被拒绝,完成阶段拒绝任何超过 ContentsSize 字节的 CMS

定小了是昂贵的错误:服务已经签完名,操作已经消耗,唯一的出路是用更大的槽位重新准备、重新签名。定大了只是每份签名文件多带点填充。宁可偏大。假设你的服务返回约 7,000 字节、带三证书链的 CMS,默认值仍有一半以上的槽位空着。如果服务还把签名时间戳令牌或吊销数据作为无符号属性嵌进来,它们落进同一个 CMS、占用同一个限额,所以从生产链路上量一次真实响应再定尺寸,给日后更长的中间证书链留出余量

完成之后:B-B,然后是 LTV 与校验

完成的远程签名是 PAdES B-B。长期校验在稍后的增量更新里加入文档时间戳与校验材料,即一个 DSS 及其每个签名的 VRI 字典,见 带 RFC 3161 时间戳与 DSS 的长期签名。这一步在本地运行,因为证书、OCSP 响应和 CRL 都不需要私钥

用依赖方将来会走的同一条路径校验输出,见 检查数字签名与 PAdES 级别。远程流水线里构建 CMS 的代码活在别人的服务器上,它的输出第一次遇到真正校验器的地方应该是你自己的构建,而不是你的客户

远程签名调用随 Delphi 和 Lazarus 的 PDFium Component Enterprise 版提供,与原生 Pascal 的 PAdES 签名、时间戳与校验代码并列。API 参考和试用下载见 PDFium Component 产品页