技術記事

PDFium VCLのリモートPAdES署名:HSMとクラウド鍵

16,384バイトのPAdES署名プレースホルダーは、ファイルの中では角括弧に挟まれた32,768個のASCIIゼロとして現れます。そしてその並びの外側にあるPDFの全バイトは、署名者が承認するハッシュで既にカバーされています。ここに触れない鍵で署名する厄介な部分があります。ドキュメントはCMSが存在するより前に最終レイアウトへコミットし、その後、ネットワークHSMやクラウド署名サービスがスマートフォン上で人の確認を求めている間、時には何時間も待つことになります。その待ち時間にファイルに何が起きるかで、署名が検証に通るかどうかが決まります

リモート鍵がSignPadesBytesを使えない理由

通常の呼び出しは、秘密鍵がその呼び出しの中で届く範囲にあることを前提とします。PDFium ComponentのSignPadesBytesは増分更新を組み立て、ByteRangeをハッシュし、WindowsストアのCertificateThumbprintで指定された証明書で署名し、戻る前に完成したファイルを書き込みます。ローカルストアの鍵なら、これこそが望む形です

信頼サービス提供者が運用する適格な署名作成デバイスはそうはいきません。第二要素のステップがあるクラウド署名APIも、キューの奥に座るHSMも同様です。やり取りは会話です。ダイジェストを送り、プロセスの外にある何かが人間を認証し、CMSは後から別のスレッドへ、別のリクエストハンドラへ、場合によっては別のサーバーへ届きます。同期呼び出しは、誰かのスマートフォン上でスレッドを止めることでしかそれを表現できません

そこでリモート経路は2つの呼び出しに分かれます。PreparePadesRemoteSignatureが準備済みPDFと小さなリクエストレコードを生成し、CompletePadesRemoteSignatureが準備済みPDF、レコード、返されたDERのCMSを受け取って署名済みファイルを書き込みます。2つの呼び出しを同じプロセスに縛るものは何もありません

PreparePadesRemoteSignatureでドキュメントを準備する

PreparePadesRemoteSignatureはソースPDFを読み、1ページ目に不可視の署名ウィジェットを伴う増分更新を追加し、/Filter /Adobe.PPKLiteと/SubFilter /ETSI.CAdES.detachedを持つ署名辞書を書き込みます。/Contentsエントリは固定幅のゼロで満たされ、4つのByteRange数値がその周囲に書き込まれ、その2つの範囲に渡るSHA-256がRequest.DocumentDigestになります。ソースファイルの元のバイトは触られず、更新は追記だけを行います

出力レコードのTPadesRemoteSigningRequestには6つのフィールドがあります。FormatVersion、PreparedFingerprint(準備済みファイル全体のSHA-256)、DocumentDigest、4要素のByteRange、ContentsHexOffset(16進数字の開始位置)、ContentsSizeです。署名サービスへ送るのはダイジェストだけです。残りは、2番目の呼び出しが「ダイジェストの元になった同じバイトを完了している」ことを証明するために存在します

オプションの規則のうち3つは準備済みファイルに影響し、4つ目はビルドに影響します。CommitmentTypeOidを設定すると、辞書は/Reasonを持ちません。ETSI EN 319 142-1は、CMS内のコミットメントタイプとPDFの理由を代替物として扱うからです。署名サービスはコミットメントタイプ指示をCMSの署名済み属性へ書き込む必要があります。SigningTimeUtcは/Mエントリになります。暗号化されたソースはその場で拒否されるので、先に復号してください。リモート関数はEnterpriseエディションの所属で、ユニットFPdfPadesRemoteをリンクしていなければならず、そうしないとFPdfPadesのエントリポイントはEPdfEnterpriseRequiredを上げます

Delphi における 2 相 PDFium リモート PAdES フロー。PreparePadesRemoteSignature が CMS スロットを予約しドキュメントダイジェストを HSM かクラウドサービスへ引き渡し、CompletePadesRemoteSignature が返された CMS を後から任意のプロセスやマシンで埋め込む
フェーズ 1 が CMS スロットを予約してドキュメントダイジェストを引き渡し、フェーズ 2 が 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のクラスメソッドなので、第2フェーズにロード済みドキュメントは一切要りません

署名サービスが返さなければならないもの

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を組み立てるのが誰であれ、完了処理が受け入れるのは特定の1形状だけです。SignerInfoをちょうど1つ持つdetached(カプセル化コンテンツなし)のSignedData、content-typeとmessage-digestの署名済み属性、MD5やSHA-1以外のダイジェストアルゴリズム、有効なsigning-certificate-v2属性。これらはETSI EN 319 142-1がPAdESベースライン署名に求めるものと一致するため、既にPAdES互換のCAdESを出力するサービスは追加作業なしで収まります

CompletePadesRemoteSignatureは何を拒否するのか

CompletePadesRemoteSignatureは、宛先ストリームに1バイトも書き込む前にすべてのチェックを行い、拒否のたびに失敗したチェック名を含むメッセージのEPadesCryptoを上げます。まずリクエストレコード自体を検証します。フォーマットバージョン1、32バイトのフィンガープリントとダイジェスト、1024バイトから64 MiBの間のContentsSize、正の16進オフセット。その次が準備済みファイルです

  1. 記録されたオフセットがファイル内に収まっていること、ByteRangeがプレースホルダーとファイル長と正確に整列していること
  2. /Contentsを囲む<と>がまだ所定の位置にあり、その間の16進数字がすべて0のままであること
  3. ファイル全体のSHA-256がPreparedFingerprintと一致し、ByteRangeのハッシュがDocumentDigestと一致すること

その次がCMSです。後続バイトのない1つの正確なDER値であること、長さがContentsSize以下であること、サポートされるSignedData形状であること、signing-certificate-v2が存在すること、そして最後に、message-digest属性がDocumentDigestと一致すること

フェーズ間で再生成された準備済みファイルは、ビューアでは同一に見えてもフィンガープリントが変わります。プレースホルダーのオールゼロ検査は二重完了を捉えます。再試行が既に署名のある場所へ2つ目のCMSを上書きするケースです。message-digest比較は最も質の悪いケースを捉えます。キューが同時実行の2セッションを取り違えたために、自分の証明書で別のドキュメントに署名された、形式は正しいCMSです。そのファイルは問題なく開き、別の契約向けの承認を運んでくるのです

signing-certificate-v2チェックは、完全性というより適合性に関わります。これを欠くCMSは暗号学的には検証に通ってもPAdESバリデータには失敗しかねず、完了時に拒否することで、その発見が顧客の検証レポートから自分のログへ移ります。バリデータが探すその他の属性は、バリデータがPAdES署名を拒否する理由が扱います

Delphi における PDFium リモート PAdES 署名の完了ゲート図。CompletePadesRemoteSignature がファイル完全性、CMS 形状、PAdES 適合を確認し、全チェック合格時のみ署名済み PDF を書き込む
CompletePadesRemoteSignature は、1 バイトでも書かれる前に、整合性、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;   // 自分のコード。Base64 ではなく DER バイト

  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をJSONの中のBase64で返し、PEMヘッダーが付いてくることもあります。渡すのはデコード済みのDERだけにしてください。末尾の改行や残ったヘッダーバイトは「1つの正確なDER値」チェックに失敗しますが、それが意図した結果です。替わりにあるのは、後ろにゴミの付いたCMSが解析を通ってしまう道です

プロセスとマシンをまたぐセッションファイル

SavePadesRemoteSigningRequestは固定120バイトのバイナリレコードを書きます。8バイトのPDRSIG01マジック、フォーマットバージョン、16進オフセット、ContentsSize、4つのByteRange値、その後にダイジェストとフィンガープリントです。LoadPadesRemoteSigningRequestは、サイズ違い、マジック違い、後続データ、バージョン1以外を拒否します。レコードは鍵素材もドキュメント内容も持たないため、準備済みPDFの隣にデータベース行やオブジェクトストアで保存して問題ありません

これでWebアプリケーションのケースも素直に組み立てられます。あるリクエストハンドラがファイルを準備して両方の成果物を保存し、ブラウザかスマートフォンアプリがダイジェストを承認し、別ノードのコールバックハンドラがセッションをロードして完了させます。制約があるのは準備済みPDFのほうで、1バイト単位で戻ってこなければなりません。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のバイト数です。ファイル内のプレースホルダーはその2倍の16進文字数になるため、デフォルトの16384が冒頭の32,768個のゼロを生みます。1024未満の値は1024へ引き上げられ、64 MiB超の値は準備時に拒否され、完了処理はContentsSizeバイトを超えるCMSを一切受け入れません

小さすぎるのが高くつく間違いです。サービスは既に署名済みで、操作料は払い、前に進む道は大きなスロットで再準備して再署名するしかありません。大きすぎるのは、署名済みファイルごとのパディングという代償で済みます。大きめに寄せましょう。サービスが3証明書チェーン付きの約7,000バイトのCMSを返すとしても、デフォルトはスロットの半分以上を空けています。サービスが署名タイムスタンプトークンや失効データを未署名属性として埋め込むなら、それらも同じCMS内に収まり同じ上限に数えられるので、実運用のチェーンから実レスポンスを1つ計測し、後で長くなる中間チェーンの余地も残してサイズを決めてください

完了後:B-B、そしてLTVと検証

完了したリモート署名はPAdES B-Bです。長期検証は、後の増分更新でDSSと署名ごとのVRI辞書とともにドキュメントタイムスタンプと検証素材を追加します。RFC 3161タイムスタンプとDSSによる長期署名で述べた内容です。このステップはローカルで実行できます。証明書、OCSPレスポンス、CRLは秘密鍵を必要としないからです

出力は、依拠当事者が辿るのと同じ経路で検証してください。デジタル署名とPAdESレベルの検査で扱った方法です。リモートパイプラインではCMSを組み立てるコードは他人のサーバーで動くので、その出力が本物のバリデータに会う最初の場所は、顧客より先に自分のビルドであるべきです

リモート署名呼び出しは、ネイティブPascalのPAdES署名、タイムスタンプ、検証コードと並んで、DelphiとLazarus向けPDFium ComponentのEnterpriseエディションに同梱されています。APIリファレンスとトライアルダウンロードは、PDFium Component製品ページにあります