Chilkat.Pdf Class Overview

What the Class Is Used For

Use Chilkat.Pdf when an application needs to work with PDF signatures, certification signatures, embedded files, metadata, and verification information. The class is especially useful for signing workflows, countersigning existing PDFs, adding PDF/A-3-style attachments, extracting embedded files, and validating digital signatures. Since v11.7.0 it also covers everyday document processing: extracting text, filling templates by replacing text, watermarking, shrinking files, and encrypting or restricting PDFs.

Load and Inspect PDFs Open a PDF from a file or BinData, then inspect page count, embedded file count, and signature count.

Digitally Sign PDFs Sign with a certificate and private key, add visible signature appearance, request timestamp tokens, and create LTV-enabled signatures.

Verify Signatures Verify existing PDF signatures, retrieve signature details, and access the signer certificate.

Manage Attachments and Metadata Add or extract embedded files and read or update XMP metadata.

Process Document Content v11.7.0 Extract text, replace text, add or remove watermarks, optimize file size, and encrypt or set permissions. See the section below.

New in v11.7.0: Document Processing

Version 11.7.0 adds five operation groups to Chilkat.Pdf. Each is a single method that takes an op string naming the operation, a JsonObject of options in, and a JsonObject of results out. Load the PDF first; operations that change the document work on the in-memory copy, which is then written with WriteFile or WriteBd. Each group has its own page documenting every JSON option with examples.

Feature	Methods	Operations (op)	What it does
Text Extraction	ExtractText, ExtractTextSb	text, markdown, search, tables, assess	Returns a PDF's text as plain text, Markdown, search matches, or detected tables, located by page and by label ("Invoice Number:"). Every call includes a quality report that says how far the text can be trusted and which pages need OCR.
Text Replacement	TextReplace	check, apply	Fills a PDF template by replacing {{placeholders}} and the values after labels directly in the page content, drawn with the font and size of the text replaced. check reports beforehand whether every replacement is possible; apply is all or nothing.
Watermarking	Watermark	add, detect, list, remove	Adds text, image, or PDF-page watermarks with control over placement, styling, and storage; then detects, lists, and removes watermarks — Chilkat's own, Acrobat's, and the standard forms other tools write.
Optimization	Optimize	audit, optimize	Shrinks a PDF without changing how any page looks: recompresses, deduplicates, subsets fonts, and tidies the file. audit reports where the bytes go and what each option would save before anything is changed.
Protection	Protection, PreLoadCheck, PreLoadCheckBd, AddEncryptCert, ClearEncryptCerts, SetDecryptCert	encrypt, removeEncryption, removeRestrictions, changePasswords, changePermissions, getInfo	Encrypts with passwords (RC4 to AES-256-GCM) or for certificate recipients, sets permissions, changes passwords or permissions, removes encryption, and reports a document's security before it is loaded.

Typical pattern: load, call the method with op and the options JSON, read the results JSON, then write the PDF if the operation changed it. The non-modifying operations (assess, check, detect, list, audit, getInfo) let an application decide what to do before touching the document.

Typical Workflow: Load and Inspect a PDF

Create a Pdf object.
If the PDF is password protected, set UserPassword or OwnerPassword before loading.
Load the PDF with LoadFile or LoadBd.
Inspect NumPages, NumSignatures, NumEmbeddedFiles, and HasCertificationSig.
Use specialized methods such as GetMetadata, GetUnsignedSigFields, GetEmbeddedFileInfo, or GetDss as needed.
Check LastErrorText after failures or unexpected behavior.

Typical Workflow: Sign a PDF

Load the PDF with LoadFile or LoadBd.
Set the signing certificate with SetSigningCert or set both certificate and private key with SetSigningCert2.
Optionally call AddSigningCert when a single signing operation should use multiple certificates.
Optionally call SetHttpObj if TSA, OCSP, proxy, or LTV-related HTTP settings are needed.
Optionally call SetSignatureJpeg if a custom JPG should appear in the visible signature.
Build the signature options in a JsonObject, including placement, appearance, reason, location, timestamp, LTV, DocMDP, or field-selection options.
Call SignPdf to write a signed PDF file, or SignPdfBd to write the signed PDF to BinData.

Signing requirement: PDF signing requires both a certificate and the corresponding private key. The private key may be implicit when the certificate came from a PFX containing the private key, or when the certificate and private key are installed on Windows.

Core Concepts

Concept	Meaning	Important Members
Loaded PDF	Most operations act on the currently open PDF loaded into the Pdf object.	LoadFile, LoadBd
Approval Signature	A normal PDF signature. A PDF can contain any number of approval signatures.	SignPdf, VerifySignature, NumSignatures
Certification Signature	A certifying signature. A PDF can contain only one certification signature, and it must be the first signature in the document.	HasCertificationSig, lockAfterSigning, docMDP.add
Visible Signature Appearance	Optional signature rectangle containing text and/or graphics.	appearance.*, SetSignatureJpeg
Invisible Signature	A digital signature with no visual appearance on a page.	invisibleSignature
DSS / LTV	Long-term validation information stored in the PDF Document Security Store, including certificates, OCSP responses, and CRL information.	AddVerificationInfo, GetDss, ltvOcsp
Embedded Files	Files attached inside the PDF.	AddEmbeddedFiles, GetEmbeddedFileInfo, GetEmbeddedFileBd

Loading and Password Properties

Member	Purpose	Guidance
LoadFile	Loads a PDF file into the object in memory.	Call before inspecting, signing, verifying, embedding, or updating metadata.
LoadBd	Loads a PDF from a BinData object.	Use when the PDF is already in memory.
UserPassword	User password for opening a protected PDF, if required.	Set before loading a password-protected PDF when the user password is needed.
OwnerPassword	Owner password for the PDF, if required.	Set before loading when owner-level access is needed.

v11.7.0: to find out whether a PDF is encrypted and which passwords it needs before loading it, call PreLoadCheck or PreLoadCheckBd. To encrypt, change passwords or permissions, or remove encryption, use Protection. See PDF Encryption and Permissions.

Inspection Properties

Property	Meaning	Use Case
NumPages	Number of pages in the currently open PDF.	Use when selecting a page for visible signature placement.
NumSignatures	Number of digital signatures in the currently open PDF.	Use to iterate signatures with VerifySignature, GetSignatureContent, or GetSignerCert.
NumEmbeddedFiles	Number of embedded files in the currently open PDF.	Use to iterate attachments with GetEmbeddedFileInfo and GetEmbeddedFileBd.
HasCertificationSig	True if the currently open PDF has a certification signature.	Use before deciding whether to certify, countersign, or inspect document permissions.
LastErrorText	Diagnostic information for the last method or property access.	Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Embedded Files

Method / Property	Purpose	Important Details
AddEmbeddedFiles	Embeds one or more files and writes the updated PDF to a file.	The input JSON contains an array of file objects. On success, the updated PDF is written to outFilePath.
AddEmbeddedFilesBd	Same as AddEmbeddedFiles, but writes the updated PDF to BinData.	Use for memory-based workflows.
NumEmbeddedFiles	Number of embedded files in the open PDF.	Indexing begins at 0.
GetEmbeddedFileInfo	Gets information about the Nth embedded file.	Returns information in a JsonObject.
GetEmbeddedFileBd	Extracts the Nth embedded file into BinData.	The first embedded file is at index 0.

AddEmbeddedFiles JSON Member	Required?	Purpose
localFilePath	Required	Local file to embed in the PDF.
description	Required	Short description of the embedded file.
subType	Optional	MIME type such as application/xml or text/plain. If omitted, Chilkat chooses based on file extension.
embeddedFilename	Optional	Name to use inside the PDF when different from the local filename.
AFRelationship	Optional	Relationship of the embedded file. Possible values include Source, Data, Alternative, Supplement, and Unspecified. Default is Alternative.

Metadata

Method	Purpose	Output / Behavior
GetMetadata	Retrieves XMP metadata XML from the open PDF.	Loads metadata XML into a StringBuilder and returns true if metadata exists. If no metadata exists, clears the StringBuilder and returns false.
UpdateMetadata	Updates or adds XMP metadata.	Writes the updated PDF to a file.
UpdateMetadataBd	Updates or adds XMP metadata.	Writes the updated PDF to BinData.

Document Info during signing: The signing JSON can also include info.* members to add or update values in the PDF document’s /Info dictionary, such as Creator, Producer, Title, and custom names. Chilkat ignores ModDate and CreationDate in this area because ModDate is automatically set and CreationDate should not change.

Signing Certificate Setup

Method	Purpose	Use When
SetSigningCert	Specifies the certificate used for signing.	Use when the certificate implicitly provides access to the private key, such as from a PFX containing the private key or a Windows-installed certificate with associated private key.
SetSigningCert2	Specifies both certificate and private key for signing.	Use when the private key is supplied separately from the certificate.
AddSigningCert	Adds a certificate for a single signing operation with multiple certificates.	Call once per certificate. This is different from signing once, then signing again later with another certificate.

PDF Signing Methods

Method	Output	Purpose
SignPdf	Signed PDF file.	Signs the open PDF according to JSON options and writes the result to an output file path.
SignPdfBd	Signed PDF in BinData.	Same as SignPdf, but writes the signed PDF to memory.
SetSignatureJpeg	Signature appearance image.	Sets custom JPG data for use when appearance.image is custom-jpg. JPG must be Baseline, not Progressive.
SetHttpObj	HTTP object for TSA/OCSP communication.	Use when timestamp authority requests, OCSP requests, proxies, or custom HTTP timeouts/settings are needed.

Signature allocation: SigAllocateSize defaults to 15000 and is usually left unchanged. Increase it only if signing fails with a message indicating that not enough space was allocated for the PDF signature.

Important Signing JSON Option Groups

Option Group	Examples	Purpose
Signature placement	page, appearance.x, appearance.y, appearance.width, appearance.height	Controls where the visible signature appears. The page value is 1-based.
Unsigned signature fields	appearance.fillUnsignedSignatureField, unsignedSignatureField	Signs an existing unsigned signature field and optionally chooses the field by name.
Visible appearance	appearance.text[i], appearance.fontScale, appearance.image, appearance.imagePlacement, appearance.imageOpacity	Controls text, font size, image, placement, and opacity for visible signatures.
Invisible signature	invisibleSignature	Creates a signature without a visible annotation.
Signature metadata	reason, location, contactInfo, legalAttestation, sigTextLabel	Adds signer-related descriptive information.
Certification / DocMDP	lockAfterSigning, docMDP.add, docMDP.accessPermissions	Creates a certifying signature and controls permitted document changes.
Cryptographic options	signingAlgorithm, hashAlgorithm, subFilter, embedCertChain, includeRootCert	Controls RSA padding, PSS hash algorithm, PDF signature subfilter, and certificate-chain inclusion.
Authenticated attributes	signingCertificateV2, signingTime	Adds common CMS authenticated attributes. These are desired in most cases.
Timestamp token	timestampToken.enabled, timestampToken.tsaUrl, timestampToken.tsaUsername, timestampToken.tsaPassword, timestampToken.bearerToken, timestampToken.requestTsaCert	Requests a timestamp token from a TSA server and includes it in the signature’s authenticated attributes.
LTV / DSS	ltvOcsp, noDss	Controls LTV-enabled signing and whether the Document Security Store is added.
PDF document info	info.*	Adds or updates entries in the PDF document’s /Info dictionary.

DocMDP Access Permission Levels

Value	Permission Level	Effect
1	No changes permitted.	Any changes invalidate the signature.
2	Forms, page templates, and signing.	Allows filling forms, instantiating page templates, and signing.
3	Level 2 plus annotations.	Same as level 2, and also allows annotation creation, deletion, and modification.

Certification signature: To create a certifying signature, specify both lockAfterSigning and docMDP.add. The default DocMDP permission level is 2.

Signature Appearance Text Keywords

Each visible signature text line can be supplied in appearance.text[i]. The text may contain keywords that Chilkat replaces with certificate details or current date/time values.

Keyword Group	Examples	Replacement Value
Certificate subject	cert_cn, cert_dn, cert_email, cert_organization, cert_ou	Fields from the signing certificate subject.
Certificate issuer and identity	cert_issuer_cn, cert_serial_dec, cert_serial_hex, cert_thumbprint	Issuer name, serial number, and certificate thumbprint values.
Certificate location details	cert_country, cert_state, cert_locality	Geographic fields from the certificate subject.
Current date/time	current_datetime, current_dt, current_rfc822_dt_gmt, current_rfc822_dt_local, current_timestamp_gmt, current_timestamp_local	Current local or GMT date/time in different formats.

Verification, Signer Certificates, and Signature Content

Method / Property	Purpose	Important Details
NumSignatures	Number of signatures in the currently open PDF.	Signature indexing begins at 0.
VerifySignature	Verifies the Nth signature in the PDF.	Populates a JsonObject with information about the validated or unvalidated signature.
GetSignerCert	Retrieves the signer certificate after calling VerifySignature.	Use the same signature index that was passed to VerifySignature.
GetSignatureContent	Returns the CMS signature for the Nth PDF signature.	Loads the CMS signature into BinData.
GetLastJsonData	Provides detailed JSON about what happened in the last method call when available.	Useful after signature verification to inspect algorithms used during verification.

Unsigned Signature Fields

Member	Purpose	Use Case
GetUnsignedSigFields	Returns JSON containing the names of unsigned signature fields found in the PDF.	Use before signing a specific pre-existing signature field.
appearance.fillUnsignedSignatureField	Tells Chilkat to sign an existing unsigned signature field.	Chilkat automatically scales the visual appearance to fit the existing field.
unsignedSignatureField	Specifies the unsigned signature field name to use.	If omitted, the first available unsigned field is used.

DSS and Long-Term Validation

Method / Option	Purpose	Important Details
AddVerificationInfo	Adds LTV verification information and writes the updated PDF to a file.	Creates or updates the PDF’s DSS with needed certificates, OCSP responses, and CRL information. Pass an empty JSON object for options.
GetDss	Retrieves the contents of the PDF Document Security Store.	Returns DSS information as JSON. If no DSS exists, returns an empty JSON object.
SetHttpObj	Supplies HTTP settings for TSA and OCSP communication.	Use when proxies, timeouts, or other HTTP settings are needed for timestamp or OCSP requests.
ltvOcsp	Signature option for creating an LTV-enabled signature.	Requests OCSP-related LTV behavior during signing.
noDss	Signature option to prevent adding a DSS.	Use only when a DSS should not be added during signing.

Uncommon Options and Signature Allocation

Member	Purpose	Guidance
SigAllocateSize	Space allocated for the PDF signature.	Default is 15000. Leave unchanged unless signing fails and LastErrorText says not enough signature space was allocated.
UncommonOptions	Comma-separated keywords for uncommon PDF writing or countersigning needs.	Normally empty. Set only when a documented option is required.

Uncommon Option	Behavior
WriteStandardXref	When writing the PDF, writes the cross-reference section in standard non-compressed format if possible.
NO_VERIFY_CERT_SIGNATURES	When countersigning, skips certificate validation for existing signatures. This can be useful when existing signatures validate but needed chain certificates are not embedded or otherwise available.

Method Summary by Category

Category	Methods / Properties	Purpose
Load PDF	LoadFile, LoadBd, UserPassword, OwnerPassword	Open PDFs from files or memory, including password-protected PDFs.
Inspect PDF	NumPages, NumSignatures, NumEmbeddedFiles, HasCertificationSig	Inspect page, signature, attachment, and certification-signature status.
Embedded files	AddEmbeddedFiles, AddEmbeddedFilesBd, GetEmbeddedFileInfo, GetEmbeddedFileBd	Add, inspect, and extract files embedded in a PDF.
Metadata	GetMetadata, UpdateMetadata, UpdateMetadataBd	Read, update, or insert XMP metadata.
Signing setup	SetSigningCert, SetSigningCert2, AddSigningCert, SetSignatureJpeg, SetHttpObj	Configure certificate, private key, visual signature image, and HTTP support for TSA/OCSP/LTV operations.
Sign PDF	SignPdf, SignPdfBd	Apply a visible, invisible, approval, or certifying digital signature.
Verify signatures	VerifySignature, GetSignerCert, GetSignatureContent, GetLastJsonData	Verify signatures, retrieve signer certificates, extract CMS signature content, and inspect verification details.
LTV / DSS	AddVerificationInfo, GetDss	Add or inspect Document Security Store information for long-term validation.
Unsigned fields	GetUnsignedSigFields	Find unsigned signature field names before filling a specific field.
Text extraction v11.7.0	ExtractText, ExtractTextSb	Get plain text, Markdown, search matches, or tables, with a quality report. See Text Extraction.
Text replacement v11.7.0	TextReplace	Fill placeholders and label values in page content; check first, then apply. See Text Replacement.
Watermarks v11.7.0	Watermark	Add text, image, or PDF-page watermarks; detect, list, and remove watermarks. See Watermarking.
Optimization v11.7.0	Optimize	Audit where a PDF's bytes go and shrink the file losslessly. See Optimization.
Encryption and permissions v11.7.0	Protection, PreLoadCheck, PreLoadCheckBd, AddEncryptCert, ClearEncryptCerts, SetDecryptCert	Encrypt with passwords or certificates, set or change permissions, remove encryption, and inspect security before loading. See Protection.

Diagnostics and Troubleshooting

Problem Area	Member	What to Check
PDF fails to load	LoadFile, LoadBd, UserPassword, OwnerPassword	Confirm the file or memory data is a valid PDF and set any required PDF password before loading.
Signing fails because of missing private key	SetSigningCert, SetSigningCert2	Ensure the signing certificate has access to the corresponding private key, or explicitly provide the private key with SetSigningCert2.
Signing fails because signature allocation is too small	SigAllocateSize	Increase the allocation size if LastErrorText reports that not enough space was allocated for the PDF signature.
Custom JPG does not appear in signature	SetSignatureJpeg, appearance.image	Use a Baseline JPG and set appearance.image to custom-jpg.
Timestamp or OCSP request fails	SetHttpObj, timestampToken.*, ltvOcsp	Configure the HTTP object for proxies, timeouts, or authentication needed by the TSA or OCSP endpoints.
Need to sign a specific empty signature field	GetUnsignedSigFields, unsignedSignatureField, appearance.fillUnsignedSignatureField	List unsigned fields first, then choose the desired field by name in the signing JSON.
Signature verification fails or gives unexpected results	VerifySignature, GetLastJsonData, GetSignerCert	Inspect the signature info JSON, last JSON data, and signer certificate where available.
Countersigning fails because existing cert-chain validation is incomplete	NO_VERIFY_CERT_SIGNATURES	Use this uncommon option only when existing signatures are otherwise valid but required chain certificates are missing or unavailable.
Need operation details after failure	LastErrorText	Check diagnostic text after failed or unexpected load, sign, verify, embedded-file, metadata, LTV, DSS, TSA, or OCSP operations.

Common Pitfalls

Pitfall	Better Approach
Trying to sign without access to the private key.	Use SetSigningCert2 when the private key is not implicitly available from the certificate.
Confusing approval signatures and certification signatures.	Use a normal approval signature unless the PDF should be certified and locked. A PDF can have many approval signatures but only one certification signature, and it must be first.
Using zero-based page numbering in signing options.	The page option for signature placement uses page 1 as the first page.
Using one-based indexing for signatures or embedded files.	Signature and embedded-file indexes begin at 0.
Expecting GetSignerCert to work before verification.	Call VerifySignature first, then call GetSignerCert with the same index.
Using a Progressive JPG for the custom signature image.	Use a Baseline JPG for SetSignatureJpeg.
Assuming all PDFs already contain a DSS.	Use GetDss to check. If no DSS exists, an empty JSON object is returned.
Skipping LastErrorText after a failed PDF operation.	PDF signing and verification failures often require diagnostic details from LastErrorText.

Best Practices

Recommendation	Reason
Inspect the PDF before modifying it.	NumPages, NumSignatures, NumEmbeddedFiles, and HasCertificationSig help determine the correct workflow.
Use SetSigningCert2 when certificate and private key are separate.	It makes the signing credentials explicit and avoids private-key lookup ambiguity.
Use GetUnsignedSigFields before signing an existing field.	It helps avoid accidentally signing the wrong unsigned signature field.
Use SetHttpObj for timestamping and LTV workflows.	TSA and OCSP requests may require proxies, authentication, or custom timeout settings.
Use AddVerificationInfo when LTV material needs to be added after signing.	It creates or updates the DSS with certificates, OCSP responses, and CRL information.
Use BinData methods for memory-only workflows.	LoadBd, SignPdfBd, AddEmbeddedFilesBd, and UpdateMetadataBd avoid intermediate files.
Keep UncommonOptions empty unless a documented edge case applies.	These options alter lower-level behavior and should be used deliberately.
Check LastErrorText and GetLastJsonData when troubleshooting.	LastErrorText gives diagnostic text, while GetLastJsonData can provide structured details for some operations, such as signature verification.

Summary

Chilkat.Pdf is the Chilkat class for PDF signing, signature verification, embedded files, metadata, and LTV/DSS-related operations. It can load PDFs from files or memory, inspect pages, signatures, and attachments, add embedded files, update metadata, configure signing certificates and private keys, create visible or invisible signatures, certify and lock PDFs, request timestamp tokens, verify existing signatures, retrieve signer certificates, inspect or add DSS information, and write updated PDFs to files or BinData. As of v11.7.0 it also extracts text (ExtractText), fills templates (TextReplace), adds and removes watermarks (Watermark), reduces file size (Optimize), and encrypts or sets permissions (Protection).

The most important practical guidance is to load the PDF first, set passwords when required, ensure the signing certificate has access to the private key, use the signing JSON to control appearance and signature behavior, remember that page numbers are 1-based while signature and embedded-file indexes are 0-based, and inspect LastErrorText whenever a PDF operation fails or behaves unexpectedly.