THotPDF.AddLoadedSignedSignatureField Method

Adds a signature field that is ready to sign to a loaded document. The field carries a signature dictionary with reserved /ByteRange and /Contents space, so SignPDFWithPFX, PreparePDFForSigning and InsertSignatureHex can sign it once the document is saved. Together with BeginIncrementalUpdate this is how an already signed PDF receives a second signature

Declaration

function AddLoadedSignedSignatureField(PageIndex: Integer; X1, Y1, X2, Y2: Single;
  const AFieldName: AnsiString; ContentsBytes: Integer = 8192;
  const SubFilter: AnsiString = 'adbe.pkcs7.detached';
  const Reason: AnsiString = ''; const Location: AnsiString = '';
  const ContactName: AnsiString = ''): Integer;

Unit

HPDFDoc

Parameters

Name	Purpose
`PageIndex`	Zero-based index of the loaded page that shows the signature widget
`X1`, `Y1`, `X2`, `Y2`	Widget rectangle in PDF user space (points, origin at the bottom left); the width and height must be positive
`AFieldName`	Name of the new signature field; it must not be empty and must not already exist in the document
`ContentsBytes`	Bytes reserved for the CMS signature (written as twice as many hex digits); it must hold the complete signature, including certificates and any timestamp token
`SubFilter`	Signature format, for example `adbe.pkcs7.detached` or `ETSI.CAdES.detached`
`Reason`, `Location`, `ContactName`	Optional `/Reason`, `/Location` and `/ContactInfo` entries of the signature dictionary

Return value

Returns the index of the new form field, or -1 when PageIndex is out of range

Usage notes

No page is current after BeginIncrementalUpdate or LoadFromFile, so use this method rather than THPDFPage.AddSignedSignatureField, which is meant for documents created with BeginDoc
In incremental mode the field, its signature dictionary, the updated AcroForm and the page /Annots are appended as a new revision. The bytes covered by earlier signatures are not changed, so those signatures stay valid, and the new signature covers the whole file
The AcroForm gets /SigFlags 3 (signatures exist, append only). Unlike the other AddLoaded* field methods, it does not add /NeedAppearances, which would ask viewers to rewrite a signed document
Sign the saved file with SignPDFWithPFX. For an external signer or HSM, read the file into an AnsiString, call PreparePDFForSigning to get the two byte ranges to hash, build the CMS over them and write its hex with InsertSignatureHex
Use AddLoadedSignatureField for an empty field that a viewer or another tool signs later

Example

PDF := THotPDF.Create(nil);
try
  PDF.BeginIncrementalUpdate('Signed.pdf');
  PDF.AddLoadedSignedSignatureField(0, 300, 120, 500, 160, 'Approver', 8192,
    'adbe.pkcs7.detached', 'Approved');
  PDF.SaveIncrementalUpdate('Prepared.pdf');
finally
  PDF.Free;
end;
// Signs the reserved field; the first signature stays valid
THotPDF.SignPDFWithPFX('Prepared.pdf', 'SignedTwice.pdf', 'Signer.pfx', 'password');