Technischer Artikel

PDF 2.0 AES-GCM-Verschlüsselung in Delphi (ISO/TS 32003)

Ein AES-256-verschlüsselter PDF-String mit einem gekippten Bit in seinen ersten 16 Bytes, dem Teil mit dem CBC-Initialisierungsvektor, entschlüsselt weiter mit dem richtigen Passwort. Der zurückkommende Klartext weicht vom Original in genau einem Bit ab, an derselben Position, die gekippt wurde. So arbeitet CBC. Der IV wird per XOR in den ersten Klartextblock gemischt, wer also die Datei bearbeiten kann, kann die ersten 16 Bytes jedes verschlüsselten Strings lenken, ohne den Schlüssel zu kennen. ISO/TS 32003 antwortet darauf mit AES-256 im GCM-Modus (Crypt-Filter-Methode AESV4, Security-Handler-Revision 7). Jeder verschlüsselte Wert trägt ein 16-Byte-Authentifizierungs-Tag, und ein geändertes Byte lässt die Entschlüsselung rundheraus scheitern

Was GCM gegenüber AESV3-CBC ändert

GCM fügt der Vertraulichkeit Authentifizierung hinzu. AESV3, das AES-256-CBC-Schema in ISO 32000-2, hält Inhalte ohne Passwort unlesbar, bemerkt eine Veränderung aber nicht. Ein gekipptes Bit im IV ändert das passende Bit des ersten Klartextblocks. Ein gekipptes Bit sonstwo macht einen 16-Byte-Block unleserlich und kippt dasselbe Bit im darauffolgenden Block. Keiner der Fälle erzeugt einen Fehler, und der Entschlüssler reicht heraus, was herauskam

PDFium Component schreibt beide Formate in demselben Objektdurchlauf, und die Bytes auf der Platte zeigen den Unterschied. Ein AESV3-String oder -Stream liegt als zufälliger 16-Byte-IV gefolgt von PKCS#7-gepolstertem Chiffretext. Ein AESV4-Wert liegt als 12-Byte-IV || Chiffretext || 16-Byte-Tag, ohne Padding und mit leerer zusätzlicher authentifizierter Daten, der Chiffretext ist also exakt so lang wie der Klartext, und jeder Wert wächst um 28 Bytes. Das Tag wird vollständig serialisiert. Auf der Leseseite berechnet DecryptAesGcmDocumentBytes das Tag für jeden String und Stream neu und stoppt bei der ersten Abweichung mit einem Fehler wie AESV4 stream authentication failed; teilweise entschlüsselte Ausgabe gibt es nicht zurück

Diagramm: die AES-256-CBC- und AESV4-GCM-Manipulationsbehandlung beim Schreiben verschlüsselter PDFs aus Delphi mit PDFiumPas
Ein gekipptes Bit unter AES-256-CBC entschlüsselt zu verändertem Klartext, während jeder AESV4-GCM-Wert ein 16-Byte-Tag trägt, das dasselbe Manipulieren zu einem harten Fehler bei der Entschlüsselung macht

Die IVs sind nicht pro Objekt zufällig. Der Writer zieht einmal pro Dokument ein zufälliges 64-Bit-Präfix und hängt einen 32-Bit-Big-Endian-Zähler an, den jeder Literal-String, Hex-String, Stream-Dictionary-String und Stream-Body teilt. GCM bricht katastrophal, wenn derselbe IV auch nur zweimal unter einem Schlüssel verwendet wird, und ein Zähler macht Eindeutigkeit leicht beweisbar, wo unabhängige Zufallsziehungen sie nur wahrscheinlich machen. Brauchte ein Dokument je mehr als etwa 4,29 Milliarden verschlüsselte Werte, wirft der Writer AESV4 IV counter exhausted, statt umzulaufen

Eine R7-Datei mit PDF-MAC aus Delphi schreiben

TPdf.SaveAsEncrypted nimmt einen TPdfEncryptOptions-Record aus der Unit FPdfEncrypt. Revision auf erR7 wählt AESV4-GCM, EnableIntegrityProtection ergänzt den eigenständigen PDF-MAC. Die Revision jedes Mal explizit setzen: TPdfEncryptOptions.Default liefert erR5, alle Berechtigungen erlaubt, Metadaten verschlüsselt und Integritätsschutz aus, Code, der die Zeile vergisst, bekommt also das älteste der drei Schemata

uses
  System.SysUtils, PDFium, FPdfEncrypt;

procedure WriteProtectedReport;
var
  Pdf: TPdf;
  Opts: TPdfEncryptOptions;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := 'quarterly-report.pdf';
    Pdf.Active := True;
    if not Pdf.Active then
      raise Exception.Create('Could not open quarterly-report.pdf');

    Opts := TPdfEncryptOptions.Default;       // hier Revision = erR5
    Opts.UserPassword := 'open-secret';
    Opts.OwnerPassword := 'admin-secret';
    Opts.EncryptMetadata := True;
    // ISO 32000-1 Tabelle 22: Bit 3 (Drucken) und Bit 12 (hochwertiger Druck) löschen
    Opts.Permissions := Opts.Permissions and not Cardinal($0004 or $0800);
    Opts.Revision := erR7;                    // ISO/TS 32003 AESV4-GCM
    Opts.EnableIntegrityProtection := True;   // eigenständiger ISO/TS-32004-MAC

    if not Pdf.SaveAsEncrypted('quarterly-report.enc.pdf', Opts) then
      raise Exception.Create('Encrypted save failed');
  finally
    Pdf.Free;
  end;
end;

Die Ausgabe ist eine neu gebaute Datei mit vollständiger klassischer Querverweistabelle und einem %PDF-2.0-Header. Das Encrypt-Dictionary liest sich als /V 6 /R 7 mit /CFM /AESV4 im Standard-Crypt-Filter, und der Katalog bekommt einen /Extensions-Eintrag, dessen /ISO_-Array /ExtensionLevel 32003 /ExtensionRevision (:2023) deklariert. Mit eingeschaltetem Integritätsschutz deklariert dasselbe Array zusätzlich /ExtensionLevel 32004 /ExtensionRevision (:2024), das Encrypt-Dictionary trägt ein 32-Byte-/KDFSalt, und der Trailer endet mit einem /AuthCode-Dictionary. Eine weitere Änderung sieht man beim Zurücklesen der Berechtigungen: Der Writer löscht Bit 13 ($1000) sowohl in /P als auch in der verschlüsselten /Perms-Kopie, wann immer der MAC aktiv ist, der übergebene Wert läuft auf diesem Bit also nicht unverändert durch

Warum ein MAC über die ganze Datei zusätzlich zu Tags pro Wert?

ISO/TS 32004 ergänzt einen MAC über die ganze Datei, denn ein Tag an jedem Wert sagt weiterhin nichts darüber, wie die Werte angeordnet sind. GCM-Tags schützen die Werte, und die Dateistruktur besteht nicht aus verschlüsselten Werten. Die Querverweistabelle, die Objektnummern, der Trailer und die Dictionary-Schlüssel bleiben alle im Klartext. Wer das Passwort nicht hat, kann keinen einzigen String oder Stream fälschen, aber nichts in der Chiffre hindert daran, den Seitenbaum auf eine andere Objektmenge zu richten, ein Objekt fallen zu lassen oder einen verschlüsselten Objektblock einzuspleißen, der aus einer früheren Revision derselben Datei kopiert wurde und unter demselben Schlüssel verschlüsselt war

Das ISO/TS-32004-Token deckt diese Schicht ab. Der Writer legt das Token in /AuthCode << /MACLocation /Standalone /ByteRange [0 L1 S L2] /MAC <...> >> ab, wobei der Byte-Bereich jedes Byte der Datei umfasst außer dem Hex-String, der das Token selbst hält, und der zweite Bereich muss exakt am physischen Dateiende enden. Der Digest über diese Bytes ist SHA-256. Die Schlüsselbehandlung folgt der Schichtung der Spezifikation: HKDF-SHA256 leitet aus dem Dateiverschlüsselungsschlüssel und /KDFSalt einen Schlüsselverschlüsselungsschlüssel ab, ein zufälliger 256-Bit-MAC-Schlüssel wird mit AES Key Wrap verpackt, und das Token selbst ist eine CMS-AuthenticatedData-Struktur mit HMAC-SHA256. Ein Reader braucht also das Benutzer- oder Owner-Passwort, um es zu prüfen, und wer keins von beiden hat, kann kein Token erzeugen, das verifiziert

Der MAC ist nicht an R7 gebunden. EnableIntegrityProtection funktioniert auch mit erR5 und erR6, und diese Dateien bekommen ebenfalls den %PDF-2.0-Header und den 32004-Extension-Eintrag. Bei neuer R7-Ausgabe einschalten: Es kostet ein Trailer-Dictionary, einen weiteren Katalog-Extension-Eintrag und ein 32-Byte-Salz, und der Entschlüsselungspfad verifiziert es automatisch, wann immer es vorhanden ist

Eine AESV4-Datei zurücklesen und das Token prüfen

Eine R7-Datei geht nicht den normalen Passwort-und-Laden-Weg, und der Grund liegt in der Engine darunter. PDFiums eingebauter Standard-Security-Handler kennt AESV2 und AESV3 und mappt beide auf CBC; einen GCM-Pfad hat er nicht. PDFium Component entschlüsselt AESV4 daher in Pascal mit DecryptAesGcmDocumentBytes, das das Passwort und /Perms prüft, den eigenständigen MAC verifiziert, falls einer vorhanden ist, jeden String und Stream authentifiziert und ein nacktes PDF zurückgibt, das TPdf.LoadDocument öffnen kann

Diese nackten Kopie hat die Einträge /Encrypt und /AuthCode entfernt und jeden Offset neu geschrieben. Die MAC-Prüfung gehört also auf die Original-Bytes, vor der Entschlüsselung. Pdf.ValidatePdfMac nach dem Laden der entschlüsselten Kopie aufzurufen liefert pmvsNotPresent, denn die Kopie hat tatsächlich kein Token. ValidateEncryptedDocumentMac in FPdfEncrypt nimmt die rohen Datei-Bytes und ein Passwort und liefert dasselbe TPdfMacValidationResult

uses
  System.SysUtils, System.IOUtils, PDFium, FPdfEncrypt;

procedure OpenAesV4Report(const FileName: string; const Password: AnsiString);
var
  Raw, Plain: TBytes;
  Mac: TPdfMacValidationResult;
  ErrorText: string;
  Pdf: TPdf;
begin
  Raw := TFile.ReadAllBytes(FileName);

  // Das Token auf den Bytes prüfen, wie sie auf der Platte liegen
  Mac := ValidateEncryptedDocumentMac(Raw, Password);
  case Mac.Status of
    pmvsValid: ;
    pmvsNotPresent:
      LogWarning(FileName, Mac.MessageText);   // eigene Logging-Routine
    pmvsInvalid:
      raise Exception.Create('Rejected: ' + Mac.MessageText);
    pmvsUnsupported:
      raise Exception.Create('Needs manual review: ' + Mac.MessageText);
  end;

  if not DecryptAesGcmDocumentBytes(Raw, Password, Plain, ErrorText) then
    raise Exception.Create('AESV4 decryption failed: ' + ErrorText);

  Pdf := TPdf.Create(nil);
  try
    Pdf.LoadDocument(Plain);
    // Pdf.ValidatePdfMac würde hier pmvsNotPresent melden: die
    // entschlüsselte Kopie trägt kein /AuthCode
    ProcessDocument(Pdf);                       // eigene Verarbeitung
  finally
    Pdf.Free;
  end;
end;

Bei R5- und R6-Dateien entschlüsselt die Engine nativ, der Aufruf auf Komponentenebene funktioniert also. Wie üblich mit Password und FileName laden, dann TPdf.ValidatePdfMac aufrufen. Es liest die Original-Bytes, aus denen das Dokument geladen wurde, ob Datei, Buffer oder eigener Stream. Ist die Quelle ein Progressive Download, der noch nicht vollständig angekommen ist, liefert es pmvsUnsupported mit der Meldung, dass die vollständige Quelle nötig ist

var
  Pdf: TPdf;
  Mac: TPdfMacValidationResult;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.Password := 'open-secret';
    Pdf.FileName := 'contract.r6.pdf';         // geschrieben mit erR6 + MAC
    Pdf.Active := True;
    if not Pdf.Active then
      raise Exception.Create('Wrong password or unreadable file');

    Mac := Pdf.ValidatePdfMac('open-secret');
    if not Mac.IsValid then
      Writeln('MAC check: ', Mac.MessageText);
  finally
    Pdf.Free;
  end;
end;

Vier Statuswerte, vier Antworten

TPdfMacValidationStatus auf einen Boolean zu reduzieren, wirft den Teil weg, der entscheidet, was als Nächstes zu tun ist. pmvsNotPresent heißt, der Trailer hat gar kein /AuthCode. ISO/TS 32004 stammt von 2024, und der MAC ist optional, die meisten verschlüsselten PDFs in einem bestehenden Archiv landen also wahrscheinlich hier, und sie in Quarantäne zu schicken würde das Archiv am ersten Tag leeren. Loggen und weiter

pmvsInvalid deckt mehr als Manipulation ab. Der Status kommt zurück für ein Token, das nicht verifiziert, einen Byte-Bereich, der vor dem Dateiende aufhört, einen Header, der nicht PDF 2.0 deklariert, einen fehlenden oder missgestalteten 32004-Extension-Eintrag und ein falsches Passwort, denn der Schlüssel, der das Token prüft, stammt aus dem Passwort. MessageText lesen, bevor man es einen Angriff nennt. Eine beim Upload abgeschnittene Datei und eine von jemandem bearbeitete Datei landen beide hier, und beide sollten die Verarbeitung stoppen

pmvsUnsupported ist enger. Die Komponente prüft eigenständige Tokens, die Form /MACLocation /Standalone; ein an eine Signatur angehängtes Token, das ISO/TS 32004 ebenfalls definiert, meldet diesen Status und ist ein Fall für einen menschlichen Blick, kein Alarm

Diagramm, das die vier ValidatePdfMac-Statuswerte routet, die beim Öffnen einer AESV4-verschlüsselten PDF durch eine Delphi-Anwendung zurückkommen
ValidatePdfMac routet seine vier Token-Zustände zu vier verschiedenen Antworten, und nur pmvsInvalid stoppt die Verarbeitung, während pmvsNotPresent Dateien beschreibt, die ohne PDF-MAC geschrieben wurden

R5, R6 oder R7 für das jeweilige Publikum wählen

TPdfEncryptionRevision bietet erR5, erR6 und erR7, und die Wahl ist eher eine Frage davon, wer die Datei öffnet, als eine kryptografische. R5 ist das ursprüngliche AES-256-Schema, als Erweiterung zu PDF 1.7 veröffentlicht, mit einem einzigen SHA-256-Durchlauf über das Passwort; ISO 32000-2 verwirft es. R6 ist die gehärtete Ableitung, standardisiert in ISO 32000-2, Algorithmus 2.B in §7.6.4.3, der über SHA-256, SHA-384 und SHA-512 iteriert. R7 übernimmt exakt die R6-Passwortableitung für /U, /O, /UE, /OE und /Perms und ändert nur, wie Strings und Streams verschlüsselt werden

Diagramm der R5-, R6- und R7-PDF-Verschlüsselungsrevisionen und ihrer Reader-Unterstützungsbereiche in PDFiumPas
R5 ist das älteste AES-256-Schema und wird in ISO 32000-2 verworfen, R6 ist der PDF-2.0-Standard-Handler, und R7 übernimmt die R6-Passwortableitung, während Strings und Streams auf AES-GCM wechseln

Ein Betrachter muss ISO/TS 32003 implementieren, um R7 überhaupt zu öffnen, und eine Engine, die nur AESV2 und AESV3 kennt, weist die Datei zurück. Wenn jeder Reader Software ist, die man selbst kontrolliert, etwa in einer internen Pipeline oder einem Akten-System, das ebenfalls diese Komponente nutzt, ist R7 mit dem MAC die stärkste verfügbare Kombination. Geht die Datei an Empfänger mit unbekannten Viewern, ist R6 die konservative Wahl: Es ist Teil von ISO 32000-2 selbst, und der MAC lässt sich trotzdem ergänzen. R5 gehört nur dorthin, wo ein bekannter Alt-Konsument es braucht, und diese Entscheidung verdient es, neben der Aufbewahrungsrichtlinie notiert zu werden

Die Berechtigungs-Flags ändern sich mit der Revision nicht. Die /P-Bits aus ISO 32000-1 Tabelle 22, die Drucken oder Kopieren untersagen, sind Bitten, die konforme Viewer beachten, und wer das Benutzerpasswort hält, hält bereits den entschlüsselten Inhalt. Die Verschlüsselung entscheidet, wer lesen kann; die Berechtigungen beschreiben, worum der Autor danach gebeten hat

An eine geschützte Datei anhängen und das Ergebnis prüfen

Ein eigenständiger MAC ist eine Aussage über jedes Byte bis zum Dateiende, ein danach angehängtes inkrementelles Update fällt also außerhalb des signierten Bereichs, und ein Werkzeug, das anhängt, ohne das Token neu zu berechnen, macht aus einer gültigen Datei eine pmvsInvalid. Das verschlüsselte inkrementelle Speichern der Komponente verifiziert das vorhandene Token vor dem Anhängen und berechnet dann Byte-Bereich und Token für das neue Dateiende neu. Die Regeln für weitere Revisionen an verschlüsselten Dokumenten, einschließlich der Frage, wie neue Objekte den vorhandenen Dateischlüssel wiederverwenden, stehen in inkrementellen Updates an verschlüsselten PDFs

Nach jedem Speichern die Ausgabe erneut öffnen und so prüfen, wie ein Empfänger es täte: ValidateEncryptedDocumentMac über die Bytes laufen lassen, sie entschlüsseln oder laden und bestätigen, dass der Header die erwartete Version deklariert, mit den Prüfungen aus exakter PDF-Versionskonformität. Eine breitere Empfangs-Checkliste für Dokumente, die man nicht selbst geschrieben hat, steht in Prüfen von PDF-Sicherheitsrisiken

Der AES-256-, GCM-, HKDF-, Key-Wrap- und CMS-Code hinter diesen Aufrufen ist in Pascal geschrieben und in die Komponente kompiliert, neben der eigenen Executable fährt also keine externe Krypto-DLL mit, und dieselben Units bauen unter Delphi und Lazarus. Options-Records, Statuswerte und der Rest der Verschlüsselungs-API sind auf der Produktseite PDFium Component für Delphi gelistet