PDFSign Component

Properties   Methods   Events   Config Settings   Errors  

The PDFSign component signs PDF documents.

Syntax

nsoftware.SecurePDF.PDFSign

Remarks

The PDFSign component can sign PDF documents in accordance with a selection of PDF and PAdES signature standards, including basic Adobe signatures (ISO 32000) and PAdES signatures (ETSI EN 319 142-1).

Preparing the Signature

Optionally specify the Signature* properties and the TimestampServer property, and adjust any chain validation parameters as necessary (please see the Chain Validation Setup section for more details). Finally, call the Sign method.

PDFSign also provides means to customize the appearance of the signature widget to be shown on the document page. You can create your very own signatures (e.g., in the form of your company's logo) by adjusting the widget properties available in the SetWidgetProperty method. Alternatively, you can choose not to associate any widget with your signature by setting the Invisible widget property to true.

The Signing Process

If an external TSA server was provided via the TimestampServer property, the component will also contact it to timestamp the new signature.

During signing, PDFSign may fire events to notify your code about certain conditions. For example, if the input document is encrypted but no decryption parameters were found in the Password or DecryptionCert properties, the component will fire either the Password or RecipientInfo event to tell your code that it needs decryption information to be able to continue with the signing. Additionally, the SSLServerAuthentication event will fire if one of the HTTP endpoints involved during the operation (which may be a TSA, CRL, OCSP, or Trusted List service) operates over TLS and needs its certificate to be validated.

Basic Adobe Signatures

PAdES Signatures and Profiles

PAdES B-B

The PAdES B-B profile is the baseline profile that uses the PAdES-BES signature level by default, meaning the signature only contains the signing time and signer information.

Use the following code to create a B-B signature: pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "signed.pdf"; pdfsign.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*"); pdfsign.SignatureProfile = PDFSignSignatureProfiles.pfBaselineB; pdfsign.ValidationPolicy = PDFSignValidationPolicies.vpNone; pdfsign.Sign(); PAdES-EPES

To instead create a PAdES-EPES signature that includes the signature-policy-identifier attribute, set the PolicyHash, PolicyHashAlgorithm, and PolicyId configuration settings before calling the Sign method.

This profile, in both the BES and EPES settings, creates a basic signature that remains valid as long as the signing certificate has not expired or been revoked. Signatures at this level need not contain any validation material.

PAdES B-T

The PAdES B-T profile extends the basic BES or EPES signature by adding a signature timestamp. This timestamp certifies that the signature was created at a specific moment in time. Similar to the B-B profile, signatures at this level need not contain any validation material.

Use the following code to create a B-T signature: pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "signed.pdf"; pdfsign.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*"); pdfsign.SignatureProfile = PDFSignSignatureProfiles.pfBaselineT; pdfsign.TimestampServer = "https://freetsa.org/tsr"; pdfsign.ValidationPolicy = PDFSignValidationPolicies.vpNone; pdfsign.Sign(); PAdES B-LTA

The PAdES B-LTA profile is used to achieve signatures that are equipped with long-term archival (LTA) or long-term validation (LTV) capabilities. It incorporates into the signature all the material required to validate the signature, including signing certificates, timestamping certificates, and revocation information. It also adds a document timestamp, which certifies the integrity of both the document and the complete validation material at a specific moment in time. This guarantees that no relevant certificates were expired or revoked at the signature creation time, and enables the signature to be verified offline.

Creating a B-LTA signature with PDFSign is a two-step process. First Sign the document and add a signature timestamp, setting SignatureProfile appropriately. Then Update the signature to take care of the rest (collect and embed the validation material, and add a document timestamp): pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "signed.pdf"; pdfsign.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*"); pdfsign.SignatureProfile = PDFSignSignatureProfiles.pfBaselineLTA; pdfsign.TimestampServer = "https://freetsa.org/tsr"; pdfsign.Sign(); // Update the signature to LTV - this will retrieve the necessary revocation // elements, embed them into the document, and add a document timestamp pdfsign.Reset(); pdfsign.InputFile = "signed.pdf"; pdfsign.OutputFile = "updated.pdf"; pdfsign.TimestampServer = "https://freetsa.org/tsr"; pdfsign.Update(); Note that validation material "completeness" can be subjective and depends on several factors, including:

• The working environment. For example, your organization may explicitly trust its own self-signed TSA certificate. Signatures timestamped with this certificate will be considered B-LTA by your organization, but for any external bodies, those signatures would be rendered as B-LT or even B-B, as they do not know or trust the custom TSA certificate.
• The time that has passed since the last document timestamp. If an archived (B-LTA) document is not re-timestamped before its last timestamp expires, it will drop back to a lower signature level.

Chain Validation Setup

Note that these parameters apply to the Sign and Update methods in PDFSign as well as the Verify method in PDFVerify, as all three methods execute the chain validation procedure (if it is enabled).

Validation Policy

The ValidationPolicy property dictates how thoroughly the chain will be validated. It includes options to control which checks the component will perform, allowing you to tailor the validation process to meet your specific security needs. For example, if it is not essential to check each certificate's revocation status, set this property to vpFullNoRevocation.

Revocation

The revocation aspect of chain validation is controlled by the RevocationCheck property, which allows you to choose between and prioritize revocation origins. Note that OCSP sources are often preferred to CRL endpoints because of their real-time capability and the smaller size of the responses they produce.

Trust

The trust aspect of chain validation is controlled by the TrustSources property, which allows you to specify the locations in which the component will search for trust anchors. Local system stores, your own trusted root certificates (via the TrustedCerts property), and Trusted Lists (via the TrustedLists property) are all supported.

Offline Mode

The OfflineMode property provides the ability to verify the document without contacting online sources. If this property is enabled, the component will only use KnownCerts, TrustedCerts, data structures within the document itself, and revocation and Trusted List data that it previously saved to its internal cache when looking for missing validation material.

Property List

The following is the full list of the properties of the component with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the component with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the component with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the component with short descriptions. Click on the links for further details.

Attachments Property (PDFSign Component)

A collection of all attached files found in the PDF document.

Syntax

• C#
• VB.NET

public PDFAttachmentList Attachments { get; }

Public Property Attachments As PDFAttachmentList

Remarks

This property is used to access the details of all the attached files identified in the document. Use the AddAttachment, RemoveAttachment, and SaveAttachment methods to add, remove, and save attachments to/from this collection respectively.

This property is not available at design time.

BlockedCerts Property (PDFSign Component)

The certificates that must be rejected as trust anchors.

Syntax

• C#
• VB.NET

public CertificateList BlockedCerts { get; }

Public Property BlockedCerts As CertificateList

Remarks

This property is used to supply a list of compromised or blocked certificates to the component. Note that any chain containing a blocked certificate will fail validation.

This property is not available at design time.

DecryptionCert Property (PDFSign Component)

The decryption certificate.

Syntax

• C#
• VB.NET

public Certificate DecryptionCert { get; set; }

Public Property DecryptionCert As Certificate

Remarks

This property is used to provide the certificate used for decryption. Note that this certificate must have a private key associated with it.

This property is not available at design time.

DocumentCerts Property (PDFSign Component)

A collection of certificates read from the document during processing.

Syntax

• C#
• VB.NET

public CertificateList DocumentCerts { get; }

Public ReadOnly Property DocumentCerts As CertificateList

Remarks

This property is used to access all certificates encountered during document processing and embedded into the signature(s). When signing or verifying, this collection will be populated automatically during chain validation.

This property is read-only and not available at design time.

Firewall Property (PDFSign Component)

A set of properties related to firewall access.

Syntax

• C#
• VB.NET

public Firewall Firewall { get; set; }

Public Property Firewall As Firewall

Remarks

This is a Firewall-type property, which contains fields describing the firewall through which the component will attempt to connect.

InputData Property (PDFSign Component)

A byte array containing the PDF document to process.

Syntax

• C#
• VB.NET

public byte[] InputData { get; set; }

Public Property InputData As Byte()

Remarks

This property is used to assign a byte array containing the PDF document to be processed.

This property is not available at design time.

InputFile Property (PDFSign Component)

The PDF file to process.

Syntax

• C#
• VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

""

Remarks

This property is used to provide a path to the PDF document to be processed.

KnownCerts Property (PDFSign Component)

A collection of additional certificates for chain validation.

Syntax

• C#
• VB.NET

public CertificateList KnownCerts { get; }

Public Property KnownCerts As CertificateList

Remarks

This property is used to supply a list of additional certificates to the component that might be needed for chain validation. For instance, intermediary CA certificates may be absent from the standard system locations (or there may be no standard system locations) and therefore should be supplied to the component manually.

The purpose of this certificate collection is roughly equivalent to that of the Intermediate Certification Authorities system store in Windows.

Note: Do not add trust anchors or root certificates to this collection; add them to TrustedCerts instead.

This property is not available at design time.

OfflineMode Property (PDFSign Component)

Whether the component is operating in offline mode.

Syntax

• C#
• VB.NET

public bool OfflineMode { get; set; }

Public Property OfflineMode As Boolean

Default Value

False

Remarks

This property indicates whether the component should operate in offline mode.

In offline mode, the component restricts itself from accessing online Trusted Lists and revocation information sources such as CRLs or OCSP responders. It may be useful to set this property to true if there is a need to verify the completeness of the validation information included within the signature or provided via KnownCerts.

OutputData Property (PDFSign Component)

A byte array containing the PDF document after processing.

Syntax

• C#
• VB.NET

public byte[] OutputData { get; }

Public ReadOnly Property OutputData As Byte()

Remarks

This property is used to read the byte array containing the produced output after the operation has completed. It will only be set if an output file and output stream have not been assigned via OutputFile and SetOutputStream respectively.

This property is read-only and not available at design time.

OutputFile Property (PDFSign Component)

The path to a local file where the output will be written.

Syntax

• C#
• VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

This property is used to provide a path where the resulting PDF document will be saved after the operation has completed.

Overwrite Property (PDFSign Component)

Whether or not the component should overwrite files.

Syntax

• C#
• VB.NET

public bool Overwrite { get; set; }

Public Property Overwrite As Boolean

Default Value

False

Remarks

This property indicates whether or not the component will overwrite OutputFile, OutputData, or the stream set in SetOutputStream. If set to false, an error will be thrown whenever OutputFile, OutputData, or the stream set in SetOutputStream exists before an operation.

Password Property (PDFSign Component)

The password to decrypt the document with.

Syntax

• C#
• VB.NET

public string Password { get; set; }

Public Property Password As String

Default Value

""

Remarks

This property is used to provide the user password for decryption. Though it may be different from OwnerPassword, most implementations use the same value for both.

Proxy Property (PDFSign Component)

A set of properties related to proxy access.

Syntax

• C#
• VB.NET

public Proxy Proxy { get; set; }

Public Property Proxy As Proxy

Remarks

This property contains fields describing the proxy through which the component will attempt to connect.

RevocationCheck Property (PDFSign Component)

The kind(s) of revocation check to perform for all chain certificates.

Syntax

• C#
• VB.NET

public PDFSignRevocationChecks RevocationCheck { get; set; }

enum PDFSignRevocationChecks {
  rcAllCRL,
  rcAllOCSP,
  rcAllCRLAndOCSP,
  rcAnyCRL,
  rcAnyOCSP,
  rcAnyCRLOrOCSP,
  rcAnyOCSPOrCRL
}

Public Property RevocationCheck As PdfsignRevocationChecks

Enum PDFSignRevocationChecks
  rcAllCRL
  rcAllOCSP
  rcAllCRLAndOCSP
  rcAnyCRL
  rcAnyOCSP
  rcAnyCRLOrOCSP
  rcAnyOCSPOrCRL
End Enum

Default Value

6

Remarks

This property is used to specify the revocation sources and preferences the component will use during chain validation. Revocation checking is necessary to ensure the integrity of the chain and to obtain up-to-date certificate validity and trust information.

Certificate Revocation Lists (CRLs) and Online Certificate Status Protocol (OCSP) responses serve the same purpose of ensuring that the certificate has not been revoked by the Certificate Authority (CA) at the time of use. Depending on the circumstances and security policy requirements, either one or both of the revocation information source types may be used.

Possible values are:

This property controls the way revocation checks are performed for every certificate in the chain. Typically, certificates come with two types of revocation information sources: CRLs (Certificate Revocation Lists) and OCSP responses. CRLs are static objects periodically published by the CA at some online location. OCSP responders are active online services maintained by the CA that can provide up-to-date information on certificate statuses in near real time.

There are some conceptual differences between the two. CRLs are normally larger in size. Their use involves some latency because there is normally a delay between the time at which a certificate was revoked and the time at which the subsequent CRL mentioning that revocation is published. The benefits of CRLs are that the same object can provide statuses for all certificates issued by a particular CA, and that the whole technology is much simpler than OCSP (and thus is supported by more CAs).

This property allows the validation course to be adjusted by including or excluding certain types of revocation sources from the validation process. The rcAnyOCSPOrCRL setting (give preference to the faster OCSP route and only demand one source to succeed) is a good choice for most typical validation environments. The rcAll* modes are much stricter, and may be used in scenarios where bulletproof validity information is essential.

Note: If no CRL or OCSP endpoints are provided by the CA, the revocation check will be considered successful. This is because the CA chose not to supply revocation information for its certificates, meaning they are considered irrevocable.

Note: Within each of the above settings, if any retrieved CRL or OCSP response indicates that the certificate has been revoked, the revocation check fails.

SignatureAuthorName Property (PDFSign Component)

The human-readable name of the signer.

Syntax

• C#
• VB.NET

public string SignatureAuthorName { get; set; }

Public Property SignatureAuthorName As String

Default Value

""

Remarks

This property is used to specify the human-readable name of the signer.

Note: This property only applies when creating a new signature.

SignatureClaimedSigningTime Property (PDFSign Component)

The signature's creation time.

Syntax

• C#
• VB.NET

public string SignatureClaimedSigningTime { get; set; }

Public Property SignatureClaimedSigningTime As String

Default Value

""

Remarks

This property is used to specify the signature creation time from the signer's computer. The time should be provided in UTC in yyyyMMddHHmmssZ format.

Note: This property only applies when creating a new signature.

SignatureField Property (PDFSign Component)

The index of the empty signature field to sign.

Syntax

• C#
• VB.NET

public int SignatureField { get; set; }

Public Property SignatureField As Integer

Default Value

-1

Remarks

This property is used to specify the empty signature field that should be signed. If the default value of -1 is assigned to this property, a new signature field will be created.

Example: pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "emptyfield.pdf"; pdfsign.SignatureType = PDFSignSignatureTypes.stEmptyField; pdfsign.Sign(); // Later pdfsign.Reset(); pdfsign.InputFile = "emptyfield.pdf"; pdfsign.OutputFile = "signed.pdf"; pdfsign.SigningCert = new Certificate(CertStoreTypes.cstPFXFile, "cert.pfx", "password", "*"); pdfsign.SignatureField = 0; // Configure signature properties as desired pdfsign.Sign();

SignatureHashAlgorithm Property (PDFSign Component)

The hash algorithm to be used for signing.

Syntax

• C#
• VB.NET

public string SignatureHashAlgorithm { get; set; }

Public Property SignatureHashAlgorithm As String

Default Value

"SHA256"

Remarks

This property is used to specify the hash algorithm to be used for signing.

Possible values are:

• SHA1
• SHA224
• SHA256
• SHA384
• SHA512
• MD5

SignatureProfile Property (PDFSign Component)

The PAdES profile to apply when creating the signature.

Syntax

• C#
• VB.NET

public PDFSignSignatureProfiles SignatureProfile { get; set; }

enum PDFSignSignatureProfiles {
  pfNone,
  pfBaselineB,
  pfBaselineT,
  pfBaselineLT,
  pfBaselineLTA
}

Public Property SignatureProfile As PdfsignSignatureProfiles

Enum PDFSignSignatureProfiles
  pfNone
  pfBaselineB
  pfBaselineT
  pfBaselineLT
  pfBaselineLTA
End Enum

Default Value

0

Remarks

This property is used to specify a pre-defined PAdES profile to apply when creating the signature, as defined by ETSI.

Advanced signatures come in many variants, and they are often defined by parties that need to process them or by local standards. Profiles are sets of pre-defined configurations that correspond to particular signature variants. Specifying a profile pre-configures the component to make it produce the signature that matches the configuration corresponding to that profile.

Possible values are:

To apply a custom profile that is not defined by ETSI, set the CustomProfile configuration setting.

Note: This property only applies when creating a new signature.

SignatureReason Property (PDFSign Component)

The reason for signing.

Syntax

• C#
• VB.NET

public string SignatureReason { get; set; }

Public Property SignatureReason As String

Default Value

""

Remarks

This property is used to specify the reason for signing.

Note: This property only applies when creating a new signature.

Signatures Property (PDFSign Component)

A collection of all the signatures and empty fields found in the PDF document.

Syntax

• C#
• VB.NET

public PDFSignatureList Signatures { get; }

Public ReadOnly Property Signatures As PDFSignatureList

Remarks

This property is used to access the details of all the signatures and empty signature fields identified in the document.

This property is read-only and not available at design time.

SignatureType Property (PDFSign Component)

The type of signature to create.

Syntax

• C#
• VB.NET

public PDFSignSignatureTypes SignatureType { get; set; }

enum PDFSignSignatureTypes {
  stLegacy,
  stAdvanced,
  stDTS,
  stEmptyField
}

Public Property SignatureType As PdfsignSignatureTypes

Enum PDFSignSignatureTypes
  stLegacy
  stAdvanced
  stDTS
  stEmptyField
End Enum

Default Value

0

Remarks

This property is used to specify the type of the signature.

Possible values are:

Note: This property only applies when creating a new signature.

SignatureWidgetHeight Property (PDFSign Component)

The height of the signature widget.

Syntax

• C#
• VB.NET

public string SignatureWidgetHeight { get; set; }

Public Property SignatureWidgetHeight As String

Default Value

"70"

Remarks

This property is used to specify the height of the signature widget in points. Both integer and decimal values are supported.

Note: This property only applies when creating a new signature.

SignatureWidgetOffsetX Property (PDFSign Component)

The signature widget offset from the left-hand page border.

Syntax

• C#
• VB.NET

public string SignatureWidgetOffsetX { get; set; }

Public Property SignatureWidgetOffsetX As String

Default Value

"0"

Remarks

This property is used to specify the signature widget offset from the left-hand page border in points. Both integer and decimal values are supported.

Note: This property only applies when creating a new signature.

SignatureWidgetOffsetY Property (PDFSign Component)

The signature widget offset from the bottom page border.

Syntax

• C#
• VB.NET

public string SignatureWidgetOffsetY { get; set; }

Public Property SignatureWidgetOffsetY As String

Default Value

"0"

Remarks

This property is used to specify the signature widget offset from the bottom page border in points. Both integer and decimal values are supported.

Note: This property only applies when creating a new signature.

SignatureWidgetPages Property (PDFSign Component)

The pages to place the signature and its widget on.

Syntax

• C#
• VB.NET

public string SignatureWidgetPages { get; set; }

Public Property SignatureWidgetPages As String

Default Value

""

Remarks

This property is used to specify the pages on which the signature and its widget will be placed.

A variety of syntaxes are supported:

• A single page number: 3
• A comma-separated list of page numbers: 1,2,5,7
• The asterisk character (*) indicates that the widget should be placed on all pages in the document.
• The first and last placeholders specify that the signature should be placed on the respective page, independently of its number.

SignatureWidgetWidth Property (PDFSign Component)

The width of the signature widget.

Syntax

• C#
• VB.NET

public string SignatureWidgetWidth { get; set; }

Public Property SignatureWidgetWidth As String

Default Value

"70"

Remarks

This property is used to specify the width of the signature widget in points. Both integer and decimal values are supported.

Note: This property only applies when creating a new signature.

SigningCert Property (PDFSign Component)

The certificate to be used for signing.

Syntax

• C#
• VB.NET

public Certificate SigningCert { get; set; }

Public Property SigningCert As Certificate

Remarks

This property is used to provide the certificate used for signing the document. Note that this certificate must have a private key associated with it.

This property is not available at design time.

TimestampServer Property (PDFSign Component)

The address of the timestamping server.

Syntax

• C#
• VB.NET

public string TimestampServer { get; set; }

Public Property TimestampServer As String

Default Value

""

Remarks

This property is used to specify the address of the TSA (Timestamping Authority) server to use for timestamping the signature (normal signing) or the document (LTV update).

If the timestamping service enforces credential-based user authentication (basic or digest), the credentials can be provided in the same URL. For example: pdfsign.TimestampServer = "http://user:password@timestamp.server.com/TsaService"; If the TSA requires TLS client authentication, provide the client certificate via the TSATLSClientCertStoreType, TSATLSClientCertStore, TSATLSClientCertSubject, and TSATLSClientCertStorePassword configuration settings.

TrustedCerts Property (PDFSign Component)

A collection of trusted certificates for chain validation.

Syntax

• C#
• VB.NET

public CertificateList TrustedCerts { get; }

Public Property TrustedCerts As CertificateList

Remarks

This property is used to supply a list of trusted certificates to the component that might be needed for chain validation. For instance, root CA certificates may be absent from the standard system locations (or there may be no standard system locations) and therefore should be supplied to the component manually.

The purpose of this certificate collection is largely the same as that of the Windows Trusted Root Certification Authorities system store.

Use this property with extreme care as it directly affects chain verifiability; a wrong certificate added to the list of trusted certificates may result in bad chains being accepted and forfeited signatures being recognized as genuine. Only add certificates that originate from parties that are known and trusted.

This property is not available at design time.

TrustedLists Property (PDFSign Component)

A list of known Trusted Lists for chain validation.

Syntax

• C#
• VB.NET

public string TrustedLists { get; set; }

Public Property TrustedLists As String

Default Value

"%EUTL%"

Remarks

This property is used to supply a semicolon-separated list of URLs or paths of known Trusted Lists to the component for chain validation.

A Trusted List is an XML document that contains a government-issued list of CAs that have passed regulated compliance checks. When validating the chain, the component will consult the Trusted List to establish certificate trust, ensuring that the CA is legitimate and entitled to issue certificates of the kind being checked.

The default value is the special %EUTL% macro, which, if applicable, instructs the component to check the root certificate against up-to-date versions of the primary EU Trusted Lists from the EU LOTL. Custom values can be appended: component.TrustedLists = "%EUTL%;http://my.company/tsl;c:\tsls\mytsl.xml"; Note: The component will cache all Trusted Lists it downloads and uses during chain validation. This cache is shared between component instances within the same process. If this property contains a URL that is also present in the cache, the component will retrieve the cached data and reuse them in the current validation. If the data are invalid, the component will download a fresh Trusted List and add it to the cache.

TrustSources Property (PDFSign Component)

The trust sources to use during chain validation.

Syntax

• C#
• VB.NET

public PDFSignTrustSources TrustSources { get; set; }

enum PDFSignTrustSources {
  tsManual,
  tsLocal,
  tsTrustedLists,
  tsLocalAndTrustedLists
}

Public Property TrustSources As PdfsignTrustSources

Enum PDFSignTrustSources
  tsManual
  tsLocal
  tsTrustedLists
  tsLocalAndTrustedLists
End Enum

Default Value

3

Remarks

This property is used to specify the sources the component will use to establish certificate trust during chain validation.

Establishing trust for a particular certificate, when either signing or verifying, involves building a chain up to a valid trust anchor. This trust anchor is a root certificate that typically resides on the local system. If the certificate does not eventually chain up to a valid trust anchor, the chain is considered untrusted and therefore invalid.

Possible values are:

ValidationFlags Property (PDFSign Component)

Additional chain validation settings.

Syntax

• C#
• VB.NET

public int ValidationFlags { get; set; }

Public Property ValidationFlags As Integer

Default Value

0

Remarks

This property is used to specify additional settings that affect the overall flow of the chain validation.

Its value should be provided as a bitmask of the following flags:

ValidationPolicy Property (PDFSign Component)

The level at which to perform chain validation.

Syntax

• C#
• VB.NET

public PDFSignValidationPolicies ValidationPolicy { get; set; }

enum PDFSignValidationPolicies {
  vpNone,
  vpFull,
  vpFullNoTrust,
  vpFullNoRevocation,
  vpBestEffort
}

Public Property ValidationPolicy As PdfsignValidationPolicies

Enum PDFSignValidationPolicies
  vpNone
  vpFull
  vpFullNoTrust
  vpFullNoRevocation
  vpBestEffort
End Enum

Default Value

1

Remarks

This property is used to specify the overall validation policy the component will follow.

Possible values are:

Validation Policy Heuristics

Creating a new signature:

• For a basic signature with or without a timestamp, chain validation is not required, so it is recommended to use vpNone. This policy may also be used in test environments or on offline systems.
• For an LTV signature, use vpFull or vpFullNoTrust depending on whether trust checks are necessary in the current environment. If the signature is being created in an environment that does not match the prospective validation environment, consider vpFullNoTrust to validate the chain properly and fully without expecting good trust.

Updating or extending an existing signature:

• When updating a basic signature to LTV, similarly use vpFull or vpFullNoTrust as above.
• When extending an LTV signature, similarly use vpFull or vpFullNoTrust as above.

Validating an existing signature:

• For basic signature validation, use vpFullNoRevocation if trust checks, but not revocation checks, are necessary in the current environment. This policy may also be used on offline systems if the trust anchor is already available to the component.
• For archival validation, use vpFull to validate the chain properly and fully. This policy expects the trust anchor and all the revocation material to be available.

ValidationTime Property (PDFSign Component)

The time point at which the signature should be validated.

Syntax

• C#
• VB.NET

public string ValidationTime { get; set; }

Public Property ValidationTime As String

Default Value

""

Remarks

This property is used to specify the moment in time at which the signature validity should be established. The time should be provided in UTC in yyyyMMddHHmmssZ format.

Leave this property empty to stick to the default time point. The component will then prioritize:

• The signature creation time if the signature contains a signature timestamp (ValidatedSigningTime), or
• The local time included in the signature by the signer (ClaimedSigningTime).

AddAttachment Method (PDFSign Component)

Adds an attachment to a PDF document.

Syntax

• C#
• VB.NET

public void AddAttachment(string fileName, string description);

Async Version
public async Task AddAttachment(string fileName, string description);
public async Task AddAttachment(string fileName, string description, CancellationToken cancellationToken);

Public Sub AddAttachment(ByVal FileName As String, ByVal Description As String)

Async Version
Public Sub AddAttachment(ByVal FileName As String, ByVal Description As String) As Task
Public Sub AddAttachment(ByVal FileName As String, ByVal Description As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to add an attachment (embedded file) to the document specified in InputFile, InputData, or SetInputStream and to the Attachments collection.

The document containing the newly added attachment will be saved to OutputFile, OutputData, or the stream set in SetOutputStream.

The FileName and Description parameters specify the filename and description of the attachment respectively.

Example: pdfsign.InputFile = "input.pdf"; pdfsign.OutputFile = "input_with_attachment.pdf"; pdfsign.Open(); pdfsign.AddAttachment("foo.txt", "desc"); // Alternatively, create a PDFAttachment object and add it to Attachments manually: PDFAttachment attachment = new PDFAttachment(); attachment.FileName = "foo.txt"; // or attachment.DataB = new byte[] { ... }; // or attachment.InputStream = new FileStream(...); attachment.Description = "desc"; pdfsign.Attachments.Add(attachment); // Or using one of the constructors: pdfsign.Attachments.Add(new PDFAttachment("foo.txt", "desc")); pdfsign.Close(); The full list of attachments is contained in the Attachments property.

Note: If the document is not already opened, this method will open it, perform the operation, then close it.

AddTimestamp Method (PDFSign Component)

Adds a document timestamp to a PDF document.

Syntax

• C#
• VB.NET

public void AddTimestamp();

Async Version
public async Task AddTimestamp();
public async Task AddTimestamp(CancellationToken cancellationToken);

Public Sub AddTimestamp()

Async Version
Public Sub AddTimestamp() As Task
Public Sub AddTimestamp(cancellationToken As CancellationToken) As Task

Remarks

This method is used to obtain a document timestamp and embed it into the document specified in InputFile, InputData, or SetInputStream. The document containing the newly added document timestamp will be saved to OutputFile, OutputData, or the stream set in SetOutputStream.

A document timestamp is a fully independent signature that is added to the PDF document after the initial signature. Unlike the main signature, the document timestamp is made by a TSA, and its purpose is to preserve the document's long-term validity. Typically, adding a document timestamp is done close to the expiration date of the certificate that produced the last timestamp (which is either embedded in the main signature, or is a previous document timestamp). An LTV document therefore contains a chain of document timestamps updated periodically to keep its long-term status.

Example: pdfsign.InputFile = "signed.pdf"; pdfsign.OutputFile = "signed_with_dts.pdf"; pdfsign.TimestampServer = "https://freetsa.org/tsr"; pdfsign.AddTimestamp(); Note: If the document is not already opened, this method will open it, perform the operation, then close it.

Close Method (PDFSign Component)

Closes an opened PDF document.

Syntax

• C#
• VB.NET

public void Close();

Async Version
public async Task Close();
public async Task Close(CancellationToken cancellationToken);

Public Sub Close()

Async Version
Public Sub Close() As Task
Public Sub Close(cancellationToken As CancellationToken) As Task

Remarks

This method is used to close the previously opened document specified in InputFile, InputData, or SetInputStream. It should always be preceded by a call to the Open method.

Example: component.InputFile = "input.pdf"; component.Open(); // Some operation component.Close();

If any changes are made to the document, they will be saved automatically to OutputFile, OutputData, or the stream set in SetOutputStream when this method is called. To configure this saving behavior, set the SaveChanges configuration setting.

Config Method (PDFSign Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Async Version
public async Task<string> Config(string configurationString);
public async Task<string> Config(string configurationString, CancellationToken cancellationToken);

Public Function Config(ByVal ConfigurationString As String) As String

Async Version
Public Function Config(ByVal ConfigurationString As String) As Task(Of String)
Public Function Config(ByVal ConfigurationString As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

Config is a generic method available in every component. It is used to set and retrieve configuration settings for the component.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Encrypted Method (PDFSign Component)

Checks whether a PDF document is encrypted.

Syntax

• C#
• VB.NET

public bool Encrypted();

Async Version
public async Task<bool> Encrypted();
public async Task<bool> Encrypted(CancellationToken cancellationToken);

Public Function Encrypted() As Boolean

Async Version
Public Function Encrypted() As Task(Of Boolean)
Public Function Encrypted(cancellationToken As CancellationToken) As Task(Of Boolean)

Remarks

This method is used to determine whether or not the document specified in InputFile, InputData, or SetInputStream is encrypted. It will return false if the document is pseudo-encrypted with an empty password.

Example: component.InputFile = "input.pdf"; if (component.Encrypted()) { // Set Password or DecryptionCert } component.Open(); // Some operation component.Close(); Note: If the document is not already opened, this method will open it, perform the operation, then close it.

GetPageProperty Method (PDFSign Component)

Retrieves the value of a page property.

Syntax

• C#
• VB.NET

public string GetPageProperty(int page, string property);

Async Version
public async Task<string> GetPageProperty(int page, string property);
public async Task<string> GetPageProperty(int page, string property, CancellationToken cancellationToken);

Public Function GetPageProperty(ByVal Page As Integer, ByVal Property As String) As String

Async Version
Public Function GetPageProperty(ByVal Page As Integer, ByVal Property As String) As Task(Of String)
Public Function GetPageProperty(ByVal Page As Integer, ByVal Property As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method is used to read general information about the pages of the document specified in InputFile, InputData, or SetInputStream, such as their dimensions and content positioning details.

The Page parameter specifies the page to read information about, and the Property parameter specifies the page property to read. The latter can take one of the following values:

Note: Each page property is only populated once the document has been loaded, which is reported by the DocumentInfo event.

Example: int pageCount = 0; component.OnDocumentInfo += (s, e) => { pageCount = e.PageCount; }; component.InputFile = "input.pdf"; component.Open(); for (int i = 1; i <= pageCount; i++) component.GetPageProperty(i, "Height"); component.Close(); The page properties can be used to adjust the position of the signature widget based on the page dimensions. For example: int x = int.Parse(pdfsign.GetPageProperty(1, "Width")) - 100; int y = int.Parse(pdfsign.GetPageProperty(1, "Height")) - 100; pdfsign.SetWidgetProperty("OffsetX", x.ToString()); pdfsign.SetWidgetProperty("OffsetY", y.ToString()); Note: If the document is not already opened, this method will open it, perform the operation, then close it.

GetWidgetProperty Method (PDFSign Component)

Retrieves the value of a signature widget property.

Syntax

• C#
• VB.NET

public string GetWidgetProperty(int signatureIndex, string property);

Async Version
public async Task<string> GetWidgetProperty(int signatureIndex, string property);
public async Task<string> GetWidgetProperty(int signatureIndex, string property, CancellationToken cancellationToken);

Public Function GetWidgetProperty(ByVal SignatureIndex As Integer, ByVal Property As String) As String

Async Version
Public Function GetWidgetProperty(ByVal SignatureIndex As Integer, ByVal Property As String) As Task(Of String)
Public Function GetWidgetProperty(ByVal SignatureIndex As Integer, ByVal Property As String, cancellationToken As CancellationToken) As Task(Of String)

Remarks

This method is used to retrieve the value of a signature widget property. Together with SetWidgetProperty, this method provides an extensible way of managing the widget settings that are not available through the primary properties of the component. The list of settings below may be extended in the future.

The SignatureIndex parameter is the index of the signature of interest in the Signatures collection, and the Property parameter specifies the widget property to read. The latter can take one of the following values:

Example: pdfsign.InputFile = "signed.pdf"; pdfsign.Open(); bool invisible = bool.Parse(pdfsign.GetWidgetProperty(0, "Invisible")); pdfsign.Close(); Note: Each widget property is only populated after the document has been signed and the signature widget has been generated.

Note: If the document is not already opened, this method will open it, perform the operation, then close it.

Interrupt Method (PDFSign Component)

Interrupts the current action.

Syntax

• C#
• VB.NET

public void Interrupt();

Async Version
public async Task Interrupt();
public async Task Interrupt(CancellationToken cancellationToken);

Public Sub Interrupt()

Async Version
Public Sub Interrupt() As Task
Public Sub Interrupt(cancellationToken As CancellationToken) As Task

Remarks

This method interrupts the current action. It can be used, for example, within the ChainCert event to abort the chain validation procedure.

If there is no action in progress, this method simply returns, doing nothing.

Open Method (PDFSign Component)

Opens a PDF document for processing.

Syntax

• C#
• VB.NET

public void Open();

Async Version
public async Task Open();
public async Task Open(CancellationToken cancellationToken);

Public Sub Open()

Async Version
Public Sub Open() As Task
Public Sub Open(cancellationToken As CancellationToken) As Task

Remarks

This method is used to open the document specified in InputFile, InputData, or SetInputStream before performing some operation on it, such as signing, updating, verifying signatures, or removing signatures. When finished, call Close to complete or discard the operation.

It is recommended to use this method (alongside Close) when performing multiple operations on the document at once.

Automatic Decryption Functionality

Once the correct decryption material is supplied, the component will then attempt to decrypt the document automatically within this method. When this occurs, the decrypted content is kept in memory so that the document's encrypted status is preserved when it is saved later. Use the Decrypt method to save a decrypted copy of the document instead.

RemoveAttachment Method (PDFSign Component)

Removes an attachment from a PDF document.

Syntax

• C#
• VB.NET

public void RemoveAttachment(int index);

Async Version
public async Task RemoveAttachment(int index);
public async Task RemoveAttachment(int index, CancellationToken cancellationToken);

Public Sub RemoveAttachment(ByVal Index As Integer)

Async Version
Public Sub RemoveAttachment(ByVal Index As Integer) As Task
Public Sub RemoveAttachment(ByVal Index As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to remove an attachment from the document specified in InputFile, InputData, or SetInputStream and from the Attachments collection.

The document without the attachment will be saved to OutputFile, OutputData, or the stream set in SetOutputStream.

The Index parameter is the index of the attachment in the Attachments collection to be removed.

Example: pdfsign.InputFile = "input_with_attachment.pdf"; pdfsign.OutputFile = "attachment_removed.pdf"; pdfsign.Open(); pdfsign.RemoveAttachment(0); // Alternatively, remove an attachment from Attachments manually: PDFAttachment attachment = pdfsign.Attachments[0]; pdfsign.Attachments.Remove(attachment); pdfsign.Close(); Note: If the document is not already opened, this method will open it, perform the operation, then close it.

Reset Method (PDFSign Component)

Resets the component.

Syntax

• C#
• VB.NET

public void Reset();

Async Version
public async Task Reset();
public async Task Reset(CancellationToken cancellationToken);

Public Sub Reset()

Async Version
Public Sub Reset() As Task
Public Sub Reset(cancellationToken As CancellationToken) As Task

Remarks

This method is used to reset the component's properties and configuration settings to their default values.

SaveAttachment Method (PDFSign Component)

Saves a PDF attachment to a file.

Syntax

• C#
• VB.NET

public void SaveAttachment(int index, string fileName);

Async Version
public async Task SaveAttachment(int index, string fileName);
public async Task SaveAttachment(int index, string fileName, CancellationToken cancellationToken);

Public Sub SaveAttachment(ByVal Index As Integer, ByVal FileName As String)

Async Version
Public Sub SaveAttachment(ByVal Index As Integer, ByVal FileName As String) As Task
Public Sub SaveAttachment(ByVal Index As Integer, ByVal FileName As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to retrieve the contents of an attachment from the document specified in InputFile, InputData, or SetInputStream and save it to the file specified by FileName. It does not modify the existence of the Attachments collection's contents.

The Index parameter is the index of the attachment in the Attachments collection to be saved.

The FileName parameter specifies the filename that the attachment will be saved to.

Example: component.InputFile = "input_with_attachment.pdf"; component.Open(); component.SaveAttachment(0, "a.dat"); component.Close(); Example (saving to a stream): component.InputFile = "input_with_attachment.pdf"; component.Attachments[0].OutputStream = myStream; component.SaveAttachment(0, null); // null means use the OutputStream field if it's set Note: If the document is not already opened, this method will open it, perform the operation, then close it.

SetInputStream Method (PDFSign Component)

Sets the stream containing the PDF document to process.

Syntax

• C#
• VB.NET

public void SetInputStream(System.IO.Stream inputStream);

Async Version
public async Task SetInputStream(System.IO.Stream inputStream);
public async Task SetInputStream(System.IO.Stream inputStream, CancellationToken cancellationToken);

Public Sub SetInputStream(ByVal InputStream As System.IO.Stream)

Async Version
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream) As Task
Public Sub SetInputStream(ByVal InputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method is used to set the stream from which the component will read the PDF document to be processed. If an input stream is set before the component attempts to perform operations on the document, the component will read the data from the input stream instead of from the InputFile or InputData properties.

Note: It may be useful to additionally set the CloseInputStreamAfterProcessing configuration setting to true when using input streams.

SetOutputStream Method (PDFSign Component)

Sets the stream to write the processed document to.

Syntax

• C#
• VB.NET

public void SetOutputStream(System.IO.Stream outputStream);

Async Version
public async Task SetOutputStream(System.IO.Stream outputStream);
public async Task SetOutputStream(System.IO.Stream outputStream, CancellationToken cancellationToken);

Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream)

Async Version
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream) As Task
Public Sub SetOutputStream(ByVal OutputStream As System.IO.Stream, cancellationToken As CancellationToken) As Task

Remarks

This method is used to set the stream to which the component will write the resulting PDF document. If an output stream is set before the component attempts to perform operations on the document, the component will write the data to the output stream instead of writing to OutputFile or populating OutputData.

Note: It may be useful to additionally set the CloseOutputStreamAfterProcessing configuration setting to true when using output streams.

SetWidgetProperty Method (PDFSign Component)

Sets the value of a signature widget property.

Syntax

• C#
• VB.NET

public void SetWidgetProperty(string property, string value);

Async Version
public async Task SetWidgetProperty(string property, string value);
public async Task SetWidgetProperty(string property, string value, CancellationToken cancellationToken);

Public Sub SetWidgetProperty(ByVal Property As String, ByVal Value As String)

Async Version
Public Sub SetWidgetProperty(ByVal Property As String, ByVal Value As String) As Task
Public Sub SetWidgetProperty(ByVal Property As String, ByVal Value As String, cancellationToken As CancellationToken) As Task

Remarks

This method is used to adjust the look of the signature widget when creating a signature. Together with GetWidgetProperty, this method provides an extensible way of managing the widget settings that are not available through the primary properties of the component. The list of settings below may be extended in the future.

The Property and Value parameters specify the widget property and value to set respectively. The former can take one of the following values:

Example: pdfsign.SetWidgetProperty("Width", "100"); pdfsign.SetWidgetProperty("Height", "100"); pdfsign.SetWidgetProperty("ShowDate", "false"); pdfsign.SetWidgetProperty("SignerInfo", "Hello\r\nworld!"); pdfsign.SetWidgetProperty("TitleFontSize", "11"); pdfsign.Sign();

Sign Method (PDFSign Component)

Signs a PDF document.

Syntax

• C#
• VB.NET

public void Sign();

Async Version
public async Task Sign();
public async Task Sign(CancellationToken cancellationToken);

Public Sub Sign()

Async Version
Public Sub Sign() As Task
Public Sub Sign(cancellationToken As CancellationToken) As Task

Remarks

This method is used to sign the document specified in InputFile, InputData, or SetInputStream. The document will be signed with SigningCert and saved in OutputFile, OutputData, or the stream set in SetOutputStream.

Use the following properties to adjust new signature settings:

• SignatureAuthorName
• SignatureClaimedSigningTime
• SignatureHashAlgorithm
• SignatureProfile
• SignatureReason
• SignatureType
• SignatureWidgetHeight
• SignatureWidgetOffsetX
• SignatureWidgetOffsetY
• SignatureWidgetPages
• SignatureWidgetWidth

Use the following properties to adjust chain validation parameters:

• BlockedCerts
• KnownCerts
• OfflineMode
• RevocationCheck
• TrustedCerts
• TrustedLists
• TrustSources
• ValidationFlags
• ValidationPolicy
• ValidationTime

Note: If the document is not already opened, this method will open it, perform the operation, then close it.

Signed Method (PDFSign Component)

Checks whether a PDF document is signed.

Syntax

• C#
• VB.NET

public bool Signed();

Async Version
public async Task<bool> Signed();
public async Task<bool> Signed(CancellationToken cancellationToken);

Public Function Signed() As Boolean

Async Version
Public Function Signed() As Task(Of Boolean)
Public Function Signed(cancellationToken As CancellationToken) As Task(Of Boolean)

Remarks

This method is used to determine whether or not the document specified in InputFile, InputData, or SetInputStream is signed. It will return false if the document contains only empty signature fields.

Example: pdfverify.InputFile = "input.pdf"; if (pdfverify.Signed()) { // Configure validation-related properties as desired pdfverify.Verify(); } Note: If the document is not already opened, this method will open it, perform the operation, then close it.

Update Method (PDFSign Component)

Updates the most recent signature.

Syntax

• C#
• VB.NET

public void Update();

Async Version
public async Task Update();
public async Task Update(CancellationToken cancellationToken);

Public Sub Update()

Async Version
Public Sub Update() As Task
Public Sub Update(cancellationToken As CancellationToken) As Task

Remarks

This method is used to update the most recent signature by embedding newer or missing revocation information into the signed document specified in InputFile, InputData, or SetInputStream. The updated document will be saved to OutputFile, OutputData, or the stream set in SetOutputStream.

Updating a signature starts with its cryptographic validation. Before any new validation material is inserted, the signature's integrity must be validated. If the signature is found to be correct, the component will proceed with chain validation and the retrieval of any missing chain elements. If the signature is cryptographically wrong, the component will throw an exception.

The update approach is typically used to extend the validity of an LTV signature. For LTA signatures, updating is typically accompanied with a document timestamping operation. Set TimestampServer to have the component obtain and embed a document timestamp automatically.

Further validation material and document timestamps may be added to a document over time to maintain its authenticity and integrity.

Use the following properties to adjust chain validation parameters:

• BlockedCerts
• KnownCerts
• OfflineMode
• RevocationCheck
• TrustedCerts
• TrustedLists
• TrustSources
• ValidationFlags
• ValidationPolicy
• ValidationTime

Note: To choose a different signature to update, set the UpdateIndex configuration setting.

Note: If the document is not already opened, this method will open it, perform the operation, then close it.

ChainCert Event (PDFSign Component)

Fired when the component encounters a chain certificate.

Syntax

• C#
• VB.NET

public event OnChainCertHandler OnChainCert;

public delegate void OnChainCertHandler(object sender, PDFSignChainCertEventArgs e);

public class PDFSignChainCertEventArgs : EventArgs {
  public string CertEncoded { get; }
  public byte[] CertEncodedB { get; }
  public string CertSubject { get; }
  public string CertIssuer { get; }
  public string ValidationTime { get; }
  public int ValidationResult { get; set; }
  public int ValidationDetails { get; set; }
}

Public Event OnChainCert As OnChainCertHandler

Public Delegate Sub OnChainCertHandler(sender As Object, e As PDFSignChainCertEventArgs)

Public Class PDFSignChainCertEventArgs Inherits EventArgs
  Public ReadOnly Property CertEncoded As String
  Public ReadOnly Property CertEncodedB As Byte()
  Public ReadOnly Property CertSubject As String
  Public ReadOnly Property CertIssuer As String
  Public ReadOnly Property ValidationTime As String
  Public Property ValidationResult As Integer
  Public Property ValidationDetails As Integer
End Class

Remarks

This event is fired once for each certificate encountered during chain validation to report that it is about to be processed. The component will try to retrieve all required chain certificates automatically.

The CertEncoded parameter specifies the PEM (Base64-encoded) public certificate.

The CertSubject and CertIssuer parameters specify the distinguished names of the certificate owner and issuer respectively.

The ValidationTime parameter specifies the time point (in UTC) at which the certificate validity was established.

The ValidationResult parameter reports the outcome of the individual certificate validation and can be one of the following values:

In the case of a failure, the ValidationDetails parameter provides more details on its reasons. Its value is a bitmask of the following flags:

Overridable Chain Validation

For example, set ValidationResult to cvrValid and ValidationDetails to 0 in order to:

• Ignore CA or TLS key usage requirements
• Ignore the AuthorityKeyId extension in certificate-issuing CAs (helps with incorrectly renewed certificates)
• Ignore the Basic Constraints or Name Constraints extensions of CA certificates
• Tolerate some weaker algorithms
• Implicitly trust self-signed certificates
• Skip validity period checks for trusted certificates (helps with older devices that have expired root certificates)
• Ignore chain loops (helps with buggy CAs that include subchains that sign themselves)

Note: The user code is ultimately responsible for certificate validity decisions made via these two parameters. If their values are modified within this event, the resulting chain validation procedure may deviate from the standard.

DocumentInfo Event (PDFSign Component)

Fired when the document has been loaded into memory.

Syntax

• C#
• VB.NET

public event OnDocumentInfoHandler OnDocumentInfo;

public delegate void OnDocumentInfoHandler(object sender, PDFSignDocumentInfoEventArgs e);

public class PDFSignDocumentInfoEventArgs : EventArgs {
  public int PageCount { get; }
  public int SignatureCount { get; }
}

Public Event OnDocumentInfo As OnDocumentInfoHandler

Public Delegate Sub OnDocumentInfoHandler(sender As Object, e As PDFSignDocumentInfoEventArgs)

Public Class PDFSignDocumentInfoEventArgs Inherits EventArgs
  Public ReadOnly Property PageCount As Integer
  Public ReadOnly Property SignatureCount As Integer
End Class

Remarks

This event is fired once per document processing routine to report that the document has been processed and loaded into memory.

The handler for this event is a good place to check the document structure and access document-related information such as page number and document file details. These may be useful when preparing the signature. For example, the GetPageProperty method can be used to find the optimal position for the signature widget.

The PageCount parameter reports the number of pages in the document.

The SignatureCount parameter reports the number of signatures in the document.

This event is fired when the Open method is called, but only after Password or RecipientInfo is fired (if applicable) and the document has been decrypted.

This event will populate the Attachments, DocumentCerts, and Signatures collections with any corresponding objects found in the document.

Error Event (PDFSign Component)

Fired when information is available about errors during data delivery.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

public delegate void OnErrorHandler(object sender, PDFSignErrorEventArgs e);

public class PDFSignErrorEventArgs : EventArgs {
  public int ErrorCode { get; }
  public string Description { get; }
}

Public Event OnError As OnErrorHandler

Public Delegate Sub OnErrorHandler(sender As Object, e As PDFSignErrorEventArgs)

Public Class PDFSignErrorEventArgs Inherits EventArgs
  Public ReadOnly Property ErrorCode As Integer
  Public ReadOnly Property Description As String
End Class

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component throws an exception.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

Log Event (PDFSign Component)

Fired once for each log message.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

public delegate void OnLogHandler(object sender, PDFSignLogEventArgs e);

public class PDFSignLogEventArgs : EventArgs {
  public int LogLevel { get; }
  public string Message { get; }
  public string LogType { get; }
}

Public Event OnLog As OnLogHandler

Public Delegate Sub OnLogHandler(sender As Object, e As PDFSignLogEventArgs)

Public Class PDFSignLogEventArgs Inherits EventArgs
  Public ReadOnly Property LogLevel As Integer
  Public ReadOnly Property Message As String
  Public ReadOnly Property LogType As String
End Class

Remarks

This event is fired once for each log message generated by the component. The verbosity is controlled by the LogLevel configuration setting.

The LogLevel parameter indicates the detail level of the message. Possible values are:

The Message parameter is the log message.

The LogType parameter identifies the type of log entry. Possible values are:

• CertValidator
• Font
• HTTP
• PDFInvalidSignature
• PDFRevocationInfo
• Timestamp
• TSL

Password Event (PDFSign Component)

Fired when the component detects that the PDF document is encrypted with a password.

Syntax

• C#
• VB.NET

public event OnPasswordHandler OnPassword;

public delegate void OnPasswordHandler(object sender, PDFSignPasswordEventArgs e);

public class PDFSignPasswordEventArgs : EventArgs {
  public bool Available { get; }
  public bool Cancel { get; set; }
}

Public Event OnPassword As OnPasswordHandler

Public Delegate Sub OnPasswordHandler(sender As Object, e As PDFSignPasswordEventArgs)

Public Class PDFSignPasswordEventArgs Inherits EventArgs
  Public ReadOnly Property Available As Boolean
  Public Property Cancel As Boolean
End Class

Remarks

This event is fired during document processing to report that the document is encrypted with a password. It may be used to supply the correct decryption password to the Password property.

The Available parameter indicates whether the decryption password is already available to the component or still needs to be set. If this parameter is set to false, the correct password must be provided for the decryption attempt to succeed.

The Cancel parameter determines whether the component will stop firing this event to request a password.

RecipientInfo Event (PDFSign Component)

Fired for each recipient certificate of the encrypted PDF document.

Syntax

• C#
• VB.NET

public event OnRecipientInfoHandler OnRecipientInfo;

public delegate void OnRecipientInfoHandler(object sender, PDFSignRecipientInfoEventArgs e);

public class PDFSignRecipientInfoEventArgs : EventArgs {
  public string Issuer { get; }
  public string SerialNumber { get; }
  public string SubjectKeyIdentifier { get; }
  public bool Available { get; }
  public bool Cancel { get; set; }
}

Public Event OnRecipientInfo As OnRecipientInfoHandler

Public Delegate Sub OnRecipientInfoHandler(sender As Object, e As PDFSignRecipientInfoEventArgs)

Public Class PDFSignRecipientInfoEventArgs Inherits EventArgs
  Public ReadOnly Property Issuer As String
  Public ReadOnly Property SerialNumber As String
  Public ReadOnly Property SubjectKeyIdentifier As String
  Public ReadOnly Property Available As Boolean
  Public Property Cancel As Boolean
End Class

Remarks

This event is fired during document processing for each recipient certificate that the document has been encrypted for (if applicable). It may be used to identify the certificate(s) to load and supply to the DecryptionCert property.

The Issuer parameter specifies the subject of the issuer certificate.

The SerialNumber parameter specifies the serial number of the encryption certificate.

The SubjectKeyIdentifier parameter specifies the X.509 subjectKeyIdentifier extension value of the encryption certificate, encoded as a hex string.

The Available parameter indicates whether the decryption certificate is already available to the component or still needs to be set. If this parameter is set to false, the correct certificate must be provided for the decryption attempt to succeed.

The Cancel parameter determines whether the component will stop firing this event to request a certificate.

Note: The document may be encrypted with more than one certificate (or have "more than one recipient"), in which case each certificate will cause its own invocation of this event.

SignatureInfo Event (PDFSign Component)

Fired when the component finds a signature in the document.

Syntax

• C#
• VB.NET

public event OnSignatureInfoHandler OnSignatureInfo;

public delegate void OnSignatureInfoHandler(object sender, PDFSignSignatureInfoEventArgs e);

public class PDFSignSignatureInfoEventArgs : EventArgs {
  public int SignatureIndex { get; }
  public bool ValidateSignature { get; set; }
  public bool ValidateChain { get; set; }
}

Public Event OnSignatureInfo As OnSignatureInfoHandler

Public Delegate Sub OnSignatureInfoHandler(sender As Object, e As PDFSignSignatureInfoEventArgs)

Public Class PDFSignSignatureInfoEventArgs Inherits EventArgs
  Public ReadOnly Property SignatureIndex As Integer
  Public Property ValidateSignature As Boolean
  Public Property ValidateChain As Boolean
End Class

Remarks

This event is fired once for each signature found in the document to report that the signature specified by SignatureIndex is about to be validated.

The SignatureIndex parameter is the index of the signature in the Signatures collection.

Signature validation consists of two independent stages: cryptographic signature validation and chain validation. The ValidateSignature and ValidateChain parameters determine whether each stage should be included in the validation. They can be overridden to modify the validation policy on a per-signature basis, allowing signatures to be verified individually instead of all at once (via Verify). To skip validation entirely, set both parameters to false.

Use the following properties to adjust chain validation parameters:

• BlockedCerts
• KnownCerts
• OfflineMode
• RevocationCheck
• TrustedCerts
• TrustedLists
• TrustSources
• ValidationFlags
• ValidationPolicy
• ValidationTime

SignatureProcessed Event (PDFSign Component)

Fired after a signature has been processed.

Syntax

• C#
• VB.NET

public event OnSignatureProcessedHandler OnSignatureProcessed;

public delegate void OnSignatureProcessedHandler(object sender, PDFSignSignatureProcessedEventArgs e);

public class PDFSignSignatureProcessedEventArgs : EventArgs {
  public int SignatureIndex { get; }
  public int SignatureValidationResult { get; }
  public int ChainValidationResult { get; }
  public int ChainValidationDetails { get; }
}

Public Event OnSignatureProcessed As OnSignatureProcessedHandler

Public Delegate Sub OnSignatureProcessedHandler(sender As Object, e As PDFSignSignatureProcessedEventArgs)

Public Class PDFSignSignatureProcessedEventArgs Inherits EventArgs
  Public ReadOnly Property SignatureIndex As Integer
  Public ReadOnly Property SignatureValidationResult As Integer
  Public ReadOnly Property ChainValidationResult As Integer
  Public ReadOnly Property ChainValidationDetails As Integer
End Class

Remarks

This event is fired once for each signature found in the document to report that the signature specified by SignatureIndex has completed validation. It is fired after SignatureInfo if that event's ValidateSignature parameter is set to true.

The SignatureIndex parameter is the index of the signature in the Signatures collection.

Signature validation consists of two independent stages: cryptographic signature validation and chain validation. Separate validation results are reported for each in the SignatureValidationResult and ChainValidationResult parameters.

The former reports the validity of the signature and can be one of the following values:

The latter reports the validity of the chain and can be one of the following values:

In the case of a failure, the ChainValidationDetails parameter provides more details on its reasons. Its value is a bitmask of the following flags:

Note: SignatureValidationResult, ChainValidationResult, and ChainValidationDetails are also available as fields in the PDFSignature type.

SSLServerAuthentication Event (PDFSign Component)

Fired after the server presents its certificate to the client.

Syntax

• C#
• VB.NET

public event OnSSLServerAuthenticationHandler OnSSLServerAuthentication;

public delegate void OnSSLServerAuthenticationHandler(object sender, PDFSignSSLServerAuthenticationEventArgs e);

public class PDFSignSSLServerAuthenticationEventArgs : EventArgs {
  public string CertEncoded { get; }
  public byte[] CertEncodedB { get; }
  public string CertSubject { get; }
  public string CertIssuer { get; }
  public string Status { get; }
  public bool Accept { get; set; }
}

Public Event OnSSLServerAuthentication As OnSSLServerAuthenticationHandler

Public Delegate Sub OnSSLServerAuthenticationHandler(sender As Object, e As PDFSignSSLServerAuthenticationEventArgs)

Public Class PDFSignSSLServerAuthenticationEventArgs Inherits EventArgs
  Public ReadOnly Property CertEncoded As String
  Public ReadOnly Property CertEncodedB As Byte()
  Public ReadOnly Property CertSubject As String
  Public ReadOnly Property CertIssuer As String
  Public ReadOnly Property Status As String
  Public Property Accept As Boolean
End Class

Remarks

This event is fired during timestamping or chain validation after the server presents its SSL/TLS certificate to the component. It only applies if the TSA, CRL, OCSP, or Trusted List endpoint operates over HTTPS.

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When the Accept parameter is false, the Status parameter shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to true.

SSLStatus Event (PDFSign Component)

Fired when secure connection progress messages are available.

Syntax

• C#
• VB.NET

public event OnSSLStatusHandler OnSSLStatus;

public delegate void OnSSLStatusHandler(object sender, PDFSignSSLStatusEventArgs e);

public class PDFSignSSLStatusEventArgs : EventArgs {
  public string Message { get; }
}

Public Event OnSSLStatus As OnSSLStatusHandler

Public Delegate Sub OnSSLStatusHandler(sender As Object, e As PDFSignSSLStatusEventArgs)

Public Class PDFSignSSLStatusEventArgs Inherits EventArgs
  Public ReadOnly Property Message As String
End Class

Remarks

This event is fired during timestamping or chain validation for informational and logging purposes only. This event tracks the progress of the SSL/TLS connection. It only applies if the TSA, CRL, OCSP, or Trusted List endpoint operates over HTTPS.

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

Fields

Constructors

• C#
• VB.NET

public Certificate();

Public Certificate()

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

• C#
• VB.NET

public Certificate(byte[] encoded);

Public Certificate(ByVal Encoded As Byte())

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, string store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, string store, string storePassword, byte[] encoded);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As String, ByVal StorePassword As String, ByVal Encoded As Byte())

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, string subject, string configurationString);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Subject As String, ByVal ConfigurationString As String)

• C#
• VB.NET

public Certificate(CertStoreTypes storeType, byte[] store, string storePassword, byte[] encoded);

Public Certificate(ByVal StoreType As CertStoreTypes, ByVal Store As Byte(), ByVal StorePassword As String, ByVal Encoded As Byte())

Firewall Type

The firewall the component will connect through.

Remarks

When connecting through a firewall, this type is used to specify different properties of the firewall, such as the firewall Host and the FirewallType.

Fields

Constructors

• C#
• VB.NET

public Firewall();

Public Firewall()

PDFAttachment Type

This describes the file being attached to the PDF document.

Remarks

This type contains information about the file that is being attached to the document.

Fields

Constructors

• C#
• VB.NET

public PDFAttachment();

Public PDFAttachment()

• C#
• VB.NET

public PDFAttachment(string fileName);

Public PDFAttachment(ByVal FileName As String)

• C#
• VB.NET

public PDFAttachment(string fileName, string description);

Public PDFAttachment(ByVal FileName As String, ByVal Description As String)

• C#
• VB.NET

public PDFAttachment(byte[] data, string name, string description);

Public PDFAttachment(ByVal Data As Byte(), ByVal Name As String, ByVal Description As String)

• C#
• VB.NET

public PDFAttachment(System.IO.Stream inputStream, string name, string description);

Public PDFAttachment(ByVal InputStream As System.IO.Stream, ByVal Name As String, ByVal Description As String)

PDFSignature Type

A container for PDF signature details.

Remarks

This type contains details about the signature. Use it to read information about the signature when processing it.

Fields

Constructors

• C#
• VB.NET

public PDFSignature();

Public PDFSignature()

Proxy Type

The proxy the component will connect to.

Remarks

When connecting through a proxy, this type is used to specify different properties of the proxy, such as the Server and the AuthScheme.

Fields

Constructors

• C#
• VB.NET

public Proxy();

Public Proxy()

• C#
• VB.NET

public Proxy(string server, int port);

Public Proxy(ByVal Server As String, ByVal Port As Integer)

• C#
• VB.NET

public Proxy(string server, int port, string user, string password);

Public Proxy(ByVal Server As String, ByVal Port As Integer, ByVal User As String, ByVal Password As String)

Config Settings (PDFSign Component)

PDFSign Config Settings

Base Config Settings

Trappable Errors (PDFSign Component)

PDFSign Errors

PDF Errors

Parsing Errors

The component may also return one of the following error codes, which are inherited from other components.

HTTP Errors

The component may also return one of the following error codes, which are inherited from other components.

TCPClient Errors

SSL Errors

TCP/IP Errors