技術文章

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,在第一頁附加一個帶隱形簽章 widget 的增量更新,並寫入帶 /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 的 reason 視為二選一;這時簽署服務必須把 commitment-type-indication 寫進 CMS 的已簽署屬性。SigningTimeUtc 成為 /M 條目。加密的來源一律拒收,所以先解密。遠端函式屬於 Enterprise 版:必須連結 FPdfPadesRemote 單元,否則 FPdfPades 裡的進入點會 raise 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 的 class methods,所以第二階段完全不需要載入任何文件

簽署服務必須回傳什麼

DocumentDigest 裡那 32 個位元組,是 CMS 必須放進 message-digest 已簽署屬性的值,但它們通常不是私鑰實際簽的位元組。RFC 5652 §5.4 規定:只要存在已簽署屬性,簽章就計算在屬性集合的 DER 編碼之上。所以回傳完整 CMS 的服務自己做了這一步,而只簽雜湊的裸 HSM 把這一步留給你。後一種情況下,你的程式碼要建出 SignedAttributes(content-type、message-digest、signing-certificate-v2),把它們以成員排序過的 SET OF 做 DER 編碼、對結果求雜湊,再請 HSM 簽這個雜湊。排序錯了,做出來的 CMS 看起來沒問題、密碼學驗證卻會失敗;CMS 已簽署屬性中的 DER SET OF 排序逐步走過這個陷阱

不管 CMS 是誰組的,完成階段只接受一種特定形狀:SignedData 帶恰好一個 SignerInfo、分離式(無封裝內容)、帶 content-type 與 message-digest 已簽署屬性、摘要演算法不是 MD5 或 SHA-1,並有有效的 signing-certificate-v2 屬性。這些正是 ETSI EN 319 142-1 對 PAdES baseline 簽章的要求,所以已經產出 PAdES 相容 CAdES 的服務不必做任何額外調整就能接上

CompletePadesRemoteSignature 拒絕什麼?

CompletePadesRemoteSignature 在對目的地串流寫出任何一個位元組之前,會跑完每一項檢查;每次拒絕都會 raise EPadesCrypto,訊息指名未通過的檢查。請求記錄本身先查:格式版本 1、32 位元組的指紋與摘要、ContentsSize 介於 1024 位元組與 64 MiB 之間、十六進位偏移量為正。然後是備妥的檔案:

  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 magic、格式版本、十六進位偏移量、ContentsSize、四個 ByteRange 值,然後是摘要與指紋。LoadPadesRemoteSigningRequest 拒絕大小不對、magic 不對、帶尾隨資料或格式版本不是 1 的任何東西。記錄裡沒有金鑰材料、也沒有文件內容,所以把它連同備妥 PDF 一起放進資料庫資料列或物件儲存都沒問題

網頁應用程式的場景因此很直接:一個請求處理常式備妥檔案、把兩份產物都存起來,瀏覽器或手機應用程式核准摘要,另一個節點上的 callback 處理常式載入工作階段並完成簽署。約束落在備妥的 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 的位元組數;檔案裡的佔位空間是它的兩倍長的十六進位字元,這就是為什麼預設值 16384 會產生開頭那段裡的 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 都不需要私鑰

用信賴方會走的同一路徑驗證產出,檢視 PDF 數位簽章與 PAdES 等級一文有涵蓋。在遠端管線裡,組出 CMS 的程式碼住在別人的伺服器上,它的產出第一個該遇到真正驗證器的地方,應該是你自己的建置,而且要在你的客戶之前

遠端簽署呼叫隨 Delphi 與 Lazarus 版 PDFium Component 的 Enterprise 版出貨,與原生 Pascal 的 PAdES 簽署、時間戳記與驗證程式碼並列。API 參考與試用下載請見 PDFium Component 產品頁