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
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:
- de opgeschreven offsets moeten binnen het bestand liggen, en het ByteRange moet exact aansluiten op de placeholder en de bestandslengte
- de
<en>rond/Contentsmoeten er nog staan, en elk hexadecimaal cijfer ertussen moet nog0zijn - de SHA-256 van het hele bestand moet gelijk zijn aan
PreparedFingerprint, en de ByteRange-hash moet gelijk zijn aanDocumentDigest
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
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