THPDFHeadlessDocument.SignToFile

function SignToFile(FieldIndex: Integer; const FileName: string;
  const CertificatePEM, PrivateKeyPEM: SysUtils.TBytes;
  const Options: THPDFHeadlessCMSOptions;
  ReservedCMSBytes: Integer = 16384): THPDFHeadlessCMSResult;

Signs an existing unsigned AcroForm signature field and atomically publishes a separate output on native Linux or Windows

FieldIndex is the zero-based form-field index returned by FindFormField or GetFormField, which may differ from the signed-signature index accepted by VerifySignature

The certificate and matching private key must be PEM bytes; encrypted private keys are rejected without prompting, and OpenSSL 3 is loaded via the same provider used by HPDFSignHeadlessCMS

ReservedCMSBytes reserves a fixed hexadecimal Contents gap before hashing; it must be positive, fit within the document object budget and accommodate the complete generated CMS DER

The default profile is adbe.pkcs7.detached; RequireCAdES=true writes ETSI.CAdES.detached and includes a signing-certificate attribute, document verification automatically authenticates its ESS binding, with explicit CA trust evaluated separately

The writer copies the source bytes, appends replacement field values and a new signature object through the shared xref writer, patches fixed-width ByteRange slots, signs the actual staging-file ranges and verifies the resulting CMS before flushing and atomic publication

Each older approval signature retains its exact original bytes; its verification result reports a valid earlier revision together with the number of later unsigned bytes

The source is opened read-only, the loaded field graph is unchanged by signing, and source path aliases or physical file aliases are refused

Failures preserve an existing destination and delete the unpublished staging file, including cancellation, insufficient reservations, certificate/key failures, cryptographic errors and object or file budget exhaustion

Read-only fields, signed field values, disallowed certified-document policies and denied AES form-fill permissions are rejected; owner authentication can authorise restricted sources, whilst output retains the original user password and security policy

CertificationPermission from 1 to 3 creates a first certification signature with catalog Perms.DocMDP and a SigRef transform; zero creates an approval signature, including a permitted subsequent signature in an existing field under DocMDP P2 or P3

The document and CMS options must use the same cancellation token if both specify one; otherwise the CMS provider inherits the document token

The returned THPDFHeadlessCMSResult separates integrity from explicitly evaluated CA trust; no timestamp, revocation or long-term validation conclusion is implied

Use AddSignatureField and SetSignatureFieldAppearance to prepare a new visible signature widget, or SignPFXToFile to load a PKCS12 identity via OpenSSL 3

Use TimestampToFile to append a standalone RFC3161 document timestamp without an application signing identity