SecurePDF Component

Properties   Methods   Events   Config Settings   Errors  

TBD

Syntax

nsoftware.IPWorksPDF.SecurePDF

Remarks

TBD

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 (SecurePDF 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. TBD

This property is not available at design time.

DecryptionCert Property (SecurePDF 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. Uncommon because encryption/decryption are usually done via a password, but still needed. The encryption cert is RecipientCert. TBD

This property is not available at design time.

DocumentCerts Property (SecurePDF 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 by its creator. Not user-supplied but rather an "inbound" property.

A huge unsorted pile of certificates that we encounter from the signatures, timestamps, DSS, etc., including all the chains. Populated automatically during chain validation.

Along with KnownCerts, can potentially be useful for including the full signing chain into the signature (something users commonly want to do). See the IncludeSigningChain config.

Named as such because the SBB equivalent, Certificates, was too vague. TBD

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

EncryptionAlgorithm Property (SecurePDF Component)

The encryption algorithm to encrypt the PDF document with.

Syntax

• C#
• VB.NET

public string EncryptionAlgorithm { get; set; }

Public Property EncryptionAlgorithm As String

Default Value

"AES256"

Remarks

This property is used to specify the encryption algorithm to encrypt the document with. For certificate-based encryption, set the RecipientCert property.

Possible values are:

• RC4
• AES128
• AES256

FieldIndex Property (SecurePDF Component)

The index of the empty signature field to sign.

Syntax

• C#
• VB.NET

public int FieldIndex { get; set; }

Public Property FieldIndex 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.

Users need to be able to specify which empty field to sign, for example if multiple people need to sign the document and it gets passed around. Will be used after the document has already been "signed" with SigningSettings.Type = stEmptyField: // assuming InputFile, OutputFile, SigningCert, etc. are already set signer.SigningSettings.Type = PDFSignatureTypes.stEmptyField; signer.Sign(); // later signer.FieldIndex = 0; // set Profile, widget properties, etc. signer.Sign(); Can rename to EmptyFieldIndex (matches SBB) for clarity. TBD

Firewall Property (SecurePDF 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 (SecurePDF 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. TBD

This property is not available at design time.

InputFile Property (SecurePDF 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. TBD

InputStream Property (SecurePDF Component)

A stream containing the PDF document to process.

Syntax

• C#
• VB.NET

public System.IO.Stream InputStream { get; set; }

Public Property InputStream As System.IO.Stream

Default Value

null

Remarks

This property is used to assign a stream containing the PDF document to be processed. TBD

This property is not available at design time.

KnownCerts Property (SecurePDF 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.

Part of the BlockedCerts-KnownCerts-TrustedCerts trio for chain validation. User-supplied. To prevent "known" chain certificates from residing in the same collection as trusted or blocked certificates.

Similar to DocumentCerts, an unsorted pile of certificates from different chains (TSA, OCSP, etc., not just the signing chain) but that we will use to actually build the chains if we can't find the certificates elsewhere.

Along with DocumentCerts, can potentially be useful for including the full signing chain into the signature (something users commonly want to do). See the IncludeSigningChain config.

The user can add Certificate objects to it if they have their own certificates on hand and want to provide them before validation. An example scenario is when intermediary CA certificates are absent from the standard system locations (or when there are no standard system locations) and therefore should be supplied to the component manually.

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

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

This property is not available at design time.

OutputData Property (SecurePDF 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 the OutputFile and OutputStream properties have not been assigned. TBD

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

OutputFile Property (SecurePDF 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. TBD

OutputStream Property (SecurePDF Component)

The stream to write the processed document to.

Syntax

• C#
• VB.NET

public System.IO.Stream OutputStream { get; set; }

Public Property OutputStream As System.IO.Stream

Default Value

null

Remarks

This property is used to assign a stream where the resulting PDF document will be written to after the operation has completed. TBD

This property is not available at design time.

Overwrite Property (SecurePDF 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 OutputStream. If set to false, an error will be thrown whenever OutputFile, OutputData, or OutputStream exists before an operation.

Password Property (SecurePDF Component)

The password to encrypt or 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 encryption/decryption. To specify the owner password, set the OwnerPassword configuration setting. Though it may be different from OwnerPassword, most implementations use the same value for both.

Most encrypted documents in the wild are "pseudo-encrypted" with an empty password in order to embed the permissions/access rights. TBD

Proxy Property (SecurePDF 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.

RecipientCert Property (SecurePDF Component)

The encryption certificate.

Syntax

• C#
• VB.NET

public Certificate RecipientCert { get; set; }

Public Property RecipientCert As Certificate

Remarks

This property is used to provide the certificate used for encryption. Uncommon because encryption/decryption are usually done via a password, but still needed. Can rename to EncryptionCert for clarity/symmetry. We will not support encryption for multiple recipients. TBD

This property is not available at design time.

Signatures Property (SecurePDF 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 all the signatures and empty signature fields identified in the document. For example, the user may want to check a signature's Profile, SignatureValidationResult, or ChainValidationResult, or identify an empty field to sign later using FieldIndex.

Index can be obtained from the SignatureInfo/SignatureProcessed events' SigIndex parameter. TBD

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

SigningCert Property (SecurePDF 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 specify the certificate that should be used for signing the data. Note that this certificate should have a private key associated with it.

Use KnownCerts (or DocumentCerts) and the IncludeSigningChain config to supply the rest of the certificate chain for inclusion into the signature. TBD

This property is not available at design time.

SigningSettings Property (SecurePDF Component)

Manages signing settings.

Syntax

• C#
• VB.NET

public PDFSigningSettings SigningSettings { get; }

Public ReadOnly Property SigningSettings As PDFSigningSettings

Remarks

This property is used to tune up new signature settings. To adjust the visual parameters of the signature widget, use the SetWidgetProperty method.

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

TimestampServer Property (SecurePDF 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). See the pseudocode in the Sign method for when it must be set.

If the timestamping service enforces credential-based user authentication (basic or digest), the credentials can be provided in the same URL. For example: signer.TimestampServer = "http://user:password@timestamp.server.com/TsaService"; Needed for both signature timestamps and document timestamps. Communication with the TSA operates over HTTP, so if it requires HTTP authentication we should parse user credentials from the string like above.

Since TSAs can operate over HTTPS too, we have the SSLServerAuthentication and SSLStatus events. In the rare case that the TSA requires TLS client authentication, the user can provide the client certificate via the TSATLSClientCertStoreType, TSATLSClientCertStore, TSATLSClientCertSubject, and TSATLSClientCertStorePassword configs. TBD

TrustedCerts Property (SecurePDF 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.

Part of the BlockedCerts-KnownCerts-TrustedCerts trio. User-supplied. To prevent trusted certificates from residing in the same collection as blocked certificates. If we find a certificate in a chain (any chain we encounter and process, not just the signing chain) that's also in this collection, the certificate is explicitly trusted, and prior certificates therefore chain up to a trust anchor (meaning the trust aspect of that portion of chain validation succeeds).

Similar to KnownCerts, the user can add Certificate objects to it if they have their own certificates on hand and want the component to register them as trust anchors. An example scenario is when root CA certificates are absent from the standard system locations (or when there are 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 the parties that you know and trust.

The original idea was to have a Trust field in the Certificate type instead of these 3 different collections, but we decided not to go through with that because it would lead to confusion in existing products. Overall we sought to leave the Certificate type and the CertMgr component as intact as possible. TBD

This property is not available at design time.

TrustedLists Property (SecurePDF Component)

A list of 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 custom 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 validator will consult the Trusted List to establish certificate trust and obtain certificate qualifications, 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 (https://ec.europa.eu/tools/lotl/eu-lotl.xml) (later on, we can add more macros for different countries if needed). The user can append their own values: securepdf.TrustedLists = "%EUTL%;http://my.company/tsl;c:\tsls\mytsl.xml"; Just like the chain validator downloads CRLs when required, it will download a Trusted List and check the certificate against it without any specific user involvement. TBD

TrustSources Property (SecurePDF Component)

The trust sources to use during chain validation.

Syntax

• C#
• VB.NET

public SecurePDFTrustSources TrustSources { get; set; }

enum SecurePDFTrustSources {
  tsLocal,
  tsTrustedLists,
  tsLocalAndTrustedLists
}

Public Property TrustSources As SecurepdfTrustSources

Enum SecurePDFTrustSources
  tsLocal
  tsTrustedLists
  tsLocalAndTrustedLists
End Enum

Default Value

2

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. (TBD this info can go elsewhere)

Possible values are:

ValidationSettings Property (SecurePDF Component)

Manages chain validation settings.

Syntax

• C#
• VB.NET

public ValidationSettings ValidationSettings { get; }

Public ReadOnly Property ValidationSettings As ValidationSettings

Remarks

This property is used to tune up chain validation settings.

Probably the most important property for chain validation-related matters. Motivated by a need for users to have more fine-grained (and easier) control over the many parameters that dictate how chain validation should be performed in their environment. This includes both revocation and trust aspects.

Compared to SBB, it's more intuitive and packaged into one property here, with more advanced settings moved to Config that we expect will be used rarely (e.g. ValidationFlags). As opposed to something like IgnoreChainValidationErrors in SBB which is more of a catch-all. TBD

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

AddAttachment Method (SecurePDF 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 InputStream and to the Attachments collection.

The document containing the newly added attachment will be saved to OutputFile, OutputData, or OutputStream.

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

Example usage: securepdf.Open(); securepdf.AddAttachment("foo.txt", "desc"); securepdf.Close();

Alternatively, the user can create a PDFAttachment object and add it to Attachments manually: PDFAttachment attachment = new PDFAttachment(); attachment.FileName = "foo.txt"; // or attachment.Data = byte array // or attachment.InputStream = FileStream(...) attachment.Description = "desc"; securepdf.Attachments.Add(attachment); Or using one of the constructors: PDFAttachment attachment = new PDFAttachment("foo.txt", "desc"); securepdf.Attachments.Add(attachment); The full list of attachments is contained in the Attachments property. TBD

AddDocumentTimestamp Method (SecurePDF Component)

Adds a document timestamp to a PDF document.

Syntax

• C#
• VB.NET

public void AddDocumentTimestamp();

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

Public Sub AddDocumentTimestamp()

Async Version
Public Sub AddDocumentTimestamp() As Task
Public Sub AddDocumentTimestamp(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 InputStream. The updated document will be saved to OutputFile, OutputData, or OutputStream.

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

Example usage: // assuming InputFile and OutputFile are already set securepdf.AddDocumentTimestamp(); For visibility, this method is a shortcut/alias for the following: // assuming InputFile and OutputFile are already set securepdf.SigningSettings.Type = stDTS; securepdf.Update(0); Can be used to update a B-B/B-T signature to B-LTA or extend an existing B-LTA. In PDF, document timestamps are fully independent signatures made by the TSA, so TimestampServer will also need to be set before this method is called.

The user does not need to provide a signing certificate or chain when adding document timestamps, since this type of signature is done with a TSA's certificate. TBD

Close Method (SecurePDF 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 InputStream. It should always be preceded by a call to the Open method.

Example usage: securepdf.InputFile = "input.pdf"; securepdf.Open(); // some action securepdf.Close();

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

We won't write to OutputFile, OutputData, or OutputStream by default if the document is unchanged. TBD

Config Method (SecurePDF 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.

Decrypt Method (SecurePDF Component)

Decrypts a PDF document.

Syntax

• C#
• VB.NET

public void Decrypt();

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

Public Sub Decrypt()

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

Remarks

This method is used to permanently remove encryption from the PDF document specified in InputFile, InputData, or InputStream. The document will be decrypted with either Password (for password-based encryption) or DecryptionCert (for certificate-based encryption) and saved in OutputFile, OutputData, or OutputStream.

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

Should be called consciously, i.e. when the user is aware that the document is encrypted. We therefore expect the user to set the correct decryption material before calling this method. But it will still fire the EncryptionInfo event (like Open does) which gives the user one last chance to provide the correct decryption material. We shouldn't necessarily advertise this approach though. In general,

• User is aware that the document is encrypted: set Password/DecryptionCert and call Decrypt. For example, users who will want to process encrypted documents as part of some batch flow.
• User is unaware that the document is encrypted: call Open and subscribe to EncryptionInfo. For example, users who will come across encrypted documents occasionally as part of the verification process.

Example usage: securepdf.InputFile = "encrypted.pdf"; securepdf.OutputFile = "decrypted.pdf"; // set decryption material (Password or DecryptionCert) here securepdf.Decrypt(); ... // then they can Sign(), AddAttachment(), etc. Can also be called after the Open method to save a decrypted copy of the document before calling the Close method. For example: securepdf.InputFile = "encrypted.pdf"; securepdf.Open(); // some action, say Verify() or SaveAttachment() securepdf.OutputFile = "decrypted.pdf"; securepdf.Decrypt(); securepdf.Close(); The Verify method cannot be called after this method because since the encryption trailer gets removed when encryption is removed, invalidating all signatures. Because of this, this method will call Unsign internally, automatically removing all signatures from the document. The user can/should Verify any signatures before this method is called. TBD

Encrypt Method (SecurePDF Component)

Encrypts a PDF document.

Syntax

• C#
• VB.NET

public void Encrypt();

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

Public Sub Encrypt()

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

Remarks

This method is used to encrypt the PDF document specified in InputFile, InputData, or InputStream. The document will be encrypted with either Password (for password-based encryption) or RecipientCert (for certificate-based encryption), EncryptionAlgorithm, and saved in OutputFile, OutputData, or OutputStream.

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

Example usage: securepdf.InputFile = "input.pdf"; securepdf.OutputFile = "encrypted.pdf"; securepdf.Password = "password"; securepdf.EncryptionAlgorithm = "AES256"; securepdf.Encrypt(); We will not support encryption for multiple recipients. TBD

GetPageProperty Method (SecurePDF 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 InputStream, 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 is one of the following values:

Complements the PageCount parameter in the DocumentInfo event. For example: int pageCount = 0; securepdf.OnDocumentInfo += (s, e) => { pageCount = e.PageCount; }; securepdf.Open(); for (int i = 1; i <= pageCount; i++) securepdf.GetPageProperty(i, "Height"); securepdf.Close();

The alternative, which we dismissed, was to have a Pages collection and PDFPage type to house the same properties. We thought having that info at the top level would pollute the API because the user only really needs to query the page properties to adjust the position of the signature widget based on the page dimensions. For example: int x = int.Parse(securepdf.GetPageProperty(1, "Width")) - 100; int y = int.Parse(securepdf.GetPageProperty(1, "Height")) - 100; securepdf.SetWidgetProperty("OffsetX", x.ToString()); securepdf.SetWidgetProperty("OffsetY", y.ToString()); Having a Config-like method here also allows us to expand the properties in the future if needed.

There is no accompanying SetPageProperty method because these are read-only properties from the document itself, they cannot be modified. TBD

GetSignedVersion Method (SecurePDF Component)

Returns the part of a signed PDF document that is covered by the signature.

Syntax

• C#
• VB.NET

public void GetSignedVersion(int sigIndex);

Async Version
public async Task GetSignedVersion(int sigIndex);
public async Task GetSignedVersion(int sigIndex, CancellationToken cancellationToken);

Public Sub GetSignedVersion(ByVal SigIndex As Integer)

Async Version
Public Sub GetSignedVersion(ByVal SigIndex As Integer) As Task
Public Sub GetSignedVersion(ByVal SigIndex As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to retrieve the revision of the document specified in InputFile, InputData, or InputStream that is covered by the signature specified by SigIndex. The extracted revision will be saved to OutputFile, OutputData, or OutputStream.

The SigIndex parameter is the index of the signature of interest in the Signatures collection.

Example usage: // assuming InputFile and OutputFile are already set securepdf.Open(); securepdf.GetSignedVersion(0); securepdf.Close(); PDF documents often use an incremental update approach, with any changes being appended to the document without altering the existing revision. This may lead to situations where a signature only covers part of the document (one of the past revisions), but not subsequent changes. This method provides a means to extract the revision that is actually certified by the signature.

It is recommended that you use this method when validating signatures to make sure the signature covers what you expect it to cover.

An alternative to this method is to check the CoverageEndsAt field of the signature object and match it to the document length. TBD

GetWidgetProperty Method (SecurePDF Component)

Retrieves the value of a signature widget property.

Syntax

• C#
• VB.NET

public string GetWidgetProperty(int sigIndex, string property);

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

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

Async Version
Public Function GetWidgetProperty(ByVal SigIndex As Integer, ByVal Property As String) As Task(Of String)
Public Function GetWidgetProperty(ByVal SigIndex 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.

The SigIndex 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 is one of the following values:

Example usage: securepdf.Open(); bool invisible = bool.Parse(securepdf.GetWidgetProperty(0, "Invisible")); securepdf.Close(); Having a Config-like method here also allows us to expand the properties in the future if needed. TBD

Interrupt Method (SecurePDF 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 ChainCertInfo event to abort the chain validation procedure.

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

IsDocumentEncrypted Method (SecurePDF Component)

Checks whether a PDF document is encrypted.

Syntax

• C#
• VB.NET

public bool IsDocumentEncrypted();

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

Public Function IsDocumentEncrypted() As Boolean

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

Remarks

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

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

Used to notify the user that the document is encrypted before they try to call Open or Decrypt. For example: securepdf.InputFile = "input.pdf"; if (securepdf.IsDocumentEncrypted()) { // set Password or DecryptionCert as an alternative to providing it in the EncryptionInfo event } securepdf.Open(); // some action securepdf.Close(); securepdf.InputFile = "input.pdf"; if (securepdf.IsDocumentEncrypted()) { securepdf.OutputFile = "decrypted.pdf"; // set Password or DecryptionCert securepdf.Decrypt(); } As for checking whether the document is encrypted, we need to parse the trailer first and then check if the Encrypt dictionary reference is present in the trailer. Then parse xref to get the address of Encrypt dictionary and seek to read Encrypt dictionary. If the Encrypt dictionary is found, then the document is encrypted. In this process a temp file might be created in case of the inputStream is not seekable. We do not need to call the Open method in the API. But it shares some logic. So we will call Close internally to close stream and release temp file at the end of this method. TBD

IsDocumentSigned Method (SecurePDF Component)

Checks whether a PDF document is signed.

Syntax

• C#
• VB.NET

public bool IsDocumentSigned();

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

Public Function IsDocumentSigned() As Boolean

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

Remarks

This method is used to determine whether or not the document specified in InputFile, InputData, or InputStream is signed.

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

Example usage: securepdf.InputFile = "input.pdf"; if (securepdf.IsDocumentSigned()) securepdf.Verify(); TBD

Open Method (SecurePDF 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 InputStream 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. If changes were made, the modified document will be saved to OutputFile, OutputData, or OutputStream.

Will fire EncryptionInfo (when applicable) and DocumentInfo. To be used alongside Close whenever some action needs to be performed on the document, mostly for updating signatures. This method will NOT automatically verify signatures.

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

Automatic Decryption Scheme

Once the user supplies the decryption material (or is unaware and Password is kept empty in the pseudo-encrypted case), we will then attempt to decrypt the document automatically within this method for two reasons:

• There is little point in having an opened yet still encrypted document. We can't get anything from such document unless we decrypt it. The only action that the user can do with such document is Decrypt it (or Close it). This makes the Decrypt call redundant - the user will be either forced to call it (if the document is encrypted) or forced not to call it (if it isn't).
• Most encrypted documents in the wild are "pseudo-encrypted" (with an empty password), and many users don't even know that their document is encrypted as Acrobat decrypts it on-the-fly and behind the scenes. Telling them a story of such pseudo-encrypted documents would be challenging both for such users and ourselves.

After we decrypt, the user can then conduct some manipulation on the document (verify signatures, extract attachments).

Now, if the user wants to get a decrypted copy of the document, they must call Decrypt - if they don't, we will preserve the document's encrypted status when saving it later.

The user calls Close (SaveChanges set to 1 or 2). The document is saved in decrypted form (Decrypt has been called) or in encrypted form (Decrypt was not called).

Automatic Decryption Scheme Issues

• The PDF may be encrypted with both a user password (Password) and an OwnerPassword. If these passwords are different (e.g. the OwnerPassword is empty to protect the permissions) and the user password is used to open the PDF, we will decrypt with the user password.

  This means we will remove the owner password, which ultimately means the user can remove the permissions without knowing the owner password. We decided that the component shouldn't necessarily be responsible for enforcing the intent of the original owner. Can always add a config later if a customer comes in exposing this problem.

• For a signed AND encrypted PDF, if we first decrypt the PDF, we will modify the encryption trailer and then verification will fail. The encryption trailer needs to be preserved on Sign/Verify and deleted on Decrypt. So to allow the user to actually call methods, we need to keep the encryption trailer intact.

  We should follow what SBB does with its dmSign decryption mode: only the necessary parts of the document are decrypted (e.g. those related to signatures), then optionally new objects (e.g. attachments, new signatures) are added, and then the decrypted and new objects are re-encrypted (assuming the de/encryption material is available). The Encrypt dictionary is not changed in this case.

  Note that you can update an encrypted document in the 'incremental update' way (append new objects to the end), which lets you add new stuff without invalidating existing signatures.

RemoveAttachment Method (SecurePDF 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 InputStream and from the Attachments collection.

The document without the attachment will be saved to OutputFile, OutputData, or OutputStream.

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

Example usage: securepdf.Open(); securepdf.RemoveAttachment(0); securepdf.Close(); Alternatively, the user can remove an attachment from Attachments manually: securepdf.Open(); PDFAttachment attachment = securepdf.Attachments[0]; securepdf.Attachments.Remove(attachment); securepdf.Close(); TBD

Reset Method (SecurePDF 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 to their default values.

SaveAttachment Method (SecurePDF 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 InputStream 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 usage: securepdf.Open(); securepdf.SaveAttachment(0, "a.dat"); securepdf.Close(); Saving to a stream: securepdf.Attachments[0].OutputStream = myStream; securepdf.SaveAttachment(0, ""); // empty string means use the OutputStream field if it's not null TBD

SetWidgetProperty Method (SecurePDF 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.

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

No index because setting is ONLY applicable to the signature the user is about to create. Widgets cannot be modified after the fact.

Example usage: securepdf.SetWidgetProperty("Width", "100"); securepdf.SetWidgetProperty("Height", "100"); securepdf.Sign(); Having a Config-like method here also allows us to expand the properties in the future if needed. TBD

Sign Method (SecurePDF 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 InputStream. The document will be signed with SigningCert as configured in SigningSettings and saved in OutputFile, OutputData, or OutputStream.

Use KnownCerts, TrustedCerts, and ValidationSettings to adjust chain validation parameters. During signing, the chain validation log will be available via the Log event if applicable.

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

Achieving Each PAdES Profile

Updating a B-B or B-T to B-LT: // assuming InputFile, OutputFile, etc. are already set (don't need SigningCert here) signer.TimestampServer = "https://freetsa.org/tsr"; // internally, we DO need to collect revocation info here signer.Update(0); Updating a B-B or B-T to B-LTA: // assuming InputFile, OutputFile, etc. are already set (don't need SigningCert here) signer.SigningSettings.Type = PDFSignatureTypes.stDTS; signer.TimestampServer = "https://freetsa.org/tsr"; // internally, we DO need to collect revocation info here signer.Update(0); Updating a B-B or B-T to B-LTA (simpler alternative): // assuming InputFile, OutputFile, etc. are already set (don't need SigningCert here) signer.TimestampServer = "https://freetsa.org/tsr"; // internally, we DO need to collect revocation info here signer.AddDocumentTimestamp(); Extending an existing B-LTA: // assuming InputFile, OutputFile, etc. are already set (don't need SigningCert here) signer.SigningSettings.Type = PDFSignatureTypes.stDTS; signer.TimestampServer = "https://freetsa.org/tsr"; // internally, we DO need to collect revocation info here signer.Update(0); Extending an existing B-LTA (simpler alternative): // assuming InputFile, OutputFile, etc. are already set (don't need SigningCert here) signer.TimestampServer = "https://freetsa.org/tsr"; // internally, we DO need to collect revocation info here signer.AddDocumentTimestamp(); TBD

Unsign Method (SecurePDF Component)

Removes a signature from a PDF document.

Syntax

• C#
• VB.NET

public void Unsign(int sigIndex, int unsignKind);

Async Version
public async Task Unsign(int sigIndex, int unsignKind);
public async Task Unsign(int sigIndex, int unsignKind, CancellationToken cancellationToken);

Public Sub Unsign(ByVal SigIndex As Integer, ByVal UnsignKind As Integer)

Async Version
Public Sub Unsign(ByVal SigIndex As Integer, ByVal UnsignKind As Integer) As Task
Public Sub Unsign(ByVal SigIndex As Integer, ByVal UnsignKind As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to remove/delete an existing signature specified by SigIndex from the document specified in InputFile, InputData, or InputStream. The document with the removed signature will be saved to OutputFile, OutputData, or OutputStream.

The SigIndex parameter is the index of the signature in the Signatures collection to be removed.

The UnsignKind parameter specifies the kind of unsign to perform. Possible values are:

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

Example usage: securepdf.InputFile = "signed.pdf"; securepdf.Open(); securepdf.Unsign(0, 0); // uskFull securepdf.Close();

Note that unsigning is different from GetSignedVersion. The latter returns the revision of the document including the mentioned signature (thus removing anything after that signature was created). Unsign removes the signature completely by carving it out of the document.

Will typically be sandwiched in between Open and Close because we will need to load existing signatures in order to remove them. Plus they can grab the SigIndex from e.g. the SignatureInfo event (which Verify will fire) to pass to this method. TBD

Update Method (SecurePDF Component)

Updates a signature.

Syntax

• C#
• VB.NET

public void Update(int sigIndex);

Async Version
public async Task Update(int sigIndex);
public async Task Update(int sigIndex, CancellationToken cancellationToken);

Public Sub Update(ByVal SigIndex As Integer)

Async Version
Public Sub Update(ByVal SigIndex As Integer) As Task
Public Sub Update(ByVal SigIndex As Integer, cancellationToken As CancellationToken) As Task

Remarks

This method is used to update a signature specified by SigIndex by embedding newer or missing revocation information into the signed document specified in InputFile, InputData, or InputStream. The updated document will be saved to OutputFile, OutputData, or OutputStream.

The SigIndex parameter is the index of the signature in the Signatures collection to be updated.

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 and SigningSettings.Type to stDTS to have the component obtain and embed a document timestamp automatically. See the pseudocode in the Sign method for when these must be set (including for adding document timestamps).

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

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

We don't have a simple Timestamp method because adding a signature timestamp to an existing signature (i.e. "updating" B-B to B-T), though possible, is technically not permitted in PDF. The design flaw is that you can't extend a signature once you've added it because the space for the signature + timestamp must be pre-allocated.

Will typically be sandwiched in between Open and Close because we will need to load existing signatures in order to update them. Plus they can grab the SigIndex from e.g. the SignatureInfo event (which Verify will fire) to pass to this method. TBD

Verify Method (SecurePDF Component)

Verifies a signed PDF document.

Syntax

• C#
• VB.NET

public void Verify();

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

Public Sub Verify()

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

Remarks

This method is used to validate all signatures in the document specified in InputFile, InputData, or InputStream.

This method walks through the signed document and reports every signature via the SignatureInfo event. Subscribe to the event to be notified about the signatures and adjust validation settings on the fly.

Upon completion of this method, the signature details will be published in the Signatures property.

This method only validates the signatures and does not check their coverage. It is a good idea to use mechanisms such as GetSignedVersion or CoverageEndsAt to ensure that the signature covers the expected document revision.

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

Example usage: securepdf.InputFile = "signed.pdf"; securepdf.Verify(); PDFSignature signature = securepdf.Signatures[0]; if (signature.SignatureValidationResult == svrValid) Console.WriteLine("Signature is good"); if (signature.ChainValidationResult == cvrValid) Console.WriteLine("Chain is good"); In the case of document timestamps, signatures should be verified in a backwards order:

• Verify/check the validation result of the document timestamp.
• If the result is valid, use the document timestamp's ValidatedSigningTime as the ValidationMoment for the next "normal" signature.

We initially had a SigIndex parameter here so the user could validate each signature individually, but we removed it to match SBB and Adobe. To verify individual signatures, the user can subscribe to the SignatureInfo event and set the ValidateSignature and ValidateChain parameters. The results are reported via the SignatureProcessed event's SignatureValidationResult and ChainValidationResult parameters.

This provides enough flexibility to control the validation process, as chain validation can be a very time-consuming process, and just going ahead with the validation for every signature in the document may result in dramatic slowdowns. Two example use cases for individual control over validation:

• Letting the user stop further validation if one of the signatures is found to be invalid
• Providing an option for avoiding or tuning up chain validation for certain signing certificates (for example adjusting ValidationSettings on a per-signature basis within SignatureInfo)

ChainCertInfo Event (SecurePDF Component)

Fired when the component encounters a chain certificate.

Syntax

• C#
• VB.NET

public event OnChainCertInfoHandler OnChainCertInfo;

public delegate void OnChainCertInfoHandler(object sender, SecurePDFChainCertInfoEventArgs e);

public class SecurePDFChainCertInfoEventArgs : EventArgs {
  public string CertEncoded { get; }
  public byte[] CertEncodedB { get; }
  public string CertSubject { get; }
  public string CertIssuer { get; }
  public string ValidationMoment { get; }
  public int ValidationResult { get; }
  public int ValidationDetails { get; }
}

Public Event OnChainCertInfo As OnChainCertInfoHandler

Public Delegate Sub OnChainCertInfoHandler(sender As Object, e As SecurePDFChainCertInfoEventArgs)

Public Class SecurePDFChainCertInfoEventArgs 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 ValidationMoment As String
  Public ReadOnly Property ValidationResult As Integer
  Public ReadOnly 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. Could be from the main signing chain, a TSA chain, a CRL/OCSP chain, etc. The component will try to retrieve all required chain certificates automatically to prevent user involvement as much as possible.

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 ValidationMoment parameter specifies the time point at which the certificate validity was established. The time is provided in UTC.

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

Can potentially be useful for displaying the full chain for a particular signature as an asynchronous alternative to reading them from KnownCerts or DocumentCerts after validation. TBD

DocumentInfo Event (SecurePDF Component)

Fired when the document has been processed.

Syntax

• C#
• VB.NET

public event OnDocumentInfoHandler OnDocumentInfo;

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

public class SecurePDFDocumentInfoEventArgs : EventArgs {
  public int PageCount { get; }
  public int SigCount { get; }
  public int FieldCount { get; }
}

Public Event OnDocumentInfo As OnDocumentInfoHandler

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

Public Class SecurePDFDocumentInfoEventArgs Inherits EventArgs
  Public ReadOnly Property PageCount As Integer
  Public ReadOnly Property SigCount As Integer
  Public ReadOnly Property FieldCount As Integer
End Class

Remarks

This event is fired once per document processing routine to report the completion of the document processing.

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 SigCount parameter reports the number of signatures in the document.

The FieldCount parameter reports the number of empty signature fields in the document.

(Signatures.Count = SigCount + FieldCount)

This event is fired when the Open method is called, but only after EncryptionInfo 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. TBD

EncryptionInfo Event (SecurePDF Component)

Fired when the component detects that the PDF document is encrypted.

Syntax

• C#
• VB.NET

public event OnEncryptionInfoHandler OnEncryptionInfo;

public delegate void OnEncryptionInfoHandler(object sender, SecurePDFEncryptionInfoEventArgs e);

public class SecurePDFEncryptionInfoEventArgs : EventArgs {
  public bool CertUsed { get; }
  public string Issuer { get; }
  public string SerialNumber { get; }
}

Public Event OnEncryptionInfo As OnEncryptionInfoHandler

Public Delegate Sub OnEncryptionInfoHandler(sender As Object, e As SecurePDFEncryptionInfoEventArgs)

Public Class SecurePDFEncryptionInfoEventArgs Inherits EventArgs
  Public ReadOnly Property CertUsed As Boolean
  Public ReadOnly Property Issuer As String
  Public ReadOnly Property SerialNumber As String
End Class

Remarks

This event is fired during document processing to report that the document is encrypted and to pass certificate parameters. When Open or Decrypt is called, this event is fired once for each encryption mechanism used in the document, providing the opportunity to supply the correct decryption material via the DecryptionCert or Password property (depending on the encryption method used). Most of the time it will fire just once overall because encryption for multiple recipients is uncommon.

The CertUsed parameter indicates whether the document was encrypted with a certificate. If set to false, the document uses password encryption, so provide the password via the Password property.

The Issuer parameter specifies the subject of the issuer certificate (if CertUsed is set to true).

The SerialNumber parameter specifies the serial number of the encryption certificate (if CertUsed is set to true).

Note that 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. We will not support encryption for multiple recipients though.

We will decrypt on-the-fly (once the user supplies the necessary decryption material by setting the Password or DecryptionCert properties within this event) but keep the decrypted document in memory unless the user calls Decrypt.

Even if the user does not subscribe to this event, they will still be able to process pseudo-encrypted documents as those will be decrypted for them automatically without their knowledge.

Will fire before DocumentInfo can fire because we can't process the document if it's still encrypted.

We originally had a Skip parameter here that would have skipped the current encryption mechanism. We determined it wasn't required because we don't fire this event repeatedly for a single encryption mechanism (only once), so skipping wouldn't do anything. TBD

Error Event (SecurePDF 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, SecurePDFErrorEventArgs e);

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

Public Event OnError As OnErrorHandler

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

Public Class SecurePDFErrorEventArgs 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 (SecurePDF Component)

Fired when log information is available during processing.

Syntax

• C#
• VB.NET

public event OnLogHandler OnLog;

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

public class SecurePDFLogEventArgs : 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 SecurePDFLogEventArgs)

Public Class SecurePDFLogEventArgs 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 will need to be extremely detailed (LogLevel=3), especially for chain validation. SBB's ValidationLog uses a tree-like view with indentations which helps make it more readable. We want ours to be super readable too. TBD

SignatureInfo Event (SecurePDF 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, SecurePDFSignatureInfoEventArgs e);

public class SecurePDFSignatureInfoEventArgs : EventArgs {
  public int SigIndex { 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 SecurePDFSignatureInfoEventArgs)

Public Class SecurePDFSignatureInfoEventArgs Inherits EventArgs
  Public ReadOnly Property SigIndex 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 SigIndex is about to be validated. Will fire for normal signatures as well as document timestamps.

The SigIndex parameter is the index of the signature in the Signatures collection. Can be used for example to read some of the indexed signature configs like FullSignatureName.

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 the user to verify signatures individually instead of all at once (what Verify does). To skip validation entirely, set both parameters to false.

We considered removing this event altogether since the user can iterate over all the signatures in the Signatures collection after the Open call succeeds anyway, but that was before ValidateSignature and ValidateChain were topics of discussion. TBD

SignatureProcessed Event (SecurePDF Component)

Fired after a signature has been processed.

Syntax

• C#
• VB.NET

public event OnSignatureProcessedHandler OnSignatureProcessed;

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

public class SecurePDFSignatureProcessedEventArgs : EventArgs {
  public int SigIndex { 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 SecurePDFSignatureProcessedEventArgs)

Public Class SecurePDFSignatureProcessedEventArgs Inherits EventArgs
  Public ReadOnly Property SigIndex 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 SigIndex has completed validation. Will fire if Verify is called (verifying all signatures at once) OR if one or both of the ValidateSignature and ValidateChain parameters in SignatureInfo are true (verifying signatures individually). Will fire for normal signatures as well as document timestamps.

The SigIndex 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:

SignatureValidationResult, ChainValidationResult, and ChainValidationDetails can also be read from the PDFSignature type after chain validation completes. TBD

SSLServerAuthentication Event (SecurePDF 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, SecurePDFSSLServerAuthenticationEventArgs e);

public class SecurePDFSSLServerAuthenticationEventArgs : 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 SecurePDFSSLServerAuthenticationEventArgs)

Public Class SecurePDFSSLServerAuthenticationEventArgs 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

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 Accept is False, Status 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 (SecurePDF Component)

Fired when secure connection progress messages are available.

Syntax

• C#
• VB.NET

public event OnSSLStatusHandler OnSSLStatus;

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

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

Public Event OnSSLStatus As OnSSLStatusHandler

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

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

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

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()

Creates a Certificate instance whose properties can be set. This is useful for use with CERTMGR when generating new certificates.

• C#
• VB.NET

public Certificate(string certificateFile);

Public Certificate(ByVal CertificateFile As String)

Opens CertificateFile and reads out the contents as an X.509 public key.

• C#
• VB.NET

public Certificate(byte[] encoded);

Public Certificate(ByVal Encoded As Byte())

Parses Encoded as an X.509 public key.

• 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)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

• 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)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. ConfigurationString is a newline separated list of name-value pairs that may be used to modify the default behavior. Possible values include "PersistPFXKey", which shows whether or not the PFX key is persisted after performing operations with the private key. This correlates to the PKCS12_NO_PERSIST_KEY CryptoAPI option. The default value is True (the key is persisted). "Thumbprint" - an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load. When specified, this value is used to select the certificate in the store. This is applicable to cstUser, cstMachine, cstPublicKeyFile, and cstPFXFile store types. "UseInternalSecurityAPI" shows whether the platform (default) or the internal security API is used when performing certificate-related operations. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

• 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())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

• 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)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or Base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

• 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)

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or Base64-encoded) containing the certificate data. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

• 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())

CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or Base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the component will load Encoded as an X.509 certificate and search the opened store for a corresponding private key.

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()

PDFSigningSettings Type

A container for PDF signing settings.

Remarks

This type contains settings used to configure PDF signing. Use it to tune up signature properties and widget appearance when creating a signature.

Fields

Constructors

• C#
• VB.NET

public PDFSigningSettings();

Public PDFSigningSettings()

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)

ValidationSettings Type

A container for chain validation settings.

Remarks

This type contains settings used to configure chain validation, such as revocation checks and the overall validation policy.

Fields

Constructors

• C#
• VB.NET

public ValidationSettings();

Public ValidationSettings()

Config Settings (SecurePDF Component)

SecurePDF Config Settings

Base Config Settings

Trappable Errors (SecurePDF Component)

SecurePDF Errors