Articolo tecnico

Signature wrapping PDF: gap del ByteRange e seconde firme

Un PDF firmato può portare una pagina contraffatta, passare un controllo di digest CMS e riferire che la sua firma copre l'intero documento, tutto insieme. Ogni byte firmato resta esattamente come il firmatario l'ha lasciato, il /ByteRange parte ancora da 0 e arriva alla dimensione del file, e gli oggetti extra stanno nell'unico tratto del file che una firma PDF lascia deliberatamente fuori dal digest: lo spazio riservato alla stringa esadecimale /Contents

Quel tratto è più grande di come la maggior parte della gente se lo immagina. Riservare 8.192 byte al contenitore CMS mette 16.384 cifre esadecimali su disco, e la parte di loro che la firma reale non usa viene riempita con la cifra 0. Un verificatore che chiede solo se il varco tra i due range è non vuoto non guarda mai cosa il varco contiene. La stessa domanda di layout ricompare dalla direzione opposta quando un contratto vuole una controfirma: la firma dell'approvatore deve essere appesa senza toccare un solo byte che il fornitore ha firmato, e il suo segnaposto deve finire esattamente nella forma che un verificatore severo accetta

Cosa il gap del ByteRange deve contenere

Il varco deve contenere il valore /Contents completo e nient'altro. ISO 32000-1 §12.8.3.3 dice che la stringa esadecimale, con i suoi delimitatori < e >, sta esattamente nello spazio tra i due byte range, e ISO 32000-2 §12.8.1 porta avanti la stessa regola. La Table 252 e i documenti PAdES lo enunciano più alla larga, dicendo solo che il digest esclude il valore Contents. Letto in fretta, sembra "escludi le cifre esadecimali", e un firmatore che segue la lettura larga fa l'hash delle due parentesi angolari insieme a tutto il resto. I validatori che confrontano il varco col valore della firma segnalano allora il byte range come invalido

HotPDF segue la formulazione del §12.8.3.3 su entrambi i suoi percorsi di firma. THotPDF.PreparePDFForSigning chiude il primo range immediatamente prima di < e apre il secondo immediatamente dopo >, e la preparazione in streaming dentro la pipeline di firma CMS calcola gli stessi offset. Il segnaposto /ByteRange nel dizionario di firma è una stringa literal a larghezza fissa, quindi appuntarci i numeri veri non sposta mai un byte e la cross-reference table resta valida. Ognuno dei quattro valori è allineato a destra in un campo di dieci caratteri, per cui un file firmato così mostra /ByteRange [ seguito da file di spazi. Abbiamo pagato quel padding una volta guidando un verificatore standalone nostro: la prima versione divideva i quattro numeri sui singoli spazi e non trovava niente, e l'esadecimale /Contents produceva i veri byte del CMS solo dopo che il suo padding a zero in coda era stato tolto

Due byte bastano per controllare voi stessi qualunque file firmato, chiunque l'abbia prodotto. Il byte all'offset ByteRange[1] dev'essere <, e il byte all'offset ByteRange[2] - 1 dev'essere >. L'helper qui sotto non è parte della libreria; è una dozzina di righe da buttare dentro uno strumento di audit, nutrita con l'array ByteRange da GetLoadedSignatureInfo

// Helper suggerito per il vostro codice di audit, non una API HotPDF
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];               // primo byte del varco
    if (FS.Read(B, 1) <> 1) or (B <> '<') then Exit;
    FS.Position := BR[2] - 1;           // ultimo byte del varco
    if (FS.Read(B, 1) <> 1) or (B <> '>') then Exit;
    Result := True;
  finally
    FS.Free;
  end;
end;

// Uso, dopo Pdf.LoadFromFile('Signed.pdf'):
//   if not GapIsSpecLayout('Signed.pdf',
//     Pdf.GetLoadedSignatureInfo(0).ByteRange) then
//     Writeln('Le parentesi stanno dentro i range firmati');

Per la metà crittografica, OpenSSL verifica il CMS indipendentemente: concatenate i due range in un solo file e passatelo come contenuto esterno, per esempio openssl cms -verify -binary -inform DER -in contents.der -content signed-ranges.bin -noverify. Quel comando controlla il digest e la firma esattamente sui byte che gli passate. Non vede mai il varco, quindi il controllo a due byte qui sopra resta compito vostro

| Anatomia di un ByteRange di firma PDF correttamente riempito in HotPDF: il primo range copre il file dal byte zero, il varco contiene la stringa esadecimale /Contents completa con i delimitatori minore e maggiore, il secondo range copre il trailer fino alla fine, e due controlli di un byte a ByteRange[1] e ByteRange[2] - 1 confermano il layout su qualunque file firmato
I delimitatori stanno fuori dai range firmati, quindi il digest copre solo le cifre e il varco si può validare byte per byte

Perché un controllo sul gap non vuoto si lascia sfuggire il signature wrapping?

Un varco non vuoto dimostra che qualcosa è stato lasciato fuori dal digest e non dice niente sul cosa. Quella è l'intera superficie di attacco. Il segnaposto /Contents è riservato con migliaia di cifre zero, e un contenitore CMS reale lo riempie raramente. Un attaccante chiude in anticipo la stringa esadecimale dentro quel padding con un >, scrive nuovi oggetti o un'intera revisione contraffatta nel resto dello spazio riservato, e lascia i byte range intatti. Il CMS verifica ancora, perché ogni byte firmato è invariato. I range corrono ancora da 0 alla dimensione del file. Un verificatore che si fermi a "il varco è non vuoto" riporta svValid con CoversWholeDocument a True, mentre qualunque parser PDF che apre il file segue gli oggetti che stanno nel buco non firmato

THotPDF.VerifyLoadedSignatureEx tratta il varco come dati da validare. Una volta che il controllo CMS passa, il verificatore legge il varco, toglie i delimitatori e accetta solo cifre esadecimali più i cinque byte di whitespace PDF (tab, line feed, form feed, carriage return, spazio). Le cifre decodificate devono poi eguagliare byte per byte il /Contents del dizionario di firma stesso. Una > di troppo, un byte binario, o un valore decodificato un byte troppo lungo o troppo corto volge il risultato in svInvalidByteRange, e così fa un varco più grande di 64 MiB. Lo stesso controllo gira in ValidateLoadedSignatureBatch; VerifyAllLoadedSignatures e VerifyLoadedSignatureWithTrust passano per il percorso a firma singola, quindi lo ereditano anche loro

Un layout viene deliberatamente lasciato passare: i file il cui firmatario ha tenuto le parentesi dentro i range firmati, così il varco contiene solo le cifre. Per quelli, il verificatore conferma che il byte subito prima del varco è < e il byte subito dopo è >, poi applica lo stesso test cifre-e-whitespace. Rifiutare quel layout non comprerebbe nessuna sicurezza, dato che il varco contiene comunque nient'altro che il valore della firma, e farebbe fallire contratti archiviati perfettamente intatti. Accettarlo è il default giusto

Come il signature wrapping sfrutta un ByteRange PDF vagamente controllato in Delphi: l'attaccante chiude in anticipo la stringa esadecimale dentro migliaia di cifri zero riservati, scrive una revisione contraffatta nel gap non firmato senza toccare alcun byte coperto, e il vecchio controllo HotPDF riportava svValid con CoversWholeDocument true finché la v2.759.0 non ha iniziato a validare il gap byte per byte
Un gap non vuoto dimostra solo che qualcosa è stato lasciato fuori dal digest, non cosa — il buco riempito di padding è tutta la superficie d'attacco
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;

Sia GetLoadedSignatureFieldCount che l'indice passato a VerifyLoadedSignatureEx contano i campi firma in ordine di form-field, partendo da 0. In un file controfirmato la firma del fornitore atterra nel primo ramo con CoversWholeDocument = False e un UnsignedTrailingBytes positivo: tutto ciò che è stato appeso dopo di lei, revisione dell'approvatore compresa. Se le basi di questa API sono nuove per voi, la guida alla verifica delle firme digitali PDF con HotPDF copre i valori di stato e il record info più a fondo

Controfirmare con AddLoadedSignedSignatureField

Una controfirma prende quattro chiamate: aprire il file firmato con BeginIncrementalUpdate, aggiungere il campo con AddLoadedSignedSignatureField, scrivere la nuova revisione con SaveIncrementalUpdate, poi firmare il file preparato con la class function THotPDF.SignPDFWithPFX. La THPDFPage.AddSignedSignatureField a livello pagina non si applica qui, perché CurrentPage è nil durante un aggiornamento incrementale; il documento è caricato, non in fase di layout. Il metodo su documento caricato crea il widget su una pagina esistente e appende sotto /V lo stesso dizionario di firma segnaposto che il percorso a documento nuovo costruisce, quindi entrambi i percorsi di firma vedono byte identici. Per la prima firma in sé, l'articolo su come creare firme digitali PAdES in Delphi attraversa la pipeline PFX

var
  Pdf: THotPDF;
  FieldIndex: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.BeginIncrementalUpdate('Signed.pdf');
    // Pagina 0, rettangolo del widget in punti, 8192 byte riservati al 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;

  // Firma il primo segnaposto non riempito; solleva su errori PFX o crittografici
  if not THotPDF.SignPDFWithPFX('Prepared.pdf', 'SignedTwice.pdf',
    'approver.pfx', 'pfx-password') then
    raise Exception.Create('Second signature failed');
end;

La lista dei parametri è corta ma ogni valore ha un effetto visibile. ContentsBytes fa default a 8192 e dimensiona il contenitore CMS decodificato; il segnaposto su disco contiene il doppio di cifre esadecimali, con un minimo di 64 byte. SubFilter fa default a adbe.pkcs7.detached, e Reason, Location e ContactName finiscono nel dizionario di firma come /Reason, /Location e /ContactInfo, accanto a un timestamp /M preso quando il campo viene creato. Il valore di ritorno è il nuovo indice di campo, o -1 quando l'indice di pagina è fuori intervallo. Un nome di campo vuoto o un rettangolo con larghezza o altezza zero sollevano un'eccezione prima che venga scritto qualcosa

Cosa porta la revisione appesa, e cosa lascia in pace

AddLoadedSignedSignatureField è deliberatamente più silenziosa delle sue sorelle. Gli altri creatori di campi AddLoaded* impostano /NeedAppearances true sull'AcroForm, che chiede a un viewer di rigenerare le apparenze dei campi quando apre il file. Su un documento firmato quella rigenerazione può riscrivere contenuto che il primo firmatario copriva. Così il nuovo metodo toglie di nuovo il flag ogni volta che il file sorgente non lo portava già, e un file arrivato con /NeedAppearances lo tiene esattamente com'era. /SigFlags tiene i suoi bit esistenti e guadagna 3, che è SignaturesExist (1) più AppendOnly (2) da ISO 32000-1 §12.7.2, Table 219

Lasciate stare MarkDirty per la pagina. In modalità incrementale, gli oggetti appena creati vengono scritti automaticamente, e gli oggetti caricati vengono scritti solo quando qualcosa li marca. Aggiungere il widget alle /Annots della pagina e alle /Fields dell'AcroForm mette già nella nuova revisione qualunque oggetto indiretto possieda quegli array. Una marca esplicita della pagina trascina con sé il dizionario di pagina anche quando il suo array /Annots vive in un oggetto separato, e l'analisi delle revisioni riporta allora una modifica di pagina in una revisione che dovrebbe contenere nient'altro che un campo firma

Il dizionario segnaposto scrive /ByteRange prima di /Contents. Quell'ordine conta se post-processate il file preparato con strumenti vostri: PreparePDFForSigning trova prima la sentinella /ByteRange e poi cerca in avanti il prossimo /Contents <. Un dizionario con le chiavi scambiate manderebbe quella ricerca in avanti oltre la propria stringa esadecimale e dentro qualunque cosa venga dopo nel file

Quando il primo firmatario ha applicato una restrizione DocMDP o FieldMDP, SaveIncrementalUpdateAuthenticated è il modo più severo di scrivere la revisione 2. Salva su un file candidato nella stessa directory, autentica ogni firma che porta una transform policy, valuta tutte le revisioni dopo ciascuna di loro e pubblica il candidato solo quando ogni policy permette la modifica. Su un contratto senza restrizioni, la semplice SaveIncrementalUpdate fa il lavoro con meno cerimonia

| Il flusso di lavoro HotPDF Delphi per controfirmare un PDF già firmato: BeginIncrementalUpdate apre il file, AddLoadedSignedSignatureField crea il widget e riserva il segnaposto /Contents, SaveIncrementalUpdate appende una seconda revisione, e SignPDFWithPFX la riempie, lasciando la prima firma valida con UnsignedTrailingBytes mentre il nuovo ByteRange copre l'intero file cresciuto
Un segnaposto per revisione, preparato e appuntato dalla stessa serializzazione su entrambi i percorsi di firma — il layout pulito che il verificatore severo si aspetta

Consegnare il digest a un firmatore esterno o a un HSM

Niente nel flusso di lavoro cambia quando il CMS arriva da una smart card, un HSM o un servizio di firma remoto; solo l'ultimo passo lo fa. THotPDF.PreparePDFForSigning appunta il /ByteRange nei byte preparati e restituisce due range a base 0 il cui varco è l'intera stringa /Contents, più ContentsHexStart, l'indice a base 1 della prima cifra esadecimale nell'AnsiString, e ContentsHexLen. Mescolare offset di file a base 0 con indici di stringa a base 1 è il classico off-by-one di questo passo. L'esempio asserisce entrambe le posizioni dei delimitatori prima di fare l'hash di qualcosa

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

  // Controlli di sanità suggeriti (vostri, non chiamate di libreria):
  // '<' chiude il range 1, '>' sta proprio prima del range 2
  Assert(Bytes[R1Start + R1Len + 1] = '<');
  Assert(Bytes[R2Start] = '>');

  ToSign := Copy(Bytes, R1Start + 1, R1Len) + Copy(Bytes, R2Start + 1, R2Len);
  CmsHex := SignDetachedWithHsm(ToSign);           // il vostro firmatore CMS, DER esadecimale
  if not THotPDF.InsertSignatureHexAt(Bytes, HexStart, HexLen, CmsHex) then
    raise Exception.Create('CMS does not fit the reserved space');
  SaveAnsiStringToFile(Bytes, 'SignedTwice.pdf');  // helper vostro
end;

Preparate esattamente un segnaposto per revisione. PreparePDFForSigning appunta la prima sentinella /ByteRange non ancora appuntata che trova, e un secondo segnaposto lasciato nella stessa revisione sta dentro i byte che la prima firma copre, quindi riempirlo più tardi rompe quella firma. Per riscrivere il CMS, InsertSignatureHexAt con gli offset restituiti è la chiamata da usare. InsertSignatureHex cerca la prima stringa /Contents le cui cifre sono tutte zero, il che funziona su un file con un solo segnaposto vuoto; con gli offset in mano non c'è niente da cercare e niente da disabbinare. Un CMS più corto viene riempito con 0 in coda, prima della > di chiusura. Uno più lungo fa restituire a InsertSignatureHexAt False senza toccare i byte del file

Cosa dimostra il controllo del varco, e cosa no?

Il controllo del varco chiude un buco specifico. svValid significa ancora integrità dei byte più una firma che combacia col certificato incastonato nel CMS; se quel certificato incatena a un trust anchor che accettate lo risponde VerifyLoadedSignatureWithTrust, dati i vostri trust anchor e le prove di revoca. Senza byte sorgente niente raggiunge affatto svValid. VerifyLoadedSignatureEx li legge dal file da cui il documento è stato caricato e restituisce svSourceUnavailable per un documento caricato da stream, dove l'overload TStream di VerifyLoadedSignature prende quelli da voi

Per la prima firma in un file controfirmato, CoversWholeDocument è correttamente False. Se la revisione appesa ha solo aggiunto una firma o ha anche cambiato pagine è una domanda per AnalyzeLoadedSignatureRevisions, spiegata in DocMDP, FieldMDP e analisi delle revisioni in HotPDF

Il layout delle parentesi trapela anche nel PDF MAC attached definito da ISO TS 32004 (/MACLocation /AttachedToSig), il cui confronto paragona gli offset alle posizioni esatte di < e > nel file. HotPDF accetta entrambi i layout anche lì. Uno strumento fatto in casa che cabla offset inclusivi delle parentesi è di solito la prima cosa a rompersi quando incontra un file firmato secondo il layout del §12.8.3.3, e far girare l'helper a due byte della prima sezione sull'output del vostro strumento richiede un minuto

La maggior parte dei guai di firma in questa zona inizia quando lo strumento che firma, lo strumento che controfirma e lo strumento che audita sono in disaccordo su dove vanno le parentesi. HotPDF, il componente PDF nativo per Delphi e C++Builder scrive il layout del §12.8.3.3 su ogni percorso di firma, controlla il varco byte per byte su ogni percorso di verifica, e appende le controfirme come revisioni incrementali pulite da una sola API