Technical Article

PDFium VCL Remote PAdES Signing: HSM and Cloud Keys

A PAdES signature placeholder of 16,384 bytes shows up in the file as 32,768 ASCII zeros between angle brackets, and every byte of the PDF outside that run is already covered by the hash the signer will approve. That is the awkward part of signing with a key you cannot touch: the document has to commit to its final layout before the CMS exists, then wait, sometimes for hours, while a network HSM or a cloud signing service asks a person to confirm on a phone. Whatever happens to the file during that wait decides whether the signature validates

Why can a remote key not use SignPadesBytes?

The ordinary call assumes the private key is reachable inside the call. SignPadesBytes in PDFium Component builds the incremental update, hashes the ByteRange, signs with the certificate named by CertificateThumbprint in the Windows store, and writes the finished file before it returns. For a key in the local store, that is exactly the shape you want

A qualified signature-creation device run by a trust service provider does not work that way. Neither does a cloud signing API with a second-factor step, or an HSM that sits behind a queue. The exchange is a conversation: you send a digest, something outside your process authenticates a human, and a CMS arrives later on a different thread, in a different request handler, maybe on a different server. A synchronous call can only model that by blocking a thread on someone's phone

So the remote path splits into two calls. PreparePadesRemoteSignature produces the prepared PDF and a small request record. CompletePadesRemoteSignature takes the prepared PDF, the record and the returned DER CMS, and writes the signed file. Nothing ties the two calls to the same process

Preparing the document with PreparePadesRemoteSignature

PreparePadesRemoteSignature reads the source PDF, appends an incremental update with an invisible signature widget on the first page, and writes a signature dictionary with /Filter /Adobe.PPKLite and /SubFilter /ETSI.CAdES.detached. The /Contents entry is filled with zeros of a fixed width, the four ByteRange numbers are patched in around it, and the SHA-256 over those two ranges becomes Request.DocumentDigest. The original bytes of the source file stay untouched; the update only appends

The output record, TPadesRemoteSigningRequest, has six fields: FormatVersion, PreparedFingerprint (SHA-256 of the whole prepared file), DocumentDigest, the four-element ByteRange, ContentsHexOffset (where the hex digits start) and ContentsSize. Only the digest goes to the signing service. The rest exists so the second call can prove it is completing the same bytes the digest came from

Three option rules affect the prepared file, and a fourth affects your build. When CommitmentTypeOid is set, the dictionary carries no /Reason, because ETSI EN 319 142-1 treats the commitment type in the CMS and the PDF reason as alternatives; the signing service then has to write the commitment-type-indication into the CMS signed attributes. SigningTimeUtc becomes the /M entry. Encrypted sources are refused outright, so decrypt first. The remote functions belong to the Enterprise edition: the unit FPdfPadesRemote must be linked, otherwise the entry points in FPdfPades raise EPdfEnterpriseRequired

Two-phase PDFium remote PAdES flow in Delphi where PreparePadesRemoteSignature reserves the CMS slot and hands the document digest to an HSM or cloud service, and CompletePadesRemoteSignature embeds the returned CMS in any process or machine later
Phase one reserves the CMS slot and hands off the document digest; phase two embeds the CMS that comes back from the HSM or cloud key
uses
  System.SysUtils, System.Classes, System.DateUtils,
  FPdfCrypto, FPdfPades,
  FPdfPadesRemote;   // links the Enterprise implementation

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;

  // Your own code: hand the 32-byte digest to the HSM or signing API
  SendDigestToSigningService(Request.DocumentDigest);
end;

If the document is already open in a TPdf component, TPdf.PreparePadesRemoteSignature(Prepared, Options, Request) saves the current state and prepares from that, returning False when no document is active. Completion and the session helpers are class methods on TPdf as well, so the second phase does not need a loaded document at all

What the signing service has to send back

The 32 bytes in DocumentDigest are the value the CMS must carry in its message-digest signed attribute. They are usually not the bytes the private key signs. RFC 5652 §5.4 says that when signed attributes are present, the signature is computed over the DER encoding of the attribute set, so a service that returns a complete CMS does that step itself, while a bare HSM that only signs hashes leaves it to you. In the second case your code builds the SignedAttributes (content-type, message-digest, signing-certificate-v2), DER-encodes them as a SET OF with sorted members, hashes that, and asks the HSM to sign the hash. Getting the sort order wrong yields a CMS that looks fine and fails cryptographic verification; DER SET OF sorting in CMS signed attributes walks through that trap

Whoever assembles the CMS, completion accepts one specific shape: a SignedData with exactly one SignerInfo, detached (no encapsulated content), with content-type and message-digest signed attributes, a digest algorithm other than MD5 or SHA-1, and a valid signing-certificate-v2 attribute. Those match what PAdES baseline signatures require under ETSI EN 319 142-1, so a service that already produces PAdES-compatible CAdES output fits without extra work

What does CompletePadesRemoteSignature refuse?

CompletePadesRemoteSignature runs every check before it writes a single byte to the destination stream, and each refusal raises EPadesCrypto with a message naming the failed check. The request record itself is checked first: format version 1, 32-byte fingerprint and digest, a ContentsSize between 1024 bytes and 64 MiB, a positive hex offset. Then the prepared file:

  1. the recorded offsets must lie inside the file, and the ByteRange must line up exactly with the placeholder and the file length
  2. the < and > around /Contents must still be in place, and every hex digit between them must still be 0
  3. the SHA-256 of the whole file must equal PreparedFingerprint, and the ByteRange hash must equal DocumentDigest

Then the CMS: it must be one exact DER value with no trailing bytes, no longer than ContentsSize, of the supported SignedData shape, with signing-certificate-v2 present, and finally its message-digest attribute must equal DocumentDigest

A prepared file regenerated between phases changes the fingerprint even when it looks identical in a viewer. An all-zero test on the placeholder catches double completion, where a retry writes a second CMS over a signature that is already there. The message-digest comparison catches the nastiest case: a correctly formed CMS from your own certificate, signed over a different document because a queue swapped two concurrent sessions. That file would open fine and carry an approval meant for another contract

The signing-certificate-v2 check is about conformance more than integrity. A CMS without it may verify cryptographically and still fail a PAdES validator, and refusing it at completion moves that discovery from a customer's validation report into your own logs. Why validators reject PAdES signatures covers the other attributes validators look for

Completion gate diagram for PDFium remote PAdES signing in Delphi where CompletePadesRemoteSignature checks file integrity, CMS shape, and PAdES conformance, writing the signed PDF only when every check passes
CompletePadesRemoteSignature validates integrity, CMS shape, and PAdES conformance before any byte is written
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;   // your own code: DER bytes, not 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);   // your own code: keep the exact message
      end;
    finally
      Dest.Free;
    end;
  finally
    Prepared.Free;
  end;
end;

Many signing APIs return the CMS as Base64 inside JSON, sometimes with PEM headers around it. Pass the decoded DER only. A trailing newline or a leftover header byte fails the one-exact-DER-value check, which is the intended result: the alternative is a CMS that parses with garbage after it

Session files across processes and machines

SavePadesRemoteSigningRequest writes a fixed 120-byte binary record: an 8-byte PDRSIG01 magic, the format version, the hex offset, ContentsSize, the four ByteRange values, then the digest and the fingerprint. LoadPadesRemoteSigningRequest rejects anything with the wrong size, wrong magic, trailing data or a format version other than 1. The record holds no key material and no document content, so storing it next to the prepared PDF in a database row or object store is fine

That makes the web-application case straightforward. One request handler prepares the file and stores both artifacts, the browser or a phone app approves the digest, and a callback handler on another node loads the session and completes it. The constraint is on the prepared PDF: it has to come back byte for byte. Re-saving it through a PDF library, running it through an optimizer, or letting a transfer layer touch line endings all change the fingerprint

A metered qualified-signature service charges per operation, so it pays to check the stored file before asking for a signature at all. The sketch below compares the file hash with PreparedFingerprint using the Delphi RTL's System.Hash; it is a check you add yourself, and completion repeats it anyway

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

// Suggested pre-flight check you add yourself; not part of the component
function PreparedFileStillMatches(const PreparedPath: string;
  const Request: TPadesRemoteSigningRequest): Boolean;
var
  S: TFileStream;
  H: TBytes;
begin
  S := TFileStream.Create(PreparedPath, fmOpenRead or fmShareDenyWrite);
  try
    // TStream overload of GetHashBytes needs a recent Delphi System.Hash;
    // Lazarus has no System.Hash, so call your own SHA-256 routine there
    H := THashSHA2.GetHashBytes(S);   // SHA-256 by default
  finally
    S.Free;
  end;
  Result := (Length(H) = Length(Request.PreparedFingerprint)) and
    CompareMem(@H[0], @Request.PreparedFingerprint[0], Length(H));
end;

Sizing ContentsSize before the CMS exists

ContentsSize counts bytes of DER CMS. The placeholder in the file is twice that many hex characters, which is why the default of 16384 produces the 32,768 zeros from the opening paragraph. Values below 1024 are raised to 1024, a value above 64 MiB is refused at prepare time, and completion refuses any CMS longer than ContentsSize bytes

Too small is the expensive mistake: the service has already signed, the operation is spent, and the only way forward is to prepare again with a larger slot and sign again. Too large only costs padding in every signed file. Lean toward the large side. Suppose your service returns a CMS of about 7,000 bytes with a three-certificate chain; the default still leaves more than half the slot free. If the service also embeds a signature timestamp token or revocation data as unsigned attributes, those land inside the same CMS and count against the same limit, so measure one real response from your production chain and size from that, with room for a longer intermediate chain later

After completion: B-B, then LTV and verification

A completed remote signature is PAdES B-B. Long-term validation adds a document timestamp and validation material in a later incremental update with a DSS and its per-signature VRI dictionaries, described in long-term signatures with RFC 3161 timestamps and DSS. That step runs locally because certificates, OCSP responses and CRLs do not need the private key

Verify the output with the same path a relying party would take, as covered in inspecting digital signatures and PAdES levels. In a remote pipeline the code that builds the CMS lives on someone else's server, and the first place its output meets a real validator should be your own build, ahead of your customers

The remote signing calls ship with the Enterprise edition of PDFium Component for Delphi and Lazarus, alongside the native Pascal PAdES signing, timestamping and validation code. API reference and trial downloads are on the PDFium Component product page