PDFEncrypt Control

Properties   Methods   Events   Config Settings   Errors  

The PDFEncrypt control encrypts PDF documents.

Syntax

PDFEncrypt

Remarks

As with signing, PDF encryption is part of the PDF format itself. It is used to prevent unauthorized access to documents and is performed using either an encryption password (known as password-based or symmetric encryption) or the intended document recipient's public X.509 certificate (known as certificate-based or asymmetric encryption). The PDFEncrypt control supports both encryption types.

The benefit of this encryption scheme as defined in the standard is that encrypted PDF documents are still valid PDF documents and can be handled by almost any PDF reader. Of course, this software will need to be able to decrypt such documents, but it can always reach the metadata (information about the document) and document structure.

Password-Based Encryption

In password-based encryption, the publishers and intended users of the document must know some secret key (a password), which is used both to protect the document and access the protected data. Once the document has been protected (encrypted), the password is required to get access to the document's contents. Although this method is straightforward and widely used for protecting PDF documents, the password must be passed from the publisher to the intended users, which presents a significant disadvantage.

The following code shows how to encrypt a PDF document with a user password: pdfencrypt.InputFile = "input.pdf"; pdfencrypt.OutputFile = "password_encrypted.pdf"; pdfencrypt.Password = "password"; pdfencrypt.Encrypt(); Owner passwords are also supported. Compared to user passwords, these passwords are used to protect the permissions (set via the Permissions property) that will be embedded into the document. For example, you may want to prevent the recipient from printing or editing the document. You can encrypt the document with an owner password by specifying the OwnerPassword configuration setting before calling the Encrypt method.

Certificate-Based Encryption

Certificate-based encryption uses X.509 digital certificates to encrypt data. This encryption type provides a higher level of security compared to password-based encryption, as it relies on cryptographic key pairs, making it more difficult for unauthorized users to gain access. It is often used in environments where secure and authenticated document exchange is critical. Encrypting with a certificate (as opposed to a password) ensures that only the intended recipient who possesses the corresponding private key can decrypt the PDF document.

The following code shows how to encrypt a PDF document with a certificate: pdfencrypt.InputFile = "input.pdf"; pdfencrypt.OutputFile = "cert_encrypted.pdf"; pdfencrypt.EncryptionCert = new Certificate(CertStoreTypes.cstPublicKeyFile, "C:/MyCerts/cert.cer", "", "*"); pdfencrypt.Encrypt(); When encrypting using either a password or certificate, set the EncryptionAlgorithm property to the desired encryption algorithm. As additional encryption options, you can also decide whether the document metadata will be encrypted and embed permissions into the document via the EncryptMetadata and Permissions properties respectively.

Property List


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

EncryptionAlgorithmThe encryption algorithm to encrypt the PDF document with.
EncryptionCertEffectiveDateThe date on which this certificate becomes valid.
EncryptionCertExpirationDateThe date on which the certificate expires.
EncryptionCertExtendedKeyUsageA comma-delimited list of extended key usage identifiers.
EncryptionCertFingerprintThe hex-encoded, 16-byte MD5 fingerprint of the certificate.
EncryptionCertFingerprintSHA1The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.
EncryptionCertFingerprintSHA256The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.
EncryptionCertIssuerThe issuer of the certificate.
EncryptionCertPrivateKeyThe private key of the certificate (if available).
EncryptionCertPrivateKeyAvailableWhether a PrivateKey is available for the selected certificate.
EncryptionCertPrivateKeyContainerThe name of the PrivateKey container for the certificate (if available).
EncryptionCertPublicKeyThe public key of the certificate.
EncryptionCertPublicKeyAlgorithmThe textual description of the certificate's public key algorithm.
EncryptionCertPublicKeyLengthThe length of the certificate's public key (in bits).
EncryptionCertSerialNumberThe serial number of the certificate encoded as a string.
EncryptionCertSignatureAlgorithmThe text description of the certificate's signature algorithm.
EncryptionCertStoreThe name of the certificate store for the client certificate.
EncryptionCertStorePasswordIf the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.
EncryptionCertStoreTypeThe type of certificate store for this certificate.
EncryptionCertSubjectAltNamesComma-separated lists of alternative subject names for the certificate.
EncryptionCertThumbprintMD5The MD5 hash of the certificate.
EncryptionCertThumbprintSHA1The SHA-1 hash of the certificate.
EncryptionCertThumbprintSHA256The SHA-256 hash of the certificate.
EncryptionCertUsageThe text description of UsageFlags .
EncryptionCertUsageFlagsThe flags that show intended use for the certificate.
EncryptionCertVersionThe certificate's version number.
EncryptionCertSubjectThe subject of the certificate used for client authentication.
EncryptionCertEncodedThe certificate (PEM/Base64 encoded).
EncryptMetadataWhether to encrypt the document metadata.
InputDataA byte array containing the PDF document to process.
InputFileThe PDF file to process.
OutputDataA byte array containing the PDF document after processing.
OutputFileThe path to a local file where the output will be written.
OverwriteWhether or not the control should overwrite files.
PasswordThe password to encrypt the document with.
PermissionsThe document permissions associated with the encryption.

Method List


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

CloseCloses an opened PDF document.
ConfigSets or retrieves a configuration setting.
EncryptEncrypts a PDF document.
EncryptedChecks whether a PDF document is encrypted.
OpenOpens a PDF document for processing.
ResetResets the control.

Event List


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

ErrorFired when information is available about errors during data delivery.
LogFired once for each log message.
PasswordFired when the control detects that the PDF document is encrypted with a password.
RecipientInfoFired for each recipient certificate of the encrypted PDF document.

Config Settings


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

CloseInputStreamAfterProcessingWhether to close the input stream after processing.
CloseOutputStreamAfterProcessingWhether to close the output stream after processing.
CompressStreamsWhether to compress stream objects.
HardenedKeyGenerationWhether to use hardened key generation.
LogLevelThe level of detail that is logged.
OAEPMGF1HashAlgorithmThe MGF1 hash algorithm used with OAEP.
OAEPParamsThe hex-encoded OAEP parameters.
OAEPRSAHashAlgorithmThe RSA hash algorithm used with OAEP.
OwnerPasswordThe owner password to encrypt the document with.
RC4KeyBitsThe number of key bits used for the RC4 algorithm.
SaveChangesWhether to save changes made to the PDF document.
TempPathThe location where temporary files are stored.
UseOAEPWhether to use Optimal Asymmetric Encryption Padding (OAEP) during encryption and decryption.
CodePageThe system code page used for Unicode to Multibyte translations.
MaskSensitiveDataWhether sensitive data is masked in log messages.
UseInternalSecurityAPIWhether or not to use the system security libraries or an internal implementation.

EncryptionAlgorithm Property (PDFEncrypt Control)

The encryption algorithm to encrypt the PDF document with.

Syntax

pdfencryptcontrol.EncryptionAlgorithm[=string]

Default Value

"AES256"

Remarks

This property is used to specify the encryption algorithm to encrypt the document with.

Possible values are:

  • RC4
  • AES128
  • AES256

Data Type

String

EncryptionCertEffectiveDate Property (PDFEncrypt Control)

The date on which this certificate becomes valid.

Syntax

pdfencryptcontrol.EncryptionCertEffectiveDate

Default Value

""

Remarks

The date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

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

Data Type

String

EncryptionCertExpirationDate Property (PDFEncrypt Control)

The date on which the certificate expires.

Syntax

pdfencryptcontrol.EncryptionCertExpirationDate

Default Value

""

Remarks

The date on which the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

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

Data Type

String

EncryptionCertExtendedKeyUsage Property (PDFEncrypt Control)

A comma-delimited list of extended key usage identifiers.

Syntax

pdfencryptcontrol.EncryptionCertExtendedKeyUsage

Default Value

""

Remarks

A comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

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

Data Type

String

EncryptionCertFingerprint Property (PDFEncrypt Control)

The hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

pdfencryptcontrol.EncryptionCertFingerprint

Default Value

""

Remarks

The hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

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

Data Type

String

EncryptionCertFingerprintSHA1 Property (PDFEncrypt Control)

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

pdfencryptcontrol.EncryptionCertFingerprintSHA1

Default Value

""

Remarks

The hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

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

Data Type

String

EncryptionCertFingerprintSHA256 Property (PDFEncrypt Control)

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

pdfencryptcontrol.EncryptionCertFingerprintSHA256

Default Value

""

Remarks

The hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

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

Data Type

String

EncryptionCertIssuer Property (PDFEncrypt Control)

The issuer of the certificate.

Syntax

pdfencryptcontrol.EncryptionCertIssuer

Default Value

""

Remarks

The issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

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

Data Type

String

EncryptionCertPrivateKey Property (PDFEncrypt Control)

The private key of the certificate (if available).

Syntax

pdfencryptcontrol.EncryptionCertPrivateKey

Default Value

""

Remarks

The private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The EncryptionCertPrivateKey may be available but not exportable. In this case, EncryptionCertPrivateKey returns an empty string.

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

Data Type

String

EncryptionCertPrivateKeyAvailable Property (PDFEncrypt Control)

Whether a PrivateKey is available for the selected certificate.

Syntax

pdfencryptcontrol.EncryptionCertPrivateKeyAvailable

Default Value

False

Remarks

Whether a EncryptionCertPrivateKey is available for the selected certificate. If EncryptionCertPrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

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

Data Type

Boolean

EncryptionCertPrivateKeyContainer Property (PDFEncrypt Control)

The name of the PrivateKey container for the certificate (if available).

Syntax

pdfencryptcontrol.EncryptionCertPrivateKeyContainer

Default Value

""

Remarks

The name of the EncryptionCertPrivateKey container for the certificate (if available). This functionality is available only on Windows platforms.

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

Data Type

String

EncryptionCertPublicKey Property (PDFEncrypt Control)

The public key of the certificate.

Syntax

pdfencryptcontrol.EncryptionCertPublicKey

Default Value

""

Remarks

The public key of the certificate. The key is provided as PEM/Base64-encoded data.

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

Data Type

String

EncryptionCertPublicKeyAlgorithm Property (PDFEncrypt Control)

The textual description of the certificate's public key algorithm.

Syntax

pdfencryptcontrol.EncryptionCertPublicKeyAlgorithm

Default Value

""

Remarks

The textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

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

Data Type

String

EncryptionCertPublicKeyLength Property (PDFEncrypt Control)

The length of the certificate's public key (in bits).

Syntax

pdfencryptcontrol.EncryptionCertPublicKeyLength

Default Value

0

Remarks

The length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

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

Data Type

Integer

EncryptionCertSerialNumber Property (PDFEncrypt Control)

The serial number of the certificate encoded as a string.

Syntax

pdfencryptcontrol.EncryptionCertSerialNumber

Default Value

""

Remarks

The serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

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

Data Type

String

EncryptionCertSignatureAlgorithm Property (PDFEncrypt Control)

The text description of the certificate's signature algorithm.

Syntax

pdfencryptcontrol.EncryptionCertSignatureAlgorithm

Default Value

""

Remarks

The text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

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

Data Type

String

EncryptionCertStore Property (PDFEncrypt Control)

The name of the certificate store for the client certificate.

Syntax

pdfencryptcontrol.EncryptionCertStore[=string]

Default Value

"MY"

Remarks

The name of the certificate store for the client certificate.

The EncryptionCertStoreType property denotes the type of the certificate store specified by EncryptionCertStore. If the store is password-protected, specify the password in EncryptionCertStorePassword.

EncryptionCertStore is used in conjunction with the EncryptionCertSubject property to specify client certificates. If EncryptionCertStore has a value, and EncryptionCertSubject or EncryptionCertEncoded is set, a search for a certificate is initiated. Please see the EncryptionCertSubject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.

When the certificate store type is cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

To read or write binary data to the property, a Variant (Byte Array) version is provided in .EncryptionCertStoreB.

This property is not available at design time.

Data Type

Binary String

EncryptionCertStorePassword Property (PDFEncrypt Control)

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

pdfencryptcontrol.EncryptionCertStorePassword[=string]

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

This property is not available at design time.

Data Type

String

EncryptionCertStoreType Property (PDFEncrypt Control)

The type of certificate store for this certificate.

Syntax

pdfencryptcontrol.EncryptionCertStoreType[=integer]

Possible Values

cstUser(0), 
cstMachine(1), 
cstPFXFile(2), 
cstPFXBlob(3), 
cstJKSFile(4), 
cstJKSBlob(5), 
cstPEMKeyFile(6), 
cstPEMKeyBlob(7), 
cstPublicKeyFile(8), 
cstPublicKeyBlob(9), 
cstSSHPublicKeyBlob(10), 
cstP7BFile(11), 
cstP7BBlob(12), 
cstSSHPublicKeyFile(13), 
cstPPKFile(14), 
cstPPKBlob(15), 
cstXMLFile(16), 
cstXMLBlob(17), 
cstJWKFile(18), 
cstJWKBlob(19), 
cstSecurityKey(20), 
cstBCFKSFile(21), 
cstBCFKSBlob(22), 
cstPKCS11(23), 
cstAuto(99)

Default Value

0

Remarks

The type of certificate store for this certificate.

The control supports both public and private keys in a variety of formats. When the cstAuto value is used, the control will automatically determine the type. This property can take one of the following values:

0 (cstUser - default)For Windows, this specifies that the certificate store is a certificate store owned by the current user.

Note: This store type is not available in Java.

1 (cstMachine)For Windows, this specifies that the certificate store is a machine store.

Note: This store type is not available in Java.

2 (cstPFXFile)The certificate store is the name of a PFX (PKCS#12) file containing certificates.
3 (cstPFXBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in PFX (PKCS#12) format.
4 (cstJKSFile)The certificate store is the name of a Java Key Store (JKS) file containing certificates.

Note: This store type is only available in Java.

5 (cstJKSBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in Java Key Store (JKS) format.

Note: This store type is only available in Java.

6 (cstPEMKeyFile)The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains an SSH-style public key.
11 (cstP7BFile)The certificate store is the name of a PKCS#7 file containing certificates.
12 (cstP7BBlob)The certificate store is a string (binary) representing a certificate store in PKCS#7 format.
13 (cstSSHPublicKeyFile)The certificate store is the name of a file that contains an SSH-style public key.
14 (cstPPKFile)The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 (cstPPKBlob)The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 (cstXMLFile)The certificate store is the name of a file that contains a certificate in XML format.
17 (cstXMLBlob)The certificate store is a string that contains a certificate in XML format.
18 (cstJWKFile)The certificate store is the name of a file that contains a JWK (JSON Web Key).
19 (cstJWKBlob)The certificate store is a string that contains a JWK (JSON Web Key).
21 (cstBCFKSFile)The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store).

Note: This store type is only available in Java and .NET.

22 (cstBCFKSBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format.

Note: This store type is only available in Java and .NET.

23 (cstPKCS11)The certificate is present on a physical security key accessible via a PKCS#11 interface.

To use a security key, the necessary data must first be collected using the CertMgr control. The ListStoreCertificates method may be called after setting CertStoreType to cstPKCS11, CertStorePassword to the PIN, and CertStore to the full path of the PKCS#11 DLL. The certificate information returned in the CertList event's CertEncoded parameter may be saved for later use.

When using a certificate, pass the previously saved security key information as the EncryptionCertStore and set EncryptionCertStorePassword to the PIN.

Code Example. SSH Authentication with Security Key: certmgr.CertStoreType = CertStoreTypes.cstPKCS11; certmgr.OnCertList += (s, e) => { secKeyBlob = e.CertEncoded; }; certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"; certmgr.CertStorePassword = "123456"; //PIN certmgr.ListStoreCertificates(); sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*"); sftp.SSHUser = "test"; sftp.SSHLogon("myhost", 22);

99 (cstAuto)The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

This property is not available at design time.

Data Type

Integer

EncryptionCertSubjectAltNames Property (PDFEncrypt Control)

Comma-separated lists of alternative subject names for the certificate.

Syntax

pdfencryptcontrol.EncryptionCertSubjectAltNames

Default Value

""

Remarks

Comma-separated lists of alternative subject names for the certificate.

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

Data Type

String

EncryptionCertThumbprintMD5 Property (PDFEncrypt Control)

The MD5 hash of the certificate.

Syntax

pdfencryptcontrol.EncryptionCertThumbprintMD5

Default Value

""

Remarks

The MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

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

Data Type

String

EncryptionCertThumbprintSHA1 Property (PDFEncrypt Control)

The SHA-1 hash of the certificate.

Syntax

pdfencryptcontrol.EncryptionCertThumbprintSHA1

Default Value

""

Remarks

The SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

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

Data Type

String

EncryptionCertThumbprintSHA256 Property (PDFEncrypt Control)

The SHA-256 hash of the certificate.

Syntax

pdfencryptcontrol.EncryptionCertThumbprintSHA256

Default Value

""

Remarks

The SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

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

Data Type

String

EncryptionCertUsage Property (PDFEncrypt Control)

The text description of UsageFlags .

Syntax

pdfencryptcontrol.EncryptionCertUsage

Default Value

""

Remarks

The text description of EncryptionCertUsageFlags.

This value will be one or more of the following strings and will be separated by commas:

  • Digital Signature
  • Non-Repudiation
  • Key Encipherment
  • Data Encipherment
  • Key Agreement
  • Certificate Signing
  • CRL Signing
  • Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

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

Data Type

String

EncryptionCertUsageFlags Property (PDFEncrypt Control)

The flags that show intended use for the certificate.

Syntax

pdfencryptcontrol.EncryptionCertUsageFlags

Default Value

0

Remarks

The flags that show intended use for the certificate. The value of EncryptionCertUsageFlags is a combination of the following flags:

0x80Digital Signature
0x40Non-Repudiation
0x20Key Encipherment
0x10Data Encipherment
0x08Key Agreement
0x04Certificate Signing
0x02CRL Signing
0x01Encipher Only

Please see the EncryptionCertUsage property for a text representation of EncryptionCertUsageFlags.

This functionality currently is not available when the provider is OpenSSL.

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

Data Type

Integer

EncryptionCertVersion Property (PDFEncrypt Control)

The certificate's version number.

Syntax

pdfencryptcontrol.EncryptionCertVersion

Default Value

""

Remarks

The certificate's version number. The possible values are the strings "V1", "V2", and "V3".

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

Data Type

String

EncryptionCertSubject Property (PDFEncrypt Control)

The subject of the certificate used for client authentication.

Syntax

pdfencryptcontrol.EncryptionCertSubject[=string]

Default Value

""

Remarks

The subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

FieldMeaning
CNCommon Name. This is commonly a hostname like www.server.com.
OOrganization
OUOrganizational Unit
LLocality
SState
CCountry
EEmail Address

If a field value contains a comma, it must be quoted.

This property is not available at design time.

Data Type

String

EncryptionCertEncoded Property (PDFEncrypt Control)

The certificate (PEM/Base64 encoded).

Syntax

pdfencryptcontrol.EncryptionCertEncoded[=string]

Default Value

""

Remarks

The certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The EncryptionCertStore and EncryptionCertSubject properties also may be used to specify a certificate.

When EncryptionCertEncoded is set, a search is initiated in the current EncryptionCertStore for the private key of the certificate. If the key is found, EncryptionCertSubject is updated to reflect the full subject of the selected certificate; otherwise, EncryptionCertSubject is set to an empty string.

To read or write binary data to the property, a Variant (Byte Array) version is provided in .EncryptionCertEncodedB.

This property is not available at design time.

Data Type

Binary String

EncryptMetadata Property (PDFEncrypt Control)

Whether to encrypt the document metadata.

Syntax

pdfencryptcontrol.EncryptMetadata[=boolean]

Default Value

True

Remarks

This property indicates whether the document metadata will be encrypted when the Encrypt method is called. Metadata contains additional information about the document, such as its name and author.

Data Type

Boolean

InputData Property (PDFEncrypt Control)

A byte array containing the PDF document to process.

Syntax

pdfencryptcontrol.InputData[=byte array]

Remarks

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

This property is not available at design time.

Data Type

Byte Array

InputFile Property (PDFEncrypt Control)

The PDF file to process.

Syntax

pdfencryptcontrol.InputFile[=string]

Default Value

""

Remarks

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

Data Type

String

OutputData Property (PDFEncrypt Control)

A byte array containing the PDF document after processing.

Syntax

pdfencryptcontrol.OutputData

Remarks

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

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

Data Type

Byte Array

OutputFile Property (PDFEncrypt Control)

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

Syntax

pdfencryptcontrol.OutputFile[=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.

Data Type

String

Overwrite Property (PDFEncrypt Control)

Whether or not the control should overwrite files.

Syntax

pdfencryptcontrol.Overwrite[=boolean]

Default Value

False

Remarks

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

Data Type

Boolean

Password Property (PDFEncrypt Control)

The password to encrypt the document with.

Syntax

pdfencryptcontrol.Password[=string]

Default Value

""

Remarks

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

Data Type

String

Permissions Property (PDFEncrypt Control)

The document permissions associated with the encryption.

Syntax

pdfencryptcontrol.Permissions[=integer]

Default Value

0

Remarks

This property is used to specify the permissions protected by this encryption. The PDF specification expects applications to comply with these permissions when handling encrypted documents, but note that it is a policy-like requirement rather than an enforcement.

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

0x001 (pepAnnotations) Annotating is allowed.
0x002 (pepAssemble) Assembling a new document on the basis of the processed one is allowed.
0x004 (pepExtract) Extraction/copying of the pictures and text from the document is allowed.
0x008 (pepExtractAcc) Content extraction is allowed for accessibility purposes only.
0x010 (pepFillInForms) Filling in forms is allowed.
0x020 (pepHighQualityPrint) High quality printing is allowed.
0x040 (pepLowQualityPrint) Low quality printing is allowed.
0x080 (pepModify) Modifications are allowed.

This property is not available at design time.

Data Type

Integer

Close Method (PDFEncrypt Control)

Closes an opened PDF document.

Syntax

pdfencryptcontrol.Close 

Remarks

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

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

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

Config Method (PDFEncrypt Control)

Sets or retrieves a configuration setting.

Syntax

pdfencryptcontrol.Config ConfigurationString

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the control, 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.

Encrypt Method (PDFEncrypt Control)

Encrypts a PDF document.

Syntax

pdfencryptcontrol.Encrypt 

Remarks

This method is used to encrypt the PDF document specified in InputFile, InputData, or SetInputStream. The document will be encrypted using EncryptionAlgorithm and either Password (for password-based encryption) or EncryptionCert (for certificate-based encryption), then saved in OutputFile, OutputData, or the stream set in SetOutputStream.

Example: pdfencrypt.InputFile = "input.pdf"; pdfencrypt.OutputFile = "encrypted.pdf"; pdfencrypt.Password = "password"; pdfencrypt.EncryptionAlgorithm = "AES256"; pdfencrypt.Encrypt(); Note: If the document is not already opened, this method will open it, perform the operation, then close it.

Encrypted Method (PDFEncrypt Control)

Checks whether a PDF document is encrypted.

Syntax

pdfencryptcontrol.Encrypted 

Remarks

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

Example: pdfencrypt.InputFile = "input.pdf"; if (!pdfencrypt.Encrypted()) { pdfencrypt.OutputFile = "encrypted.pdf"; // Set Password or EncryptionCert pdfencrypt.Encrypt(); } Note: If the document is not already opened, this method will open it, perform the operation, then close it.

Open Method (PDFEncrypt Control)

Opens a PDF document for processing.

Syntax

pdfencryptcontrol.Open 

Remarks

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

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

Automatic Decryption Functionality

If this method is called on an encrypted document, the Password or RecipientInfo event will fire (depending on the encryption type) as a notification that the document must be decrypted before processing can continue.

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

Reset Method (PDFEncrypt Control)

Resets the control.

Syntax

pdfencryptcontrol.Reset 

Remarks

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

Error Event (PDFEncrypt Control)

Fired when information is available about errors during data delivery.

Syntax

Sub pdfencryptcontrol_Error(ErrorCode As Integer, Description As String)

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the control fails with an error.

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

Fired once for each log message.

Syntax

Sub pdfencryptcontrol_Log(LogLevel As Integer, Message As String, LogType As String)

Remarks

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

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

0 (None) No messages are logged.
1 (Info - default) Informational events such as the basics of the chain validation procedure are logged.
2 (Verbose) Detailed data such as HTTP requests are logged.
3 (Debug) Debug data including the full chain validation procedure are logged.

The Message parameter is the log message.

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

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

Password Event (PDFEncrypt Control)

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

Syntax

Sub pdfencryptcontrol_Password(Available As Boolean, Cancel As Boolean)

Remarks

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

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

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

RecipientInfo Event (PDFEncrypt Control)

Fired for each recipient certificate of the encrypted PDF document.

Syntax

Sub pdfencryptcontrol_RecipientInfo(Issuer As String, SerialNumber As String, SubjectKeyIdentifier As String, Available As Boolean, Cancel As Boolean)

Remarks

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

The Issuer parameter specifies the subject of the issuer certificate.

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

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

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

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

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

Config Settings (PDFEncrypt Control)

The control accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the control, access to these internal properties is provided through the Config method.

PDFEncrypt Config Settings

CloseInputStreamAfterProcessing:   Whether to close the input stream after processing.

This setting determines whether the input stream specified in SetInputStream will be closed after processing is complete. The default value is .

CloseOutputStreamAfterProcessing:   Whether to close the output stream after processing.

This setting determines whether the output stream specified in SetOutputStream will be closed after processing is complete. The default value is .

CompressStreams:   Whether to compress stream objects.

This setting specifies whether the bytes in the document's stream objects will be compressed when the Encrypt method is called. The default value is .

HardenedKeyGeneration:   Whether to use hardened key generation.

This setting specifies whether hardened key generation will be used when the AES-256 encryption algorithm and password encryption are used. The default value is .

LogLevel:   The level of detail that is logged.

This setting controls the level of detail that is logged through the Log event. Possible values are:

0 (None) No messages are logged.
1 (Info - default) Informational events such as the basics of the chain validation procedure are logged.
2 (Verbose) Detailed data such as HTTP requests are logged.
3 (Debug) Debug data including the full chain validation procedure are logged.
OAEPMGF1HashAlgorithm:   The MGF1 hash algorithm used with OAEP.

This setting specifies the MGF1 hash algorithm used when UseOAEP is set to . Possible values are:

  • "SHA1"
  • "SHA224"
  • "SHA256" (default)
  • "SHA384"
  • "SHA512"
  • "RIPEMD160"
  • "MD2"
  • "MD5"
  • "MD5SHA1"

Note: This setting is not applicable when UseFIPSCompliantAPI is set to or when the private key of the signing certificate is not exportable since the underlying system implementation does not support separate OAEPRSAHashAlgorithm and OAEPMGF1HashAlgorithm values. In this case, the OAEPRSAHashAlgorithm is also used for MGF1.

OAEPParams:   The hex-encoded OAEP parameters.

This setting optionally specifies Optimal Asymmetric Encryption Padding (OAEP) parameters to be used when UseOAEP is set to . The specified value should be hex-encoded.

OAEPRSAHashAlgorithm:   The RSA hash algorithm used with OAEP.

This setting specifies the RSA hash algorithm used when UseOAEP is set to . Possible values are:

  • "SHA1"
  • "SHA224"
  • "SHA256" (default)
  • "SHA384"
  • "SHA512"
  • "RIPEMD160"
  • "MD2"
  • "MD5"
  • "MD5SHA1"
OwnerPassword:   The owner password to encrypt the document with.

This setting is used to provide the document owner password for encryption. Though it may be different from Password, most implementations use the same value for both.

RC4KeyBits:   The number of key bits used for the RC4 algorithm.

This setting specifies the number of key bits used for the RC4 algorithm. The default value is 128.

SaveChanges:   Whether to save changes made to the PDF document.

This setting specifies whether and how changes made to the PDF document will be saved when the Close method is called. Possible values are:

0 Discard all changes.
1 Save the document to OutputFile, OutputData, or the stream set in SetOutputStream, even if it has not been modified.
2 (default) Save the document to OutputFile, OutputData, or the stream set in SetOutputStream, but only if it has been modified.
TempPath:   The location where temporary files are stored.

This setting specifies an absolute path to the location on disk where temporary files are stored. It can be useful to reduce memory usage.

UseOAEP:   Whether to use Optimal Asymmetric Encryption Padding (OAEP) during encryption and decryption.

This setting specifies whether Optimal Asymmetric Encryption Padding (OAEP) will be used during encryption and decryption. The default value is , meaning the control will use PKCS#1.

To specify non-default OAEP options, please see OAEPRSAHashAlgorithm, OAEPMGF1HashAlgorithm, and OAEPParams.

Base Config Settings

CodePage:   The system code page used for Unicode to Multibyte translations.

The default code page is Unicode UTF-8 (65001).

The following is a list of valid code page identifiers:

IdentifierName
037IBM EBCDIC - U.S./Canada
437OEM - United States
500IBM EBCDIC - International
708Arabic - ASMO 708
709Arabic - ASMO 449+, BCON V4
710Arabic - Transparent Arabic
720Arabic - Transparent ASMO
737OEM - Greek (formerly 437G)
775OEM - Baltic
850OEM - Multilingual Latin I
852OEM - Latin II
855OEM - Cyrillic (primarily Russian)
857OEM - Turkish
858OEM - Multilingual Latin I + Euro symbol
860OEM - Portuguese
861OEM - Icelandic
862OEM - Hebrew
863OEM - Canadian-French
864OEM - Arabic
865OEM - Nordic
866OEM - Russian
869OEM - Modern Greek
870IBM EBCDIC - Multilingual/ROECE (Latin-2)
874ANSI/OEM - Thai (same as 28605, ISO 8859-15)
875IBM EBCDIC - Modern Greek
932ANSI/OEM - Japanese, Shift-JIS
936ANSI/OEM - Simplified Chinese (PRC, Singapore)
949ANSI/OEM - Korean (Unified Hangul Code)
950ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC)
1026IBM EBCDIC - Turkish (Latin-5)
1047IBM EBCDIC - Latin 1/Open System
1140IBM EBCDIC - U.S./Canada (037 + Euro symbol)
1141IBM EBCDIC - Germany (20273 + Euro symbol)
1142IBM EBCDIC - Denmark/Norway (20277 + Euro symbol)
1143IBM EBCDIC - Finland/Sweden (20278 + Euro symbol)
1144IBM EBCDIC - Italy (20280 + Euro symbol)
1145IBM EBCDIC - Latin America/Spain (20284 + Euro symbol)
1146IBM EBCDIC - United Kingdom (20285 + Euro symbol)
1147IBM EBCDIC - France (20297 + Euro symbol)
1148IBM EBCDIC - International (500 + Euro symbol)
1149IBM EBCDIC - Icelandic (20871 + Euro symbol)
1200Unicode UCS-2 Little-Endian (BMP of ISO 10646)
1201Unicode UCS-2 Big-Endian
1250ANSI - Central European
1251ANSI - Cyrillic
1252ANSI - Latin I
1253ANSI - Greek
1254ANSI - Turkish
1255ANSI - Hebrew
1256ANSI - Arabic
1257ANSI - Baltic
1258ANSI/OEM - Vietnamese
1361Korean (Johab)
10000MAC - Roman
10001MAC - Japanese
10002MAC - Traditional Chinese (Big5)
10003MAC - Korean
10004MAC - Arabic
10005MAC - Hebrew
10006MAC - Greek I
10007MAC - Cyrillic
10008MAC - Simplified Chinese (GB 2312)
10010MAC - Romania
10017MAC - Ukraine
10021MAC - Thai
10029MAC - Latin II
10079MAC - Icelandic
10081MAC - Turkish
10082MAC - Croatia
12000Unicode UCS-4 Little-Endian
12001Unicode UCS-4 Big-Endian
20000CNS - Taiwan
20001TCA - Taiwan
20002Eten - Taiwan
20003IBM5550 - Taiwan
20004TeleText - Taiwan
20005Wang - Taiwan
20105IA5 IRV International Alphabet No. 5 (7-bit)
20106IA5 German (7-bit)
20107IA5 Swedish (7-bit)
20108IA5 Norwegian (7-bit)
20127US-ASCII (7-bit)
20261T.61
20269ISO 6937 Non-Spacing Accent
20273IBM EBCDIC - Germany
20277IBM EBCDIC - Denmark/Norway
20278IBM EBCDIC - Finland/Sweden
20280IBM EBCDIC - Italy
20284IBM EBCDIC - Latin America/Spain
20285IBM EBCDIC - United Kingdom
20290IBM EBCDIC - Japanese Katakana Extended
20297IBM EBCDIC - France
20420IBM EBCDIC - Arabic
20423IBM EBCDIC - Greek
20424IBM EBCDIC - Hebrew
20833IBM EBCDIC - Korean Extended
20838IBM EBCDIC - Thai
20866Russian - KOI8-R
20871IBM EBCDIC - Icelandic
20880IBM EBCDIC - Cyrillic (Russian)
20905IBM EBCDIC - Turkish
20924IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol)
20932JIS X 0208-1990 & 0121-1990
20936Simplified Chinese (GB2312)
21025IBM EBCDIC - Cyrillic (Serbian, Bulgarian)
21027Extended Alpha Lowercase
21866Ukrainian (KOI8-U)
28591ISO 8859-1 Latin I
28592ISO 8859-2 Central Europe
28593ISO 8859-3 Latin 3
28594ISO 8859-4 Baltic
28595ISO 8859-5 Cyrillic
28596ISO 8859-6 Arabic
28597ISO 8859-7 Greek
28598ISO 8859-8 Hebrew
28599ISO 8859-9 Latin 5
28605ISO 8859-15 Latin 9
29001Europa 3
38598ISO 8859-8 Hebrew
50220ISO 2022 Japanese with no halfwidth Katakana
50221ISO 2022 Japanese with halfwidth Katakana
50222ISO 2022 Japanese JIS X 0201-1989
50225ISO 2022 Korean
50227ISO 2022 Simplified Chinese
50229ISO 2022 Traditional Chinese
50930Japanese (Katakana) Extended
50931US/Canada and Japanese
50933Korean Extended and Korean
50935Simplified Chinese Extended and Simplified Chinese
50936Simplified Chinese
50937US/Canada and Traditional Chinese
50939Japanese (Latin) Extended and Japanese
51932EUC - Japanese
51936EUC - Simplified Chinese
51949EUC - Korean
51950EUC - Traditional Chinese
52936HZ-GB2312 Simplified Chinese
54936Windows XP: GB18030 Simplified Chinese (4 Byte)
57002ISCII Devanagari
57003ISCII Bengali
57004ISCII Tamil
57005ISCII Telugu
57006ISCII Assamese
57007ISCII Oriya
57008ISCII Kannada
57009ISCII Malayalam
57010ISCII Gujarati
57011ISCII Punjabi
65000Unicode UTF-7
65001Unicode UTF-8
The following is a list of valid code page identifiers for Mac OS only:
IdentifierName
1ASCII
2NEXTSTEP
3JapaneseEUC
4UTF8
5ISOLatin1
6Symbol
7NonLossyASCII
8ShiftJIS
9ISOLatin2
10Unicode
11WindowsCP1251
12WindowsCP1252
13WindowsCP1253
14WindowsCP1254
15WindowsCP1250
21ISO2022JP
30MacOSRoman
10UTF16String
0x90000100UTF16BigEndian
0x94000100UTF16LittleEndian
0x8c000100UTF32String
0x98000100UTF32BigEndian
0x9c000100UTF32LittleEndian
65536Proprietary

MaskSensitiveData:   Whether sensitive data is masked in log messages.

In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to to mask sensitive data. The default is .

This setting only works on these controls: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.

UseInternalSecurityAPI:   Whether or not to use the system security libraries or an internal implementation.

When set to , the control will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to tells the control to use the internal implementation instead of using the system security libraries.

This setting is set to by default on all platforms.

Trappable Errors (PDFEncrypt Control)

PDFEncrypt Errors

20862    Cannot encrypt signed document.

PDF Errors

20805    PDF decompression failed.
20806    Cannot add entry to cross-reference table.
20807    Unsupported field size.
20808    Unsupported Encoding filter.
20809    Unsupported predictor algorithm.
20810    Unsupported document version.
20813    Cannot read PDF file stream.
20814    Cannot write to PDF file stream.
20815    OutputFile already exists and Overwrite is .
20816    Invalid parameter.
20818    Bad cross-reference entry.
20819    Invalid object or generation number.
20820    Invalid object stream.
20821    Invalid stream dictionary.
20822    Invalid AcroForm entry.
20823    Invalid Root entry.
20824    Invalid annotation.
20825    The input document is empty.
20827    OpenType font error. The error description contains the detailed message.
20829    Invalid CMS data. The error description contains the detailed message.
20836    Cannot change decryption mode for opened document.
20837    Unsupported Date string.
20839    Cryptographic error. The error description contains the detailed message.
20841    No decryption key found.
20842    Encryption failed. The error description contains the detailed message.
20843    No proper certificate for encryption found.
20847    Unsupported revision.
20848    Unsupported security handler SubFilter.
20849    Failed to verify permissions.
20850    Invalid password.
20851    Invalid password information.
20853    Unsupported encryption algorithm.
20860    Cannot encrypt encrypted document.
20865    Cannot modify document after signature update.
20869    Cannot encrypt or decrypt object.
20870    Invalid security handler information.
20871    Invalid encrypted data.
20872    Invalid block cipher padding.
20873    Failed to reload signature.
20874    Object is not encrypted.
20875    Unexpected cipher information.
20878    Invalid document. Bad document catalog.
20879    Invalid document Id.
20881    Invalid document. Invalid requirements dictionary.
20882    Invalid linearization dictionary.
20883    Invalid signature information.
20884    Unsupported document format.
20891    Unsupported feature.
20892    Internal error. The error description contains the detailed message.

Parsing Errors

21002    Bad object.
21003    Bad document trailer.
21004    Illegal stream dictionary.
21005    Illegal string.
21006    Indirect object expected.
21008    Invalid reference.
21009    Invalid reference table.
21010    Invalid stream data.
21011    Unexpected character.
21012    Unexpected EOF.
21013    Unexpected indirect object in cross-reference table.
21022    Invalid type in Root object list.