Getting Started With the BizTalk PDF Pipeline Component

Resources:

• /n software Adapters for Microsoft BizTalk

Contents

1. Introduction
2. PDF Encoder
   • Signing/Certifying PDF Documents
   • Encrypting PDF Documents
3. PDF Decoder
   • Verifying Signed/Certified PDF Documents
   • Decrypting PDF Documents
4. Details on Using Certificates
   • Alternate Certificates and Specifying Multiple Certificates
   • Using PKCS#11 Certificates (Hardware Tokens)

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:

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

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

Encrypting PDF Documents

The EncryptData property determines whether the PDF should be encrypted.

The following properties are applicable when encrypting PDF documents:

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

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:

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

Decrypting PDF Documents

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

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

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 PKCS#11 certificates via the *CertPKCS11Params properties. This is discussed in more detail in the Using PKCS#11 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:

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:

• CurrentService
• CurrentUser
• CurrentUserGroupPolicy
• LocalMachine (default)
• LocalMachineEnterprise
• LocalMachineGroupPolicy
• Services
• Users

Using PKCS#11 Certificates (Hardware Tokens)

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

For instance:

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