PDF Pipeline Component
Properties Configuration Settings
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.
Using the PDF Encoder Pipeline Component
Encryption Notes
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.
- 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.
Using the PDF Decoder Pipeline Component
The PDF Decoder provides PDF decryption and signature verification functionality.
Decryption Notes
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.
Decryption with Certificates
The adapter will use the certificate specified in DecryptionCert to decrypt encrypted PDF documents. For more details on the use of certificates, please see the Notes on Using Certificates section below.
Decryption by Password
Password must be set to the password used to encrypt the PDF.
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
Cert Properties
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:
- 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. |
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 adapter processes it. |
TimestampServer | The URL of the timestamp server. |
TransportLog | Tells the adapter 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. |
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 adapter processes it. |
TransportLog | Tells the adapter 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.
AltCertType[index] | Specifies how an alternate Certificate should be used. |
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. |
AltCertPassword[index] | Specifies the password for an alternate Certificate. |
AlgorithmInfo | The displayed algorithm info in the signature widget. |
AllowComments | Whether the recipient may add comments. |
AllowFillInForms | Whether the recipient may fill in forms. |
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. |
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. |
PipelineOptions | Options defining the validation and protection functionality of the pipeline component. |