PDFEncryptor Component

Properties   Methods   Events   Config Settings   Errors  

The PDFEncryptor component encrypts PDF documents.

Syntax

nsoftware.SecureBlackbox.Pdfencryptor

Remarks

PDFEncryptor encrypts PDF documents with passwords or certificates.

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.

DocumentInfo Property (PDFEncryptor Component)

Contains information about the document properties.

Syntax

• C#
• VB.NET

public PDFDocumentInfo DocumentInfo { get; }

Public ReadOnly Property DocumentInfo As PDFDocumentInfo

Remarks

Use this property to access general parameters of the document being processed. A good place to check this property is in the handler of the DocumentLoaded event.

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

EncryptionAlgorithm Property (PDFEncryptor Component)

The encryption algorithm to encrypt the document with.

Syntax

• C#
• VB.NET

public string EncryptionAlgorithm { get; set; }

Public Property EncryptionAlgorithm As String

Default Value

"AES256"

Remarks

Use this property to specify the encryption algorithm to encrypt the PDF document with.

Supported values:

EncryptionCertificate Property (PDFEncryptor Component)

The encryption certificate.

Syntax

• C#
• VB.NET

public Certificate EncryptionCertificate { get; set; }

Public Property EncryptionCertificate As Certificate

Remarks

Use this property to provide the encryption certificate. It does not need to have a private key, but the intended recipient of this PDF document does.

This property is not available at design time.

EncryptMetadata Property (PDFEncryptor Component)

Specifies whether to encrypt the document metadata.

Syntax

• C#
• VB.NET

public bool EncryptMetadata { get; set; }

Public Property EncryptMetadata As Boolean

Default Value

True

Remarks

Use this property to enable or disable metadata encryption.

Metadata contains additional information about the document, such as its name and author.

FIPSMode Property (PDFEncryptor Component)

Reserved.

Syntax

• C#
• VB.NET

public bool FIPSMode { get; set; }

Public Property FIPSMode As Boolean

Default Value

False

Remarks

This property is reserved for future use.

InputBytes Property (PDFEncryptor Component)

Use this property to pass the input to component in byte array form.

Syntax

• C#
• VB.NET

public byte[] InputBytes { get; set; }

Public Property InputBytes As Byte()

Remarks

Assign a byte array containing the data to be processed to this property.

This property is not available at design time.

InputFile Property (PDFEncryptor Component)

The PDF file to be encrypted.

Syntax

• C#
• VB.NET

public string InputFile { get; set; }

Public Property InputFile As String

Default Value

""

Remarks

Provide the path to the PDF document to be encrypted.

InputStream Property (PDFEncryptor Component)

A stream containing the PDF document.

Syntax

• C#
• VB.NET

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

Public Property InputStream As System.IO.Stream

Default Value

null

Remarks

Use this property to supply the PDF document for encryption in a stream.

This property is not available at design time.

OutputBytes Property (PDFEncryptor Component)

Use this property to read the output the component object has produced.

Syntax

• C#
• VB.NET

public byte[] OutputBytes { get; }

Public ReadOnly Property OutputBytes As Byte()

Remarks

Read the contents of this property after the operation has completed to read the produced output. This property will only be set if the OutputFile and OutputStream properties had not been assigned.

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

OutputFile Property (PDFEncryptor Component)

The file to save the encrypted document to.

Syntax

• C#
• VB.NET

public string OutputFile { get; set; }

Public Property OutputFile As String

Default Value

""

Remarks

Specifies the path where the encrypted PDF should be saved.

OutputStream Property (PDFEncryptor Component)

The stream to write the encrypted document to.

Syntax

• C#
• VB.NET

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

Public Property OutputStream As System.IO.Stream

Default Value

null

Remarks

Use this property to pass a stream to save the encrypted document to.

This property is not available at design time.

OwnerPassword Property (PDFEncryptor Component)

The owner password.

Syntax

• C#
• VB.NET

public string OwnerPassword { get; set; }

Public Property OwnerPassword As String

Default Value

""

Remarks

Use this property to provide the document owner password. Though it may be different from UserPassword, most implementations use the same value for both.

Permissions Property (PDFEncryptor Component)

Specifies the document permissions associated with the encryption.

Syntax

• C#
• VB.NET

public int Permissions { get; set; }

Public Property Permissions As Integer

Default Value

0

Remarks

Use this property to specify the permissions protected by this encryption. The PDF specification expects applications to comply with these permissions when handling encrypted documents, but keep in mind that it is a policy-like requirement rather than an enforcement. Provide the permissions as a bit mask of the following flags:

This property is not available at design time.

UserPassword Property (PDFEncryptor Component)

The user password.

Syntax

• C#
• VB.NET

public string UserPassword { get; set; }

Public Property UserPassword As String

Default Value

""

Remarks

Use this property to provide the document user password. Though it may be different from OwnerPassword, most implementations use the same value for both.

Config Method (PDFEncryptor Component)

Sets or retrieves a configuration setting.

Syntax

• C#
• VB.NET

public string Config(string configurationString);

Public Function Config(ByVal ConfigurationString As String) As 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.

DoAction Method (PDFEncryptor Component)

Performs an additional action.

Syntax

• C#
• VB.NET

public string DoAction(string actionID, string actionParams);

Public Function DoAction(ByVal ActionID As String, ByVal ActionParams As String) As String

Remarks

DoAction is a generic method available in every component. It is used to perform an additional action introduced after the product major release. The list of actions is not fixed, and may be flexibly extended over time.

The unique identifier (case insensitive) of the action is provided in the ActionID parameter.

ActionParams contains the value of a single parameter, or a list of multiple parameters for the action in the form of PARAM1=VALUE1;PARAM2=VALUE2;....

Encrypt Method (PDFEncryptor Component)

Encrypts the PDF document.

Syntax

• C#
• VB.NET

public void Encrypt();

Public Sub Encrypt()

Remarks

Use this method to encrypt the PDF document as configured in the object's properties.

DocumentLoaded Event (PDFEncryptor Component)

This event is fired when the document has been loaded into memory.

Syntax

• C#
• VB.NET

public event OnDocumentLoadedHandler OnDocumentLoaded;

public delegate void OnDocumentLoadedHandler(object sender, PdfencryptorDocumentLoadedEventArgs e);

public class PdfencryptorDocumentLoadedEventArgs : EventArgs {
  public bool Cancel { get; set; }
}

Public Event OnDocumentLoaded As OnDocumentLoadedHandler

Public Delegate Sub OnDocumentLoadedHandler(sender As Object, e As PdfencryptorDocumentLoadedEventArgs)

Public Class PdfencryptorDocumentLoadedEventArgs Inherits EventArgs
  Public Property Cancel As Boolean
End Class

Remarks

The handler for this event is a good place to check the document structure, which may be useful when preparing the signature. For example, you can use the Pages information to find the optimal position for the signature widget.

Set Cancel to true to terminate document processing on this stage.

Error Event (PDFEncryptor Component)

Information about errors during encryption.

Syntax

• C#
• VB.NET

public event OnErrorHandler OnError;

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

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

Public Event OnError As OnErrorHandler

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

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

Remarks

The event is fired in case of exceptional conditions during PDF processing.

ErrorCode contains an error code and Description contains a textual description of the error.

Notification Event (PDFEncryptor Component)

This event notifies the application about an underlying control flow event.

Syntax

• C#
• VB.NET

public event OnNotificationHandler OnNotification;

public delegate void OnNotificationHandler(object sender, PdfencryptorNotificationEventArgs e);

public class PdfencryptorNotificationEventArgs : EventArgs {
  public string EventID { get; }
  public string EventParam { get; }
}

Public Event OnNotification As OnNotificationHandler

Public Delegate Sub OnNotificationHandler(sender As Object, e As PdfencryptorNotificationEventArgs)

Public Class PdfencryptorNotificationEventArgs Inherits EventArgs
  Public ReadOnly Property EventID As String
  Public ReadOnly Property EventParam As String
End Class

Remarks

The component fires this event to let the application know about some event, occurrence, or milestone in the component. For example, it may fire to report completion of the document processing. The list of events being reported is not fixed, and may be flexibly extended over time.

The unique identifier of the event is provided in the EventID parameter. EventParam contains any parameters accompanying the occurrence. Depending on the type of the component, the exact action it is performing, or the document being processed, one or both may be omitted.

Certificate Type

Provides details of an individual X.509 certificate.

Remarks

This type provides access to X.509 certificate details.

Fields

Constructors

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count, string password);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] certBytes, int certStartIndex, int certCount, byte[] keyBytes, int keyStartIndex, int keyCount, string password);

Public Certificate(ByVal CertBytes As Byte(), ByVal CertStartIndex As Integer, ByVal CertCount As Integer, ByVal KeyBytes As Byte(), ByVal KeyStartIndex As Integer, ByVal KeyCount As Integer, ByVal Password As String)

Loads the X.509 certificate from a memory buffer. CertBytes is a buffer containing the raw certificate data. CertStartIndex and CertCount specify the number of bytes to be read from the buffer, respectively. KeyBytes is a buffer containing the private key data. KeyStartIndex and KeyCount specify the starting position and number of bytes to be read from the buffer, respectively. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(byte[] bytes, int startIndex, int count);

Public Certificate(ByVal Bytes As Byte(), ByVal StartIndex As Integer, ByVal Count As Integer)

Loads the X.509 certificate from a memory buffer. Bytes is a buffer containing the raw certificate data. StartIndex and Count specify the starting position and number of bytes to be read from the buffer, respectively.

• C#
• VB.NET

public Certificate(string path, string password);

Public Certificate(ByVal Path As String, ByVal Password As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string certPath, string keyPath, string password);

Public Certificate(ByVal CertPath As String, ByVal KeyPath As String, ByVal Password As String)

Loads the X.509 certificate from a file. CertPath specifies the full path to the file containing the certificate data. KeyPath specifies the full path to the file containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(string path);

Public Certificate(ByVal Path As String)

Loads the X.509 certificate from a file. Path specifies the full path to the file containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream);

Public Certificate(ByVal Stream As System.IO.Stream)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data.

• C#
• VB.NET

public Certificate(System.IO.Stream stream, string password);

Public Certificate(ByVal Stream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. Stream is a stream containing the certificate data. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate(System.IO.Stream certStream, System.IO.Stream keyStream, string password);

Public Certificate(ByVal CertStream As System.IO.Stream, ByVal KeyStream As System.IO.Stream, ByVal Password As String)

Loads the X.509 certificate from a stream. CertStream is a stream containing the certificate data. KeyStream is a stream containing the private key. Password is a password encrypting the certificate.

• C#
• VB.NET

public Certificate();

Public Certificate()

Creates a new object with default field values.

PDFDocumentInfo Type

Contains document security information.

Remarks

This type provides an overview of the document security parameters, including the encryption method (if used) and signature count. This information is available early into the signing/validation process and lets you prepare for the subsequent signature validation.

Fields

Constructors

• C#
• VB.NET

public PDFDocumentInfo();

Public PDFDocumentInfo()

Initializes an instance of PDFDocumentInfo class.

Config Settings (PDFEncryptor Component)

PDFEncryptor Config Settings

Base Config Settings

Trappable Errors (PDFEncryptor Component)

PDFEncryptor Errors