Technisch artikel

PDF 2.0 AES-GCM-versleuteling in Delphi: ISO/TS 32003

Een met AES-256 versleutelde PDF-string met één omgegooide bit in de eerste 16 bytes — het deel dat de CBC-initialisatievector bevat — ontsleutelt nog steeds met het juiste wachtwoord. De klare tekst die terugkomt verschilt van het origineel in precies één bit, op dezelfde positie die was omgegooid. Zo werkt CBC nu eenmaal. De IV wordt in het eerste klare-tekstblok ge-XORd, dus wie het bestand kan bewerken, kan de eerste 16 bytes van elke versleutelde string sturen zonder de sleutel te kennen. ISO/TS 32003 antwoordt daarop met AES-256 in GCM-modus (crypt filter method AESV4, security handler revisie 7). Elke versleutelde waarde draagt een 16-byte-authenticatietag, en één veranderde byte laat de ontsleuteling ronduit falen

Wat GCM verandert ten opzichte van AESV3-CBC

GCM voegt authenticatie toe aan vertrouwelijkheid. AESV3, het AES-256-CBC-schema uit ISO 32000-2, houdt de content onleesbaar zonder het wachtwoord maar heeft geen enkele manier om wijziging op te merken. Een omgegooide bit in de IV verandert de overeenkomstige bit van het eerste klare-tekstblok. Een omgegooide bit ergens anders verminkt één blok van 16 bytes en gooit in het blok erna dezelfde bit om. Geen van beide gevallen geeft een foutmelding, en de ontsleutelaar geeft terug wat eruit kwam

PDFium Component schrijft beide formaten via dezelfde objectsweep, en de bytes op schijf laten het verschil zien. Een AESV3-string of -stream wordt opgeslagen als een willekeurige IV van 16 bytes gevolgd door PKCS#7-opgevulde cijfertekst. Een AESV4-waarde wordt opgeslagen als 12-byte IV || ciphertext || 16-byte tag, zonder opvulling en met lege additional authenticated data, dus de cijfertekst is exact zo lang als de klare tekst en elke waarde groeit met 28 bytes. De tag wordt volledig geserialiseerd. Aan de leeskant herberekent DecryptAesGcmDocumentBytes de tag voor elke string en stream en stopt bij de eerste mismatch met een fout als AESV4 stream authentication failed; hij geeft geen gedeeltelijk ontsleutelde uitvoer terug

Diagram dat het tampergedrag van AES-256-CBC en AESV4 GCM tegen elkaar afzet bij het schrijven van versleutelde PDF's vanuit Delphi met PDFiumPas
Een bitflip in AES-256-CBC ontsleutelt tot gewijzigde klare tekst, terwijl elke AESV4 GCM-waarde een tag van 16 bytes draagt die dezelfde manipulatie bij de ontsleuteling in een harde fout verandert

De IV's zijn niet willekeurig per object. De schrijver trekt één keer per document een willekeurige prefix van 64 bits en plakt daar een 32-bits big-endian-teller achter die elke literal string, hexadecimale string, streamdictionary-string en streambody deelt. GCM gaat eraan kapot als dezelfde IV ooit tweemaal onder één sleutel wordt gebruikt, en een teller maakt uniciteit bewijsbaar waar onafhankelijke willekeurige trekkingen die slechts waarschijnlijk maken. Heeft een document ooit meer dan circa 4,29 miljard versleutelde waarden nodig, dan geeft de schrijver AESV4 IV counter exhausted in plaats van terug naar nul te springen

Een R7-bestand met PDF MAC schrijven vanuit Delphi

TPdf.SaveAsEncrypted neemt een TPdfEncryptOptions-record uit de unit FPdfEncrypt. Revision op erR7 zetten kiest AESV4-GCM, en EnableIntegrityProtection zetten voegt de standalone PDF MAC toe. Zet de revisie elke keer expliciet: TPdfEncryptOptions.Default geeft erR5 terug, met alle permissies toegestaan, metadata versleuteld en integriteitsbescherming uit, dus code die die regel vergeet krijgt het oudste van de drie schema's

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 Tabel 22: wis bit 3 (printen) en bit 12 (printen in hoge kwaliteit)
    Opts.Permissions := Opts.Permissions and not Cardinal($0004 or $0800);
    Opts.Revision := erR7;                    // ISO/TS 32003 AESV4-GCM
    Opts.EnableIntegrityProtection := True;   // ISO/TS 32004 standalone MAC

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

De uitvoer is een herbouwd bestand met een volledige klassieke cross-reference-tabel en een %PDF-2.0-header. Het Encrypt-dictionary toont /V 6 /R 7 met /CFM /AESV4 in de standaard crypt filter, en de catalog krijgt een /Extensions-entry waarvan de /ISO_-array /ExtensionLevel 32003 /ExtensionRevision (:2023) declareert. Met integriteitsbescherming aan declareert dezelfde array ook /ExtensionLevel 32004 /ExtensionRevision (:2024), draagt het Encrypt-dictionary een /KDFSalt van 32 bytes, en eindigt de trailer met een /AuthCode-dictionary. Nog één verandering is zichtbaar als u de permissies terugleest: de schrijver wist bit 13 ($1000) in zowel /P als de versleutelde /Perms-kopie zodra de MAC aan staat, dus de waarde die u doorgaf komt op die bit niet ongewijzigd terug

Waarom een MAC over het hele bestand náást tags per waarde?

ISO/TS 32004 voegt een MAC over het hele bestand toe, want een tag op elke waarde zegt nog steeds niets over hoe de waarden gerangschikt zijn. GCM-tags beschermen de waarden, en de bestandsstructuur is niet uit versleutelde waarden opgebouwd. De cross-reference-tabel, objectnummers, de trailer en de dictionary-sleutels blijven allemaal in klare tekst. Iemand zonder het wachtwoord kan geen enkele string of stream vervalsen, maar niets in het cijfer houdt hem tegen om de paginaboom naar een andere set objecten te laten wijzen, een object te laten vallen, of een versleuteld object in te plakken dat uit een eerdere revisie van hetzelfde bestand is gekopieerd en onder dezelfde sleutel was versleuteld

Het ISO/TS 32004-token dekt die laag. De schrijver zet het token in /AuthCode << /MACLocation /Standalone /ByteRange [0 L1 S L2] /MAC <...> >>, waarbij het bytebereik elke byte van het bestand omvat behalve de hexadecimale string die het token zelf bevat, en het tweede bereik moet exact eindigen op het fysieke einde van het bestand. De digest over die bytes is SHA-256. Sleutelbehandeling volgt de gelaagdheid van de specificatie: HKDF-SHA256 leidt een sleutelversleutelingssleutel af uit de bestandsversleutelingssleutel en /KDFSalt, een willekeurige MAC-sleutel van 256 bits wordt verpakt met AES Key Wrap, en het token zelf is een CMS AuthenticatedData-structuur met HMAC-SHA256. Een lezer heeft dus het gebruikers- of eigenaarswachtwoord nodig om hem te controleren, en wie geen van beide heeft, kan geen token produceren dat verifieert

De MAC is niet aan R7 gebonden. EnableIntegrityProtection werkt ook met erR5 en erR6, en die bestanden krijgen ook de %PDF-2.0-header en de 32004-extensie-entry. Zet haar aan voor nieuwe R7-uitvoer: ze kost een trailerdictionary, één catalogus-extensie-entry extra en een salt van 32 bytes, en het ontsleutelpad verifieert haar automatisch zodra ze aanwezig is

Een AESV4-bestand teruglezen en het token controleren

Een R7-bestand volgt niet de normale wachtwoord-en-laden-route, en de reden zit in de engine eronder. PDFiums ingebouwde standard security handler herkent AESV2 en AESV3 en mapt beide op CBC; een GCM-pad heeft hij niet. PDFium Component ontsleutelt AESV4 daarom in Pascal met DecryptAesGcmDocumentBytes, die het wachtwoord en /Perms controleert, de standalone MAC verifieert als die er is, elke string en stream authenticeert, en een kale PDF teruggeeft die TPdf.LoadDocument kan openen

Die kale kopie heeft de entries /Encrypt en /AuthCode laten verwijderen en elke offset herschreven. Het controleren van de MAC hoort dus bij de originele bytes, vóór de ontsleuteling. Pdf.ValidatePdfMac aanroepen na het laden van de ontsleutelde kopie geeft pmvsNotPresent, want de kopie heeft echt geen token. ValidateEncryptedDocumentMac in FPdfEncrypt neemt de rauwe bestandsbytes en een wachtwoord en geeft dezelfde TPdfMacValidationResult terug

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);

  // Controleer het token op de bytes zoals ze op schijf staan
  Mac := ValidateEncryptedDocumentMac(Raw, Password);
  case Mac.Status of
    pmvsValid: ;
    pmvsNotPresent:
      LogWarning(FileName, Mac.MessageText);   // uw eigen loggingroutine
    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 zou hier pmvsNotPresent melden: de
    // ontsleutelde kopie draagt geen /AuthCode
    ProcessDocument(Pdf);                       // eigen verwerking
  finally
    Pdf.Free;
  end;
end;

Voor R5- en R6-bestanden ontsleutelt de engine native, dus de aanroep op componentniveau werkt. Laad zoals gebruikelijk met Password en FileName en roep dan TPdf.ValidatePdfMac aan. Hij leest de originele bytes waarvan het document is geladen, of dat nu een bestand, een buffer of een eigen stream was. Is de bron een progressive download die nog niet klaar is met binnenkomen, dan geeft hij pmvsUnsupported terug met de melding dat de complete bron vereist is

var
  Pdf: TPdf;
  Mac: TPdfMacValidationResult;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.Password := 'open-secret';
    Pdf.FileName := 'contract.r6.pdf';         // geschreven met 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 statussen, vier reacties

TPdfMacValidationStatus terugbrengen tot een booleaanse waarde gooit precies dat deel weg dat bepaalt wat er verder moet gebeuren. pmvsNotPresent betekent dat de trailer helemaal geen /AuthCode heeft. ISO/TS 32004 stamt uit 2024 en de MAC is optioneel, dus de meeste versleutelde PDF's in een bestaand archief zullen hier waarschijnlijk uitkomen, en quarantaine zou het archief op dag één al leegmaken. Log het en ga verder

pmvsInvalid dekt meer dan manipulatie. De status komt terug voor een token dat niet verifieert, een bytebereik dat vóór het einde van het bestand stopt, een header die geen PDF 2.0 declareert, een ontbrekende of misvormde 32004-extensie-entry, en een verkeerd wachtwoord, want de sleutel die het token controleert komt uit het wachtwoord. Lees MessageText voordat u het een aanval noemt. Een bestand dat tijdens de upload is afgebroken en een bestand dat iemand heeft bewerkt, komen hier beiden uit, en beiden moeten de verwerking stoppen

pmvsUnsupported is smaller. De component controleert standalone tokens, de vorm /MACLocation /Standalone; een token dat aan een handtekening hangt, dat ISO/TS 32004 ook definieert, meldt deze status en is een geval voor een mens om naar te kijken in plaats van een alarm

Diagram dat de vier ValidatePdfMac-statuswaarden routeert die terugkomen wanneer een Delphi-applicatie een met AESV4 versleutelde PDF opent
ValidatePdfMac leidt zijn vier tokenstatussen naar vier verschillende reacties, en alleen pmvsInvalid stopt de verwerking, terwijl pmvsNotPresent bestanden beschrijft die zonder PDF MAC zijn geschreven

R5, R6 of R7 kiezen voor een gegeven doelgroep

TPdfEncryptionRevision biedt erR5, erR6 en erR7 aan, en de keuze gaat meer over wie het bestand opent dan over cryptografie. R5 is het oorspronkelijke AES-256-schema, gepubliceerd als extensie op PDF 1.7, met één SHA-256-pas over het wachtwoord; ISO 32000-2 ontraadt het. R6 is de geharde afleiding die in ISO 32000-2 is gestandaardiseerd, algoritme 2.B in §7.6.4.3, die itereert over SHA-256, SHA-384 en SHA-512. R7 houdt exact de R6-wachtwoordafleiding aan voor /U, /O, /UE, /OE en /Perms en verandert alleen hoe strings en streams worden versleuteld

Diagram van de R5-, R6- en R7-PDF-versleutelingsrevisies en hun lezersondersteuningsbereiken in PDFiumPas
R5 is het oudste AES-256-schema en is ontraden in ISO 32000-2, R6 is de standaardhandler van PDF 2.0, en R7 houdt de R6-wachtwoordafleiding aan terwijl strings en streams naar AES-GCM gaan

Een viewer moet ISO/TS 32003 implementeren om R7 überhaupt te openen, en een engine die alleen AESV2 en AESV3 kent, wijst het bestand af. Zijn alle lezers software die u zelf beheert, zoals in een interne pijplijn of een archiefsysteem dat ook deze component gebruikt, dan is R7 met de MAC de sterkste combinatie die er is. Gaat het bestand naar ontvangers met onbekende viewers, dan is R6 de conservatieve keuze: hij maakt deel uit van ISO 32000-2 zelf, en de MAC kunt u nog steeds toevoegen. R5 hoort alleen daar waar een bekende legacy-consument hem nodig heeft, en die beslissing verdient het om naast het retentiebeleid genoteerd te worden

Permissievlaggen veranderen niet met de revisie. De /P-bits uit ISO 32000-1 Tabel 22 die printen of kopiëren verbieden zijn verzoeken die conforme viewers opvolgen, en wie het gebruikerswachtwoord heeft, heeft de ontsleutelde inhoud al. Versleuteling bepaalt wie kan lezen; permissies beschrijven wat de auteur daarna heeft gevraagd

Toevoegen aan een beveiligd bestand en het resultaat controleren

Een standalone MAC is een uitspraak over elke byte tot aan het einde van het bestand, dus elke incrementele update die daarna wordt toegevoegd valt buiten het ondertekende bereik, en een tool die toevoegt zonder het token te herberekenen verandert een geldig bestand in een pmvsInvalid bestand. De versleutelde incrementele opslag van de component verifieert het bestaande token vóór het toevoegen en herberekent daarna het bytebereik en het token voor het nieuwe einde van het bestand. De regels voor het toevoegen van revisies aan versleutelde documenten, inclusief hoe nieuwe objecten de bestaande bestandssleutel hergebruiken, staan in incrementele updates op versleutelde PDF's

Open na elke opslag de uitvoer opnieuw en controleer haar zoals een ontvanger dat zou doen: draai ValidateEncryptedDocumentMac op de bytes, ontsleutel of laad ze, en bevestig dat de header de versie declareert die u verwacht, met de controles uit exacte PDF-versieconformiteit. Een bredere intakechecklist voor documenten die u niet zelf heeft geschreven staat in PDF-beveiligingsrisico's auditen

De AES-256-, GCM-, HKDF-, key-wrap- en CMS-code achter deze aanroepen is in Pascal geschreven en in de component gecompileerd, dus er wordt geen externe crypto-DLL naast uw executable meegeleverd, en dezelfde units bouwen onder Delphi en Lazarus. Optierecords, statuswaarden en de rest van de versleutelings-API staan vermeld op de productpagina van PDFium Component for Delphi