PDFVerifier Class

Properties   Methods   Events   Configuration Settings   Errors  

The PDFVerifier class verifies signatures over PDF documents.

Syntax

class secureblackbox.PDFVerifier

Remarks

Use PDFVerifier to validate electronic signatures over PDF documents. Generic and PAdES signatures are supported.

PDFVerifier validates each signature from two perspectives: the integrity and validity of the signature itself (i.e. its correspondence to the document data it covers), and the validity and trustworthiness of the signing certificate chain. These two signature aspects are generally independent of each other: the signature may be valid but the chain may not be trusted, or, the other way round, the chain may be trusted, but the integrity of the signature may be violated. Under normal circumstances both the signature and the chain must be valid for the signature to be considered good.

To initiate the validation, assign the path to the signed PDF file to the input_file property (alternatively, you can provide it in a memory buffer via input_bytes property), and call verify method. For every signature located in the document, PDFVerifier will fire the on_signature_found event. This event lets you specify whether you want PDFVerifier to validate the signature, the chain, or both.

Note: it does not mean that any of the two is optional. This API lets you be flexible in how you validate documents in your code in accordance with the specifics of your application and its usage scenarios. For example, if your trust environment relies on certificate pinning, validating the chain by PDFVerifier internally may cause unnecessary burden on the system, in which case it may be reasonable to disable it in the event handler.

Once on_signature_found returns, PDFVerifier proceeds to the signature validation routine in accordance with the provided settings. Upon completion of the validation, on_signature_validated event is fired, and the validation results are separately provided via signature_validation_result and chain_validation_result properties. Other information about the signature can be accessed via the signature property.

PDF format uses incremental updates to introduce changes to the document. This implies that a signature may cover not the whole document but, rather, a certain revision of it. Strictly speaking, every signature in a PDF document apart from, perhaps, the last one covers just some part of the document. In most cases that part matches the revision of the document that existed before all the subsequent signatures had been added.

Because of this specifics of PDF format it is crucially important to understand what part of the document is covered by a specific signature. Use the to establish the scope of a signature. The revision of the document covered by that specific signature ranges from byte 0 to CoverageEndsAt. Alternatively, you can use the get_signed_version method to extract the signed revision to a file.

Useful settings and properties

The following properties of PDFVerifier may be handy when working with this component:

• offline_mode lets you validate the document without contacting online revocation sources. Paired with switched off system trust settings, it can be used to establish the long-term validity of the document and the completeness of validation material included in it.
• revocation_check lets you adjust the revocation checking preferences.
• validated_signing_time returns the signing time as recorded in the embedded signature timestamp. This is in contrast to claimed_signing_time, which returns the signing time as specified by the signer.
• validation_log is a great way to find out the details of chain validation failures. This property returns a comprehensive validation log that reports all the issues encountered during the validation.
• If the document is encrypted (in addition to being signed), on_decryption_info_needed event will fire, asking you for the decryption certificate or password.

By default, PDFVerifier uses the system trust settings to establish certificate chain validity. You can configure it to use your own, custom validation environment by providing the necessary trust elements via known_certificates, trusted_certificates, known_cr_ls, and other similar properties.