endesive
endesive is a Python library for creating and verifying digital signatures in:
- PDF documents (CMS/CAdES detached signatures, Adobe-compatible)
- S/MIME messages (sign, verify, encrypt, decrypt)
- Plain data streams (CMS detached signatures)
- XML documents (XAdES BES/T, enveloped and enveloping)
Features
- PDF signing and verification with optional TSA timestamping and OCSP data
- S/MIME signing/verification and envelope encryption/decryption
- CMS detached signatures for arbitrary binary/text payloads
- XAdES BES/T generation for XML workflows
- Hardware-backed signing through PKCS#11 (PyKCS11) and SSH agent support (paramiko)
- Verification result model exposing signature, hash, certificate, OCSP and TSP statuses
Installation
Python requirement: 3.11+
pip install endesiveFrom source:
pip install -e .Development extras:
pip install -e ".[dev,docs]"Package Overview
endesive.pdf
endesive.pdf.cms.sign(...)
- endesive.pdf.verify(...)
- endesive.pdf.PDFVerifier
endesive.email
endesive.email.sign(...)
- endesive.email.verify(...)
- endesive.email.encrypt(...)
- endesive.email.decrypt(...)
endesive.plain
endesive.plain.sign(...)
- endesive.plain.verify(...)
endesive.xades
endesive.xades.BES
endesive.hsm
endesive.hsm.HSM
Quick Start
1) Sign a PDF
import datetime
from cryptography.hazmat import backends
from cryptography.hazmat.primitives.serialization import pkcs12
from endesive.pdf import cms
with open("cert.p12", "rb") as fp:
key, cert, cert_chain = pkcs12.load_key_and_certificates(
fp.read(), b"password", backends.default_backend()
)
with open("input.pdf", "rb") as fp:
pdf_data = fp.read()
signing_date = datetime.datetime.now(datetime.UTC).strftime("D:%Y%m%d%H%M%S+00'00'")
pdf_signature_meta = {
"sigpage": 0,
"reason": "Approval",
"location": "HQ",
"contact": "[email protected]",
"signingdate": signing_date,
}
signature_block = cms.sign(
pdf_data,
pdf_signature_meta,
key,
cert,
cert_chain or [],
"sha256",
)
with open("output-signed.pdf", "wb") as fp:
fp.write(pdf_data)
fp.write(signature_block)
2) Verify a PDF signature
from endesive import pdf
trusted_certs = [open("ca-root.pem", "rb").read()]
signed_pdf = open("output-signed.pdf", "rb").read()
result, unsigned_tail = pdf.verify(signed_pdf, trusted_certs)
print("signature ok:", result.signatureok)
print("hash ok:", result.hashok)
print("certificate ok:", result.certok)
print("ocsp ok:", result.ocspok)
print("tsp ok:", result.tspok)
print("remaining unsigned data:", unsigned_tail is not None)
3) Sign/verify plain data (CMS detached)
from endesive import plain
detached_sig = plain.sign(data_bytes, private_key, certificate, cert_chain)
verify_result = plain.verify(detached_sig, data_bytes, trusted_certs)
4) S/MIME operations
from endesive import email
signed_message = email.sign(data_bytes, private_key, certificate, cert_chain)
verify_result = email.verify(signed_message_str, trusted_certs)
encrypted_message = email.encrypt(data_bytes, recipient_certs, "aes256_cbc")
decrypted_bytes = email.decrypt(encrypted_message_str, private_key)
5) XAdES
from endesive.xades import BES
bes = BES()
xml_tree = bes.enveloped(data, cert, cert_bytes, signproc, tsp_url, tsp_credentials)
xml_tree = bes.enveloping(...)
For complete XML flows, use the executable examples listed below.
Examples
The examples directory contains end-to-end scripts for certificate creation, data generation, signing, verification, HSM usage, timestamps, and advanced PDF signature appearance customization.
Useful starting points:
- Setup and test fixtures:
examples/make-cert-ca.py
- examples/make-cert-hsm.py
- examples/make-pdf.py
- examples/make-plain.py
- examples/make-smime.py
- examples/make-xml.py
- PDF:
examples/pdf-sign-cms.py
- examples/pdf-verify.py
- examples/pdf-timestamp-cms.py
- Plain/CMS:
examples/plain-sign-attr.py
- examples/plain-sign-noattr.py
- examples/plain-verify.py
- S/MIME:
examples/smime-sign-attr.py
- examples/smime-encrypt.py
- examples/smime-decrypt.py
- examples/smime-verify.py
- XAdES:
examples/xml-hsm-certum-enveloped.py
- examples/xml-hsm-certum-enveloping.py
Recommended execution order:
- Generate certificates.
- Generate input documents/messages.
- Run signing scripts.
- Run corresponding verification scripts.
Validation Tools
PDF validators:
- https://www.pdf-online.com/osa/validate.aspx
- https://demo.verapdf.org/
- https://pdfbox.apache.org/
- https://ec.europa.eu/cefdigital/DSS/webapp-demo/validation
- https://pkitools.net/pages/validator/pdf.html
Development
Run tests:
make testRun type checks:
make mypyBuild docs stubs:
make docsDependencies
Runtime dependencies (from pyproject.toml):
cryptographyasn1cryptolxmlpykcs11Pillowrequestsparamikopypdfattrs
License
MIT, with additional license files for bundled components:
LICENSELICENSE.pdf-annotateLICENSE.pyfpdf