How matthiasvalvekens/pyhanko works
Project Type & Purpose
• pyHanko is a Python-based open-source tool that serves both as a library and a command-line interface (CLI) for digitally signing, stamping, and validating PDF files. It also provides capabilities for PDF encryption, certificate management (including PKCS#11 support), and timestamping.
• The README emphasizes features such as CLI usage, embedded library functionality, and support for multiple cryptographic schemes and PDF-related operations. This tells us that the system is built with modularity and extensibility in mind.
Analyzing the File Structure
• The top-level directories include:
– “pyhanko”: Contains the core code, divided into several submodules:
• "cli": Implements the command-line interface (with subdirectories for commands, context management, and plugins).
• "pdf_utils": Houses functionality for reading, writing, embedding content, and manipulation of PDF files.
• "sign": Contains all the modules related to digital signing, including submodules for AdES, signers, timestamping, difference analysis, and validation.
• "config": Manages configuration details, logging, key handling (including PKCS#11), and trust settings.
• "generated": Likely a code-generated module for XML/schema handling.
– “docs”: Documentation (including API docs and guides) which reinforces the modularity of the functionality.
– “pyhanko_tests”: Contains unit and integration tests covering the CLI and library aspects of the project.
– “external-schemata”: Supports code generation and possibly schema validation features.
• There are also CI/CD configurations (under “.github”) and other project-level configuration files that indicate rigorous development practices.
Main Components and Their Relationships
• CLI Layer:
• Entry point is provided via pyhanko/__main__.py.
• The pyhanko/cli folder organizes commands (like signing, stamping, validation) into submodules.
• It uses click (as shown in the README) and supports YAML-based configuration.
• Core Business Logic:
• PDF Utilities (in pyhanko/pdf_utils): Handles all low-level PDF operations including barcode generation, embedding, manipulation of PDF metadata, and more.
• Digital Signing Module (in pyhanko/sign): Contains the signing logic including creation of cryptographic signatures, embedding signatures into PDFs, managing incremental updates, and supporting various signature standards (e.g., PAdES profiles, RSA/DSA/ECDSA/EdDSA).
• Validation and Analysis (in pyhanko/sign/validation and diff_analysis folders): Perform cryptographic integrity checks, certificate chain validations, and support experimental difference analysis.
• Timestamping (in pyhanko/sign/timestamps): Provides interfaces to RFC 3161 timestamp servers and accommodates asynchronous signing.
• Configuration and Integration:
• Configuration is centralized in pyhanko/config (handling logging, local key configuration, PKCS#11 setups, etc.).
• Plugin API (pyhanko/cli/plugin_api.py) exists to extend or modify the behavior via plugins – an important extensibility point.
• External Components:
• The system interacts with external libraries such as cryptography (for cryptographic primitives), and possibly PDF parsers and font handlers (as hinted by the pdf_utils and opentype font support).
Architectural Patterns
• The design splits the presentation (CLI) from the core processing modules (e.g., PDF utilities, signing, and validation) which is akin to an MVC or layered architecture.
• Modular design enables both CLI and library usage—each module (signing, PDF manipulation, configuration) is relatively independent and interacts through clear API boundaries.
• The use of plugins (via a dedicated plugin API) shows a commitment to extensibility.