Library (SDK) user’s guide

This guide offers a high-level overview of pyHanko as a Python library. For the API reference docs generated from the source, see the API reference.

The pyHanko library roughly consists of the following components.

• The pyhanko.pdf_utils package, which is essentially a (gutted and heavily modified) fork of PyPDF2, with various additions to support the kind of low-level operations that pyHanko needs to support its various signing and validation workflows.

• The pyhanko.sign package, which implements the general signature API supplied by pyHanko. This package handles both signing and validation.

• The pyhanko.stamp package, which implements the signature appearance rendering & stamping functionality.

• The pyhanko.keys package with utilities to handle key and certificate loading.

• Support subpackages to handle CLI and configuration: pyhanko.config and pyhanko.cli (packaged as part of pyhanko-cli). These mostly consist of very thin wrappers around library functionality, and shouldn’t really be considered public API, except for the parts used in the plugin system.

Support for certificate validation is provided by the pyhanko_certvalidator package.

pyHanko library topics

• Reading and writing PDF files
  • Reading files
  • Modifying files
• Signature fields
  • General API design
  • Positioning
  • Seed value settings
  • Document modification policy settings
• Signing functionality
  • General API design
  • A simple example
  • Signature appearance generation
  • Timestamp handling
  • Creating PAdES signatures
  • Using aiohttp for network I/O
  • Extending Signer
  • The low-level PdfCMSEmbedder API
  • Interrupted signing
  • Generic data signing
• Validation functionality
  • General API design
  • Accessing signatures in a document
  • Validating a PDF signature
  • Validating signatures against EU trusted lists
  • Long-term verifiability checking
  • Incremental update analysis
  • Probing different aspects of the validity of a signature
• The pdf-utils package
  • Background and future perspectives
  • PDF object model
  • PDF content abstractions
• Developing CLI plugins
  • General principles
  • The plugin API
  • Plugin discovery and registration
• Advanced examples
  • A custom Signer to use AWS KMS asynchronously
  • Using Google Cloud KMS via PKCS#11
  • A custom Signer to use Google Cloud KMS asynchronously
  • A custom Signer implementation with the YubiHSM SDK