Articolo tecnico

Firma PAdES remota in PDFium VCL: chiavi HSM e cloud

Un placeholder di firma PAdES da 16.384 byte compare nel file come 32.768 zeri ASCII tra parentesi uncinate, e ogni byte del PDF fuori da quella sequenza è già coperto dall'hash che il firmatario approverà. Questa è la parte scomoda del firmare con una chiave che non potete toccare: il documento deve impegnarsi sul suo layout finale prima che il CMS esista, poi aspettare, a volte per ore, mentre un HSM di rete o un servizio di firma cloud chiede a una persona di confermare sul telefono. Qualsiasi cosa accada al file durante quell'attesa decide se la firma valida

Perché una chiave remota non può usare SignPadesBytes?

La chiamata ordinaria presuppone che la chiave privata sia raggiungibile dentro la chiamata. SignPadesBytes in PDFium Component costruisce l'incremental update, calcola l'hash del ByteRange, firma con il certificato indicato da CertificateThumbprint nello store di Windows, e scrive il file finito prima di tornare. Per una chiave nello store locale è esattamente la forma che volete

Un dispositivo qualificato di creazione della firma gestito da un trust service provider non funziona così. Né un'API di firma cloud con un passo a secondo fattore, o un HSM che sta dietro a una coda. Lo scambio è una conversazione: voi inviate un digest, qualcosa fuori dal vostro processo autentica un essere umano, e un CMS arriva più tardi, su un thread diverso, in un gestore di richiesta diverso, magari su un server diverso. Una chiamata sincrona può modellarlo solo bloccando un thread sul telefono di qualcuno

Quindi il percorso remoto si divide in due chiamate. PreparePadesRemoteSignature produce il PDF preparato e un piccolo record di richiesta. CompletePadesRemoteSignature prende il PDF preparato, il record e il CMS DER restituito, e scrive il file firmato. Nulla lega le due chiamate allo stesso processo

Preparare il documento con PreparePadesRemoteSignature

PreparePadesRemoteSignature legge il PDF sorgente, accoda un incremental update con un widget di firma invisibile sulla prima pagina, e scrive un dizionario di firma con /Filter /Adobe.PPKLite e /SubFilter /ETSI.CAdES.detached. La voce /Contents è riempita di zeri a larghezza fissa, i quattro numeri del ByteRange vengono rattoppati attorno, e lo SHA-256 su quei due intervalli diventa Request.DocumentDigest. I byte originali del file sorgente restano intatti; l'update si limita ad aggiungere

Il record di output, TPadesRemoteSigningRequest, ha sei campi: FormatVersion, PreparedFingerprint (SHA-256 dell'intero file preparato), DocumentDigest, il ByteRange a quattro elementi, ContentsHexOffset (dove iniziano le cifre esadecimali) e ContentsSize. Al servizio di firma va solo il digest. Il resto esiste perché la seconda chiamata possa dimostrare di stare completando gli stessi byte da cui il digest proviene

Tre regole di opzioni riguardano il file preparato, e una quarta riguarda la vostra build. Quando CommitmentTypeOid è impostato, il dizionario non porta /Reason, perché ETSI EN 319 142-1 tratta il commitment type nel CMS e la reason del PDF come alternative; il servizio di firma deve allora scrivere la commitment-type-indication negli attributi firmati del CMS. SigningTimeUtc diventa la voce /M. Le sorgenti cifrate sono rifiutate a prescindere, quindi prima decifrate. Le funzioni remote appartengono all'edizione Enterprise: l'unità FPdfPadesRemote deve essere collegata, altrimenti i punti di ingresso in FPdfPades sollevano EPdfEnterpriseRequired

Flusso PAdES remoto PDFium in due fasi in Delphi dove PreparePadesRemoteSignature riserva lo slot CMS e consegna il digest del documento a un HSM o servizio cloud, e CompletePadesRemoteSignature incorpora il CMS restituito in qualsiasi processo o macchina in seguito
La fase uno riserva lo slot CMS e consegna il digest del documento; la fase due incorpora il CMS che torna dall'HSM o dalla chiave cloud
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // collega l'implementazione Enterprise

var
  Options: TPadesRemoteSignOptions;
  Request: TPadesRemoteSigningRequest;
  Source, Prepared, Session: TFileStream;
begin
  Options := TPadesRemoteSignOptions.Default;   // ContentsSize = 16384
  Options.Reason := 'Approved by finance';
  Options.Location := 'Lisbon';
  Options.Name := 'A. Moreira';
  Options.SigningTimeUtc := TTimeZone.Local.ToUniversalTime(Now);

  Source := TFileStream.Create('contract.pdf', fmOpenRead or fmShareDenyWrite);
  Prepared := TFileStream.Create('contract.prepared.pdf', fmCreate);
  try
    PreparePadesRemoteSignature(Source, Prepared, Options, Request);
  finally
    Prepared.Free;
    Source.Free;
  end;

  Session := TFileStream.Create('contract.signreq', fmCreate);
  try
    SavePadesRemoteSigningRequest(Session, Request);
  finally
    Session.Free;
  end;

  // Codice vostro: consegnate il digest di 32 byte all'HSM o all'API di firma
  SendDigestToSigningService(Request.DocumentDigest);
end;

Se il documento è già aperto in un componente TPdf, TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) salva lo stato corrente e prepara da quello, restituendo False quando nessun documento è attivo. Completamento e helper di sessione sono a loro volta metodi di classe su TPdf, quindi la seconda fase non ha bisogno affatto di un documento caricato

Cosa deve restituire il servizio di firma

I 32 byte in DocumentDigest sono il valore che il CMS deve portare nel suo attributo firmato message-digest. Di solito non sono i byte che la chiave privata firma. RFC 5652 §5.4 dice che quando gli attributi firmati sono presenti, la firma è calcolata sulla codifica DER dell'insieme degli attributi, quindi un servizio che restituisce un CMS completo fa quel passo da sé, mentre un HSM scarno che firma solo hash lascia il passo a voi. Nel secondo caso il vostro codice costruisce i SignedAttributes (content-type, message-digest, signing-certificate-v2), li codifica DER come SET OF con membri ordinati, calcola l'hash di quello, e chiede all'HSM di firmare l'hash. Sbagliare l'ordine di ordinamento produce un CMS che sembra a posto e fallisce la verifica crittografica; l'ordinamento DER SET OF negli attributi firmati del CMS percorre quella trappola

Chiunque assembli il CMS, il completamento accetta una sola forma precisa: un SignedData con esattamente un SignerInfo, distaccato (nessun contenuto incapsulato), con attributi firmati content-type e message-digest, un algoritmo di digest diverso da MD5 o SHA-1, e un attributo signing-certificate-v2 valido. Sono ciò che le firme baseline PAdES richiedono sotto ETSI EN 319 142-1, quindi un servizio che già produce output CAdES compatibile PAdES ci sta senza lavoro extra

Cosa rifiuta CompletePadesRemoteSignature?

CompletePadesRemoteSignature esegue ogni controllo prima di scrivere un solo byte nel flusso di destinazione, e ogni rifiuto solleva EPadesCrypto con un messaggio che nomina il controllo fallito. Il record di richiesta stesso viene controllato per primo: formato versione 1, fingerprint e digest da 32 byte, un ContentsSize tra 1024 byte e 64 MiB, un offset esadecimale positivo. Poi il file preparato:

  1. gli offset registrati devono stare dentro il file, e il ByteRange deve allinearsi esattamente con il placeholder e la lunghezza del file
  2. il < e il > attorno a /Contents devono essere ancora al loro posto, e ogni cifra esadecimale tra loro deve essere ancora 0
  3. lo SHA-256 dell'intero file deve eguagliare PreparedFingerprint, e l'hash del ByteRange deve eguagliare DocumentDigest

Poi il CMS: deve essere un unico valore DER esatto senza byte in coda, non più lungo di ContentsSize, della forma SignedData supportata, con signing-certificate-v2 presente, e infine il suo attributo message-digest deve eguagliare DocumentDigest

Un file preparato rigenerato tra le fasi cambia il fingerprint anche se in un visualizzatore sembra identico. Il test a soli zeri sul placeholder intercetta il doppio completamento, dove un retry scrive un secondo CMS sopra una firma che c'è già. Il confronto del message-digest intercetta il caso più sgradevole: un CMS correttamente formato dal vostro certificato, firmato su un documento diverso perché una coda ha scambiato due sessioni concorrenti. Quel file si aprirebbe bene e porterebbe un'approvazione destinata a un altro contratto

Il controllo signing-certificate-v2 riguarda la conformità più dell'integrità. Un CMS senza di esso può verificarsi crittograficamente e fallire comunque un validatore PAdES, e rifiutarlo al completamento sposta quella scoperta dal report di validazione di un cliente ai vostri stessi log. Perché i validatori rifiutano le firme PAdES copre gli altri attributi che i validatori cercano

Diagramma del gate di completamento per la firma PAdES remota PDFium in Delphi dove CompletePadesRemoteSignature controlla integrità del file, forma del CMS e conformità PAdES, scrivendo il PDF firmato solo quando ogni controllo passa
CompletePadesRemoteSignature valida integrità, forma del CMS e conformità PAdES prima che venga scritto qualsiasi byte
var
  Request: TPadesRemoteSigningRequest;
  Session, Prepared, Dest: TFileStream;
  CmsDer: TBytes;
begin
  Session := TFileStream.Create('contract.signreq', fmOpenRead);
  try
    Request := LoadPadesRemoteSigningRequest(Session);
  finally
    Session.Free;
  end;

  CmsDer := FetchDetachedCmsFromService;   // codice vostro: byte DER, non Base64

  Prepared := TFileStream.Create('contract.prepared.pdf', fmOpenRead);
  try
    Dest := TFileStream.Create('contract.signed.pdf', fmCreate);
    try
      try
        CompletePadesRemoteSignature(Prepared, Dest, Request, CmsDer);
      except
        on E: EPadesCrypto do
          FailSession(E.Message);   // codice vostro: conservate il messaggio esatto
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

Molte API di firma restituiscono il CMS come Base64 dentro JSON, a volte con intestazioni PEM attorno. Passate il solo DER decodificato. Una newline in coda o un byte di intestazione residuo fallisce il controllo del valore-DER-unico, che è il risultato voluto: l'alternativa è un CMS che si analizza con spazzatura dietro

File di sessione tra processi e macchine

SavePadesRemoteSigningRequest scrive un record binario fisso di 120 byte: un magic PDRSIG01 di 8 byte, la versione del formato, l'offset esadecimale, ContentsSize, i quattro valori del ByteRange, poi il digest e il fingerprint. LoadPadesRemoteSigningRequest rifiuta qualsiasi cosa con dimensione sbagliata, magic sbagliato, dati in coda o una versione del formato diversa da 1. Il record non contiene materiale di chiave né contenuto del documento, quindi archiviarlo accanto al PDF preparato in una riga di database o in un object store va bene

Questo rende il caso dell'applicazione web diretto. Un gestore di richiesta prepara il file e archivia entrambi gli artefatti, il browser o un'app sul telefono approva il digest, e un gestore di callback su un altro nodo carica la sessione e la completa. Il vincolo sta sul PDF preparato: deve tornare byte per byte. Risalvarlo tramite una libreria PDF, farlo passare per un ottimizzatore, o lasciare che un livello di trasporto tocchi i fine riga cambiano tutti il fingerprint

Un servizio di firma qualificata a consumo fa pagare per operazione, quindi conviene controllare il file archiviato prima ancora di chiedere una firma. Lo schema qui sotto confronta l'hash del file con PreparedFingerprint usando System.Hash della RTL Delphi; è un controllo che aggiungete voi, e comunque il completamento lo ripete

uses
  System.SysUtils, System.Classes, System.Hash,
  FPdfPades, FPdfPadesRemote;

// Controllo pre-flight suggerito che aggiungete voi; non fa parte del componente
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // L'overload TStream di GetHashBytes richiede un System.Hash Delphi recente;
    // Lazarus non ha System.Hash, quindi lì chiamate la vostra routine SHA-256
    H := THashSHA2.GetHashBytes(S);   // SHA-256 per impostazione predefinita
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

Dimensionare ContentsSize prima che il CMS esista

ContentsSize conta byte di CMS DER. Il placeholder nel file è il doppio di caratteri esadecimali, ecco perché il valore predefinito di 16384 produce i 32.768 zeri del paragrafo iniziale. I valori sotto 1024 vengono portati a 1024, un valore sopra 64 MiB viene rifiutato al prepare, e il completamento rifiuta qualsiasi CMS più lungo di ContentsSize byte

Troppo piccolo è l'errore costoso: il servizio ha già firmato, l'operazione è spesa, e l'unica strada avanti è preparare di nuovo con uno slot più grande e firmare di nuovo. Troppo grande costa solo padding in ogni file firmato. Puntate verso il lato grande. Supponete che il vostro servizio restituisca un CMS di circa 7.000 byte con una catena di tre certificati; il valore predefinito lascia ancora più della metà dello slot libera. Se il servizio incorpora anche un token di timestamp della firma o dati di revoca come attributi non firmati, quelli atterrano nello stesso CMS e pesano sullo stesso limite, quindi misurate una risposta reale dalla vostra catena di produzione e dimensionate da quella, con margine per una catena di intermediari più lunga in futuro

Dopo il completamento: B-B, poi LTV e verifica

Una firma remota completata è PAdES B-B. La validazione a lungo termine aggiunge un timestamp del documento e materiale di validazione in un successivo incremental update con un DSS e i suoi dizionari VRI per firma, descritto in firme a lungo termine con timestamp RFC 3161 e DSS. Quel passo gira in locale perché certificati, risposte OCSP e CRL non richiedono la chiave privata

Verificate l'output con lo stesso percorso che seguirebbe una relying party, come copre ispezionare le firme digitali e i livelli PAdES. In una pipeline remota il codice che costruisce il CMS vive sul server di qualcun altro, e il primo posto dove il suo output incontra un validatore vero dovrebbe essere la vostra stessa build, avanti rispetto ai vostri clienti

Le chiamate di firma remota viaggiano con l'edizione Enterprise di PDFium Component per Delphi e Lazarus, insieme al codice nativo Pascal di firma PAdES, timestamping e validazione. Riferimento API e download di prova sono sulla pagina prodotto PDFium Component