Technischer Artikel

PDFium VCL: Remote-PAdES-Signatur mit HSM & Cloud

Ein PAdES-Signatur-Platzhalter von 16.384 Bytes zeigt sich in der Datei als 32.768 ASCII-Nullen zwischen spitzen Klammern, und jedes Byte des PDFs außerhalb dieser Folge ist bereits vom Hash abgedeckt, dem der Signierer zustimmen wird. Das ist der unbequeme Teil des Signierens mit einem Schlüssel, den man nicht anfassen kann: Das Dokument muss sich auf sein endgültiges Layout festlegen, bevor das CMS existiert, und dann warten, mitunter stundenlang, während ein Netzwerk-HSM oder ein Cloud-Signierdienst eine Person zur Bestätigung auf dem Handy auffordert. Was in dieser Wartezeit mit der Datei passiert, entscheidet darüber, ob die Signatur validiert

Warum kann ein entfernter Schlüssel nicht SignPadesBytes verwenden?

Der gewöhnliche Aufruf setzt voraus, dass der private Schlüssel innerhalb des Aufrufs erreichbar ist. SignPadesBytes in PDFium Component baut das inkrementelle Update, hasht das ByteRange, signiert mit dem im Windows-Speicher durch CertificateThumbprint benannten Zertifikat und schreibt die fertige Datei, bevor es zurückkehrt. Für einen Schlüssel im lokalen Speicher ist das genau die Form, die man will

Ein von einem Vertrauensdiensteanbieter betriebenes qualifiziertes Signaturerstellungsgerät arbeitet nicht so. Eine Cloud-Signier-API mit Zweifaktor-Schritt ebenso wenig wie ein HSM hinter einer Warteschlange. Der Austausch ist ein Gespräch: Man schickt einen Digest, etwas außerhalb des eigenen Prozesses authentifiziert einen Menschen, und ein CMS kommt später an, in einem anderen Thread, in einem anderen Request-Handler, vielleicht auf einem anderen Server. Ein synchroner Aufruf kann das nur abbilden, indem er einen Thread blockiert, bis irgendwo jemand die Bestätigung auf dem Handy getippt hat

Der Remote-Pfad teilt sich daher in zwei Aufrufe. PreparePadesRemoteSignature erzeugt das vorbereitete PDF und einen kleinen Request-Record. CompletePadesRemoteSignature nimmt das vorbereitete PDF, den Record und das zurückgegebene DER-CMS entgegen und schreibt die signierte Datei. Nichts bindet die beiden Aufrufe an denselben Prozess

Das Dokument mit PreparePadesRemoteSignature vorbereiten

PreparePadesRemoteSignature liest das Quell-PDF, hängt ein inkrementelles Update mit einem unsichtbaren Signatur-Widget auf der ersten Seite an und schreibt ein Signatur-Dictionary mit /Filter /Adobe.PPKLite und /SubFilter /ETSI.CAdES.detached. Der /Contents-Eintrag wird mit Nullen fester Breite gefüllt, die vier ByteRange-Zahlen werden darum herum eingepatcht, und der SHA-256 über diese beiden Bereiche wird zu Request.DocumentDigest. Die Original-Bytes der Quelldatei bleiben unangetastet; das Update hängt nur an

Der Ausgabe-Record TPadesRemoteSigningRequest hat sechs Felder: FormatVersion, PreparedFingerprint (SHA-256 der ganzen vorbereiteten Datei), DocumentDigest, das vierelementige ByteRange, ContentsHexOffset (wo die Hex-Ziffern beginnen) und ContentsSize. Nur der Digest geht an den Signierdienst. Der Rest existiert, damit der zweite Aufruf beweisen kann, dass er dieselben Bytes vervollständigt, aus denen der Digest stammt

Drei Optionsregeln betreffen die vorbereitete Datei, eine vierte den eigenen Build. Ist CommitmentTypeOid gesetzt, trägt das Dictionary kein /Reason, denn ETSI EN 319 142-1 behandelt den Commitment-Typ im CMS und den PDF-Grund als Alternativen; der Signierdienst muss die Commitment-Type-Indication dann in die CMS-signed-Attributes schreiben. SigningTimeUtc wird zum /M-Eintrag. Verschlüsselte Quellen werden rundheraus abgelehnt, also zuerst entschlüsseln. Die Remote-Funktionen gehören zur Enterprise-Edition: Die Unit FPdfPadesRemote muss gelinkt sein, sonst werfen die Einstiegspunkte in FPdfPades EPdfEnterpriseRequired

Zweiphasiger PDFium-Fern-PAdES-Fluss in Delphi: PreparePadesRemoteSignature reserviert den CMS-Slot und reicht den Dokumentdigest an einen HSM- oder Cloud-Service weiter, und CompletePadesRemoteSignature bettet das zurückgegebene CMS später in beliebigen Prozess oder Rechner ein
Phase eins reserviert den CMS-Slot und übergibt den Dokumentdigest; Phase zwei bettet das CMS ein, das vom HSM oder Cloud-Schlüssel zurückkommt
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // linkt die Enterprise-Implementierung

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;

  // Eigener Code: den 32-Byte-Digest an das HSM oder die Signier-API übergeben
  SendDigestToSigningService(Request.DocumentDigest);
end;

Ist das Dokument bereits in einer TPdf-Komponente geöffnet, speichert TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) den aktuellen Zustand und bereitet von dem aus vor, mit False, wenn kein Dokument aktiv ist. Fertigstellung und die Session-Helfer sind ebenfalls Klassenmethoden an TPdf, die zweite Phase braucht also gar kein geladenes Dokument

Was der Signierdienst zurücksenden muss

Die 32 Bytes in DocumentDigest sind der Wert, den das CMS in seinem Message-Digest-signed-Attribute tragen muss. Meist sind sie nicht die Bytes, die der private Schlüssel signiert. RFC 5652 §5.4 besagt, dass bei vorhandenen signed Attributes die Signatur über die DER-Kodierung des Attributsatzes berechnet wird, ein Dienst, der ein komplettes CMS zurückgibt, erledigt diesen Schritt also selbst, während ein nacktes HSM, das nur Hashes signiert, ihn an einen selbst durchreicht. Im zweiten Fall baut der eigene Code die SignedAttributes (Content-Type, Message-Digest, Signing-Certificate-v2), kodiert sie als SET OF mit sortierten Mitgliedern per DER, hasht das und bittet das HSM, den Hash zu signieren. Eine falsche Sortierordnung ergibt ein CMS, das gesund aussieht und die kryptografische Verifikation scheitern lässt; DER-SET-OF-Sortierung in CMS-signed-Attributes führt durch diese Falle

Wer auch immer das CMS zusammensetzt: Die Fertigstellung akzeptiert genau eine Form — ein SignedData mit exakt einem SignerInfo, detached (ohne eingekapselten Inhalt), mit Content-Type- und Message-Digest-signed-Attributes, einem Digest-Algorithmus außer MD5 oder SHA-1 und einem gültigen Signing-Certificate-v2-Attribute. Das entspricht dem, was PAdES-Baseline-Signaturen unter ETSI EN 319 142-1 verlangen, ein Dienst, der bereits PAdES-kompatible CAdES-Ausgabe erzeugt, passt also ohne Zusatzarbeit

Was weist CompletePadesRemoteSignature zurück?

CompletePadesRemoteSignature fährt jede Prüfung, bevor es ein einziges Byte in den Zielstrom schreibt, und jede Ablehnung wirft EPadesCrypto mit einer Meldung, die die gescheiterte Prüfung nennt. Zuerst wird der Request-Record selbst geprüft: Formatversion 1, 32-Byte-Fingerprint und -Digest, ein ContentsSize zwischen 1024 Bytes und 64 MiB, ein positiver Hex-Offset. Dann die vorbereitete Datei:

  1. die aufgezeichneten Offsets müssen innerhalb der Datei liegen, und das ByteRange muss exakt mit dem Platzhalter und der Dateilänge übereinstimmen
  2. das < und > um /Contents müssen noch an ihrem Platz sein, und jede Hex-Ziffer dazwischen muss noch 0 sein
  3. der SHA-256 der ganzen Datei muss PreparedFingerprint entsprechen, und der ByteRange-Hash muss DocumentDigest entsprechen

Dann das CMS: Es muss exakt ein DER-Wert ohne angehängte Bytes sein, nicht länger als ContentsSize, von der unterstützten SignedData-Form, mit vorhandenem Signing-Certificate-v2, und zuletzt muss sein Message-Digest-Attribute DocumentDigest entsprechen

Eine zwischen den Phasen neu erzeugte vorbereitete Datei ändert den Fingerprint, selbst wenn sie im Betrachter identisch aussieht. Ein Alles-Null-Test am Platzhalter fängt die doppelte Fertigstellung, bei der ein Retry ein zweites CMS über eine bereits vorhandene Signatur schreibt. Der Message-Digest-Vergleich fängt den widerlichsten Fall: ein korrekt geformtes CMS aus dem eigenen Zertifikat, signiert über ein anderes Dokument, weil eine Warteschlange zwei gleichzeitige Sessions vertauscht hat. Diese Datei würde tadellos öffnen und eine Freigabe tragen, die für einen anderen Vertrag gedacht war

Die Signing-Certificate-v2-Prüfung ist eher eine Konformitäts- als eine Integritätsfrage. Ein CMS ohne sie kann kryptografisch verifizieren und an einem PAdES-Validator trotzdem scheitern, und sie bei der Fertigstellung abzulehnen verlagert diese Erkenntnis aus dem Validierungsbericht eines Kunden in die eigenen Logs. Warum Validatoren PAdES-Signaturen ablehnen behandelt die übrigen Attribute, nach denen Validatoren suchen

Abschlusstor-Diagramm für PDFium-Fern-PAdES-Signierung in Delphi: CompletePadesRemoteSignature prüft Dateiintegrität, CMS-Form und PAdES-Konformität und schreibt die signierte PDF erst, wenn jede Prüfung besteht
CompletePadesRemoteSignature validiert Integrität, CMS-Form und PAdES-Konformität, bevor irgendein Byte geschrieben wird
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;   // eigener Code: DER-Bytes, kein 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);   // eigener Code: die exakte Meldung aufbewahren
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

Viele Signier-APIs liefern das CMS als Base64 innerhalb von JSON, mitunter mit PEM-Headern drumherum. Nur das dekodierte DER übergeben. Ein angehängter Zeilenumbruch oder ein übrig gebliebenes Header-Byte scheitert an der Exakt-ein-DER-Wert-Prüfung, und das ist das beabsichtigte Ergebnis: Die Alternative ist ein CMS, das mit Müll danach parst

Session-Dateien über Prozesse und Maschinen hinweg

SavePadesRemoteSigningRequest schreibt einen festen 120-Byte-Binärrecord: einen 8-Byte-PDRSIG01-Magic, die Formatversion, den Hex-Offset, ContentsSize, die vier ByteRange-Werte, dann Digest und Fingerprint. LoadPadesRemoteSigningRequest weist alles mit falscher Größe, falschem Magic, angehängten Daten oder einer Formatversion ungleich 1 zurück. Der Record enthält keine Schlüssel und keinen Dokumentinhalt, er darf also neben dem vorbereiteten PDF in einer Datenbankzeile oder einem Object Store liegen

Damit ist der Webanwendungs-Fall geradlinig. Ein Request-Handler bereitet die Datei vor und legt beide Artefakte ab, der Browser oder eine Phone-App bestätigt den Digest, und ein Callback-Handler auf einem anderen Knoten lädt die Session und stellt fertig. Die Bedingung liegt am vorbereiteten PDF: Es muss Byte für Byte zurückkommen. Es über eine PDF-Bibliothek neu zu speichern, durch einen Optimizer zu jagen oder eine Transportschicht an den Zeilenenden drehen zu lassen, ändert jeweils den Fingerprint

Ein nutzungsbasierter qualifizierter Signaturdienst rechnet pro Operation ab, es lohnt sich also, die abgelegte Datei zu prüfen, bevor man überhaupt eine Signatur anfordert. Der Entwurf unten vergleicht den Datei-Hash mit PreparedFingerprint über das System.Hash der Delphi-RTL; das ist eine Prüfung, die man selbst ergänzt, und die Fertigstellung wiederholt sie ohnehin

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

// Vorgeschlagener Pre-Flight-Check, den man selbst ergänzt; nicht Teil der Komponente
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // Die TStream-Überladung von GetHashBytes braucht ein aktuelles Delphi-System.Hash;
    // Lazarus hat kein System.Hash, dort also die eigene SHA-256-Routine aufrufen
    H := THashSHA2.GetHashBytes(S);   // standardmäßig SHA-256
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

ContentsSize bemessen, bevor das CMS existiert

ContentsSize zählt Bytes des DER-CMS. Der Platzhalter in der Datei ist doppelt so lang an Hex-Zeichen, daher erzeugt der Default 16384 die 32.768 Nullen aus dem Eingangsabsatz. Werte unter 1024 werden auf 1024 angehoben, ein Wert über 64 MiB wird beim Vorbereiten abgelehnt, und die Fertigstellung weist jedes CMS zurück, das länger als ContentsSize Bytes ist

Zu klein ist der teure Fehler: Der Dienst hat bereits signiert, die Operation ist verbraucht, und der einzige Weg führt über erneutes Vorbereiten mit einem größeren Slot und erneutes Signieren. Zu groß kostet nur Auffüllung in jeder signierten Datei. Tendenz zur großen Seite. Angenommen, der Dienst liefert ein CMS von etwa 7.000 Bytes mit einer Kette aus drei Zertifikaten; der Default lässt dann noch mehr als die Hälfte des Slots frei. Betten die Zeitstempel-Token oder Sperrdaten als unsigned Attributes ein, landen sie im selben CMS und zählen gegen dasselbe Limit, also eine echte Antwort aus der eigenen Produktionskette messen und davon ausgehend dimensionieren, mit Raum für eine längere Intermediate-Kette später

Nach der Fertigstellung: B-B, dann LTV und Verifikation

Eine fertiggestellte Remote-Signatur ist PAdES B-B. Die Langzeitvalidierung ergänzt einen Dokumentzeitstempel und Validierungsmaterial in einem späteren inkrementellen Update mit einem DSS und dessen VRI-Dictionarys pro Signatur, beschrieben in Langzeitsignaturen mit RFC-3161-Zeitstempeln und DSS. Dieser Schritt läuft lokal, denn Zertifikate, OCSP-Antworten und CRLs brauchen den privaten Schlüssel nicht

Die Ausgabe mit demselben Pfad verifizieren, den eine vertrauende Partei nehmen würde, behandelt in Inspektion digitaler Signaturen und PAdES-Level. In einer Remote-Pipeline lebt der Code, der das CMS baut, auf dem Server von jemand anderem, und der erste Ort, an dem seine Ausgabe auf einen echten Validator trifft, sollte der eigene Build sein, vor den Kunden

Die Remote-Signier-Aufrufe kommen mit der Enterprise-Edition von PDFium Component für Delphi und Lazarus, neben dem nativen Pascal-PAdES-Code für Signieren, Zeitstempeln und Validierung. API-Referenz und Trial-Downloads gibt es auf der PDFium-Component-Produktseite