Article technique

Signature PAdES distante PDFium VCL : HSM et cloud

Un espace réservé de signature PAdES de 16 384 octets apparaît dans le fichier sous forme de 32 768 zéros ASCII entre crochets angulaires, et chaque octet du PDF hors de cette série est déjà couvert par l'empreinte que le signataire va approuver. C'est la partie délicate de la signature avec une clé que vous ne pouvez pas toucher : le document doit s'engager sur sa mise en page finale avant que le CMS existe, puis attendre, parfois des heures, qu'un HSM réseau ou un service de signature cloud demande à une personne de confirmer sur un téléphone. Tout ce qui arrive au fichier pendant cette attente décide de la validité de la signature

Pourquoi une clé distante ne peut-elle pas utiliser SignPadesBytes ?

L'appel ordinaire suppose que la clé privée est joignable à l'intérieur de l'appel. SignPadesBytes dans PDFium Component construit la mise à jour incrémentielle, calcule le haché du ByteRange, signe avec le certificat désigné par CertificateThumbprint dans le magasin Windows, et écrit le fichier fini avant de retourner. Pour une clé du magasin local, c'est exactement la forme qu'il vous faut

Un dispositif qualifié de création de signature exploité par un prestataire de services de confiance ne fonctionne pas ainsi. Pas plus qu'une API de signature cloud avec une étape de second facteur, ou un HSM placé derrière une file. L'échange est une conversation : vous envoyez un condensé, quelque chose hors de votre processus authentifie un humain, et un CMS arrive plus tard sur un autre thread, dans un autre gestionnaire de requêtes, peut-être sur un autre serveur. Un appel synchrone ne peut modéliser cela qu'en bloquant un thread sur le téléphone de quelqu'un

La voie distante se scinde donc en deux appels. PreparePadesRemoteSignature produit le PDF préparé et un petit enregistrement de requête. CompletePadesRemoteSignature prend le PDF préparé, l'enregistrement et le CMS DER renvoyé, et écrit le fichier signé. Rien ne lie les deux appels au même processus

Préparer le document avec PreparePadesRemoteSignature

PreparePadesRemoteSignature lit le PDF source, ajoute une mise à jour incrémentielle avec un widget de signature invisible sur la première page, et écrit un dictionnaire de signature avec /Filter /Adobe.PPKLite et /SubFilter /ETSI.CAdES.detached. L'entrée /Contents est remplie de zéros sur une largeur fixe, les quatre nombres du ByteRange sont patchés autour, et le SHA-256 sur ces deux plages devient Request.DocumentDigest. Les octets d'origine du fichier source restent intacts ; la mise à jour ne fait qu'ajouter

L'enregistrement de sortie, TPadesRemoteSigningRequest, a six champs : FormatVersion, PreparedFingerprint (SHA-256 de tout le fichier préparé), DocumentDigest, le ByteRange à quatre éléments, ContentsHexOffset (où commencent les chiffres hexadécimaux) et ContentsSize. Seul le condensé part vers le service de signature. Le reste existe pour que le second appel puisse prouver qu'il complète bien les mêmes octets d'où vient le condensé

Trois règles d'options affectent le fichier préparé, et une quatrième affecte votre build. Quand CommitmentTypeOid est défini, le dictionnaire ne porte pas de /Reason, car ETSI EN 319 142-1 traite le type d'engagement dans le CMS et la raison PDF comme des alternatives ; le service de signature doit alors écrire l'indication de type d'engagement dans les attributs signés du CMS. SigningTimeUtc devient l'entrée /M. Les sources chiffrées sont refusées sans appel, donc déchiffrez d'abord. Les fonctions distantes relèvent de l'édition Enterprise : l'unité FPdfPadesRemote doit être liée, sinon les points d'entrée de FPdfPades lèvent EPdfEnterpriseRequired

Flux PAdES distant PDFium en deux phases en Delphi où PreparePadesRemoteSignature réserve l'emplacement CMS et remet le condensé du document à un HSM ou un service cloud, et CompletePadesRemoteSignature incorpore le CMS renvoyé dans n'importe quel processus ou machine plus tard
La phase un réserve l'emplacement CMS et remet l'empreinte du document ; la phase deux incorpore le CMS qui revient de l'HSM ou de la clé cloud
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // lie l'implémentation 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;

  // Votre propre code : remettez le condensé de 32 octets au HSM ou à l'API de signature
  SendDigestToSigningService(Request.DocumentDigest);
end;

Si le document est déjà ouvert dans un composant TPdf, TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) sauvegarde l'état courant et prépare à partir de là, en renvoyant False quand aucun document n'est actif. La complétion et les aides de session sont aussi des méthodes de classe sur TPdf, si bien que la seconde phase n'a pas besoin du tout d'un document chargé

Ce que le service de signature doit renvoyer

Les 32 octets de DocumentDigest sont la valeur que le CMS doit porter dans son attribut signé message-digest. Ce ne sont généralement pas les octets que la clé privée signe. RFC 5652 §5.4 dit que quand des attributs signés sont présents, la signature est calculée sur l'encodage DER de l'ensemble d'attributs, si bien qu'un service qui renvoie un CMS complet fait cette étape lui-même, tandis qu'un HSM brut qui ne signe que des hachés vous la laisse. Dans le second cas, votre code construit les SignedAttributes (content-type, message-digest, signing-certificate-v2), les encode en DER comme un SET OF aux membres triés, hache cela, et demande au HSM de signer le haché. Se tromper dans l'ordre de tri produit un CMS qui a l'air bon et échoue à la vérification cryptographique ; le tri DER SET OF des attributs signés CMS détaille ce piège

Qui que soit l'assembleur du CMS, la complétion n'accepte qu'une forme précise : un SignedData avec exactement un SignerInfo, détaché (pas de contenu encapsulé), avec des attributs signés content-type et message-digest, un algorithme de condensé autre que MD5 ou SHA-1, et un attribut signing-certificate-v2 valide. Cela correspond à ce qu'exigent les signatures PAdES baseline sous ETSI EN 319 142-1, si bien qu'un service qui produit déjà une sortie CAdES compatible PAdES s'insère sans travail supplémentaire

Que refuse CompletePadesRemoteSignature ?

CompletePadesRemoteSignature exécute chaque vérification avant d'écrire le moindre octet dans le flux de destination, et chaque refus lève EPadesCrypto avec un message nommant la vérification en échec. L'enregistrement de requête lui-même est vérifié d'abord : version de format 1, empreinte et condensé de 32 octets, un ContentsSize entre 1024 octets et 64 Mio, un offset hexadécimal positif. Puis le fichier préparé :

  1. les offsets enregistrés doivent se trouver à l'intérieur du fichier, et le ByteRange doit s'aligner exactement avec l'espace réservé et la longueur du fichier
  2. les < et > autour de /Contents doivent toujours être en place, et chaque chiffre hexadécimal entre eux doit toujours être 0
  3. le SHA-256 de tout le fichier doit égaler PreparedFingerprint, et le haché du ByteRange doit égaler DocumentDigest

Puis le CMS : il doit être exactement une valeur DER sans octet terminal, pas plus long que ContentsSize, de la forme SignedData prise en charge, avec signing-certificate-v2 présent, et enfin son attribut message-digest doit égaler DocumentDigest

Un fichier préparé régénéré entre les phases change l'empreinte même s'il paraît identique dans un visualiseur. Un test tout-zéro sur l'espace réservé attrape la double complétion, où un nouvel essai écrit un second CMS par-dessus une signature déjà présente. La comparaison du message-digest attrape le cas le plus sournois : un CMS correctement formé, venant de votre propre certificat, signé sur un document différent parce qu'une file a échangé deux sessions concurrentes. Ce fichier s'ouvrirait bien et porterait une approbation destinée à un autre contrat

La vérification signing-certificate-v2 concerne la conformité plus que l'intégrité. Un CMS qui en est dépourvu peut se vérifier cryptographiquement et échouer quand même devant un validateur PAdES, et le refuser à la complétion déplace cette découverte du rapport de validation d'un client vers vos propres journaux. Pourquoi les validateurs rejettent les signatures PAdES couvre les autres attributs que cherchent les validateurs

Diagramme du verrou de finalisation de la signature PAdES distante PDFium en Delphi où CompletePadesRemoteSignature vérifie l'intégrité du fichier, la forme du CMS et la conformité PAdES, n'écrivant le PDF signé que si chaque vérification passe
CompletePadesRemoteSignature valide intégrité, forme du CMS et conformité PAdES avant l'écriture du moindre octet
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;   // votre propre code : octets DER, pas du 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);   // votre propre code : gardez le message exact
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

Beaucoup d'API de signature renvoient le CMS en Base64 dans du JSON, parfois avec des en-têtes PEM autour. Ne passez que le DER décodé. Un retour à la ligne final ou un octet d'en-tête résiduel fait échouer la vérification d'une unique valeur DER exacte, ce qui est le résultat voulu : l'alternative est un CMS qui s'analyse avec des déchets derrière

Des fichiers de session entre processus et machines

SavePadesRemoteSigningRequest écrit un enregistrement binaire fixe de 120 octets : une magie PDRSIG01 de 8 octets, la version de format, l'offset hexadécimal, ContentsSize, les quatre valeurs du ByteRange, puis le condensé et l'empreinte. LoadPadesRemoteSigningRequest rejette tout ce qui a la mauvaise taille, la mauvaise magie, des données terminales ou une version de format autre que 1. L'enregistrement ne porte ni matériel de clé ni contenu de document, si bien que le stocker à côté du PDF préparé dans une ligne de base de données ou un magasin d'objets se fait sans souci

Cela rend le cas de l'application web direct. Un gestionnaire de requêtes prépare le fichier et stocke les deux artefacts, le navigateur ou une appli téléphone approuve le condensé, et un gestionnaire de callback sur un autre nœud charge la session et la complète. La contrainte porte sur le PDF préparé : il doit revenir octet pour octet. Le réenregistrer via une bibliothèque PDF, le passer dans un optimiseur, ou laisser une couche de transfert toucher aux fins de ligne changent tous l'empreinte

Un service de signature qualifiée facturé à l'opération fait payer chaque opération, aussi vaut-il la peine de vérifier le fichier stocké avant même de demander une signature. L'esquisse ci-dessous compare le haché du fichier avec PreparedFingerprint à l'aide de System.Hash de la RTL Delphi ; c'est une vérification que vous ajoutez vous-même, et la complétion la répète de toute façon

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

// Vérification de pré-flight suggérée à ajouter vous-même ; ne fait pas partie du composant
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // La surcharge TStream de GetHashBytes exige un System.Hash Delphi récent ;
    // Lazarus n'a pas de System.Hash, appelez donc votre propre routine SHA-256 là-bas
    H := THashSHA2.GetHashBytes(S);   // SHA-256 par défaut
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

Dimensionner ContentsSize avant que le CMS existe

ContentsSize compte des octets de CMS DER. L'espace réservé dans le fichier compte deux fois plus de caractères hexadécimaux, voilà pourquoi le défaut de 16384 produit les 32 768 zéros du paragraphe d'ouverture. Les valeurs sous 1024 sont remontées à 1024, une valeur au-dessus de 64 Mio est refusée à la préparation, et la complétion refuse tout CMS plus long que ContentsSize octets

Trop petit est l'erreur coûteuse : le service a déjà signé, l'opération est dépensée, et la seule voie qui reste est de préparer à nouveau avec un emplacement plus grand et de signer à nouveau. Trop grand ne coûte que du remplissage dans chaque fichier signé. Penchez vers le grand. Supposez que votre service renvoie un CMS d'environ 7 000 octets avec une chaîne de trois certificats ; le défaut laisse encore plus de la moitié de l'emplacement libre. Si le service incorpore aussi un jeton d'horodatage de signature ou des données de révocation comme attributs non signés, tout cela atterrit dans le même CMS et compte contre la même limite, alors mesurez une vraie réponse de votre chaîne de production et dimensionnez à partir de là, avec de la marge pour une chaîne d'intermédiaires plus longue plus tard

Après la complétion : B-B, puis LTV et vérification

Une signature distante complétée est PAdES B-B. La validation à long terme ajoute un horodatage de document et du matériel de validation dans une mise à jour incrémentielle ultérieure avec un DSS et ses dictionnaires VRI par signature, décrite dans les signatures à long terme avec horodatages RFC 3161 et DSS. Cette étape tourne en local, car certificats, réponses OCSP et CRL n'ont pas besoin de la clé privée

Vérifiez la sortie par le même chemin qu'emprunterait une partie utilisatrice, comme le couvre l'inspection des signatures numériques et des niveaux PAdES. Dans un pipeline distant, le code qui construit le CMS vit sur le serveur de quelqu'un d'autre, et le premier endroit où sa sortie rencontre un vrai validateur devrait être votre propre build, avant vos clients

Les appels de signature distante sont livrés avec l'édition Enterprise de PDFium Component pour Delphi et Lazarus, aux côtés du code Pascal natif de signature, d'horodatage et de validation PAdES. La référence API et les téléchargements d'essai se trouvent sur la page produit PDFium Component