Getting Started With the BizTalk PDF Pipeline Component
Contents
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:
| SignData | Determines whether a signature/certification should be generated for the PDF. |
| SignatureType | Whether to generate a signature (0) or certification (1). |
| SignatureHashAlgorithm | The algorithm used when signing. |
| SignExistingFields | Whether 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. |
| SigningCert | The Certificate with a private key that will be used to sign the PDF; please see the Details on Using Certificates section for more information. |
| SigningCertPKCS11Params | If the Certificate is in PKCS#11 format (hardware token), this should be set instead of SigningCert; please see the Using PKCS#11 Certificates section for more information. |
| Location | The 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:
| Invisible | The signature widget will not be visible on the resulting PDF unless this is set to false. |
| AlgorithmCaption | A caption describing the signature algorithm. |
| BackgroundStyle | Used to specify the background image in the signature widget: Default (0), None (1), or Custom (2). |
| Background | When using a custom signature background image, set this to the full path to the image file. |
| ShowOnAllPages | Whether the signature widget should be displayed on every page in the PDF; otherwise it will only be displayed on the first page. |
| Page | If the signature widget should be displayed on a specific page, set this to the appropriate page number. |
| Reason | A custom message stating the reason for the signature. |
| SignerCaption | A 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:
Encrypting PDF Documents
The EncryptData property determines whether the PDF should be encrypted.
The following properties are applicable when encrypting PDF documents:
| EncryptData | Determines whether the PDF will be encrypted. |
| EncryptionType | Whether to encrypt with Public Key Encryption (0) or Password-based Encryption (1). |
| EncryptionAlgorithm | The algorithm used when encrypting. |
| EncryptionCert | If 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. |
| EncryptionCertPKCS11Params | If using public key encryption and the Certificate is in PKCS#11 format (hardware token), this should be set instead of EncryptionCert; please see the Using PKCS#11 Certificates section for more information. |
| Password | If using password-based encryption, set this to the encryption password. |
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:
| RequireSignature | Whether an error should be thrown if no signature is found or cannot be verified. |
| RequireAllSignatures | If 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. |
| RequireTimestamp | If true, signatures that do not include a timestamp will not be considered valid. |
| SignerCert | The Certificate with a private key that will be used to sign the PDF; please see the Details on Using Certificates section for more information. |
| SignerCertPKCS11Params | If the Certificate is in PKCS#11 format, this should be set instead of SigningCert; please see the Using PKCS#11 Certificates section for more information. |
| KnownCert | Specifies an intermediary certificate in a trusted certificate chain; please see the Details on Using Certificates section for more information. |
| KnownCertPKCS11Params | If the Certificate is in PKCS#11 format, this should be set instead of KnownCert; please see the Using PKCS#11 Certificates section for more information. |
| TrustedCert | Specifies a certificate that can be used to validate the trust of other certificates; please see the Details on Using Certificates section for more information. |
| TrustedCertPKCS11Params | If the Certificate is in PKCS#11 format (hardware token), this should be set instead of TrustedCert; please see the Using PKCS#11 Certificates section for more information. |
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:
| RequireEncryption | If true, an error will be thrown if the PDF is not encrypted. |
| RequireNonEmptyPass | If true, an error will be thrown if the PDF was password-encrypted with an empty string. |
| RequirePublicKeyEncryption | If true, an error will be thrown if the PDF was not encrypted with a public key. |
| DecryptionCert | If 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. |
| DecryptionCertPKCS11Params | If using public key encryption and the Certificate is in PKCS#11 format (hardware token), this should be set instead of EncryptionCert; please see the Using PKCS#11 Certificates section for more information. |
| Password | If the PDF was encrypted with a password, set this to the decryption password. |
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:
| AltCertType[index] | How the Certificate at the given index should be used | Possible values: 0 (Encryption) 1 (Signing) 2 (Decryption) 3 (Known) 4 (Signer) 5 (Trusted) |
| AltCertSource[index] | The current format of the Certificate at the given index | Possible 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 index | Example: "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 | Description | Example |
|---|---|---|
| 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:
| AccessType="CurrentUser" |
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:
| Param Name | Description | Example |
|---|---|---|
| dllpath | Path to PKCS#11 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.