THPDFHeadlessDocument.TimestampToFile
function TimestampToFile(FieldIndex: Integer; const FileName: string;
const Options: THPDFHeadlessCMSOptions;
ReservedTimestampBytes: Integer = 16384): THPDFHeadlessCMSResult;Creates a real document timestamp in an existing unsigned signature field and atomically publishes an independent incremental PDF output
FieldIndex is the zero-based form-field index returned by FindFormField; it differs from the populated signature index accepted by VerifySignature
The output dictionary uses Type DocTimeStamp and SubFilter ETSI.RFC3161, with a genuine DER timestamp token in its unencrypted Contents reservation
DigestMethod selects SHA256, SHA384, or SHA512 for the exact covered PDF ByteRange; the writer patches the numeric ranges before requesting the token
Timestamp.Transport must return a real RFC 3161 response, and Timestamp.TrustedCAFile must explicitly identify trusted TSA roots; optional TrustedCRLFile and RequireRevocation validate current issuer-signed CRLs
The response must bind the exact message imprint and fresh request nonce, use an appropriate TSA certificate and ESS binding, and pass its immediate signature, purpose, chain, and configured revocation checks before publication
No application signing key or signer certificate is needed; required signature certificate constraints evaluate the actual authenticated TSA certificate and embedded certificate chain
Required signature seed handler, RFC3161 SubFilter, digest, reason, timestamp URL, certificate subject and issuer, and current named appearance constraints remain effective
Authenticated DocMDP and FieldMDP checks allow only the changes necessary to insert a genuine document timestamp, including insertion into an existing unsigned signature field under P1 or a field lock; this standard exception does not permit ordinary approval signing or form changes that the original policy prohibits
Later modification checks authenticate the timestamp, bind the field and signature to its timestamped revision, and continue to protect the original certified object graph and locked fields
For a source before PDF 2.0, the output adds the ESIC extension declaration with BaseVersion 1.7 and ExtensionLevel 1 when needed, preserves existing extension profiles, and promotes an older effective PDF version through Catalog Version 1.7 without altering the original header
Read-only fields, source aliases, and AES form-fill permissions remain enforced; incompatible approval certification, LegalAttestation, Adobe signed revocation profiles, and timestamp FieldMDP transform references are rejected
ReservedTimestampBytes is a positive token capacity within the document object budget; the complete token must fit the fixed hexadecimal reservation
Creation preserves original source bytes and AES security, keeps signature Contents unencrypted, encrypts other metadata under the original policy, and leaves the loaded field graph unchanged
Failures, cancellation, invalid responses, and insufficient budgets preserve any existing destination and remove unpublished staging files
The document, CMS, and timestamp cancellation tokens must agree when non-nil; covered data is read in chunks of at most 64 KiB
Use AddSignatureField and SetSignatureFieldAppearance to prepare a new timestamp widget, and VerifySignature to authenticate the resulting document timestamp
TimestampCount is one and TimestampValid is true after successful creation; CertificateTrusted and TimestampTrustEvaluated reflect the explicit validated TSA trust pass
The extension profile follows ETSI EN 319 142-1, clause 5.6; necessary timestamp changes follow the ISO 32000-2 MDP clarification