Technisch artikel

PDFium VCL remote PAdES-ondertekening: HSM en cloudsleutels

Een PAdES-handtekeningsplaceholder van 16.384 bytes staat in het bestand als 32.768 ASCII-nullen tussen hoekhaken, en elke byte van de PDF buiten die reeks is al gedekt door de hash die de ondertekenaar zal goedkeuren. Dat is het ongemakkelijke van ondertekenen met een sleutel die u niet kunt aanraken: het document moet zich committeren aan zijn uiteindelijke indeling voordat de CMS bestaat, en dan wachten, soms uren, terwijl een netwerk-HSM of een cloudondertekendienst een persoon vraagt het op een telefoon te bevestigen. Wat er tijdens dat wachten met het bestand gebeurt, bepaalt of de handtekening valideert

Waarom kan een externe sleutel niet SignPadesBytes gebruiken?

De gewone aanroep veronderstelt dat de privésleutel binnen de aanroep bereikbaar is. SignPadesBytes in PDFium Component bouwt de incrementele update, hasht het ByteRange, ondertekent met het certificaat dat CertificateThumbprint in de Windows-store aanwijst, en schrijft het afgeronde bestand voordat hij terugkeert. Voor een sleutel in de lokale store is dat precies de vorm die u wilt

Een qualified signature-creation device gerund door een trust service provider werkt zo niet. Een cloud-ondertekenings-API met een tweede-factorstap ook niet, en een HSM achter een wachtrij al evenmin. De uitwisseling is een gesprek: u stuurt een digest, iets buiten uw proces authenticeert een mens, en een CMS komt later binnen op een andere thread, in een andere request handler, misschien op een andere server. Een synchrone aanroep kan dat alleen modelleren door een thread op iemands telefoon te blokkeren

Daarom splitst het externe pad zich in twee aanroepen. PreparePadesRemoteSignature levert het voorbereide PDF-bestand en een klein aanvraagrecord op. CompletePadesRemoteSignature neemt het voorbereide bestand, het record en de teruggekomen DER-CMS, en schrijft het ondertekende bestand. Niets bindt de twee aanroepen aan hetzelfde proces

Het document voorbereiden met PreparePadesRemoteSignature

PreparePadesRemoteSignature leest de bron-PDF, plakt een incrementele update aan met een onzichtbaar handtekeningveld op de eerste pagina, en schrijft een handtekeningsdictionary met /Filter /Adobe.PPKLite en /SubFilter /ETSI.CAdES.detached. De /Contents-entry wordt gevuld met nullen van een vaste breedte, de vier ByteRange-getallen worden eromheen gepatcht, en de SHA-256 over die twee bereiken wordt Request.DocumentDigest. De originele bytes van het bronbestand blijven onaangeroerd; de update voegt alleen toe

Het uitvoerrecord, TPadesRemoteSigningRequest, heeft zes velden: FormatVersion, PreparedFingerprint (SHA-256 van het hele voorbereide bestand), DocumentDigest, de vier-elementen-ByteRange, ContentsHexOffset (waar de hexadecimale cijfers beginnen) en ContentsSize. Alleen de digest gaat naar de ondertekendienst. De rest bestaat opdat de tweede aanroep kan bewijzen dat hij dezelfde bytes afmaakt waar de digest vandaan kwam

Drie optieregels raken het voorbereide bestand, en een vierde raakt uw build. Als CommitmentTypeOid is gezet, draagt het dictionary geen /Reason, want ETSI EN 319 142-1 ziet het commitmenttype in de CMS en de PDF-reden als alternatieven; de ondertekendienst moet dan de commitment-type-indication in de ondertekende CMS-attributen schrijven. SigningTimeUtc wordt de /M-entry. Versleutelde bronnen worden ronduit geweigerd, dus ontsleutel eerst. De externe functies horen bij de Enterprise-editie: de unit FPdfPadesRemote moet worden gelinkt, anders geven de entrypoints in FPdfPades EPdfEnterpriseRequired

Tweefasen-flow voor PDFium remote PAdES in Delphi waarbij PreparePadesRemoteSignature de CMS-slot reserveert en de document-digest overhandigt aan een HSM of clouddienst, en CompletePadesRemoteSignature de teruggekomen CMS later in elk proces of op elke machine inbedt
Fase één reserveert de CMS-slot en geeft de document-digest door; fase twee inbedt de CMS die van de HSM of cloudsleutel terugkomt
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // linkt de Enterprise-implementatie

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;

  // Eigen code: geef de 32-byte-digest aan de HSM of ondertekenings-API
  SendDigestToSigningService(Request.DocumentDigest);
end;

Staat het document al open in een TPdf-component, dan slaat TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) de huidige staat op en bereidt vanuit die staat voor, met False als terugkeer wanneer er geen document actief is. De afronding en de sessiehelpers zijn ook class methods op TPdf, dus de tweede fase heeft helemaal geen geladen document nodig

Wat de ondertekendienst moet terugsturen

De 32 bytes in DocumentDigest zijn de waarde die de CMS moet meedragen in zijn ondertekende message-digest-attribuut. Het zijn meestal niet de bytes die de privésleutel ondertekent. RFC 5652 §5.4 zegt dat wanneer er ondertekende attributen zijn, de handtekening wordt berekend over de DER-codering van de attribuutverzameling, dus een dienst die een complete CMS teruggeeft doet die stap zelf, terwijl een kale HSM die alleen hashes ondertekent die aan u overlaat. In dat tweede geval bouwt uw code de SignedAttributes (content-type, message-digest, signing-certificate-v2), codeert ze als een SET OF met gesorteerde leden in DER, hasht dat, en vraagt de HSM de hash te ondertekenen. Een verkeerde sorteervolgorde levert een CMS op die er goed uitziet en toch cryptografisch niet verifieert; DER SET OF-sortering in ondertekende CMS-attributen doorloopt die valkuil

Wie de CMS ook assembleert, de afronding accepteert één specifieke vorm: een SignedData met precies één SignerInfo, detached (geen ingekapselde content), met ondertekende content-type- en message-digest-attributen, een digest-algoritme anders dan MD5 of SHA-1, en een geldig signing-certificate-v2-attribuut. Dat komt overeen met wat PAdES-baselinehandtekeningen onder ETSI EN 319 142-1 eisen, dus een dienst die al PAdES-compatibele CAdES-uitvoer produceert, past zonder extra werk

Wat weigert CompletePadesRemoteSignature?

CompletePadesRemoteSignature voert elke controle uit voordat hij één byte naar de doelstream wegschrijft, en elke weigering geeft EPadesCrypto met een melding die de gefaalde controle benoemt. Eerst wordt het aanvraagrecord zelf gecontroleerd: formatversie 1, 32-byte-vingerprint en digest, een ContentsSize tussen 1024 bytes en 64 MiB, een positieve hex-offset. Dan het voorbereide bestand:

  1. de opgeschreven offsets moeten binnen het bestand liggen, en het ByteRange moet exact aansluiten op de placeholder en de bestandslengte
  2. de < en > rond /Contents moeten er nog staan, en elk hexadecimaal cijfer ertussen moet nog 0 zijn
  3. de SHA-256 van het hele bestand moet gelijk zijn aan PreparedFingerprint, en de ByteRange-hash moet gelijk zijn aan DocumentDigest

Dan de CMS: hij moet één exacte DER-waarde zijn zonder bytes erachter, niet langer dan ContentsSize, van de ondersteunde SignedData-vorm, met signing-certificate-v2 aanwezig, en tot slot moet zijn message-digest-attribuut gelijk zijn aan DocumentDigest

Een tussen de fasen opnieuw gegenereerd voorbereid bestand verandert de vingerprint, ook als hij in een viewer identiek oogt. Een alles-is-nul-test op de placeholder vangt dubbele afronding af, waarbij een retry een tweede CMS over een handtekening schrijft die er al staat. De message-digest-vergelijking vangt het smerigste geval af: een correct gevormde CMS van uw eigen certificaat, ondertekend over een ander document omdat een wachtrij twee gelijktijdige sessies verwisselde. Dat bestand zou prima openen en een goedkeuring dragen die voor een ander contract bedoeld was

De signing-certificate-v2-controle gaat meer over conformiteit dan over integriteit. Een CMS zonder dat attribuut kan cryptografisch verifiëren en toch door een PAdES-validator worden afgekeurd, en het weigeren bij de afronding verplaatst die ontdekking van het validatierapport van een klant naar uw eigen logs. Waarom validators PAdES-handtekeningen afkeuren behandelt de andere attributen waar validators op letten

Afrondingspoort-diagram voor PDFium remote PAdES-ondertekening in Delphi waarbij CompletePadesRemoteSignature bestandsintegriteit, CMS-vorm en PAdES-conformiteit controleert en de ondertekende PDF alleen wegschrijft als elke controle slaagt
CompletePadesRemoteSignature controleert integriteit, CMS-vorm en PAdES-conformiteit voordat er ook maar één byte wordt weggeschreven
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;   // eigen code: DER-bytes, geen 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);   // eigen code: houd de exacte melding bij
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

Veel ondertekenings-API's geven de CMS als Base64 binnen JSON terug, soms met PEM-headers eromheen. Geef alleen de gedecodeerde DER door. Een afsluitende newline of een achtergebleven headerbyte laat de één-exacte-DER-waarde-controle falen, en dat is de bedoeling: het alternatief is een CMS die parseert met rommel erachter

Sessiebestanden tussen processen en machines

SavePadesRemoteSigningRequest schrijft een vast binair record van 120 bytes: een 8-byte PDRSIG01-magic, de formatversie, de hex-offset, ContentsSize, de vier ByteRange-waarden, en daarna de digest en de vingerprint. LoadPadesRemoteSigningRequest wijst alles af met de verkeerde grootte, verkeerde magic, data achter het record of een formatversie anders dan 1. Het record bevat geen sleutelmateriaal en geen documentinhoud, dus opslag naast de voorbereide PDF in een databaserij of object store is prima

Daarmee is het webapplicatiegeval eenvoudig. Eén request handler bereidt het bestand voor en bewaart beide artefacten, de browser of een telefoonapp keurt de digest goed, en een callbackhandler op een andere node laadt de sessie en rondt haar af. De beperking zit op de voorbereide PDF: hij moet byte voor byte terugkomen. Hem opnieuw opslaan via een PDF-bibliotheek, hem door een optimizer halen, of een transportlaag regeleindes laten aanraken, het veranderen allemaal de vingerprint

Een qualified-ondertekendienst rekent per operatie af, dus het loont om het bewaarde bestand te controleren voordat u überhaupt een handtekening vraagt. De schets hieronder vergelijkt de bestandshash met PreparedFingerprint via de System.Hash van de Delphi-RTL; het is een controle die u zelf toevoegt, en de afronding herhaalt haar toch al

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

// Voorgestelde preflight-controle die u zelf toevoegt; geen onderdeel van de component
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // De TStream-overload van GetHashBytes vraagt om een recente Delphi System.Hash;
    // Lazarus heeft geen System.Hash, roep daar dus uw eigen SHA-256-routine aan
    H := THashSHA2.GetHashBytes(S);   // standaard SHA-256
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

ContentsSize bepalen voordat de CMS bestaat

ContentsSize telt bytes aan DER-CMS. De placeholder in het bestand is tweemaal zoveel hexadecimale tekens, wat verklaart waarom de standaard van 16384 de 32.768 nullen uit de openingsalinea oplevert. Waarden onder 1024 worden naar 1024 opgetrokken, een waarde boven 64 MiB wordt bij de voorbereiding geweigerd, en de afronding weigert elke CMS langer dan ContentsSize bytes

Te klein is de dure fout: de dienst heeft al ondertekend, de operatie is verbruikt, en de enige weg vooruit is opnieuw voorbereiden met een grotere slot en opnieuw ondertekenen. Te groot kost alleen opvulling in elk ondertekend bestand. Kies liever aan de grote kant. Stel dat uw dienst een CMS van zo'n 7.000 bytes teruggeeft met een certificaatketen van drie; de standaard laat dan nog ruim de helft van de slot vrij. Embedt de dienst ook een signature-timestamp-token of intrekkingsdata als niet-ondertekende attributen, dan belanden die in dezelfde CMS en tellen ze mee voor dezelfde limiet, dus meet één echte respons uit uw productieketen en maak daar de maat van af, met ruimte voor een langere tussencertificatenketen later

Na de afronding: B-B, daarna LTV en verificatie

Een afgeronde externe handtekening is PAdES B-B. Langetermijnvalidatie (LTV) voegt een documenttijdstempel en validatiemateriaal toe in een latere incrementele update met een DSS en zijn per-handtekening-VRI-dictionaries, zoals beschreven in langetermijnhandtekeningen met RFC 3161-tijdstempels en DSS. Die stap loopt lokaal, want certificaten, OCSP-responsen en CRL's hebben de privésleutel niet nodig

Verifieer de uitvoer via hetzelfde pad dat een relying party zou volgen, zoals behandeld in digitale handtekeningen en PAdES-niveaus inspecteren. In een externe pijplijn woont de code die de CMS bouwt op iemand anders server, en de eerste plek waar diens uitvoer een echte validator tegenkomt zou uw eigen build moeten zijn, vóór uw klanten

De externe ondertekenaanroepen worden meegeleverd met de Enterprise-editie van PDFium Component voor Delphi en Lazarus, naast de native Pascal-code voor PAdES-ondertekening, tijdstempels en validatie. API-referentie en proefdownloads staan op de PDFium Component-productpagina