pyHanko

status Codecov pypi

The lack of open-source CLI tooling to handle digitally signing and stamping PDF files was bothering me, so I went ahead and rolled my own.

Note: The working title of this project (and former name of the repository on GitHub) was pdf-stamp, which might still linger in some references.

Note: This project is currently in alpha, and not yet production-ready.

Installing

PyHanko is hosted on PyPI, and can be installed using pip:

pip install 'pyHanko[pkcs11,image-support,opentype,xmp]'

Depending on your shell, you might have to leave off the quotes:

pip install pyHanko[pkcs11,image-support,opentype,xmp]

This pip invocation includes the optional dependencies required for PKCS#11, image handling and OpenType/TrueType support.

PyHanko requires Python 3.7 or later.

Contributing

Do you have a question about pyHanko? Post it on the discussion forum!

This project welcomes community contributions. If there's a feature you'd like to have implemented, a bug you want to report, or if you're keen on contributing in some other way: that's great! However, please make sure to review the contribution guidelines before making your contribution. When in doubt, ask for help on the discussion board.

Please do not ask for support on the issue tracker. The issue tracker is for bug reports and actionable feature requests. Questions related to pyHanko usage and development should be asked in the discussion forum instead.

Features

The code in this repository functions both as a library and as a command-line tool. It's nowhere near complete, but here is a short overview of the features. Note that not all of these are necessarily exposed through the CLI.

Stamping
- Simple text-based stamps
- QR stamps
- Font can be monospaced, or embedded from a TTF/OTF font (requires [opentype] optional deps)
Document preparation
- Add empty signature fields to existing PDFs
- Add seed values to signature fields, with or without constraints
- Manage document metadata
Signing
- Option to use async signing API
- Signatures can be invisible, or with an appearance based on the stamping tools
- LTV-enabled signatures are supported
  - PAdES baseline profiles B-B, B-T, B-LT and B-LTA are all supported.
  - Adobe-style revocation info embedding is also supported.
- RFC 3161 timestamp server support
- Support for multiple signatures (all modifications are executed using incremental updates to preserve cryptographic integrity)
- Supports RSA, DSA, ECDSA and EdDSA
  - RSA padding modes: PKCS#1 v1.5 and RSASSA-PSS
  - DSA
  - ECDSA curves: anything supported by the cryptography library, see here.
  - EdDSA: both Ed25519 and Ed448 are supported (in "pure" mode only, as per RFC 8419)
- Built-in support for PDF extensions defined in ISO/TS 32001 and ISO/TS 32002.
- PKCS#11 support
  - Available both from the library and through the CLI
  - Extra convenience wrapper for Belgian eID cards
- "Interrupted signing" mode for ease of integration with remote and/or interactive signing processes.
Signature validation
- Cryptographic integrity check
- Authentication through X.509 chain of trust validation
- LTV validation/sanity check
- Difference analysis on files with multiple signatures and/or incremental updates made after signing (experimental)
- Signature seed value constraint validation
Encryption
- All encryption methods in PDF 2.0 are supported.
CLI & configuration
- YAML-based configuration (optional for most features)
- CLI based on click
  - Available as pyhanko (when installed) or python -m pyhanko when running from the source directory
  - Built-in help: run pyhanko --help to get started

Some TODOs and known limitations

See the known issues page in the documentation.

Documentation

Documentation is built using Sphinx, and hosted here on ReadTheDocs.

Acknowledgement

This repository includes code from PyPDF2 (with both minor and major modifications); the original license has been included here.

License

MIT License, see LICENSE.

Release files for pyHanko 0.17.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyHanko 0.17.0
File	Size	Uploaded
pyHanko-0.17.0.tar.gz	333.0 kB	Jan 31, 2023	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyHanko 0.17.0
File	Interpreter	ABI	Platform	Reset
pyHanko-0.17.0-py3-none-any.whl 378.3 kB Jan 31, 2023	Python 3	none	any	Details

Total release size: 711.4 kB

Release files / pyHanko-0.17.0.tar.gz

Download URL	pyHanko-0.17.0.tar.gz
Size	333.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`1f4b5edb935dd3014152cc76117e24c0bfe07d7cd631c3711a254b08c0111317`
BLAKE2b-256 checksum How to use checksums	`09de414c2dafa4276ca99e61b4f954885a9a4254acca20675edc321661b4f362`
Upload date	Jan 31, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.10.4`

Release files / pyHanko-0.17.0-py3-none-any.whl

Download URL	pyHanko-0.17.0-py3-none-any.whl
Size	378.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4f5b9083ddc0d9bd5e12d1daa17d52f596d4b89199bc1822bfa89be575660a85`
BLAKE2b-256 checksum How to use checksums	`713bbf816896598d611b999f06aa4e12fda954043bc25cc2903d8bcf541aa77b`
Upload date	Jan 31, 2023
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.10.4`