Signature Validation & Long-term Validity

The class below validates the same file three times and prints the report. The first run has no trust anchor, the second trusts the test CA, the third also supplies a CRL issued by that CA. A CRL is the simplest revocation evidence to fabricate for a test PKI: the helper TestCrl signs an empty list with the CA key at run time and hands it to the validator through ICrlClient, so that the experiment needs no network and no certificate carries a distribution point.

TestCrl needs Bouncy Castle’s certificate API, which bouncy-castle-adapter already brings in:

Output of the run (the messages are those of iText 9.8.0; paths and times differ on your machine):

This is the honest answer for a self-signed test CA, and it is worth reading slowly. The signature is cryptographically perfect in all three runs. The first run is INDETERMINATE because the validator has never heard of the issuer: the chain ends in a certificate that nobody told it to trust, which is exactly what happens when an unknown Acrobat user opens a document signed with a private CA. The second run trusts the CA but still cannot conclude, because the file contains no revocation evidence and the test certificate has no CRL distribution point or OCSP address that iText could fetch. Only when evidence is supplied does the result become VALID. Nothing was "fixed" by the last run: the three results differ only in the information given to the validator. In production the second and third runs are replaced by a real CA that publishes revocation endpoints (or by embedding revocation data in the file, see the long-term section), and the first by a trust list that you control or by the EU trusted lists described below.

The next example makes two different alterations of the signed invoice and validates both with the trust anchor and the CRL from before. The first replaces one digit of the page width inside the signed bytes (the same number of characters, so the /ByteRange offsets stay valid); the second appends a paragraph to the document in append mode, a new revision that leaves every signed byte untouched.

The first result is the textbook integrity failure. The second is more instructive: the original signature is still mathematically correct, since the bytes it covers did not change, but the document revisions validator (DocumentRevisionsValidator, which SignatureValidator calls internally) compared the later revision with the signed one and found a change to a page that the document’s modification rules (DocMDP, "document modification detection and prevention") do not allow. An uncertified signature allows little beyond adding signatures and filling form fields, and a certification signature can tighten or relax this. A consequence for the Bookshelf Billing workflow: if a stamp, a page number or an archiving annotation has to be added to an invoice, it must be added before the signature, or the document must be signed in a way that explicitly permits it.

SignatureValidationProperties holds the policy, and it is set per combination of three dimensions, each with a small enum of constants in com.itextpdf.signatures.validation.context: the validator that is running (for example CRL_VALIDATOR, OCSP_VALIDATOR, REVOCATION_DATA_VALIDATOR, CERTIFICATE_CHAIN_VALIDATOR, SIGNATURE_VALIDATOR, DOCUMENT_REVISIONS_VALIDATOR), the role of the certificate being examined (SIGNER_CERT, CERT_ISSUER, TRUSTED, TIMESTAMP, OCSP_ISSUER, CRL_ISSUER, LOTL_CERT), and whether the evidence is HISTORICAL (covered by a timestamp) or PRESENT (judged now). The factory classes ValidatorContexts, CertificateSources and TimeBasedContexts build the sets (of(...), all(), complementOf(...)).

Three settings matter most:

The policy also states which certificate extensions are required. Per the same article, a signing certificate needs no key usage extension, which technically contradicts ETSI but matches Adobe Acrobat and most other tools; a CA certificate must have the basic constraints extension with the CA flag, and keyCertSign if key usage is present; certificates that sign OCSP responses need the ocsp_signing extended key usage, and those that sign timestamps need time_stamping. For certificate validity, iText uses only the "shell" model: the whole chain must have been valid at the time of signing, so an intermediate CA’s validity must contain that of every certificate it issued. The "chain" model, which only asks that each certificate was valid when it signed the next one, is not implemented in iText (DSS’s bundled policy also declares the shell model, shown below).

Run with out/invoice-signed.pdf pki/billing-test-ca.pem:

Two additional reports appear in this example, and they answer questions that ValidationReport does not. PAdESLevelReportGenerator is an event handler registered with withPAdESLevelReportGenerator; after the validation it tells which PAdES baseline level each signature reaches (PAdESLevel.B_B, B_T, B_LT, B_LTA, or NONE/INDETERMINATE) and, for every higher level, why it was not reached. Here the file is a valid B-B signature, and the list reads like a to-do list for the upgrade: add a timestamp for B-T, a DSS dictionary with the revocation data for B-LT, and a document timestamp covering the DSS for B-LTA. XmlReportAggregator collects an ETSI TS 119 102-2 style validation report as XML (the root element is ValidationReport in the namespace http://uri.etsi.org/19102/v1.2.1#), which can be stored as an audit record of the validation. These reporting classes are present in the 9.8.0 jar, but the iText Knowledge Base did not document them at the time of writing; their API may change more readily than SignatureValidator.

Derived from Signature Module Refactoring & Built-in Signature Validation API and iText Signature Validation Policy Details.

Maintaining your own set of trust anchors is fine for a closed ecosystem, but a Spanish invoice that was signed with a qualified certificate must be checked against the trusted lists that every EU member state publishes under eIDAS. The List of Trusted Lists (LOTL) is a signed XML file at https://ec.europa.eu/tools/lotl/eu-lotl.xml that points to those national lists; each national list names the trust service providers and the certificates of their services, with a service type that tells in which role a certificate can be trusted (issuing qualified certificates, timestamps, OCSP). A careful validator must not just download the certificates, it must verify the signatures of the LOTL and of every national list. iText does this, per the Knowledge Base article on the subject.

Switching it on is one call on the builder, trustEuropeanLotl(true), plus one rule: the data is large and slow to fetch, so it lives in a static cache that you must initialise once, at application start, before the first validation, with LotlService.initializeGlobalCache(LotlFetchingProperties). Initialising it twice is refused on purpose. The cache is refreshed in the background by a timer; by default the data is refreshed about every 5.5 hours (23% of the staleness) and is usable for 24 hours if refresh fails. LotlFetchingProperties takes a mandatory strategy for what to do when one country’s list cannot be retrieved (RemoveOnFailingCountryData ignores that country, ThrowExceptionOnFailingCountryData fails), and optional filters for the countries and for the service types. Because the LOTL’s own signature must be verified with certificates that are not in the LOTL, iText needs the certificates published in the Official Journal of the EU; they ship in the separate artifact com.itextpdf:eu-trusted-lists-resources (version 1.1.0 on Maven Central at the time of writing), which you add as a dependency and update when a new version appears. The article states that a transition period of about 15 days applies when the journal certificates change, during which iText logs a warning, and afterwards LOTL validation fails if the resources are outdated.

Added to the Maven file:

The example was run with the network available (the LOTL endpoint answered). The test file is signed by a private CA that is not in any national list, so the result is again INDETERMINATE with the two familiar messages (untrusted issuer, no revocation data): the lists were fetched and validated, they just do not know the test CA. That is the expected outcome and a good sanity test of the setup. Real qualified-certificate signatures were not available for this page, so the positive case against a genuine trust service provider was not exercised. For several configurations in one process (one country for one customer, another for the next) the builder accepts its own withLotlService(Supplier<LotlService>); each LotlService has its own cache and timer and implements AutoCloseable, so close it when done. The Knowledge Base lists known problems that you will meet on a real network: an SSLHandshakeException when the JDK is too old to trust a national server’s TLS certificate, servers that refuse an empty user agent (both fixed by supplying an IResourceRetriever with withCustomResourceRetriever), and the configuration needed under GraalVM native image. The LOTL endpoint can be unstable; the KB offers samples that read local copies first.

Derived from European Union List of Trusted Lists in Validation. The API is documented in the lotl package of the Java API.

Sample documents for each report and a section on reading them are in the DSS documentation, chapter Inspection of validation reports. Stylesheets that turn the simple and detailed reports into HTML or PDF come with the library.

DSS ships its default policy as an XML file inside dss-policy-jaxb (policy/constraint.xml). Each rule has a level: FAIL, WARN, INFORM or IGNORE. That file is the policy you copy and edit to adapt the validator, and then pass to validateDocument(File), as the example above does when started with -Dpolicy=.... As an experiment, the file was copied and the two lines for the signing certificate, RevocationDataAvailable and AcceptableRevocationDataFound, were changed from FAIL to WARN. The same invoice-signed.pdf with the test CA then gave TOTAL_PASSED with an extra warning "No revocation data found for the certificate!". The lesson is double-edged: a policy is how you adapt the validator to an organisation that has no revocation infrastructure, and also how you can quietly turn a failure into a pass. A policy used in production must be reviewed, versioned and archived with the validation results.

The bundled policy also contains the cryptographic suitability rules, which matter for the long-term section. It lists the acceptable encryption and digest algorithms, minimum key sizes, and an AlgoExpirationDate table with the date from which an algorithm (or an algorithm with a key size below a given number) is no longer accepted, citing ETSI TS 119 312. In the DSS 6.5 file, for example, SHA-1 is dated 2012-08-01 and MD5 2004-08-01, SHA-224 2029-01-01, RSA keys shorter than 1900 bits 2027-01-01 and RSA keys shorter than 3000 bits 2035-01-01, while SHA-256 and larger have no end date. The signer key of the test PKI (RSA 3072, SHA-256) is therefore acceptable until the table is revised. The same file declares <Model Value="SHELL" />, the same certificate validity model that iText uses. Treat those dates as the state of the policy at the time of writing, not as law.

Two more knobs are worth knowing. The validator can be told how deep to go with setValidationLevel: BASIC_SIGNATURES, TIMESTAMPS, LONG_TERM_DATA or ARCHIVAL_DATA (the default), which correspond to sections 5.3 to 5.6 of ETSI EN 319 102-1. And revocation data can come from sources set on the CertificateVerifier (OnlineOCSPSource, OnlineCRLSource, offline sources), which are in dss-service; without them, only the data embedded in the file is used.

DSS reads the same EU trusted lists with a TLValidationJob (module dss-tsl-validation). You describe the LOTL as a LOTLSource with its URL and the certificates of the Official Journal in a KeyStoreCertificateSource, give the job a cached data loader, run onlineRefresh() and pass the resulting TrustedListsCertificateSource to the CommonCertificateVerifier as a trusted source. The sketch below was compiled against DSS 6.5 but not run, because it needs a keystore with the Official Journal certificates that this page does not ship; its path and password come from environment variables, and the maintained way to get that keystore, and the application code that schedules the refresh, are in the DSS documentation chapter on TLValidationJob.

Dependency: eu.europa.ec.joinup.sd-dss:dss-tsl-validation:6.5. Derived from the DSS documentation (dss-documentation.html, sections on the trusted-list job).

The European Commission hosts a demonstration of DSS at the DSS webapp demo. You upload a signed document and get the simple, detailed, diagnostic and ETSI reports in the browser, which is the quickest way to get a second opinion on a file that one of the libraries rejects or to see what a report looks like before writing code. Its own documentation says that the demonstration is meant for testing and that the Commission accepts no liability for its use, so do not upload confidential invoices to it; for real documents, run the same library inside your infrastructure.

The PAdES baseline levels of PAdES Baseline Levels map to these three problems. B-T adds a signature timestamp, which fixes the time of signing. B-LT embeds the validation material (the certificates, and the CRL or OCSP answers for each) in a document security store, the /DSS dictionary, so that the revocation question can be answered offline. B-LTA adds a document timestamp over the whole file, including the DSS, so that the evidence itself has a proof of existence. Before the timestamp’s own certificate expires, or before its algorithm weakens, another document timestamp is added over everything, with fresh validation data for the previous timestamp. This is the renewal, and because each timestamp is an incremental update it does not disturb the earlier ones. A chain of document timestamps is what lets a validator in 2046 accept a signature from 2026: it sees that the file existed in 2026 (first timestamp), still existed in 2031 when the algorithm was still strong (second), and so on.

The Knowledge Base article on the relation of LTV and document timestamps, quoting a StackOverflow answer by mkl, adds a historical note worth knowing: the PAdES part that defined timestamps and the part that defined LTV information were written together, so some developers believe that adding a DSS requires a timestamp. Adobe’s own statement, quoted there, is that no timestamp is required for "LTV enabled", but that whenever a timestamp is added, validation information for the timestamp must be added too. In an archive you want both.

iText offers PdfPadesSigner for the whole sequence, signWithBaselineLTAProfile(...), and prolongSignatures(ITSAClient) for the renewal of an existing B-LTA file; the Java API page is PdfPadesSigner. The example below makes an LTA file with the test PKI and a public timestamp authority, then renews it. The timestamp server is https://freetsa.org/tsr, a free service that needs no credentials and is suitable for tests only.

The TSA call succeeded from the test machine and the files were produced. Validating the results with the public CA certificate of the timestamp service added as a trust anchor (downloaded at run time from the service, not reproduced here) gave different answers in the two libraries, and the difference is worth understanding rather than hiding:

On this test PKI, signWithBaselineLTAProfile produced a file that DSS classifies as B-T, not B-LTA, because there was nothing to embed for B-LT: neither the test CA nor the free timestamp service publishes a revocation endpoint that the library can query, so the document security store could not be completed. After prolongSignatures, DSS recognises the structure as B-LTA and accepts it, while iText still reports B-T and names the missing issuer certificates and revocation data of the timestamp chain. Both reports are internally consistent; they apply different rules to a PKI that does not support the long-term profile. In production, with a CA and a TSA that publish CRLs or OCSP, the same two calls produce a file that both libraries should rate B-LTA, and the level report is how you check it in an automated test: assert on getDocumentLevel() rather than assuming. This was not verified against a real CA for this page. DSS can perform the same renewal with PAdESService.extendDocument and PAdES_BASELINE_LTA parameters plus an OnlineTSPSource (an extra document timestamp was added to the test file this way, the count of timestamps in the diagnostic data going from two to three); the details are in Signing with PDFBox & EU DSS.

When to add the next document timestamp is a policy decision, and the inputs are all measurable:

A pragmatic scheme for the Bookshelf Billing archive is a yearly batch job (the structure is described in Generating Reports from Databases & Services and the Spring Batch and scheduling pages it links to) that selects the archived invoices whose last document timestamp is older than a year, or whose timestamp authority certificate expires within the next year, calls prolongSignatures or the DSS equivalent, validates the result, and stores the validation report next to the file. Because each renewal adds tens of kilobytes (the test file grew from about 63 KB to 96 KB), the storage cost of keeping thousands of invoices for a decade should be estimated before choosing the interval. A separate approach is an evidence record (RFC 4998, an Evidence Record Syntax) that renews many documents with one hash tree; DSS can validate those, but PDF readers do not understand them, so they are for the archive, not for the customer’s copy.

Algorithm expiry works through the same table that the policy uses. When a hash function reaches its end date, a signature made with it remains acceptable only if a timestamp, made with a still-acceptable algorithm before that end date, covers it. That is exactly why the document timestamp chain exists: each one lifts the protection of the previous ones to the current algorithms. A file signed with SHA-1 in 2010 and never timestamped cannot be saved afterwards, because there is no proof it existed before the algorithm was weak; this is the situation of every B-B signature without a timestamp. The default digest of the helper above is SHA-256, which the bundled DSS policy has no end date for.

The larger risk is that RSA and elliptic-curve signatures, which every PDF signature in the world uses today, would be breakable by a sufficiently powerful quantum computer, and that a signature that must stay credible for thirty years is exposed to it. The countermeasures are signature algorithms standardised by NIST: ML-DSA (FIPS 204, from the CRYSTALS-Dilithium family) and SLH-DSA (FIPS 205, based on SPHINCS+), with FN-DSA (Falcon) expected next. The iText Knowledge Base article on PQC support states the status plainly, and it is worth repeating without embellishment:

What this means for planning, from the article and from the structure of the problem: keep signing with RSA 3072 or ECDSA P-256 and SHA-256 for production today; make sure that every long-lived invoice has document timestamps so that a later algorithm change can be bridged by a new timestamp; do not use pre-standard PQC signatures for documents that customers must open in other tools; prepare the surrounding infrastructure (key storage, certificate authorities that can issue PQC certificates, larger /Contents placeholders because PQC signatures are bigger, validators that understand the new algorithms); and follow the PDF Association and ISO work to know when the format is final. This page does not show a PQC signing example because the pre-standard result cannot be validated by anything but iText itself, and it would give a false impression of readiness. The article links iText’s sample code on GitHub for those who want to experiment.

Derived from Post-Quantum Cryptography (PQC) support in iText. The NIST standards are FIPS 204 and FIPS 205.