DSS Validator¶

The {{ product_name }} DSS validator (alpine-dss-validator) is a central, multi-tenant service that validates electronic signatures. It checks a signed document against a merged trust store holding both the EU List of Trusted Lists (LOTL) and the Swiss Trusted List, runs the full ETSI EN 319 102-1 validation process once, and reports a verdict per signature — for EU eIDAS and Swiss ZertES / VZertES.

• All AdES levels: B, T, LT, LTA.
• All formats: PAdES, CAdES, XAdES, JAdES, and ASiC containers.
• Two surfaces: a browser UI and a JSON REST API.

Deployment¶

Prerequisites¶

• Java 25 only.
• A read-only control database (PostgreSQL 18) for tenant OIDC providers and license entitlements. Leave alpine.dss.control-db.url blank only for local dev with permit-all.
• Trust-list authentication assets (not shipped — supply per deployment):
  • the EU Official-Journal keystore (tl/eu-oj-keystore.p12) holding the certificates the EU publishes as authorised to sign the LOTL;
  • the Swiss TL signer certificate (certs/CH-TL-cert-DER.cer).
• A pre-seeded tl-cache/ directory only for a deployment with no outbound access — on any machine that can reach the publishers, the startup refresh fetches the lists itself.
• Outbound network egress for AIA / OCSP / CRL revocation checks and the daily trusted-list refresh.
• The dss.validator feature license assigned to each tenant that will validate (tenant license).

Build and run¶

# Build this module and its dependencies (from the repository root)
mvn -pl 07_dss/alpine-dss-validator -am package

# Run
java -jar 07_dss/alpine-dss-validator/target/alpine-dss-validator-<version>.jar \
  --alpine.dss.control-db.url=jdbc:postgresql://db-host:5432/alpine_control \
  --alpine.dss.control-db.username=dss_ro \
  --alpine.dss.control-db.password="$ALPINE_DSS_CONTROL_DB_PASSWORD"

The validator listens on port 8090 by default.

Configuration¶

Configuration is in 07_dss/alpine-dss-validator/src/main/resources/application.yml; every key has an environment-variable override.

Core¶

EU trusted lists¶

Swiss trusted list¶

Trust-list freshness¶

A stale trust list does not fail — it answers confidently and wrongly. The validator therefore tracks how current each list is and says so wherever a verdict is shown. These thresholds tune when it says it.

The strongest signal is not configured here: it is each list's own declared NextUpdate date, which its publisher asserted. A list past that date is reported stale whatever these values say. The thresholds below cover only what a NextUpdate cannot — a list well inside its months-long validity whose contents changed (a trust service withdrawn) without this validator noticing.

What the states mean¶

The aggregate state is worst-wins across lists, so one unusable member-state list shows as NEVER_LOADED at the aggregate while the rest of the store is intact. Health and the banner wording distinguish the two: "no trusted list is loaded" is only said when nothing has anchors.

Freshness is evaluated when it is read, not when a refresh runs, and on two independent axes — how long since this validator confirmed the list online, and how long past the date the publisher itself declared. The worse of the two wins, so a validator that loses its route out drifts from CURRENT to STALE to EXPIRED on its own, and a list its publisher has abandoned expires even while every refresh succeeds. A cached copy that has never been confirmed online ages the same way, measured from the date its publisher stamped on it, so an air-gapped install does not rest at CACHE_ONLY indefinitely.

Authenticity is a separate question from freshness¶

A trusted list also has to be genuine, and that is tracked independently of how old it is. DSS reports three outcomes for a list's own signature, not two: valid, invalid (the document was tampered with), and indeterminate — the signer did not chain to the anchor this deployment configured. The last is what you get from a substituted list, and also from an anchor you simply have not configured.

Anything short of a positive confirmation means the validator is taking anchors from a list it cannot prove is genuine. That makes the trust store degraded regardless of its freshness state, raises its own banner ranked above any staleness message, and sets trustData.current to false.

What a degraded validator reports¶

It annotates; it does not refuse, and it does not silently downgrade.

The evidence in a cached trusted list is real. Discarding it because of a fact about this validator's network would throw away a genuine result and make the product useless in the on-premises deployment it is meant to serve. Equally, turning a QESIG into "not qualified" would assert something the evidence does not support. What is actually known is a statement about the evidence's currency, so that is what is said:

As of 28 August 2026 this anchor was listed as a qualified trust service on the German trusted list. This validator has not been able to re-check that list since. Trust services withdrawn in the last 21 days are not reflected in this result.

Two cases are treated differently:

• NEVER_LOADED — no trust store at all. Every signature reports as reaching no anchor, and the page says plainly that this is a configuration problem with the validator, not a property of the document.
• Dropped anchors — a parse failure (unlike a download failure) makes DSS rebuild its trust store without that list, silently removing its anchors. That is reported in its own words, because the resulting verdict says nothing about the signature.

Staleness is tracked and reported per list: a stale EU list does not qualify a fully-evidenced Swiss verdict.

The Swiss TL and the EU lists are handled identically. The Swiss list ages through the same states against the same thresholds, counts refresh failures the same way, and produces the same banner and the same API flags — only the list's name differs. In particular, a Swiss ZertES verdict reached against a Swiss TL this validator could not re-fetch is annotated, never withheld: no setting makes an out-of-date trusted list block a verdict. Where a qualified verdict cannot be attributed to any tracked list at all, it is reported as unconfirmed rather than assumed current — for Swiss and eIDAS signatures alike.

Where it is surfaced¶

Private CA trust anchors¶

For a closed ecosystem — an internal CA whose certificates will never appear on a public trusted list — an administrator can supply trust anchors that are trusted alongside the EU and Swiss lists.

A directory rather than a list of files, because that is the shape of a Kubernetes ConfigMap or Secret mount, and because adding a CA should not mean editing configuration. A concatenated bundle works: a ca-bundle.pem holding a root and its issuing CA contributes both.

The anchors apply to every validation, whichever list the signature would otherwise have been judged against. They are wired once — beside the single merged EU + Swiss trusted-list source, on the one certificate verifier every request shares — rather than per framework, so they behave the same whether swiss.enabled is true or false, and they remain trusted even when neither public list could be loaded.

classpath: is deliberately not accepted. A directory inside the packaged executable jar cannot be enumerated, so accepting it would accept a setting that silently loads nothing.

Loading is fail-soft per file: one unreadable file is logged with its name and skipped, never fatal — a validator that will not boot over a stray file in a mounted directory is worse than one that boots and reports what it loaded. A configuration that is switched on and loaded nothing is reported on the trust surfaces rather than only in the boot log, because that state and "the feature is off" look identical otherwise and need completely different fixes.

An anchor is identified by its certificate subject, not the file name, so two installs trusting different CAs cannot look alike in a diff. Its own notAfter is evaluated on every read, so an anchor that lapses while the validator runs is reported as expired rather than frozen at whatever it was at boot.

A private CA has no freshness¶

It has no publisher, no issue date, no next-update date and no refresh, so it takes no part in the freshness model: it can be neither stale nor current, and forcing it into one of those states would report something the validator invented. Anchors are therefore excluded from the aggregate and never make the trust store look degraded — or look healthy when the public lists are not.

They are named on every surface that reports trust data, because a verdict can rest on one and the reader should know which anchors are in play.

Unlike a trusted list — whose own signature this validator checks against a configured signing certificate — a private CA is the anchor. Its authenticity rests on the administrator having placed the file there, which is a deployment fact rather than something the validator can re-derive, so it is not reported as unauthenticated.

Egress control (SSRF hardening)¶

Control database¶

Table: the DSS validator's configuration keys, grouped by concern.

Authentication¶

The tenant is identified from the request in both surfaces, then bound into the runtime authorization context where the dss.validator license is enforced.

Either way, a tenant lacking the dss.validator feature license is rejected with an authorization error (tenant license).

Validation flows¶

Upload a signed document (and, for detached signatures, the original payload) and read the per-signature verdict.

curl -s \
  -H "Authorization: Bearer $TENANT_OIDC_TOKEN" \
  -F "file=@signed.pdf" \
  https://validator.example/api/validate

{
  "valid": true,
  "documentName": "signed.pdf",
  "documentSha256": "9f86d0818...",
  "signatureCount": 1,
  "signatures": [
    {
      "signatureId": "S-1",
      "signatureFormat": "PAdES_BASELINE_LTA",
      "indication": "TOTAL_PASSED",
      "subIndication": null,
      "trustFramework": "CH_ZERTES",
      "anchorCountry": "CH",
      "eidasQualification": null,
      "swissQualification": "QES",
      "handwrittenEquivalent": true,
      "errors": [],
      "warnings": []
    }
  ]
}

Validation modes¶

Each signature is projected into a SignatureReport (the array in ValidationSummary.signatures). The key fields:

Trust framework (auto-detected)¶

The framework is read from the country/scheme of the trusted list that terminated the certificate path. A certificate that is dual-listed is assessed with Swiss precedence (the Swiss legal effect applies), so a dual-listed signature runs the Swiss branch.

AdES level and indication¶

Qualification¶

FAQ¶

Related¶

• DSS Services overview
• DSS Signing Server
• tenant oidc command group
• tenant license command group