Deep dive · 03 / 04

Digital signatures.

Two modes, honest trade-off: a native tamper-detection signature that is self-contained, or an Adobe-compatible PAdES signature that needs you to bring your own trusted cert.

The two modes at a glance

Property	Native	PAdES
Credit cost	5 per signing	15 per signing
Cryptography	Ed25519 + SHA-256 content digest	X.509 + RFC 5652 CMS (PAdES B-B / B-T)
Tamper detection	Yes	Yes
Adobe Reader verify	"Unknown signer" (valid but untrusted)	Green-check if cert chains to a trusted root
Cert required	No — toolkit generates the key pair	Yes — you supply a qualified cert
Offline verification	Yes — bundled public key	Yes — given the cert path
When to use	Internal records, audit trails, legal holds where you trust your own signing path	External-facing, Adobe-validated, contracts that must look signed

Native signature — 5 credits

The native mode writes a detached Ed25519 signature over the SHA-256 of the PDF content. The public key is embedded in the signed PDF plus a canonicalized manifest of what was signed: page count, content-stream hashes per page, and an ISO-8601 timestamp.

Verification is a single call that re-hashes the document, recomputes the canonical manifest, and checks the signature against the embedded public key. Any byte flip anywhere in the content anywhere in the file causes verification to fail.

Trade-off: Adobe Reader does not know our key. It will report the signature as valid but will label the signer as unknown, because the key does not trace back to a trust store it recognizes. That is fine for internal audit and for workflows where your own team does the verification. It is not fine if your counterparty expects a green check inside Adobe.

PAdES signature — 15 credits

PAdES (PDF Advanced Electronic Signature) is the ISO profile that Adobe and the EU eIDAS framework speak. It is built on top of CMS (RFC 5652) and wraps the signature in a PKCS #7 container with your X.509 cert inside the PDF.

We support PAdES B-B (baseline) and PAdES B-T (with a trusted timestamp from an RFC 3161 TSA of your choice). To use it, you supply a qualified cert — from DigiCert, GlobalSign, Entrust, or your own internal CA if your verifiers trust it. We do not issue trust-anchor certs and do not resell them.

The cost difference reflects the extra cryptographic work: signed attributes, optional timestamp fetching, revocation metadata embedding, and the PDF-AdES structure compliance checks.

What we do not do

We are not DocuSign. There is no signing-request UI, no email routing, no "send for signature" workflow. This is a cryptographic signing operator, not a workflow product.
We do not issue trust-anchor certs. If you need Adobe's green check, you bring a cert that Adobe's AATL trusts.
We do not run a CA. For internal workflows, the native signature is typically enough. For external-facing, you bring the cert.

Code example

# native signing
doc_app sign contract.pdf --reason "Counsel review" --out signed.pdf

# PAdES signing with a customer cert
doc_app sign contract.pdf \
    --profile pades \
    --cert /path/to/signer.p12 --cert-pass "$CERT_PASS" \
    --tsa https://timestamp.your-tsa.example \
    --out signed.pdf