Getting Started With the BizTalk PDF Pipeline Component

Resources:

Contents

  1. Introduction
  2. PDF Encoder
  3. PDF Decoder
  4. Details on Using Certificates

Introduction

The PDF Pipeline component integrates signing, certifying, encrypting, decrypting, and verifying PDF documents into the BizTalk flow. This article will cover the basics of configuring a pipeline to perform each of these operations. Additional information on Certificate usage is provided at the bottom.

PDF Encoder

The PDF Encoder component supports signing, certifying, and encrypting PDF's. Note that encrypted PDF's cannot be signed.

Signing and Certifying

The PDF Encoder has a collection of properties that govern whether and how a signature/certification is generated, as well as a collection of properties that govern how the signature/certification appears on the resulting PDF document. The API for generating a signature and generating a certification is the same, with the exception of SignatureType which should be used to toggle between the two options. For brevity, both certifications and signatures will be referred to as signatures, but the same principles apply to certifications.

The following properties govern whether and how a signature is generated:

SignDataDetermines whether a signature/certification should be generated for the PDF.
SignatureTypeWhether to generate a signature (0) or certification (1).
SignatureHashAlgorithmThe algorithm used when signing.
SignExistingFieldsWhether to sign existing signature fields; if true the first empty signature field will be signed unless SigFieldName is set to a specific field to sign.
SigningCertThe Certificate with a private key that will be used to sign the PDF; please see the Details on Using Certificates section for more information.
SigningCertPKCS11ParamsIf the Certificate is in PKCS11 format (hardware token), this should be set instead of SigningCert; please see the Using PKCS11 Certificates section for more information.
LocationThe physical location or machine name where the PDF was signed.

The following properties govern how the signature/certification will be displayed on the resulting PDF document:

InvisibleThe signature widget will not be visible on the resulting PDF unless this is set to false.
AlgorithmCaptionA caption describing the signature algorithm.
BackgroundStyleUsed to specify the background image in the signature widget: Default (0), None (1), or Custom (2).
BackgroundWhen using a custom signature background image, set this to the full path to the image file.
ShowOnAllPagesWhether the signature widget should be displayed on every page in the PDF; otherwise it will only be displayed on the first page.
PageIf the signature widget should be displayed on a specific page, set this to the appropriate page number.
ReasonA custom message stating the reason for the signature.
SignerCaptionA custom caption displayed before the signature information.

Here's a simple example configuration for generating a single visible signature on the first page of a PDF:

Example configuration for signing a PDF

Encrypting PDF Documents

The EncryptData property determines whether the PDF should be encrypted.

The following properties are applicable when encrypting PDF documents:

EncryptDataDetermines whether the PDF will be encrypted.
EncryptionTypeWhether to encrypt with Public Key Encryption (0) or Password-based Encryption (1).
EncryptionAlgorithmThe algorithm used when encrypting.
EncryptionCertIf using public key encryption, set this to the Certificate that will be used to encrypt the PDF; please see the Details on Using Certificates section for more information.
EncryptionCertPKCS11ParamsIf using public key encryption and the Certificate is in PKCS11 format (hardware token), this should be set instead of EncryptionCert; please see the Using PKCS11 Certificates section for more information.
PasswordIf using password-based encryption, set this to the encryption password.

Here's a simple example configuration for password-encrypting a PDF:

Example configuration for password-encryption

PDF Decoder

The PDF Decoder component supports decrypting PDF's and verifying signatures.

Verifying Signed/Certified PDF Documents

The PDF Decoder will automatically attempt to verify signatures/certifications for incoming PDF documents. The API for verifying signatures and certifications is the same, so for brevity both certifications and signatures will be referred to as signatures.

The following properties are applicable when verifying signatures:

RequireSignatureWhether an error should be thrown if no signature is found or cannot be verified.
RequireAllSignaturesIf true, verification will only succeed if all certificates specified as SignerCerts were used to sign the PDF; if multiple SignerCerts need to be specified, please see the Using Multiple Certificates section.
RequireTimestampIf true, signatures that do not include a timestamp will not be considered valid.
SignerCertThe Certificate with a private key that will be used to sign the PDF; please see the Details on Using Certificates section for more information.
SignerCertPKCS11ParamsIf the Certificate is in PKCS11 format, this should be set instead of SigningCert; please see the Using PKCS11 Certificates section for more information.
KnownCertSpecifies an intermediary certificate in a trusted certificate chain; please see the Details on Using Certificates section for more information.
KnownCertPKCS11ParamsIf the Certificate is in PKCS11 format, this should be set instead of KnownCert; please see the Using PKCS11 Certificates section for more information.
TrustedCertSpecifies a certificate that can be used to validate the trust of other certificates; please see the Details on Using Certificates section for more information.
TrustedCertPKCS11ParamsIf the Certificate is in PKCS11 format (hardware token), this should be set instead of TrustedCert; please see the Using PKCS11 Certificates section for more information.

Here's a simple example configuration for verifying a signed PDF:

Example configuration for verifying a signature

Decrypting PDF Documents

The PDF Decoder component will automatically attempt to decrypt encrypted PDF documents. The following properties are applicable during decryption:

RequireEncryptionIf true, an error will be thrown if the PDF is not encrypted.
RequireNonEmptyPassIf true, an error will be thrown if the PDF was password-encrypted with an empty string.
RequirePublicKeyEncryptionIf true, an error will be thrown if the PDF was not encrypted with a public key.
DecryptionCertIf the PDF was encrypted with a public key, set this to the Certificate that contains the corresponding private key; please see the Details on Using Certificates section for more information.
DecryptionCertPKCS11ParamsIf using public key encryption and the Certificate is in PKCS11 format (hardware token), this should be set instead of EncryptionCert; please see the Using PKCS11 Certificates section for more information.
PasswordIf the PDF was encrypted with a password, set this to the decryption password.

Here's a simple example configuration for decrypting a PDF:

Example configuration for password decryption

Details on Using Certificates

There are several ways to load certificates with the PDF Pipeline Components. The *Cert properties (e.g. EncryptionCert, SignerCert, etc) are specified via a certificate browser. These properties can only hold a single Certificate; however, the components also support loading any number of certificates using a set of certificate parameters. This approach uses the Alternate Certificates configuration options, which are explained in more detail in the Alternate Certificates section.

Lastly, the PDF Pipeline Components support loading PKCS11 certificates via the *CertPKCS11Params properties. This is discussed in more detail in the Using PKCS11 Certificates section.

Alternate Certificates

Alternate Certificates serve two roles. First, the syntax for Alternate Certificates mirrors the syntax for selecting certificates in the previous version of the PDF Pipeline Components, BizCrypto. As such, users who are switching from BizCrypto may prefer the Alternate Certificate selection logic.

Second, Alternate Certificates allow multiple certificates to be specified for a single operation (encryption/decryption/signing/etc).

Alternate Certificates are specified via the following 5 configuration options:

AltCertType[index]How the Certificate at the given index should be usedPossible values:
0 (Encryption)
1 (Signing)
2 (Decryption)
3 (Known)
4 (Signer)
5 (Trusted)
AltCertSource[index]The current format of the Certificate at the given indexPossible values:
0 (File)
1 (String/Raw certificate data)
2 (System store)
AltCertStore[index]The path to the certificate file, or a list of comma separated name value pairs identifying the certificate location. See details below. Examples:
store="MY", subject="/CN=Administrator/C=US", serial="012345"
C:\test.pfx
AltCertPassword[index]The password (if necessary) for the Certificate at the given indexExample:
"myPassword"

These are arrays that are "stacked" on top of each other such that referencing the same index refers to the same certificate. For example, AltCertType[0] and AltCertSource[0] both refer to the certificate at index 0, and AltCertType[1] and AltCertSource[1] both refer to a different certificate, at index 1.

Configuration options are set via the Other property, one-per-line, in name=value format. So, to specify a certificate from the user store that should be used to encrypt the PDF, you might have something like this in the Other property:

AltCertType[0]=0
AltCertSource[0]=2
AltCertStore[0]="Store=MY, subject=/CN=Administrator, accesstype=CurrentUser"
AltCertPassword[0]="myPass"

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:

Param Name DescriptionExample
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"

Using PKCS11 Certificates (Hardware Tokens)

PCKS11 Certificates and are contained on a hardware token. These are specified via the following list of parameters, in name=value syntax:

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

For instance:

dllpath="C:\Windows\System32\cp11_1.dll", pin="test", subject="/CN=John Johnson"

We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.