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:

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:

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.

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:

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

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:

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:

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.

Configuration Settings

The following is a list of configuration 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.

/n software Adapters for BizTalk

PDF Pipeline Component

Remarks

Encoder Property List

Decoder Property List

Configuration Settings