A signature can be cryptographically perfect and still be a support ticket. Check three things, in this order, before a signed document leaves your system.
1. Does the signature validate
Run the file through a validator that understands PAdES:
- Cleverbase's Validator on cleverbase.com, the quickest check that the CMS is well-formed, the chain resolves and the signature verifies against the signed attributes.
- DSS (the same library, via the demo web app or
SignedDocumentValidator): a full ETSI EN 319 102 report, including the qualification status of the certificate. - pyHanko:
pyhanko sign validate --pretty-print signed.pdfgives the same verdict from the command line.
Expected for a B-B signature on acceptance: signature intact, certificate chain builds, qualification not asserted (test certificates). A signature that fails here almost always failed for one of two reasons: the hash was over the PDF instead of the signed attributes, or the algorithm named in the CMS is not the one Cleverbase used. Both are in "The hash and the signature value".
2. Does the structure say what you think it says
Open the file in a PDF inspector. Cleverbase has one on this site - the PDF analyser, free with a Cleverbase account - and qpdf --json gets you the same objects by hand. An inspector does not validate; it shows what is actually in the file: revisions, the signature dictionary, /ByteRange against the file size, the AcroForm, and a Findings card at the top that lists exactly the structural problems "PAdES pitfalls" describes. A clean B-B file shows one revision after the original, one signature, /SigFlags 3, and "nothing to report" under Findings.
Highlight the signature to see which objects the byte range covers; it should be everything except the /Contents hole.
3. Does every viewer show the same thing
Open the signed file in the viewers your users actually have. At minimum:
| Viewer | What to look for |
|---|---|
| Adobe Acrobat Reader | The signature panel lists the signature; the visible field (if any) is drawn; no "document was modified" warning. Reader is the strict one: several of the problems in "PAdES pitfalls" only show here. |
| A Chromium browser (PDFium) | The visible field is drawn. PDFium ignores most form quirks, so a file that looks right only here is not proof. |
| Nitro, Foxit or macOS Preview | Whatever your customers use. |
For B-LT and B-LTA, Acrobat must also show "LTV enabled" on the signature. If it does not, the DSS is missing revocation data for part of a chain, and the file is B-T however many timestamps follow.
Then try to change a form field. It must be refused by the lock, or impossible because the form was flattened. If you can type in a field, the fields were left open (step 0.1 and 0.4).
If the validator says valid at the level you intended, the analyser says nothing to report, and Adobe Reader shows the signature, ship it. If the validator says valid and Adobe shows nothing, do not ship it: read "PAdES pitfalls".
Keep the evidence
Store, per signed document: the credentialID, the hash you authorized, the signAlgo, the signing time you fixed at prepare, and the signature value as returned. With those and the document you can reconstruct why a signature validates (or why it stopped validating), and they are what Cleverbase will ask for when you open a ticket.