Technisch artikel

Signature wrapping: ByteRange-gap en tweede handtekening

Een ondertekende PDF kan een vervalste pagina meedragen, de CMS-digestcheck doorstaan en melden dat zijn handtekening het hele document dekt, allemaal tegelijk. Elke ondertekende byte blijft exact zoals de ondertekenaar hem achterliet, de /ByteRange begint nog steeds bij 0 en eindigt op de bestandsgrootte, en de extra objecten zitten in het enige stuk van het bestand dat een PDF-handtekening bewust buiten de digest laat: de ruimte die gereserveerd is voor de hexstring van /Contents

Dat stuk is groter dan de meeste mensen zich voorstellen. 8.192 bytes reserveren voor de CMS-container zet 16.384 hexcijfers op schijf, en wat het echte deel van de handtekening ervan ongebruikt laat wordt opgevuld met het cijfer 0. Een verificateur die alleen vraagt of het gat tussen de twee bereiken niet-leeg is, kijkt nooit naar wat het gat bevat. Dezelfde layoutvraag komt uit de tegenovergestelde richting terug wanneer een contract een countersignature nodig heeft: de handtekening van de goedkeurder moet worden toegevoegd zonder ook maar één byte aan te raken die de leverancier ondertekende, en zijn placeholder moet precies in de vorm belanden die een strenge verificateur accepteert

Wat de ByteRange-gap moet bevatten

De gap moet de volledige /Contents-waarde bevatten en niets anders. ISO 32000-1 §12.8.3.3 zegt dat de hexstring, met zijn <- en >-scheidingstekens, precies in de ruimte tussen de twee bytebereiken past, en ISO 32000-2 §12.8.1 neemt dezelfde regel mee. Table 252 en de PAdES-documenten formuleren het losser: alleen dat de digest de Contents-waarde uitsluit. Snel gelezen klinkt dat als "sluit de hexcijfers uit", en een ondertekenaar die de losse lezing volgt hasht de twee haken samen met al het andere mee. Validators die de gap tegen de handtekeningwaarde vergelijken flaggen dan het bytebereik als ongeldig

HotPDF volgt de §12.8.3.3-formulering op beide ondertekenroutes. THotPDF.PreparePDFForSigning eindigt het eerste bereik direct vóór < en begint het tweede direct na >, en de streaming-voorbereiding binnen de CMS-ondertekenpijplijn berekent dezelfde offsets. De /ByteRange-placeholder in het signature-dictionary is een literal string met vaste breedte, dus de echte getallen inpatchen verschuift nooit een byte en de cross-reference-tabel blijft geldig. Elk van de vier waarden staat rechts uitgelijnd in een veld van tien tekens, daarom laat een zo ondertekend bestand /ByteRange [ zien gevolgd door reeksen spaties. We hebben voor die vulling een keer betaald bij het bouwen van een eigen standalone verificateur: de eerste versie splitte de vier getallen op enkele spaties en vond niets, en de /Contents-hex produceerde pas de echte CMS-bytes nadat de navolgende nulvulling was gestript

Twee bytes zijn genoeg om elk ondertekend bestand zelf te controleren, wie het ook produceerde. De byte op offset ByteRange[1] moet < zijn, en de byte op offset ByteRange[2] - 1 moet > zijn. De hulp hieronder is geen deel van de library; het is een dozijn regels die je in een audit-tool kunt droppen, gevoed met de ByteRange-array uit GetLoadedSignatureInfo

// Voorgestelde hulp voor je eigen auditcode, geen HotPDF-API
function GapIsSpecLayout(const FileName: string;
  const BR: array of Int64): Boolean;
var
  FS: TFileStream;
  B: AnsiChar;
begin
  Result := False;
  if Length(BR) <> 4 then Exit;
  FS := TFileStream.Create(FileName, fmOpenRead or fmShareDenyWrite);
  try
    FS.Position := BR[1];               // eerste byte van de gap
    if (FS.Read(B, 1) <> 1) or (B <> '<') then Exit;
    FS.Position := BR[2] - 1;           // laatste byte van de gap
    if (FS.Read(B, 1) <> 1) or (B <> '>') then Exit;
    Result := True;
  finally
    FS.Free;
  end;
end;

// Gebruik, na Pdf.LoadFromFile('Signed.pdf'):
//   if not GapIsSpecLayout('Signed.pdf',
//     Pdf.GetLoadedSignatureInfo(0).ByteRange) then
//     Writeln('De haken zitten binnen de ondertekende bereiken');

Voor het cryptografische deel verifieert OpenSSL de CMS onafhankelijk: plak de twee bereiken aan elkaar tot één bestand en geef dat mee als externe content, bijvoorbeeld openssl cms -verify -binary -inform DER -in contents.der -content signed-ranges.bin -noverify. Dat commando controleert de digest en de handtekening over precies de bytes die je hem geeft. Hij ziet de gap nooit, dus de controle van twee bytes hierboven blijft jouw werk

Anatomie van een correct gevulde PDF-signature-ByteRange in HotPDF: het eerste bereik dekt het bestand vanaf byte nul, de gap bevat de volledige /Contents-hexstring inclusief de kleiner-dan- en groter-dan-scheidingstekens, het tweede bereik dekt de trailer tot het einde, en twee checks van één byte op ByteRange[1] en ByteRange[2] - 1 bevestigen de layout op elk ondertekend bestand
De scheidingstekens zitten buiten de ondertekende bereiken, dus de digest dekt alleen de cijfers en de gap is byte voor byte te valideren

Waarom mist een niet-lege gap-controle signature wrapping?

Een niet-lege gap bewijst dat er iets buiten de digest is gelaten en zegt niets over wat. Dat is het hele aanvalsoppervlak. De /Contents-placeholder is gereserveerd met duizenden nulcijfers, en een echte CMS-container vult hem zelden. Een aanvaller sluit binnen die vulling de hexstring vroegtijdig af met een >, schrijft nieuwe objecten of een hele vervalste revisie in de rest van de gereserveerde ruimte en laat de bytebereiken onaangetast. De CMS verifieert nog steeds, want elke ondertekende byte is onveranderd. De bereiken lopen nog steeds van 0 tot de bestandsgrootte. Een verificateur die stopt bij "de gap is niet-leeg" meldt svValid met CoversWholeDocument op True, terwijl elke PDF-parser die het bestand opent de objecten volgt die in het niet-ondertekende gat zitten

THotPDF.VerifyLoadedSignatureEx behandelt de gap als data om te valideren. Zodra de CMS-check slaagt, leest de verificateur de gap, stript de scheidingstekens en accepteert alleen hexcijfers plus de vijf PDF-whitespace-bytes (tab, line feed, form feed, carriage return, spatie). De gedecodeerde cijfers moeten daarna byte voor byte gelijk zijn aan het eigen /Contents van het signature-dictionary. Een verdwaalde >, één binaire byte, of een gedecodeerde waarde die één byte te lang of te kort is, maakt van het resultaat svInvalidByteRange, en een gap groter dan 64 MiB ook. Dezelfde check draait in ValidateLoadedSignatureBatch; VerifyAllLoadedSignatures en VerifyLoadedSignatureWithTrust lopen via het pad voor één handtekening, dus ze erven hem ook

Eén layout wordt bewust doorgelaten: bestanden waarvan de ondertekenaar de haken binnen de ondertekende bereiken hield, zodat de gap alleen de cijfers bevat. Daar controleert de verificateur dat de byte net vóór de gap een < is en de byte net erna een >, en past dan dezelfde cijfer-en-whitespace-test toe. Die layout weigeren zou geen veiligheid opleveren, want de gap bevat nog steeds niets dan de handtekeningwaarde, en het zou gearchiveerde contracten laten falen die volkomen intact zijn. Hem accepteren is de juiste default

Hoe signature wrapping een los gecontroleerde PDF-ByteRange in Delphi exploiteert: de aanvaller sluit de hexstring vroegtijdig af binnen duizenden gereserveerde nulcijfers, schrijft een vervalste revisie in de niet-ondertekende gap zonder een gedekte byte aan te raken, en een niet-leeg-gap-check meldt nog steeds svValid met CoversWholeDocument true, wat HotPDF ertoe brengt de gap byte voor byte te valideren
Een niet-lege gap bewijst alleen dat er iets buiten de digest is gelaten, niet wat — de opgevulde hole is het hele aanvalsoppervlak
var
  Pdf: THotPDF;
  Info: THPDFSignatureInfo;
  Status: THPDFSignatureVerifyStatus;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.LoadFromFile('SignedTwice.pdf');
    for I := 0 to Pdf.GetLoadedSignatureFieldCount - 1 do
    begin
      Status := Pdf.VerifyLoadedSignatureEx(I, Info);
      case Status of
        svValid:
          if Info.CoversWholeDocument then
            Writeln(Info.FieldName, ': valid, covers the whole file')
          else
            Writeln(Info.FieldName, ': valid, ',
              Info.UnsignedTrailingBytes, ' bytes appended later');
        svInvalidByteRange:
          Writeln(Info.FieldName, ': ByteRange gap rejected (wrapping?)');
        svSourceUnavailable:
          Writeln('Loaded from a stream: use the TStream overload');
      else
        Writeln(Info.FieldName, ': failed, status ', Ord(Status));
      end;
    end;
  finally
    Pdf.Free;
  end;
end;

Zowel GetLoadedSignatureFieldCount als de index die aan VerifyLoadedSignatureEx wordt meegegeven telt signature-velden in form-field-volgorde, beginnend bij 0. In een ge-countersigned bestand komt de handtekening van de leverancier in de eerste tak terecht met CoversWholeDocument = False en een positieve UnsignedTrailingBytes: alles wat na hem werd toegevoegd, de revisie van de goedkeurder incluis. Als de basis van deze API nieuw voor je is, behandelt de gids voor het verifiëren van PDF-digitale handtekeningen met HotPDF de statuswaarden en het info-record dieper

Countersignen met AddLoadedSignedSignatureField

Een countersignature kost vier aanroepen: het ondertekende bestand openen met BeginIncrementalUpdate, het veld toevoegen met AddLoadedSignedSignatureField, de nieuwe revisie wegschrijven met SaveIncrementalUpdate, en daarna het voorbereide bestand ondertekenen met de class function THotPDF.SignPDFWithPFX. De paginaniveau-THPDFPage.AddSignedSignatureField is hier niet van toepassing, want CurrentPage is nil tijdens een incrementele update; het document is geladen, niet in opbouw. De loaded-document-methode maakt de widget op een bestaande pagina en hangt onder /V precies hetzelfde placeholder-signature-dictionary op dat het nieuwe-document-pad bouwt, dus beide ondertekenroutes zien identieke bytes. Voor de eerste handtekening zelf loopt het artikel over het maken van PAdES-digitale handtekeningen in Delphi de PFX-pijplijn door

var
  Pdf: THotPDF;
  FieldIndex: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.BeginIncrementalUpdate('Signed.pdf');
    // Pagina 0, widget-rechthoek in punten, 8192 bytes gereserveerd voor de CMS
    FieldIndex := Pdf.AddLoadedSignedSignatureField(0, 320, 60, 520, 120,
      'ApproverSignature', 8192, 'adbe.pkcs7.detached',
      'Approved for payment', 'Head office');
    if FieldIndex < 0 then
      raise Exception.Create('Page index out of range');
    Pdf.SaveIncrementalUpdate('Prepared.pdf');
  finally
    Pdf.Free;
  end;

  // Ondertekent de eerste ongevulde placeholder; geeft een exception bij PFX- of cryptofouten
  if not THotPDF.SignPDFWithPFX('Prepared.pdf', 'SignedTwice.pdf',
    'approver.pfx', 'pfx-password') then
    raise Exception.Create('Second signature failed');
end;

De parameterlijst is kort maar elke waarde heeft een zichtbaar effect. ContentsBytes is standaard 8192 en dimensioneert de gedecodeerde CMS-container; de placeholder op schijf bevat twee keer zoveel hexcijfers, met een ondergrens van 64 bytes. SubFilter is standaard adbe.pkcs7.detached, en Reason, Location en ContactName belanden als /Reason, /Location en /ContactInfo in het signature-dictionary, naast een /M-timestamp genomen toen het veld werd gemaakt. De teruggegaven waarde is de nieuwe veldindex, of -1 wanneer de pagina-index buiten bereik is. Een lege veldnaam of een rechthoek met nul breedte of hoogte geeft een exception voordat er iets wordt geschreven

Wat de toegevoegde revisie meedraagt, en wat ze met rust laat

AddLoadedSignedSignatureField is doelbewust stiller dan zijn broertjes. De andere AddLoaded*-veldmakers zetten /NeedAppearances true op de AcroForm, wat een viewer vraagt de veldweergaven te regenereren wanneer hij het bestand opent. Op een ondertekend document kan die regeneratie content herschrijven die de eerste ondertekenaar dekte. Daarom haalt de nieuwe methode de vlag weer weg wanneer het bronbestand hem niet al droeg, en een bestand dat met /NeedAppearances aankwam houdt hem exact zoals hij was. /SigFlags houdt zijn bestaande bits en krijgt er 3 bij, wat SignaturesExist (1) plus AppendOnly (2) is, uit ISO 32000-1 §12.7.2, Table 219

Laat MarkDirty voor de pagina met rust. In incrementele modus worden nieuw gemaakte objecten automatisch weggeschreven, en geladen objecten alleen wanneer iets ze markeert. De widget toevoegen aan de /Annots van de pagina en aan de AcroForm /Fields zet al wat indirecte objecten die arrays bezitten in de nieuwe revisie. Een expliciete paginamarkering sleept het page-dictionary mee zelfs wanneer zijn /Annots-array in een apart object woont, en revisieanalyse meldt dan een paginamodificatie in een revisie die niets anders had mogen bevatten dan een signature-veld

Het placeholder-dictionary schrijft /ByteRange vóór /Contents. Die volgorde doet ertoe als je het voorbereide bestand met eigen tools nabewerkt: PreparePDFForSigning vindt eerst de /ByteRange-sentinel en zoekt daarna vooruit naar de volgende /Contents <. Een dictionary met omgewisselde sleutels zou die vooruitzoektocht langs zijn eigen hexstroom heen sturen naar wat er hierna in het bestand komt

Als de eerste ondertekenaar een DocMDP- of FieldMDP-beperking oplegde, is SaveIncrementalUpdateAuthenticated de strengere manier om revisie 2 weg te schrijven. Hij bewaart naar een kandidaatbestand in dezelfde directory, authenticeert elke handtekening die een transform-policy draagt, evalueert alle revisies na elk van hen en publiceert de kandidaat pas wanneer elk beleid de wijziging toestaat. Op een onbeperkt contract doet de kale SaveIncrementalUpdate het werk met minder ceremonie

De HotPDF Delphi-werkwijze voor het countersignen van een al ondertekende PDF: BeginIncrementalUpdate opent het bestand, AddLoadedSignedSignatureField maakt de widget en reserveert de /Contents-placeholder, SaveIncrementalUpdate voegt een tweede revisie toe, en SignPDFWithPFX vult haar, waarbij de eerste handtekening geldig blijft met UnsignedTrailingBytes terwijl de nieuwe ByteRange het hele gegroeide bestand overspant
Eén placeholder per revisie, voorbereid en gepatcht door dezelfde serialisatie op beide ondertekenroutes — de nette layout die de strenge verificateur verwacht

De digest aan een externe ondertekenaar of HSM geven

Niets in de werkwijze verandert wanneer de CMS uit een smartcard, een HSM of een remote signing-service komt; alleen de laatste stap verandert. THotPDF.PreparePDFForSigning patcht de /ByteRange in de voorbereide bytes en geeft twee 0-based bereiken terug waarvan de gap de hele /Contents-string is, plus ContentsHexStart, de 1-based index van het eerste hexcijfer in de AnsiString, en ContentsHexLen. 0-based bestandsoffsets met 1-based stringindexen mengen is de klassieke off-by-one in deze stap. Het voorbeeld bevestigt beide scheidingstekenposities met een assert voordat het iets hasht

var
  Bytes, ToSign, CmsHex: AnsiString;
  R1Start, R1Len, R2Start, R2Len, HexStart, HexLen: Integer;
begin
  Bytes := LoadFileAsAnsiString('Prepared.pdf');   // je eigen hulp
  if not THotPDF.PreparePDFForSigning(Bytes, R1Start, R1Len,
    R2Start, R2Len, HexStart, HexLen) then
    raise Exception.Create('No signature placeholder found');

  // Voorgestelde sanity checks (eigen, geen library-aanroepen):
  // '<' beëindigt bereik 1, '>' zit net vóór bereik 2
  Assert(Bytes[R1Start + R1Len + 1] = '<');
  Assert(Bytes[R2Start] = '>');

  ToSign := Copy(Bytes, R1Start + 1, R1Len) + Copy(Bytes, R2Start + 1, R2Len);
  CmsHex := SignDetachedWithHsm(ToSign);           // je eigen CMS-ondertekenaar, hex DER
  if not THotPDF.InsertSignatureHexAt(Bytes, HexStart, HexLen, CmsHex) then
    raise Exception.Create('CMS does not fit the reserved space');
  SaveAnsiStringToFile(Bytes, 'SignedTwice.pdf');  // je eigen hulp
end;

Bereid precies één placeholder per revisie voor. PreparePDFForSigning patcht de eerste nog niet gepatchte /ByteRange-sentinel die hij vindt, en een tweede placeholder die in dezelfde revisie achterblijft zit binnen de bytes die de eerste handtekening dekt, dus hem later vullen breekt die handtekening. Voor het terugschrijven van de CMS is InsertSignatureHexAt met de teruggegaven offsets de aanroep om te gebruiken. InsertSignatureHex zoekt de eerste /Contents-string waarvan de cijfers allemaal nul zijn, wat werkt op een bestand met één lege placeholder; met offsets in de hand is er niets te zoeken en niets te verhaspelen. Een kortere CMS wordt aan het einde opgevuld met 0, vóór de afsluitende >. Een langere maakt dat InsertSignatureHexAt False teruggeeft zonder de bestandsbytes aan te raken

Wat bewijst de gap-check, en wat niet?

De gap-check dicht één specifiek gat. svValid betekent nog steeds byte-integriteit plus een handtekening die bij het in de CMS ingebedde certificaat past; of dat certificaat ketent naar een vertrouwensanker dat je accepteert, beantwoordt VerifyLoadedSignatureWithTrust, met jouw vertrouwensankers en intrekkingsbewijs. Zonder bronbytes komt er helemaal niets op svValid. VerifyLoadedSignatureEx leest ze uit het bestand waaruit het document is geladen en geeft svSourceUnavailable terug voor een uit een stream geladen document, waar de TStream-overload van VerifyLoadedSignature ze van jou krijgt

Voor de eerste handtekening in een ge-countersigned bestand is CoversWholeDocument terecht False. Of de toegevoegde revisie alleen een handtekening toevoegde of ook pagina's veranderde, is een vraag voor AnalyzeLoadedSignatureRevisions, uitgelegd in DocMDP, FieldMDP en revisieanalyse in HotPDF

De hakenlayout lekt ook door in de attached PDF MAC die ISO TS 32004 definieert (/MACLocation /AttachedToSig), waarvan de check offsets vergelijkt met de exacte posities van < en > in het bestand. HotPDF accepteert daar ook beide layouts. Een eigen thuisgebakken tool die haken-inclusief-offsets hardcodeert is meestal het eerste dat breekt wanneer hij een bestand tegenkomt dat volgens de §12.8.3.3-layout is ondertekend, en de helper van twee bytes uit de eerste sectie over de output van je eigen tool draaien kost een minuut

De meeste handtekeningenproblemen in dit gebied beginnen wanneer de tool die ondertekent, de tool die countersignt en de tool die auditeert het oneens zijn over waar de haken horen. HotPDF, de native PDF-component voor Delphi en C++Builder schrijft de §12.8.3.3-layout op elke ondertekenroute, controleert de gap byte voor byte op elk verificatiepad en voegt countersignatures toe als nette incrementele revisies vanuit één API