TPDFlibSigner

Security and Signatures

Description

TPDFlibSigner is the standalone signing engine that pairs a TPDFlibSignDoc target with a TPDFlibPFXFile identity and writes the finished signature as a new incremental revision

Open the PDF from a file, stream, or string, bind the identity with one of the open methods, select the target field, configure the signature, then finish with AppendToFile, AppendToStream, or ApplySignature

The class covers the full signing feature set: digest choice, content reservation and estimation, revocation info, commitment types, signature policies, legal attestations, DocMDP certification levels, field locks, document timestamps and passthrough signatures of a fixed length

The facade exposes the same pipeline through the documented SignProcess functions; use this class directly when the signing workflow must be embedded in a larger custom revision writer

Syntax

Delphi

TPDFlibSigner = Class
  Public
    Constructor Create;
    Destructor Destroy; Override;
    Function OpenPDF(Const FileName: WideString; Const Password: WideString): TPDFlibSignerResult;
    Function OpenPDFStream(SourceStream: TStream; Const Password: WideString): TPDFlibSignerResult;
    Function OpenPDFString(Const SourceString: AnsiString; Const Password: WideString): TPDFlibSignerResult;
    Function OpenPFX(Const FileName: WideString; Const Password: AnsiString; UseMachineKeyset: Boolean): TPDFlibSignerResult;
    Function OpenCertStore(Const StoreName, CertName: WideString; UseMachineStore: Boolean): TPDFlibSignerResult;
    Function OpenCertContext(CertContext: Pointer): TPDFlibSignerResult;
    Function OpenEd25519(Const CertificateDER, PrivateKeyDER: AnsiString): TPDFlibSignerResult;
    Function OpenEd25519FromFile(Const CertificateFile, PrivateKeyFile: WideString): TPDFlibSignerResult;
    Function OpenCNGKey(Const CertificateDER: AnsiString;
      Const ProviderName, KeyName: WideString; UseMachineKey, AllowUI: Boolean): TPDFlibSignerResult;
    Function OpenCNGKeyHandle(Const CertificateDER: AnsiString; KeyHandle: TPLIntPtr; AllowUI: Boolean): TPDFlibSignerResult;
    Function OpenExternalDigestSigner(Const CertificateDER: AnsiString;
      Signer: TPDFlibExternalDigestSignEvent; Sender: TObject;
      SignProcessID, SignatureAlgorithm, SignatureReserveBytes: Integer): TPDFlibSignerResult;
    Procedure SetPrivateKeyUI(AllowUI: Boolean);
    Procedure SetRSAPSSPadding(Enable: Boolean);
    Procedure SetLegalAttestation(Const Value: WideString);
    Procedure SelectField(Const FieldName: WideString; FieldPage: Integer);
    Procedure SetSignatureProperty(SignatureProperty: TPDFlibSignatureProperty; Const NewValue: AnsiString);
    Procedure SetAppearanceText(Const Text: WideString; FontSize, FontRed, FontGreen, FontBlue: Double);
    Procedure SetSignatureBounds(Left, Top, Width, Height: Double);
    Procedure SetPassthrough(SignatureLength: Integer);
    Procedure SetDocTimeStamp(SignatureLength: Integer);
    Procedure SetDigestAlgorithm(Algorithm: TPDFlibDigestAlgorithm);
    Procedure SetContentsReserveBytes(ExtraBytes: Integer);
    Procedure SetContentsEstimate(ChainBytes, CRLBytes, OCSPBytes, TimeStampBytes, SafetyMarginPercent: Integer);
    Procedure SetRevocationInfo(Const RevocationInfoDER: AnsiString);
    Procedure SetCommitmentType(CommitmentType: Integer);
    Procedure SetDocMDP(Level: Integer);
    Function SetFieldLock(Const Action: AnsiString; Const Fields: TArray): Boolean;
    Procedure SetSignaturePolicy(Const PolicyOID: AnsiString; Const PolicyHashBytes: AnsiString; HashAlgorithm: TPDFlibDigestAlgorithm);
    Function AppendToFile(Const FileName: WideString): Boolean;
    Function AppendToStream(TargetStream: TStream): Boolean;
    Function ApplySignature: Boolean;
    Function GetByteRange(Index: Integer): Int64;
    Function GetEstimatedContentsBytes: Integer;
    Procedure SetInPlace;
    Property IsDocTimeStamp: Boolean Read FIsDocTimeStamp;
  End;

Methods

OpenPDF, OpenPDFStream, OpenPDFString	Open the document to sign from a file, stream, or ANSI string
OpenPFX, OpenCertStore, OpenCertContext	Bind a PFX file, a system-store certificate by display name, or an external certificate context
OpenEd25519, OpenEd25519FromFile	Bind an Ed25519 key pair from memory or files
OpenCNGKey, OpenCNGKeyHandle	Bind a CNG key by provider and key name, or by key handle
OpenExternalDigestSigner	Delegate the digest signature to an external callback
SelectField	Chooses the signature field by fully qualified name and page
SetSignatureProperty	Sets one of `spReason`, `spLocation`, `spContactInfo`, `spFieldImage`, `spSubFilter` and `spFieldImageOptions`
SetAppearanceText	Stores the auto-generated visible text block written into the field appearance at append time
SetSignatureBounds	Places the field at explicit coordinates
SetPassthrough	Produces a passthrough signature of exactly the given length for external signing
SetDocTimeStamp	Switches the signature to a document timestamp
SetDigestAlgorithm	Selects the digest used for the signature
SetContentsReserveBytes, SetContentsEstimate	Reserve extra bytes or size the reservation from chain, CRL, OCSP and timestamp estimates plus a safety margin
SetRevocationInfo	Embeds pre-collected revocation data in DER form
SetCommitmentType, SetSignaturePolicy, SetLegalAttestation	Declare the signing intent, policy and legal attestation
SetDocMDP	Enables a certifying signature at DocMDP level 1, 2 or 3; must be called before `SelectField`
SetFieldLock	Writes a field lock dictionary with an action and field-name list
AppendToFile, AppendToStream	Write the signed revision to a new file or stream
ApplySignature	Applies the signature to the in-place document
GetByteRange, GetEstimatedContentsBytes	Read back the ByteRange entry and the estimated contents size after the revision is built
SetInPlace	Marks the revision as an in-place update of the open document

Fields

IsDocTimeStamp	True when the signer is producing a document timestamp

Remarks

Every open method returns TPDFlibSignerResult

DocMDP levels map to the ISO 32000 transform P value: 1 no changes, 2 form filling, 3 annotations; when non-zero the AcroForm /SigFlags AppendOnly bit is set so viewers enforce the certification