Articolo tecnico

Verificare le firme digitali PDF in Delphi con HotPDF

Un verificatore di firme PDF scritto a mano può rifiutare ogni file firmato correttamente che riceve pur leggendo ogni byte in modo corretto. Estrae il blob CMS da /Contents, trova gli attributi firmati, ne fa l'hash esattamente come sono memorizzati, e il confronto RSA fallisce. Il documento è a posto. Il problema è un byte: dentro il SignerInfo gli attributi sono taggati [0] IMPLICIT, quindi il loro primo byte è 0xA0, mentre RFC 5652 §5.4 dice che il firmatario ha calcolato la firma sullo stesso contenuto codificato come SET OF DER, il cui primo byte è 0x31. Scambia quel byte prima di fare l'hash e le firme "contraffatte" diventano valide

Quel disallineamento di tag è il primo di diversi punti in cui un controllo di firma PDF può andare storto, e gli altri sono meno ovvi. Una firma può essere matematicamente perfetta su un file modificato dopo la firma. Può essere perfetta su un documento che un attaccante ha ri-firmato con un certificato fatto in casa. Una controparte rimanda indietro un contratto firmato, il tuo workflow deve archiviarlo, e qualcuno chiede se questo è il documento che hai inviato, byte per byte, firmato dal certificato che dichiara. Produrre quelle firme in primo luogo è trattato nell'articolo complementare sulla creazione di firme digitali PAdES in Delphi; questo va nella direzione opposta, partendo da un file che arriva già firmato

Dove vivono i byte firmati in un file PDF

Una firma PDF protegge intervalli di byte del file su disco, e HotPDF verifica esattamente contro quei byte. ISO 32000-1 §12.8.1 mette un contenitore CMS SignedData (RFC 5652) nella voce /Contents del dizionario di firma e, accanto, un array /ByteRange che nomina le regioni coperte dalla firma. In pratica l'array contiene due coppie offset e lunghezza: tutto dall'offset 0 fino alla stringa hex /Contents, e tutto ciò che viene dopo. Una firma non può coprire il proprio valore, quindi l'hash del file viene calcolato attorno a quel buco

La conseguenza per qualsiasi verificatore è brutale. Devi fare l'hash dell'originale serializzato. Un modello a oggetti parsato qui non serve a nulla, perché riscrivere anche un documento non toccato produce byte diversi. HotPDF legge quindi il file sorgente da cui il documento è stato caricato, o un TStream di byte grezzi che fornisci tu, e non fa mai l'hash della sua rappresentazione in memoria

Diagramma di HotPDF che verifica un PDF firmato in Delphi rifacendo l'hash dei due segmenti ByteRange del file sorgente attorno al foro Contents, mentre il modello analizzato in memoria non viene mai sottoposto a hash perché la riserializzazione cambia i byte
La verifica fa l'hashing dei due segmenti ByteRange dei byte sorgente esattamente come serializzati; un modello analizzato in memoria è inutile perché riserializzare persino un documento invariato produce byte diversi

Il buco stesso merita sospetto. I byte fuori dagli intervalli firmati sono byte che un reader può comunque parsare, e un gap che contiene qualsiasi cosa oltre al valore della firma è la porta per un attacco di signature wrapping. HotPDF controlla che /ByteRange parta dall'offset 0, che il secondo segmento inizi dopo la fine del primo, che entrambi restino dentro il file, e che il gap non contenga altro che le cifre hex del /Contents di questa stessa firma, opzionalmente con i suoi delimitatori < e >. Un file che fallisce uno qualsiasi di questi controlli restituisce svInvalidByteRange, anche quando la matematica del CMS sarebbe passata

Leggere chi ha firmato prima di controllare qualsiasi cosa

GetLoadedSignatureInfo parsa il dizionario di firma e il suo contenitore CMS senza fare l'hash di un solo byte del documento, quindi è la chiamata da fare quando una UI deve solo mostrare chi ha firmato e quando. I campi firma sono indicizzati da 0 nell'ordine dei campi modulo, e GetLoadedSignatureFieldCount restituisce quanti ce ne sono. Un indice oltre la fine solleva un'eccezione invece di restituire un record vuoto, quindi cicla sul conteggio

Il record THPDFSignatureInfo restituito porta il nome del campo, il /SubFilter, il common name del certificato del firmatario, i distinguished name di soggetto ed emittente, il numero di serie in hex, le date di validità del certificato e l'ora di firma, presa dall'attributo firmato quando presente e altrimenti dalla voce /M del dizionario. Riporta anche i nomi degli algoritmi di digest e di chiave pubblica, le stringhe /Reason, /Location e /ContactInfo, e CertificateTimeValidity, che segnala un'ora di firma che cade fuori dalla finestra di validità del certificato. Status resta svNotVerified: parsato, non controllato. L'API delle firme sta dietro il guard di compilazione per Delphi 2009 e successivi

var
  Pdf: THotPDF;
  Info: THPDFSignatureInfo;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    Pdf.LoadFromFile('signed-contract.pdf');
    for I := 0 to Pdf.GetLoadedSignatureFieldCount - 1 do
    begin
      Info := Pdf.GetLoadedSignatureInfo(I);
      Writeln('Field:     ', Info.FieldName);
      Writeln('Signer:    ', Info.SignerName);
      Writeln('Issuer:    ', Info.IssuerDN);
      Writeln('Key/hash:  ', Info.PublicKeyAlgorithm, ' / ', Info.HashAlgorithm);
      Writeln('SubFilter: ', Info.SubFilter);
      if Info.CertificateTimeValidity = stvSigningTimeOutsideCertificate then
        Writeln('Signing time is outside the certificate validity period');
    end;
  finally
    Pdf.Free;
  end;
end;

Eseguire il controllo crittografico con VerifyLoadedSignatureEx

VerifyLoadedSignatureEx esegue il controllo completo per un documento caricato da file e restituisce il record info popolato nella stessa chiamata. Riapre il file sorgente, valida /ByteRange, fa l'hash dei due segmenti con l'algoritmo di digest del SignerInfo, confronta il risultato con l'attributo firmato messageDigest, e poi verifica il valore della firma sulla forma SET OF DER degli attributi firmati usando la chiave pubblica del certificato del firmatario embedded. Quando una firma non porta attributi firmati, un controllo RSA o ECDSA gira invece direttamente sull'hash del documento

La copertura degli algoritmi segue ciò che gli strumenti di firma emettono davvero. I digest includono SHA-1, SHA-256, SHA-384, SHA-512, la famiglia SHA-3 e SHAKE256. Le firme possono essere RSA con padding PKCS#1 v1.5 o PSS, ECDSA su curve con nome, oppure Ed25519 ed Ed448. La verifica ECDSA usa il provider CNG di Windows, ed Ed25519 ed Ed448 passano da un provider di piattaforma basato su Windows CNG o su una libreria OpenSSL, quindi su una macchina dove il provider necessario non si carica il risultato è svUnsupportedAlgorithm o svCryptoProviderError invece di un verdetto sul file. VerifyLoadedSignatureWithOptions accetta un record THPDFCMSVerifyOptions quando devi puntare a una libreria OpenSSL specifica o innestare un tuo THPDFSignatureProvider

Pipeline di VerifyLoadedSignatureEx in HotPDF per Delphi: riapre il file sorgente, fa l'hash dei segmenti ByteRange, confronta con l'attributo firmato messageDigest del CMS, poi verifica la firma con la chiave pubblica del certificato del firmatario, producendo svValid, svDigestMismatch o svSignatureInvalid
VerifyLoadedSignatureEx rifà l'hash dei segmenti ByteRange, li confronta con l'attributo firmato messageDigest e verifica la firma sul SET DER degli attributi firmati prima di riportare svValid o uno stato di fallimento specifico
var
  Status: THPDFSignatureVerifyStatus;
  Info: THPDFSignatureInfo;
begin
  Status := Pdf.VerifyLoadedSignatureEx(0, Info);
  case Status of
    svValid:
      if Info.CoversWholeDocument then
        Writeln('Valid; signature covers the whole file')
      else
        Writeln('Valid; ', Info.UnsignedTrailingBytes,
          ' bytes were appended after signing');
    svDigestMismatch:
      Writeln('Document bytes changed after signing');
    svSignatureInvalid:
      Writeln('Hash matches, signature value does not verify');
    svInvalidByteRange:
      Writeln('ByteRange is malformed or the gap holds extra bytes');
    svDigestAlgorithmMismatch:
      Writeln('CMS digest algorithm identifiers disagree');
    svUnsupportedAlgorithm, svCryptoProviderError:
      Writeln('Cannot evaluate this key or digest here');
    svMalformed:
      Writeln('CMS container could not be parsed');
    svSourceUnavailable:
      Writeln('No source bytes; use the TStream overload');
  else
    Writeln('Status ', Ord(Status));
  end;
end;

Due dettagli di parsing spiegano fallimenti che da fuori sembrano misteriosi. Il primo è il ri-tag del paragrafo di apertura: HotPDF fa l'hash degli attributi firmati con il byte iniziale riscritto a 0x31, esattamente come prescrive RFC 5652 §5.4. Il secondo è il padding. Gli strumenti di firma riservano un budget fisso di byte per /Contents prima che la firma esista e riempiono la coda inutilizzata di zeri, quindi il verificatore taglia il blob decodificato alla lunghezza reale della sua SEQUENCE DER esterna prima di percorrerlo. Una sequenza di zeri in coda a /Contents è normale. La stessa famiglia di insidie nel parsing ASN.1, vista dal lato dell'import dei certificati, è l'argomento dell'articolo sull'hardening di sicurezza di PKCS#12 e ASN.1 in Delphi

Lungo il percorso girano alcuni controlli più rigorosi. L'algoritmo di digest nel SignerInfo deve concordare con la lista dei digest del SignedData, con l'identificatore dell'algoritmo di firma e con qualsiasi attributo CMS di algorithm-protection, altrimenti lo stato è svDigestAlgorithmMismatch. Gli attributi firmati devono contenere esattamente un attributo content-type che corrisponda al contenuto firmato, altrimenti svMalformed. Quando il CMS porta un timestamp di firma RFC 3161 embedded, quel token viene verificato contro il valore della firma e riportato in Info.Timestamp; un timestamp di documento ETSI.RFC3161 viene verificato allo stesso modo contro gli intervalli di byte di cui è stato fatto l'hash

Cosa dimostra davvero svValid?

svValid significa due cose: i byte indicati da /ByteRange hanno come hash il valore che il firmatario ha firmato, e quella firma si verifica con la chiave pubblica del certificato embedded nel contenitore CMS. Integrità dei byte più legame con la chiave. Non dice nulla su chi possiede quella chiave. Un attaccante che modifica un contratto e lo ri-firma con un certificato autogenerato ottiene svValid, perché la matematica è internamente coerente, e il campo SignerName mostrerà qualsiasi nome l'attaccante abbia digitato nel certificato

CoversWholeDocument copre una seconda falla. Gli aggiornamenti incrementali del PDF permettono a un writer di accodare contenuto dopo una firma senza romperla, cosa voluta ed è così che funzionano i workflow a più firme. Il flag viene calcolato durante la verifica ed è vero solo quando entrambi i segmenti più il gap di /Contents coprono l'intero file. SignedRevisionLength dà la dimensione del prefisso firmato e UnsignedTrailingBytes il numero di byte aggiunti dopo. Per un file che dichiara una revisione firmata da 48.000 byte dentro un file da 52.300 byte, UnsignedTrailingBytes vale 4.300 e CoversWholeDocument è falso

Diagramma della portata di ciò che svValid garantisce nella verifica delle firme di HotPDF: integrità dei byte del ByteRange e legame con la chiave, mentre percorso della catena, revoca e trust store appartengono a un controllo di fiducia separato e CoversWholeDocument segnala gli aggiornamenti incrementali accodati
svValid significa integrità dei byte più legame con la chiave e niente di più; percorso della catena, revoca e trust anchor appartengono a un controllo di fiducia separato, e CoversWholeDocument=false segnala byte accodati dopo la firma

Una pipeline di acquisizione in archivio non dovrebbe accettare da solo uno svValid con CoversWholeDocument falso. Esegui prima AnalyzeLoadedSignatureRevisions: classifica ogni revisione accodata dopo la firma selezionata, elenca i nomi dei campi cambiati in ChangedFieldNames, e riporta se le modifiche rispettano i permessi DocMDP e FieldMDP impostati dal firmatario, tramite DocMDPCompliant e FieldMDPCompliant. Una firma successiva aggiunta in un campo firma vuoto è routine. Una revisione che riscrive gli oggetti pagina non lo è, e ChangeKinds nell'analisi è ciò che distingue i due casi

Controllare il firmatario contro i tuoi trust anchor

La fiducia è una chiamata separata in HotPDF, e quella separazione è il default giusto. VerifyLoadedSignatureWithTrust esegue prima la stessa verifica sugli intervalli di byte, restituendo cvsSignatureInvalid se fallisce, e poi costruisce un percorso di certificazione dal firmatario agli anchor che passi in THPDFCertificateValidationOptions.TrustAnchors. Lungo il percorso valuta le prove di revoca: le risposte OCSP e le CRL memorizzate nei dizionari DSS e /VRI del documento vengono raccolte automaticamente, e quelle che fornisci in OCSPResponses o CRLs vengono aggiunte al pool

uses
  System.IOUtils;

var
  Options: THPDFCertificateValidationOptions;
  Info: THPDFSignatureInfo;
  Trust: THPDFCertificateValidationStatus;
begin
  Options := THPDFCertificateValidationOptions.Default;
  SetLength(Options.TrustAnchors, 1);
  // Certificato root codificato DER; converti i file PEM prima di caricarli
  Options.TrustAnchors[0] := TFile.ReadAllBytes('company-root.cer');
  Options.RevocationMode := rvmBestEffort;

  Trust := Pdf.VerifyLoadedSignatureWithTrust(0, Options, Info);
  if Trust = cvsTrusted then
    Writeln('Signed by a certificate chaining to our root')
  else
    Writeln('Not trusted: ', Info.CertificateValidation.Issue);
end;

La modalità di revoca è una scelta di policy. rvmBestEffort usa le prove disponibili e va avanti quando non ne trova, mentre rvmRequire trasforma le prove mancanti in cvsRevocationUnknown. Per i contratti che verranno sottoposti ad audit anni dopo, rvmRequire è l'impostazione più sicura, a patto che i tuoi firmatari incorporino dati OCSP o CRL al momento della firma; senza quelle prove nel file, ogni documento torna cvsRevocationUnknown

Perché i documenti caricati da stream restituiscono svSourceUnavailable?

Le chiamate basate su file, cioè la VerifyLoadedSignature a un argomento, VerifyLoadedSignatureEx e la VerifyLoadedSignatureWithTrust basata su file, hanno bisogno che il componente ricordi da quale file viene il documento. Un documento caricato con LoadFromStream non ha un nome di file da riaprire. Lo stesso vale dopo il ricaricamento con password usato per i documenti cifrati, descritto nell'articolo sulla cifratura PDF AES-256 in Delphi, perché il componente abbandona il riferimento al file sorgente una volta decifrato il documento. In entrambi i casi gli overload basati su file restituiscono svSourceUnavailable e non tirano a indovinare

Gli overload con TStream prendono i byte grezzi originali da dovunque li abbia conservati: un file, un buffer in memoria, un blob di database. La posizione dello stream viene ripristinata dopo l'hash, così lo stesso stream può essere passato a più indici di firma uno dopo l'altro. VerifyAllLoadedSignatures, che restituisce true solo quando esiste almeno un campo firma e ogni campo si verifica come svValid, passa dal percorso basato su file, quindi su un documento caricato da stream restituisce false qualunque cosa contengano le firme. Cicla invece sull'overload con stream

function AllSignaturesValid(Pdf: THotPDF; Src: TStream): Boolean;
// Helper da aggiungere da parte del lettore: un equivalente basato su stream di
// VerifyAllLoadedSignatures per i documenti caricati con LoadFromStream
var
  I, Count: Integer;
  Info: THPDFSignatureInfo;
begin
  Count := Pdf.GetLoadedSignatureFieldCount;
  Result := Count > 0;
  for I := 0 to Count - 1 do
    if Pdf.VerifyLoadedSignature(I, Src, Info) <> svValid then
    begin
      Writeln(Info.FieldName, ': status ', Ord(Info.Status));
      Exit(False);
    end;
end;

Verifica degli intervalli di byte, costruzione del percorso fino ai trust anchor, firma PAdES e cifratura AES-256 vivono tutte nella stessa libreria VCL nativa per Delphi e C++Builder, con hashing RSA e controlli di padding fatti in codice Pascal; edizioni, versioni IDE supportate e la lista completa delle funzionalità sono sulla pagina prodotto di HotPDF Delphi Component