PDF Pipeline Component

The PDF pipeline component adds signature and encryption security to PDF processing.

Remarks

The PDF pipeline component may be used to add security features to your PDF generation and processing applications. Supported functions include password-based and certificate-based encryption, certificate-based signing, timestamping, and compression.

PDF Encoder Pipeline Component

If EncryptData is set to True the PDF will be encrypted. The following properties are applicable when encrypting:

EncryptionAlgorithm
EncryptionCert
EncryptionType
Password

When EncryptData is set to True the adapter uses the certificate set in the EncryptionCert properties or the password set in the Password property to encrypt the document. EncryptionType determines whether to use public key encryption (default) or password encryption. For more details on the use of certificates, please see the Notes on Using Certificates section below.

The EncryptionAlgorithm property specifies the algorithm to use when encrypting. The default is 0 (RC4).

Signing Notes

If SignData is set to True the PDF will be signed. The following properties are applicable when signing:

SignatureHashAlgorithm
SignatureType
SignExistingFields
SigningCert
TimestampServer

When SignData is set to True the adapter uses the certificate set in the SigningCertificate properties to sign the document. SignatureType determines whether to create a standard document signature (default) or a certification (MDP) signature.

If TimestampServer is set to a valid Timestamp server URL the adapter will attempt to timestamp the signature.

Signature Widget Notes

Information about the signature is displayed in a signature widget within the PDF document. The widget itself may be customized in a variety of ways including the type and values of information displayed, as well as its location within the document. The following properties control the most common signature widget values.

AlgorithmCaption
AlgorithmInfo
AuthorName
Background
BackgroundStyle
ContactInfo
Header
Height
Invisible
Location
OffsetX
OffsetY
Page
Reason
ShowOnAllPages
SignerCaption
SignerInfo
Width

Additional configuration options are available to further customize the signature widget. These may be set via the Other property. See the Configuration section of the documentation for details.

PDF Decoder Pipeline Component

By default, the pipeline will automatically attempt to decrypt encrypted PDF documents. The following properties are applicable when decrypting:

DecryptionCert
Password
RequireEncryption
RequirePublicKeyEncryption
RequireNonEmptyPass

RequireEncryption governs whether an error should be thrown if the PDF is not encrypted. RequirePublicKeyEncryption will throw an error if the document is encrypted with a password or is not encrypted at all. RequireNonEmptyPass will throw an error if the document is encrypted with a public key or not at all. The usage of the remaining properties depends on whether the PDF was encrypted with a certificate/public key, or with a password/string.

Depending on the value of EncryptionType, the adapter will either use the certificate specified in DecryptionCert or the Password to decrypt encrypted PDF documents. For more details on the use of certificates, please see the Notes on Using Certificates section below.

Signature Verification Notes

The pipeline can also verify signed or certified PDF documents. The following properties are applicable when verifying:

SignerCert
SignerCertPKCS11Params
RequireSignature
RequireAllSignatures
ExtractLastSignedVersion
RequireTimestamp

SignerCert must be set to the certificate(s) with the public key that is paired with the private key used to sign the document. To load a PKCS11 certificate, SignerCertPKCS11Params should be set instead.

RequireSignature governs whether an error should be thrown if the PDF is not signed. RequireAllSignatures, if set to True, will throw an error if any of the certificates specified in SignerCert were not used to sign the PDF. Set RequireTimestamp to True if the signature must be accompanied by a timestamp.

If ExtractLastSignedVersion is set to True, the pipeline will throw away any elements of the PDF document that were not signed during the most recent signature.

Notes on Using Certificates

The following properties can be used to load a single certificate via a certificate browser:

DecryptionCert
EncryptionCert
KnownCert
SignerCert
SigningCert
TrustedCert

The certificate browser can load certificates from system stores or from a file on disk.

Alternate Certificates and Using Multiple Certificates

Certificates can also be loaded via the following set of configuration options:

AltCertType[index]
AltCertSource[index]
AltCertStore[index]
AltCertPassword[index]

These settings mirror the syntax from previous versions of the PDF components, BizCrypto, so users familiar with this syntax may prefer this approach over the certificate browser. If the certificate is stored directly as string/byte data rather than in a file or a system store, these settings must be used to load the certificate.

Additionally, these settings should be used if more than one certificate needs to be loaded to perform a single operation.

For example, if multiple certificates should be used to sign a PDF, only one of these can be specified as the SigningCert. The remaining certificates should be loaded using the AltCert* options listed above.

PKCS11 Certificates

Certificates in PKCS11 format (hardware tokens) should be loaded via the following properties:

DecryptionCertPKCS11Params
EncryptionCertPKCS11Params
KnownCertPKCS11Params
SignerCertPKCS11Params
SigningCertPKCS11Params
TrustedCertPKCS11Params

PCKS11 Certificates are specified via the following list of parameters, in name=value syntax:


dllpath	Path to PKCS11 driver DLL (required)	Example: DllPath="C:\Program Files\Token\cp11.dll"
slot	Slot number. If not specified, the first slot with the inserted token is considered.	Example: Slot="5"
pin	Token PIN.	Example: Pin="12345"
issuer	Specifies a subset of fields of the certificate issuer in DN (distinguished name) format.	Example: issuer="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
subject	Specifies a subset of fields of the certificate subject in DN (distinguished name) format.	Example: subject="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
serial	Certificate serial number in base16 format.	Example: serial="00FFA0"
fingerprint	SHA1 fingerprint of the certificate in base16 format.	Example: fingerprint="00112233445566778899AABBCCDDEEFF00112233"
keyid	The value of the subject key identifier extension of the certificate in base16 format.	Example: keyid="112233445566"

Encoder Property List

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


AlgorithmCaption	The displayed caption describing the algorithm in the signature widget.
AuthorName	The name of the author.
Background	Specifies the full path to an image file used for the signature widget background.
BackgroundStyle	This property specifies the style of signature widget background.
ContactInfo	Contact information for the signer.
EncryptData	Whether to encrypt the PDF.
EncryptionAlgorithm	The encryption algorithm.
EncryptionCert	The Certificate that will be used to encrypt the PDF.
EncryptionCertPKCS11Params	The PKCS11 Certificate(s) that will be used to encrypt the PDF.
EncryptionType	The type of encryption to perform.
Invisible	Specifies whether the signature widget is visible.
Location	The physical location or machine name where the document was signed.
Other	Defines a set of configuration settings to be used by the pipeline component.
Page	The page number on which the signature widget is displayed.
Password	Specifies the password used to encrypt the document.
Reason	Specifies a string stating the reason for the signature.
RuntimeLicense	Specifies the component runtime license key.
ShowOnAllPages	Whether to show the signature widget on all pages of the document.
SignatureHashAlgorithm	Specifies the signature hash algorithm.
SignatureType	Whether to sign or certify the PDF.
SignData	Whether to sign the PDF.
SignerCaption	Specifies the caption displayed before the signer information.
SignExistingFields	Whether to sign existing fields.
SigningCert	The certificate that will be used to sign or certify the PDF.
SigningCertPKCS11Params	The PKCS11 certificate that will be used to sign or certify the PDF.
TempPath	A temporary directory where data can be stored before the component processes it.
TimestampServer	The URL of the timestamp server.
TransportLog	Tells the component where and how to report information about its operations.
TrustedCert	Specifies a Certificate that can be used to validate the trust of other certificates.
TrustedCertPKCS11Params	Specifies a PKCS11 Certificate that can be used to validate the trust of other certificates.

Decoder Property List

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


DecryptionCert	The Certificate that will be used to decrypt the PDF.
DecryptionCertPKCS11Params	The PKCS11 Certificate that will be used to decrypt the PDF.
ExtractLastSignedVersion	Specifies whether to extract only the signed elements of the document, from the most recent signature.
KnownCert	Specifies an intermediary certificate in a trusted certificate chain.
KnownCertPKCS11Params	Specifies an intermediary PKCS11 certificate in a crusted certificate chain.
Other	Defines a set of configuration settings to be used by the pipeline component.
Password	Specifies the password used to encrypt the document.
RequireAllSignatures	Specifies whether to throw an error if not all SignerCerts were used to sign the PDF.
RequireCertification	Specifies whether an error should be thrown if the PDF document is not certified.
RequireEncryption	Specifies whether an error should be thrown if the PDF document is not encrypted.
RequireNonEmptyPass	Specifies whether an error should be thrown if the PDF was encrypted with an empty password.
RequirePublicKeyEncryption	Specifies whether an error should be thrown if the PDF document was not encrypted using a Public Key.
RequireSignature	Specifies whether to throw an error if the received PDF was not signed.
RequireTimestamp	Specifies whether a signature must have an associated timestamp to be successfully verified.
RuntimeLicense	Specifies the component runtime license key.
SignerCert	The Certificate that was used to sign or certify the PDF.
SignerCertPKCS11Params	The PKCS11 Certificate that was used to sign or certify the PDF.
TempPath	A temporary directory where data can be stored before the component processes it.
TransportLog	Tells the component where and how to report information about its operations.
TrustAllCertificates	Specifies whether Certificate validation should automatically succeed.
TrustedCert	Specifies a Certificate that can be used to validate the trust of other certificates.
TrustedCertPKCS11Params	Specifies a PKCS11 Certificate that can be used to validate the trust of other certificates.

Config Settings

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


AlgorithmInfo	The displayed algorithm info in the signature widget.
AllowComments	Whether the recipient may add comments.
AllowFillInForms	Whether the recipient may fill in forms.
AltCertPassword[index]	Specifies the password for an alternate Certificate.
AltCertSource[index]	Specifies the format from which an alternate Certificate should be loaded.
AltCertStore[index]	Specifies the store from which to load an alternate Certificate.
AltCertType[index]	Specifies how an alternate Certificate should be used.
AutoFontSize	Whether to automatically size the font in the signature widget.
AutoPos	Whether to automatically position the signature widget.
AutoSize	Whether to automatically size the signature widget.
AutoStretchBackground	Whether the background of the signature widget is automatically stretched.
AutoText	Whether to automatically determine the text to be included in the signature widget.
BackgroundHeight	The height of the background image.
BackgroundWidth	The width of the background image.
CustomHandlerName	Specifies a custom security handler used for signing and encryption.
Detached	Whether the signature is detached.
EncryptMetadata	Specifies whether the document metadata is encrypted.
FIPSMode	Determines whether to operate in FIPS mode.
Header	The header displayed on the signature widget.
Height	Sets the height of the signature widget.
IgnoreExistingAppearance	Determines if appearance settings of existing empty signature fields are ignored.
IgnoreTimestampFailure	Whether it ignore timestamp failures during signing.
LiberalMode	Specifies the validation mode of MDP signatures.
Locked	Whether the signature widget is locked in place.
NoRotate	Whether the signature widget rotation is disabled when the document rotates.
NoView	Whether the signature widget is displayed when the document is viewed.
NoZoom	Whether the signature widget is resized when the document is zoomed.
OffsetX	The offset of the signature widget from the left.
OffsetY	The offset of the signature widget from the bottom.
PipelineOptions	Options defining the validation and protection functionality of the pipeline component.
Print	Whether the signature widget will appear in printed copies.
PublicKeySignatureType	The public key signature type.
ReadOnly	Whether the signature widget is interactive or read-only.
Rotate	Specifies the rotation of the signature widget in degrees.
SaveStringsInUnicodeEncoding	Whether strings are saved in Unicode.
SectionTextFontSize	The font size of the section text.
SectionTitleFontSize	The font size of the section title.
ShowTimestamp	Whether the timestamp is displayed on the signature widget.
SigFieldName	The name of the signature field to sign.
SignerInfo	Information to be displayed about the signer.
StretchX	Specifies the horizontal stretch of the signature widget background picture.
StretchY	Specifies the vertical stretch of the signature widget background picture.
TimestampFontSize	The font size of the timestamp.
TitleFontSize	The font size of the title.
ToggleNoView	Specifies whether the signature is visible on hover.
UseHexEncoding	Whether to hex encode strings used in the signature widget.
Width	Sets the width of the signature widget.

AlgorithmCaption Property (PDF Pipeline component)

The displayed caption describing the algorithm in the signature widget.

Data Type

String

Default Value

"Public key:"

Remarks

This property specifies the caption which describes the algorithm in the signature widget.

The default value is Public key: .

This property is not available in the Disassembler/Decoder.

AuthorName Property (PDF Pipeline component)

The name of the author.

Data Type

String

Default Value

Remarks

This property specifies the name of the person or entity signing the document.

This property is not available in the Disassembler/Decoder.

Background Property (PDF Pipeline component)

Specifies the full path to an image file used for the signature widget background.

Data Type

String

Default Value

Remarks

This property specifies the full path to an image file which will be used as the background in the signature widget.

This property is only applicable when BackgroundStyle is set to 2 (Custom).

This property is not available in the Disassembler/Decoder.

BackgroundStyle Property (PDF Pipeline component)

This property specifies the style of signature widget background.

Data Type

Enumeration

Possible Values

Default (0)
No Background (1)
Custom (2)

Default Value

Remarks

This property specifies the style of signature widget background. The background may be disabled completely, or set to an image. Possible values are:


0 (Default)	A default background image is used.
1 (No Background)	No background image is used.
2 (Custom)	A customer background image is used.

If set to 2 (Custom), set Background to the path on disk to an image file that will be used for the background.

This property is not available in the Disassembler/Decoder.

ContactInfo Property (PDF Pipeline component)

Contact information for the signer.

Data Type

String

Default Value

Remarks

This property specifies contact information for the signer. This may be used by the receiving party to help verify the identity of the signer. For instance this may be a phone number, or email address of the signer.

This property is not available in the Disassembler/Decoder.

DecryptionCert Property (PDF Pipeline component)

The Certificate that will be used to decrypt the PDF.

Data Type

Certificate

Remarks

This property specifies the certificate with a private key that is paired with the public key that was used to encrypt the PDF.

If multiple unique certificates were used to encrypt the PDF, and so multiple unique certificates are required to decrypt it, the following configuration options should be used to specify the additional certificates:

AltCertType[index]
AltCertSource[index]
AltCertStore[index]
AltCertPassword[index]

This property is not available in the Assembler/Encoder.

DecryptionCertPKCS11Params Property (PDF Pipeline component)

The PKCS11 Certificate that will be used to decrypt the PDF.

Data Type

String

Default Value

Remarks

This property specifies the PKCS11 certificate with a private key that is paired with the public key that was used to encrypt the PDF.

PCKS11 Certificates are specified via the following list of parameters, in name=value syntax:


dllpath	Path to PKCS11 driver DLL (required)	Example: DllPath="C:\Program Files\Token\cp11.dll"
slot	Slot number. If not specified, the first slot with the inserted token is considered.	Example: Slot="5"
pin	Token PIN.	Example: Pin="12345"
issuer	Specifies a subset of fields of the certificate issuer in DN (distinguished name) format.	Example: issuer="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
subject	Specifies a subset of fields of the certificate subject in DN (distinguished name) format.	Example: subject="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
serial	Certificate serial number in base16 format.	Example: serial="00FFA0"
fingerprint	SHA1 fingerprint of the certificate in base16 format.	Example: fingerprint="00112233445566778899AABBCCDDEEFF00112233"
keyid	The value of the subject key identifier extension of the certificate in base16 format.	Example: keyid="112233445566"

This property is not available in the Assembler/Encoder.

EncryptData Property (PDF Pipeline component)

Whether to encrypt the PDF.

Data Type

Boolean

Default Value

true

Remarks

This property defines whether the PDF is encrypted.

If EncryptData is set to True the PDF will be encrypted. The following properties are applicable when encrypting:

EncryptionAlgorithm
EncryptionCert
EncryptionType
Password

The EncryptionAlgorithm property specifies the algorithm to use when encrypting. The default is 0 (RC4).

This property is not available in the Disassembler/Decoder.

EncryptionAlgorithm Property (PDF Pipeline component)

The encryption algorithm.

Data Type

Enumeration

Possible Values

RC4 (0)
AES128 (1)

Default Value

Remarks

This property specifies the algorithm to use when encrypting the PDF. Possible values are:

0 (RC4 - default)
1 (AES128)

This property is not available in the Disassembler/Decoder.

EncryptionCert Property (PDF Pipeline component)

The Certificate that will be used to encrypt the PDF.

Data Type

Certificate

Remarks

This property specifies the certificate with a public key that will be used to encrypt the PDF.

This property accepts a single certificate via a certificate browser. To specify multiple certificates as encryption certificates, or to use syntax similar to older versions of the PDF components (BizCrypto), the following configuration options should be used:

AltCertType[index]
AltCertSource[index]
AltCertStore[index]
AltCertPassword[index]

This property is not available in the Disassembler/Decoder.

EncryptionCertPKCS11Params Property (PDF Pipeline component)

The PKCS11 Certificate(s) that will be used to encrypt the PDF.

Data Type

String

Default Value

Remarks

If a certificate should be specified as an EncryptionCert and is in PKCS11 format, this property should be set instead of EncryptionCert.

PCKS11 Certificates are specified via the following list of parameters, in name=value syntax:


dllpath	Path to PKCS11 driver DLL (required)	Example: DllPath="C:\Program Files\Token\cp11.dll"
slot	Slot number. If not specified, the first slot with the inserted token is considered.	Example: Slot="5"
pin	Token PIN.	Example: Pin="12345"
issuer	Specifies a subset of fields of the certificate issuer in DN (distinguished name) format.	Example: issuer="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
subject	Specifies a subset of fields of the certificate subject in DN (distinguished name) format.	Example: subject="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
serial	Certificate serial number in base16 format.	Example: serial="00FFA0"
fingerprint	SHA1 fingerprint of the certificate in base16 format.	Example: fingerprint="00112233445566778899AABBCCDDEEFF00112233"
keyid	The value of the subject key identifier extension of the certificate in base16 format.	Example: keyid="112233445566"

This property is not available in the Disassembler/Decoder.

EncryptionType Property (PDF Pipeline component)

The type of encryption to perform.

Data Type

Enumeration

Possible Values

Public Key (0)
Password (1)

Default Value

Remarks

This property defines the type of encryption to perform. Possible values are:

0 (Public Key - default)
1 (Password)

This property is not available in the Disassembler/Decoder.

ExtractLastSignedVersion Property (PDF Pipeline component)

Specifies whether to extract only the signed elements of the document, from the most recent signature.

Data Type

Boolean

Default Value

true

Remarks

If true, unsigned portions of the PDF will be discarded. If the PDF has been signed multiple times, only the most recent signature will be considered.

This property is not available in the Assembler/Encoder.

Invisible Property (PDF Pipeline component)

Specifies whether the signature widget is visible.

Data Type

Boolean

Default Value

true

Remarks

This property specifies whether the signature widget is visible. If set to True (default) the signature widget is visible. Set this to False to hide the signature widget.

This property is not available in the Disassembler/Decoder.

KnownCert Property (PDF Pipeline component)

Specifies an intermediary certificate in a trusted certificate chain.

Data Type

Certificate

Remarks

This setting is only relevant if TrustAllCertificates is set to False.

During signature verification, the adapter will attempt to validate the trust of the SignerCert. To succeed, the certificate must be trusted directly or the root of the certificate chain must be a TrustedCert. Any intermediate certificates between the trusted certificate and the signer's certificate must be included as a KnownCert.

In general, certificates that are not root or are not received via a trusted channel should be set as a KnownCert to avoid affecting system security.

To include multiple unique certificates as known certificates, the following configuration options should be used:

AltCertType[index]
AltCertSource[index]
AltCertStore[index]
AltCertPassword[index]

This property is not available in the Assembler/Encoder.

KnownCertPKCS11Params Property (PDF Pipeline component)

Specifies an intermediary PKCS11 certificate in a crusted certificate chain.

Data Type

String

Default Value

Remarks

If a certificate should be specified as a KnownCert and is in PKCS11 format, this property should be set instead of KnownCert. Please see the KnownCert page for details on when certificates should be specified as known.

PCKS11 Certificates are specified via the following list of parameters, in name=value syntax:


dllpath	Path to PKCS11 driver DLL (required)	Example: DllPath="C:\Program Files\Token\cp11.dll"
slot	Slot number. If not specified, the first slot with the inserted token is considered.	Example: Slot="5"
pin	Token PIN.	Example: Pin="12345"
issuer	Specifies a subset of fields of the certificate issuer in DN (distinguished name) format.	Example: issuer="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
subject	Specifies a subset of fields of the certificate subject in DN (distinguished name) format.	Example: subject="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
serial	Certificate serial number in base16 format.	Example: serial="00FFA0"
fingerprint	SHA1 fingerprint of the certificate in base16 format.	Example: fingerprint="00112233445566778899AABBCCDDEEFF00112233"
keyid	The value of the subject key identifier extension of the certificate in base16 format.	Example: keyid="112233445566"

This property is not available in the Assembler/Encoder.

Location Property (PDF Pipeline component)

The physical location or machine name where the document was signed.

Data Type

String

Default Value

Remarks

This property specifies the physical location or machine name where the document was signed.

This property is not available in the Disassembler/Decoder.

Other Property (PDF Pipeline component)

Defines a set of configuration settings to be used by the pipeline component.

Data Type

String

Default Value

Remarks

The pipeline component accepts one or more configuration settings. These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the pipeline component, access to these internal properties is provided through the Other property.

The Other property may be set to one or more configuration settings (name/value pairs). Set one setting per line. For example: configname1=value1 configname2=value2

Page Property (PDF Pipeline component)

The page number on which the signature widget is displayed.

Data Type

Integer

Default Value

Remarks

This property specifies the page number on which the signature widget is displayed. Page numbers begin with 0. The default value is 0.

This property is not available in the Disassembler/Decoder.

Password Property (PDF Pipeline component)

Specifies the password used to encrypt the document.

Data Type

Password

Default Value

Remarks

This setting specifies the password used to encrypt the document. When EncryptionType is set to 1 (Password) this property specifies the encryption password.

Reason Property (PDF Pipeline component)

Specifies a string stating the reason for the signature.

Data Type

String

Default Value

Remarks

This property defines the reason the signature was created. This may be set to any text. For instance Document has been reviewed and approved.

This property is not available in the Disassembler/Decoder.

RequireAllSignatures Property (PDF Pipeline component)

Specifies whether to throw an error if not all SignerCerts were used to sign the PDF.

Data Type

Boolean

Default Value

true

Remarks

If true, the adapter will throw an error if a Certificate specified in SignerCert was not used to sign the current PDF.

If multiple signatures are expected, the additional SignerCerts must be specified via the following configuration settings:

AltCertType[index]
AltCertSource[index]
AltCertStore[index]
AltCertPassword[index]

If false, the pipeline will ignore any Certificates in SignerCert or the above configuration settings that were not used to sign the current PDF.

This property is not available in the Assembler/Encoder.

RequireCertification Property (PDF Pipeline component)

Specifies whether an error should be thrown if the PDF document is not certified.

Data Type

Boolean

Default Value

false

Remarks

If true, only certified PDF documents will be successfully validated.

This property is not available in the Assembler/Encoder.

RequireEncryption Property (PDF Pipeline component)

Specifies whether an error should be thrown if the PDF document is not encrypted.

Data Type

Boolean

Default Value

true

Remarks

If true, only encrypted PDF documents will be successfully validated.

This property is not available in the Assembler/Encoder.

RequireNonEmptyPass Property (PDF Pipeline component)

Specifies whether an error should be thrown if the PDF was encrypted with an empty password.

Data Type

Boolean

Default Value

true

Remarks

If True, the adapter will throw an error if the PDF was password-encrypted and the password is the empty string "".

This property is not available in the Assembler/Encoder.

RequirePublicKeyEncryption Property (PDF Pipeline component)

Specifies whether an error should be thrown if the PDF document was not encrypted using a Public Key.

Data Type

Boolean

Default Value

false

Remarks

If true, the adapter will throw an error if an unencrypted or password-encrypted PDF is detected. The DecryptionCert property should be set to the certificate with the appropriate private key.

This property is not available in the Assembler/Encoder.

RequireSignature Property (PDF Pipeline component)

Specifies whether to throw an error if the received PDF was not signed.

Data Type

Boolean

Default Value

true

Remarks

If true, the adapter will throw an error if an unsigned PDF is detected. To ensure that all certificates specified as a SignerCert were used to sign the PDF, the RequireAllSignatures property should be set as well.

This property is not available in the Assembler/Encoder.

RequireTimestamp Property (PDF Pipeline component)

Specifies whether a signature must have an associated timestamp to be successfully verified.

Data Type

Boolean

Default Value

true

Remarks

If true, only signatures that include a timestamp will be considered valid. Other rules for signature verification still apply.

This property is not available in the Assembler/Encoder.

RuntimeLicense Property (PDF Pipeline component)

Specifies the component runtime license key.

Data Type

String

Default Value

Remarks

You can use the RuntimeLicense property to set the runtime key for the adapter license.

This property may be configured on the adapter's static handler property page in the BizTalk Server administration console.

ShowOnAllPages Property (PDF Pipeline component)

Whether to show the signature widget on all pages of the document.

Data Type

Boolean

Default Value

false

Remarks

This property specifies whether the signature widget is shown on each page of the document. If False (default) the signature widget is only shown on the page specified by Page. If set to True the signature widget will be visible on each page of the document.

This property is not available in the Disassembler/Decoder.

SignatureHashAlgorithm Property (PDF Pipeline component)

Specifies the signature hash algorithm.

Data Type

Enumeration

Possible Values

SHA1 (0)
MD5 (1)
SHA224 (2)
SHA256 (3)
SHA384 (4)
SHA512 (5)
RIPEMD160 (6)

Default Value

Remarks

This property specifies the signature hash algorithm. Possible values are:

0 (SHA1 - default)
1 (MD5)
2 (SHA-224)
3 (SHA-256)
4 (SHA-384)
5 (SHA-512)
6 (RIPEMD-160)

Note: PDF references prior to 1.7 only support SHA1.

This property is not available in the Disassembler/Decoder.

SignatureType Property (PDF Pipeline component)

Whether to sign or certify the PDF.

Data Type

Enumeration

Possible Values

Signature (0)
Certification (1)

Default Value

Remarks

By default, SignatureType is set to signature (0). To certify the PDF instead of signing it, set this property to (1).

This property is not available in the Disassembler/Decoder.

SignData Property (PDF Pipeline component)

Whether to sign the PDF.

Data Type

Boolean

Default Value

true

Remarks

This property defines whether the PDF is signed.

If SignData is set to True the PDF will be signed. The following properties are applicable when signing:

SignatureHashAlgorithm
SignatureType
SignExistingFields
SigningCert
TimestampServer

If TimestampServer is set to a valid Timestamp server URL the adapter will attempt to timestamp the signature.

Signature Widget Notes

AlgorithmCaption
AlgorithmInfo
AuthorName
Background
BackgroundStyle
ContactInfo
Header
Height
Invisible
Location
OffsetX
OffsetY
Page
Reason
ShowOnAllPages
SignerCaption
SignerInfo
Width

Additional configuration options are available to further customize the signature widget. These may be set via the Other property. See the Configuration section of the documentation for details.

This property is not available in the Disassembler/Decoder.

SignerCaption Property (PDF Pipeline component)

Specifies the caption displayed before the signer information.

Data Type

String

Default Value

Remarks

This property optionally specifies a caption that is displayed in the signature widget. For instance Signer: John Doe.

This property is not available in the Disassembler/Decoder.

SignerCert Property (PDF Pipeline component)

The Certificate that was used to sign or certify the PDF.

Data Type

Certificate

Remarks

This property specifies the certificate with a public key that is paired with the private key used to sign or certify the PDF. If the signature/certification cannot be verified, an error will be thrown.

If multiple unique certificates are required to verify the PDF, the following configuration options should be used to specify the additional certificates:

AltCertType[index]
AltCertSource[index]
AltCertStore[index]
AltCertPassword[index]

This property is not available in the Assembler/Encoder.

SignerCertPKCS11Params Property (PDF Pipeline component)

The PKCS11 Certificate that was used to sign or certify the PDF.

Data Type

String

Default Value

Remarks

PCKS11 Certificates are specified via the following list of parameters, in name=value syntax:


dllpath	Path to PKCS11 driver DLL (required)	Example: DllPath="C:\Program Files\Token\cp11.dll"
slot	Slot number. If not specified, the first slot with the inserted token is considered.	Example: Slot="5"
pin	Token PIN.	Example: Pin="12345"
issuer	Specifies a subset of fields of the certificate issuer in DN (distinguished name) format.	Example: issuer="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
subject	Specifies a subset of fields of the certificate subject in DN (distinguished name) format.	Example: subject="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
serial	Certificate serial number in base16 format.	Example: serial="00FFA0"
fingerprint	SHA1 fingerprint of the certificate in base16 format.	Example: fingerprint="00112233445566778899AABBCCDDEEFF00112233"
keyid	The value of the subject key identifier extension of the certificate in base16 format.	Example: keyid="112233445566"

This property is not available in the Assembler/Encoder.

SignExistingFields Property (PDF Pipeline component)

Whether to sign existing fields.

Data Type

Boolean

Default Value

false

Remarks

This setting specifies whether existing empty signature fields will be signed.

If set to True the adapter will sign the first empty signature field within the document. To specify a particular field that should be signed instead, set SigFieldName.

The default value is False, meaning empty signature fields will not be signed.

This property is not available in the Disassembler/Decoder.

SigningCert Property (PDF Pipeline component)

The certificate that will be used to sign or certify the PDF.

Data Type

Certificate

Remarks

This property specifies the certificate with a private key that will be used to sign or certify the PDF.

If multiple unique certificates are required to sign/certify the PDF, the following configuration options should be used to specify the additional certificates:

AltCertType[index]
AltCertSource[index]
AltCertStore[index]
AltCertSubject[index]
AltCertPassword[index]

This property is not available in the Disassembler/Decoder.

SigningCertPKCS11Params Property (PDF Pipeline component)

The PKCS11 certificate that will be used to sign or certify the PDF.

Data Type

String

Default Value

Remarks

If a certificate should be set as a SigningCert and is in PKCS11 format, this property should be set instead of SigningCert.

PCKS11 Certificates are specified via the following list of parameters, in name=value syntax:


dllpath	Path to PKCS11 driver DLL (required)	Example: DllPath="C:\Program Files\Token\cp11.dll"
slot	Slot number. If not specified, the first slot with the inserted token is considered.	Example: Slot="5"
pin	Token PIN.	Example: Pin="12345"
issuer	Specifies a subset of fields of the certificate issuer in DN (distinguished name) format.	Example: issuer="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
subject	Specifies a subset of fields of the certificate subject in DN (distinguished name) format.	Example: subject="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
serial	Certificate serial number in base16 format.	Example: serial="00FFA0"
fingerprint	SHA1 fingerprint of the certificate in base16 format.	Example: fingerprint="00112233445566778899AABBCCDDEEFF00112233"
keyid	The value of the subject key identifier extension of the certificate in base16 format.	Example: keyid="112233445566"

This property is not available in the Disassembler/Decoder.

TempPath Property (PDF Pipeline component)

A temporary directory where data can be stored before the component processes it.

Data Type

String

Default Value

Remarks

This property indicates a temporary directory where the adapter can store any data before the adapter processes it. If TempPath is empty, the adapter will receive all data to memory. If set, the adapter will generate and write all inbound data to a temporary file in the specified directory.

Once the file is submitted, the adapter will handle closing the file stream and deleting the temporary file. However, if the adapter is shut down during a transfer some temporary files may be left in the directory. To ensure optimal performance, server administrators should check the directory regularly and remove old or extraneous files.

This property accepts the "%TEMP%" macro, which will be replaced with the default system temporary directory at runtime. Note: by default, this property is empty and the adapter will use memory streams to store all inbound data before submitting it. It is recommended that you use a temporary directory when downloading large batches or batches containing large files to alleviate potential increased memory requirements.

TimestampServer Property (PDF Pipeline component)

The URL of the timestamp server.

Data Type

String

Default Value

Remarks

This property optionally specifies the URL of the timestamp server. When SignData is set to True the adapter will attempt to timestamp the signature using the timestamp server URL provided here.

If no value is specified the signature is not timestamped.

This property is not available in the Disassembler/Decoder.

TransportLog Property (PDF Pipeline component)

Tells the component where and how to report information about its operations.

Data Type

Log

Remarks

This is a Log type property which contains fields describing how and where the adapter will record information about its execution.

This property may be configured on the adapter's static handler property page in the BizTalk Server administration console.

TrustAllCertificates Property (PDF Pipeline component)

Specifies whether Certificate validation should automatically succeed.

Data Type

Boolean

Default Value

true

Remarks

If true, the adapter will not attempt to validate certificate chains. If false, certificates must be a part of a trusted chain specified by TrustedCert and KnownCert.

This property is not available in the Assembler/Encoder.

TrustedCert Property (PDF Pipeline component)

Specifies a Certificate that can be used to validate the trust of other certificates.

Data Type

Certificate

Remarks

This setting is only relevant if TrustAllCertificates is set to False.

During signature verification, the adapter will attempt to validate the trust of the SignerCert. To succeed, the Certificate must be trusted directly or the root of the Certificate chain must be a trusted Certificate. Any intermediate Certificates between the trusted Certificate and the signer's Certificate must be included as a KnownCert.

In general, only root certificates received via a trusted channel should be set as a TrustedCert. Certificates that are not root or are less secure should be specified as a KnownCert to avoid affecting system security.

To include multiple unique Certificates as trusted Certificates, the following configuration options should be used:

AltCertType[index]
AltCertSource[index]
AltCertStore[index]
AltCertPassword[index]

TrustedCertPKCS11Params Property (PDF Pipeline component)

Specifies a PKCS11 Certificate that can be used to validate the trust of other certificates.

Data Type

String

Default Value

Remarks

If a Certificate should be specified as a TrustedCert and is in PKCS11 format, this property should be set instead of TrustedCert. Please see the TrustedCert page for details on when Certificates should be specified as trusted.

PCKS11 Certificates are specified via the following list of parameters, in name=value syntax:


dllpath	Path to PKCS11 driver DLL (required)	Example: DllPath="C:\Program Files\Token\cp11.dll"
slot	Slot number. If not specified, the first slot with the inserted token is considered.	Example: Slot="5"
pin	Token PIN.	Example: Pin="12345"
issuer	Specifies a subset of fields of the certificate issuer in DN (distinguished name) format.	Example: issuer="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
subject	Specifies a subset of fields of the certificate subject in DN (distinguished name) format.	Example: subject="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"
serial	Certificate serial number in base16 format.	Example: serial="00FFA0"
fingerprint	SHA1 fingerprint of the certificate in base16 format.	Example: fingerprint="00112233445566778899AABBCCDDEEFF00112233"
keyid	The value of the subject key identifier extension of the certificate in base16 format.	Example: keyid="112233445566"

Certificate Type

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

Store
String
Default Value: "MY"

The name of the certificate store for the client certificate.

The StoreType field specifies the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.

Store is used in conjunction with the Subject field in order to specify client certificates. If Store has a value, and Subject is set, a search for a certificate is initiated. Please refer to the Subject field for details.

Designations of certificate stores are platform-dependent.

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


MY	A certificate store holding personal certificates with their associated private keys.
CA	Certifying authority certificates.
ROOT	Root certificates.
SPC	Software publisher certificates.

In Java, the certificate store normally is a file containing certificates and optional private keys.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).

If the provider is OpenSSL, the certificate store is a file containing a certificate and a private key. This property must be set to the name of the file.

StorePassword
String
Default Value: ""

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

StoreType
CertStoreTypes
Default Value: 0

The type of certificate store for this certificate.

The adapter supports both public and private keys in a variety of formats. When the cstAuto value is used the adapter will automatically determine the type. This field 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 (PKCS12) file containing certificates.
3 (cstPFXBlob)	The certificate store is a string (binary or base64-encoded) representing a certificate store in PFX (PKCS12) 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 PKCS7 file containing certificates.
12 (cstP7BBlob)	The certificate store is a string (binary) representing a certificate store in PKCS7 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 PKCS11 interface. To use a security key the necessary data must first be collected using the CERTMGR adapter. The ListStoreCertificates method may be called after setting CertStoreType to `cstPKCS11`, CertStorePassword to the PIN, and CertStore to the full path of the PKCS11 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 Store and set StorePassword 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.

Subject
String
Default Value: ""

The subject of the certificate used for client authentication.

When this property is set, a search is performed in the current certificate store certificate with matching subject.

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

When setting the property to a partial subject, CN= should be omitted. For example, the following code would find the certificate with subject CN=Test Certificate, OU=People, C=US

Example (Searching with partial subject)

Control.CertSubject = "Test"

If a match is 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.

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

Thumbprint
String (read-only)
Default Value: ""

The thumbprint of the certificate.

This field is used to specify the thumbprint of the certificate. When there are multiple certificates in the store that have the same subject, the thumbprint will be used to distinguish between them.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public Certificate();

Creates a Certificate instance whose properties can be set.

public Certificate(string certificateFile);

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

public Certificate(byte[] certificateData);

Parses CertificateData as an X509 public key.

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

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 constructor will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

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

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 constructor will load Encoded as an X509 certificate and search the opened store for a corresponding private key.

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject);

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 constructor will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).

public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, byte[] encoded);

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 constructor will load Encoded as an X509 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

AutoDetect
Boolean
Default Value: False

Tells the adapter whether or not to automatically detect and use firewall system settings, if available.

FirewallType
FirewallTypes
Default Value: 0

Determines the type of firewall to connect through. The applicable values are the following:


fwNone (0)	No firewall (default setting).
fwTunnel (1)	Connect through a tunneling proxy. Port is set to 80.
fwSOCKS4 (2)	Connect through a SOCKS4 Proxy. Port is set to 1080.
fwSOCKS5 (3)	Connect through a SOCKS5 Proxy. Port is set to 1080.

Host
String
Default Value: ""

Name or IP address of firewall (optional). If a Host is given, requested connections will be authenticated through the specified firewall when connecting.

If the Host field is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the Host field is set to the corresponding address. If the search is not successful, an error is returned.

Password
String
Default Value: ""

A password if authentication is to be used when connecting through the firewall. If Host is specified, the User and Password fields are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.

Port
Integer
Default Value: 0

The TCP port for the firewall Host. See the description of the Host field for details.

Note that the Port is set automatically when FirewallType is set to a valid value. See the description of the FirewallType field for details.

User
String
Default Value: ""

A user name if authentication is to be used connecting through a firewall. If the Host is specified, the User and Password fields are used to connect and authenticate to the given Firewall. If the authentication fails, a trappable error is fired.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public Firewall();

Log Type

A log where the component will record information about its operations.

Remarks

This describes how and where the adapter will record information describing its execution.

Fields

Location
String
Default Value: "Application"

This field describes the location where the logging information is to be written.

If the EventLog LogType has been chosen, this field must contain the name of the Event Log to which the information should be written. The default value for this field is "Application". If a value other than "Application" is set the computer must be restarted for the change to take effect. Note that the same event log must be used for all send ports and receive locations that use the same adapter.

If the File LogType has been chosen, this field must contain the location of the file to write logging information to on the file system.

The adapter also supports logging to files based on the current date and time. This allows for log files to be organized by days, months, or other intervals as specified. When specifying a log filename include a valid .NET date and time format string within the < and > characters. For instance C:\logs\sftp_<yyyyMMdd>.log or C:\logs\as2_<yyyyMMdd>T<hhmm>.log.

LogMode
LogModes
Default Value: 3

This field controls what information the adapter logs. The possible values have the following affect on the adapter's behavior:


Verbose	The adapter will report all information regarding the transport.
Info	The adapter will report all major operations, as well as all warnings and errors.
Warning	The adapter will report any conditions that could result in unpredictable behavior as well as errors.
Error	The adapter will report all errors that prevent normal operations from completing.
Fatal	The adapter will report only serious errors that cause the adapter to completely stop functioning.

LogType
LogTypes
Default Value: 1

This property controls where the adapter will log the information. The possible values have the following affect on the adapter's behavior:


None	The adapter will not report any logging information.
EventLog	The adapter will report all logging information to the event log. The specific event log must be defined in the Location field when this type is selected.
File	The adapter will report all logging information to a file. The desired file must be specified in the Location field when this type has been selected.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public Log();

public Log(LogTypes logType, string location, LogModes logMode);

OAuthAuthorizationParam Type

This type holds details of the OAuth authorization.

Remarks

This type holds details of the OAuth authorization.

Fields

AuthorizationScopes
String
Default Value: ""

A space separated list of scopes as defined by the authorization server.

AuthorizationString
String
Default Value: ""

The OAuth Authorization string. This field holds the current OAuth authorization string. This is retrieved during the OAuth authorization process and is used to authenticate the request. This is a string like:

Bearer ya29.AHES6ZSZEJzATdZYjeihDn5W-VrXSsxEZu5p0pclxGdKKQ

CacheLocation
String
Default Value: ""

The location on disk of the OAuth Cache File.

This field specifies the location on disk of the OAuth cache file. This file holds OAuth credentials that may be automatically used during runtime and by other ports using the same provider. The adapter uses the data within the cache file to automatically refresh expired tokens at runtime. Do not alter the contents of the file directly.

One file for each provider is used by default. For instance for Box the value is: %APPDATA%\nsoftware\CloudStorage BizTalk Adapter\BoxOAuthCache.txt

This value may be specified manually as well.

CallbackURL
String
Default Value: ""

The Callback URL used during OAuth authorization.

This field specifies the local URL to which the browser is redirected when initially performing authorization. When initially establishing Authorization set this value to the redirect URI that is registered for your application with the service provider. For instance "http://localhost:7777".

The adapter will parse this URL and start a small embedded web server on the specified port to receive the OAuth response from the provider during OAuth authorization.

This value is required to perform OAuth authorization.

ClientId
String
Default Value: ""

The id of the client assigned when registering the application.

This field holds the id of the client that was assigned when initially registering the application.

This value is required to perform OAuth authorization.

ClientSecret
String
Default Value: ""

The secret of the client assigned when registering the application.

This field holds the secret of the client that was assigned when initially registering the application.

This value is required to perform OAuth authorization.

ExpiresIn
Integer
Default Value: 0

The expiration time of the current OAuth authorization string.

This value is populated after OAuth authorization and holds the expiration time of the OAuth access token as reported by the service provider. This is used at runtime to calculate whether the token should be refreshed before attempting an operation. If the token is expired the adapter will automatically refresh the token. If the token is not expired the adapter will use the current token.

This value should not be set manually.

Note: Not all providers provide this value. For instance Dropbox access tokens never expire.

RefreshToken
String
Default Value: ""

The refresh token received from or sent to the authorization server.

This field holds the refresh token received during the initial OAuth authorization. It is used by the adapter to automatically request a new AuthorizationString when the current value expires.

ServerAuthURL
String
Default Value: ""

The URL of the authorization server.

ServerTokenURL
String
Default Value: ""

The URL of the token server.

ServiceProvider
String
Default Value: ""

The service provider to authenticate with.

This field defines the service provider. This is used when performing OAuth authorization. OAuth authorization is only applicable to some providers. If the provider does not support OAuth a warning will be displayed. Possible values when using the Cloud Storage adapter are:

Amazon S3
Azure Blob
Azure File
Backblaze B2
Box.com
Digital Ocean Spaces
Dropbox
Google Cloud Storage
Google Drive
Hadoop DFS
IBM Cloud Object Storage
Linode Object Storage
Microsoft OneDrive
Wasabi

Possible values when using the Email adapter are:

Gmail
Other

TimeStamp
String
Default Value: "0"

The timestamp of the OAuth authorization string.

This field holds the timestamp of when the AuthorizationString was retrieved. This is used in conjunction with ExpiresIn to calculate if refreshing the token is required. For more details see ExpiresIn.

This value should not be set manually.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public OAuthAuthorizationParam();

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

AuthScheme
ProxyAuthSchemes
Default Value: 0

Use the AuthScheme field to tell the adapter which type of authorization to perform when connecting to the proxy. This is only used when the User and Password fields are set.

AuthScheme should be set to authNone (3) when no authentication is expected.

By default, AuthScheme is authBasic (0), and if the User and Password fields are set, the component will attempt basic authentication. If AuthScheme is set to authDigest (1), digest authentication will be attempted instead.

If AuthScheme is set to authProprietary (2), then the authorization token will not be generated by the adapter. Look at the configuration file for the adapter being used to find more information about manually setting this token.

If AuthScheme is set to authNtlm (4), NTLM authentication will be used. This option is only available in the SSL package.

For security reasons, setting this property will clear the values of User and Password.

AutoDetect
Boolean
Default Value: False

Tells the adapter whether or not to automatically detect and use proxy system settings, if available.

Password
String
Default Value: ""

A password if authentication is to be used for the proxy.

If AuthScheme is set to Basic Authentication, the User and Password are Base64 encoded and the proxy authentication token will be generated in the form "Basic [encoded-user-password]".

If AuthScheme is set to Digest Authentication, the User and Password fields are used to respond to the Digest Authentication challenge from the server.

If AuthScheme is set to NTLM Authentication, the User and Password fields are used to authenticate through NTLM negotiation.

Port
Integer
Default Value: 80

The TCP port for the proxy Server (default 80). See the description of the Server field for details.

Server
String
Default Value: ""

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the Server field is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the Server field is set to the corresponding address. If the search is not successful, an error is returned.

SSL
ProxySSLTypes
Default Value: 0

Determines when to use SSL for the connection to the proxy. The applicable values are the following:


psAutomatic (0)	Default setting. The connection to the Server is SSL-enabled for 'https' URL-s, and non SSL-enabled for other URL-s.
psAlways (1)	The connection is always SSL-enabled.
psNever (2)	The connection is not SSL-enabled.
psTunnel (3)	The connection is through a tunneling (HTTP) proxy.

User
String
Default Value: ""

A user name, if authentication is to be used for the proxy.

If AuthScheme is set to Basic Authentication, the User and Password are Base64 encoded and the proxy authentication token will be generated in the form "Basic [encoded-user-password]".

If AuthScheme is set to Digest Authentication, the User and Password fields are used to respond to the Digest Authentication challenge from the server.

If AuthScheme is set to NTLM Authentication, the User and Password fields are used to authenticate through NTLM negotiation.

Constructors

Constructors are only relevant when configuring adapters in orchestrations.

public Proxy();

public Proxy(string server, int port);

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

Config Settings (PDF Pipeline component)

The adapter 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 adapter, access to these internal properties is provided through the Other property.

PDF Config Settings

AlgorithmInfo: The displayed algorithm info in the signature widget.

This setting specifies information about algorithm to be displayed in the signature widget.

This setting is only applicable when AutoText; is False. When AutoText; is True (default) the value is automatically determined based on the information in the certificate. For instance RSA/1024 bits.

When AutoText; is False this may be set to a string value in the format "Algorithm/KeySize".

AllowComments: Whether the recipient may add comments.

This setting specifies whether comments may be added by recipients. If set to True the recipient of the signed PDF may still add comments. The default is False.

AllowFillInForms: Whether the recipient may fill in forms.

This setting specifies whether forms may be filled in by recipients. If set to True the recipient of the signed PDF may still fill in forms. The default is False.

AltCertPassword[index]: Specifies the password for an alternate Certificate.

This setting is used in conjunction with AltCertSource[index], AltCertStore[index], and AltCertType[index] to load certificates in addition to (or instead of) the *Cert properties of the adapter.

AltCertPassword[index] specifies the password for the certificate at the given index, and is only required if the certificate is password-protected.

AltCertSource[index]: Specifies the format from which an alternate Certificate should be loaded.

This setting is used in conjunction with AltCertType[index], AltCertStore[index], and AltCertPassword[index] to load certificates in addition to (or instead of) the *Cert properties of the adapter.

AltCertSource[index] specifies the current format of the certificate at the given index.

The possible formats are:


0 (File)	The certificate is stored in a file
1 (Value)	The raw certificate data is specified directly
2 (System)	The certificate is held in a system store

AltCertStore[index]: Specifies the store from which to load an alternate Certificate.

This setting is used in conjunction with AltCertSource[index], AltCertPassword[index], and AltCertType[index] to load certificates in addition to (or instead of) the *Cert properties of the adapter.

AltCertStore Notes

The AltCertStore[index] setting may be set to the path to a certificate file on disk, or may be a comma separated list of values used to identify the certificate location. The following are the parameters that may be used in the comma separated list:


`issuer`	Specifies the issuer subject.	`issuer="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"`
`subject`	The certificate subject.	`subject="/CN=John Johnson/O=Big Company, Inc/E=Johnson@b.com"`
`serial`	The certificate's serial number in hex.	`serial="00FFA0"`
`fingerprint`	The SHA1 fingerprint in hex.	`fingerprint="00112233445566778899AABBCCDDEEFF00112233"`
`keyid`	The value of the subject key identifier certificate extension, in hex.	`keyid="112233445566"`
`store`	The windows system store name. The default value is "MY".	`store="ROOT"`
`accesstype`	The windows system store location. Possible values are: CurrentService CurrentUser CurrentUserGroupPolicy LocalMachine (default) LocalMachineEnterprise LocalMachineGroupPolicy Services Users	`AccessType="CurrentUser"`

AltCertType[index]: Specifies how an alternate Certificate should be used.

This setting is used in conjunction with AltCertSource[index], AltCertStore[index], and AltCertPassword[index] to load certificates in addition to (or instead of) the *Cert properties of the adapter.

AltCertType[index] identifies the role/function of the certificate at the given index.

The possible roles are:


0 (Encryption)	Used by the PDF encoder to encrypt a PDF
1 (Signing)	Used by the PDF encoder to sign/certify a PDF
2 (Decryption)	Used by the PDF decoder to decrypt a PDF
3 (Known)	Used to validate the trust of signer certificates*
4 (Signer)	Used by the PDF decoder to verify a signed/certified PDF
5 (Trusted)	Used to validate the trust of signer certificates*

*Note: please see the KnownCert and TrustedCert properties for details on when a certificate should be in the Trusted role versus Known.

For example, if two certificates are required to sign a PDF, the first can be specified via SigningCert and the second should be specified under the Other property like this:

AltCertSource[0]=2

AltCertStore[0]="Store=MY, subject=/CN=Administrator, accessType=CurrentUser"

AltCertPassword[0]="test"

AltCertType[0]=1

A third certificate can be specified via AltCert*[1], and so on. It is also acceptable to specify all certificates via the AltCert* configuration options and ignore the *Cert properties (such as SignerCert).

AutoFontSize: Whether to automatically size the font in the signature widget.

If set to True (default) the adapter will automatically size the font within the signature widget. The following values will be used:


TitleFontSize	8.77
TimestampFontSize	4.89
SectionTitleFontSize	7
SectionTextFontSize	5

The standard unit is 1/72 of an inch. IN PDF 1.6 the size of this unit may be specified as greater than 1/72 of an inch via the UserUnit entry of the page dictionary.

AutoPos: Whether to automatically position the signature widget.

This setting specifies whether the position of the signature widget is automatically determined. If True (default) the signature widget will be placed in the upper right corner of the page. The default value is True.

If set to False then OffsetX and OffsetY specify the signature widget coordinates.

AutoSize: Whether to automatically size the signature widget.

This setting specifies whether the size of the signature widget is automatically determined. If True (default) the signature widget size is automatically specified. The default value is True.

If set to False then Height and Width specify the size of the signature widget.

AutoStretchBackground: Whether the background of the signature widget is automatically stretched.

This setting specifies whether the background of the signature widget is automatically stretched. If True (default) the background picture used in the signature widget will be automatically stretched to fit the size. The default value is True.

If set to False then StretchX and StretchY specify the dimension to which the image is stretched.

AutoText: Whether to automatically determine the text to be included in the signature widget.

This setting specifies whether the text on the signature widget is automatically determined. If set to True (default) text is determined automatically based on information from the certificate used to sign the document.

If set to False then AlgorithmInfo, SignerInfo, and Header specify the text to be included on the signature widget.

BackgroundHeight: The height of the background image.

This setting optionally specifies the height of the background image.

BackgroundWidth: The width of the background image.

This setting optionally specifies the width of the background image.

CustomHandlerName: Specifies a custom security handler used for signing and encryption.

This setting optionally specifies a custom security handler to be used for signing and encrypting.

Detached: Whether the signature is detached.

This setting specifies whether the signature is detached. If True (default) the adbe.pkcs7.detached subfilter will be used when signing the document. The default value is True.

Note: This setting is only applicable when PublicKeySignatureType is set to PKCS7SHA1.

EncryptMetadata: Specifies whether the document metadata is encrypted.

This setting specifies whether the document metadata is encrypted. The default value is True.

FIPSMode: Determines whether to operate in FIPS mode.

This setting determines whether to operate in FIPS mode. If set to True the adapter will operate in FIPS compliant mode. The default value is False.

Header: The header displayed on the signature widget.

This setting optionally specifies header value that is displayed on the signature widget.

Height: Sets the height of the signature widget.

This setting specifies the height of the signature widget. This is only applicable if AutoSize is False.

The default value is 70.

IgnoreExistingAppearance: Determines if appearance settings of existing empty signature fields are ignored.

This setting specifies whether appearance settings of existing empty signature fields are ignored. The default value is False.

IgnoreTimestampFailure: Whether it ignore timestamp failures during signing.

This setting determines if failures during the timestamping process are ignored. The default value is False, meaning timestamp failures will cause signing to fail.

LiberalMode: Specifies the validation mode of MDP signatures.

This setting specifies whether liberal validation is enabled for MDP signatures. The default value is False.

Locked: Whether the signature widget is locked in place.

This setting specifies whether the signature widget can be moved on the signed document. If set to True (default) the widget may not be moved after the document is signed.

Note: Adobe always treats the signature widget as locked in place regardless of this setting.

NoRotate: Whether the signature widget rotation is disabled when the document rotates.

This setting specifies whether the signature widget is rotated along with the document when the document is rotated (for instance in a browser window). The default value is False, meaning the signature widget may rotate in conjunction with the document.

NoView: Whether the signature widget is displayed when the document is viewed.

This setting specifies whether the signature widget is displayed when the document is viewed.

NoZoom: Whether the signature widget is resized when the document is zoomed.

This setting specifies whether the signature widget may change size with the zoom level of the document. The default value is False, meaning it may change size.

OffsetX: The offset of the signature widget from the left.

This setting specifies the offset of the signature widget from the left page border. This is only applicable when AutoPos is False.

OffsetY: The offset of the signature widget from the bottom.

This setting specifies the offset of the signature widget from the bottom page border. This is only applicable when AutoPos is False.

PipelineOptions: Options defining the validation and protection functionality of the pipeline component.

By default the pipeline will protect (encrypt) sensitive fields such as passwords, and will validate required properties are set. In some cases it may be desirable to change this behavior. This setting may be used to disable the protection, validation, or both. Possible values are:


0 (default)	Both Protection and Validation are enabled
1	Protection is disabled. Validation is enabled.
2	Validation is disabled. Protection is enabled.
3	Validation and Protection are disabled.

Print: Whether the signature widget will appear in printed copies.

This setting specifies whether the signature widget will appear in printed copies of the document. The default value is True.

PublicKeySignatureType: The public key signature type.

This setting specifies the public key signature type. This is typically only in legacy cases. Possible values are:

0 (X509RSASHA1)
1 (PKCS7SHA1 - default)

ReadOnly: Whether the signature widget is interactive or read-only.

This setting specifies if the signature widget is read-only. If set to True the user may not click on or otherwise interact with the signature widget. The default value is False.

Rotate: Specifies the rotation of the signature widget in degrees.

This setting specifies the rotation of the signature widget in degrees. Possible values are:

0 (default)
90
180
270

SaveStringsInUnicodeEncoding: Whether strings are saved in Unicode.

This setting specifies whether the text values in the signature widget are save in Unicode. The default value is False.

SectionTextFontSize: The font size of the section text.

This setting specifies the font size of the section text.

This setting is only applicable if AutoFontSize is False.

SectionTitleFontSize: The font size of the section title.

This setting specifies the font size of the section title.

This setting is only applicable if AutoFontSize is False.

ShowTimestamp: Whether the timestamp is displayed on the signature widget.

This setting specifies whether the timestamp is displayed on the signature widget. The default value is True.

SigFieldName: The name of the signature field to sign.

This setting optionally specifies the name of the signature field to sign. This is only applicable when SignExistingFields is set to True.

SignerInfo: Information to be displayed about the signer.

This setting optionally specifies information about the signer that is displayed on the signature widget. This setting is only applicable if AutoText is False.

StretchX: Specifies the horizontal stretch of the signature widget background picture.

This setting specifies the horizontal stretch of the signature widget background picture. This is only applicable if AutoStretchBackground is False.

StretchY: Specifies the vertical stretch of the signature widget background picture.

This setting specifies the vertical stretch of the signature widget background picture. This is only applicable if AutoStretchBackground is False.

TimestampFontSize: The font size of the timestamp.

This setting specifies the font size of the timestamp.

This setting is only applicable if AutoFontSize is False.

TitleFontSize: The font size of the title.

This setting specifies the font size of the title.

This setting is only applicable if AutoFontSize is False.

ToggleNoView: Specifies whether the signature is visible on hover.

This setting specifies whether the signature widget is visible while hovering over it with a mouse pointer. If set to true the signature widget will only be displayed when hovering over it. The default value is False.

UseHexEncoding: Whether to hex encode strings used in the signature widget.

This setting specifies whether strings used in the signature widget are hex encoded. If True the strings will be written in hex encoding. This setting may be useful if the data to be included in the signature widget text contains non-ASCII characters.

The default value is False.

Width: Sets the width of the signature widget.

This setting specifies the width of the signature widget. This is only applicable if AutoSize is False.

The default value is 70.

Supported Macros

The adapter also supports the following Macros. These values are not case sensitive and would be supplied to a property in the form %MacroName%.

TempThis is resolved to the full path to the system's temporary directory. MessageIDGlobally unique identifier (GUID) of the message in BizTalk Server. SourceFileNameThe original file name. This includes the extension and excludes the file path, for example, Sample.xml SourceFileNameNoExtThe original file name without the extension or file path, for example, Sample RemoteFileNameThe name of the file as it was uploaded to the remote server. This includes the extension and excludes the file path, for example, Sample.xml. Valid only for AS3, FTP, and SFTP Send Adapters. DestinationPartyName of the destination party. DestinationPartyQualifierQualifier of the destination party. SourcePartyName of the source party. SourcePartyQualifierQualifier of the source party. DateTime:CustomFormatThis special value allows you to specify your own custom time format. For instance DateTime:yyyy would be resolved to the 4 digit year. DateThe date format yyyy-MM-dd. DateTimeThe date format yyyy-MM-ddThhmmss. TimeThe date format hhmmss. DateTime_BTS2000The date format yyyyMMddhhmmssf. DateTime.TZThe date format yyyy-MM-ddThhmmsszzz. Time.TZThe date format hhmmsszzz. Property#<Schema>#<Name>This special value allows you to include a property from the incoming message. For instance "PROPERTY#http://schemas.microsoft.com/BizTalk/2003/system-properties#ReceivePortName" would resolve to the ReceivePortName property of the message.