Skip to content

Issuer Trust Anchors

Trust anchors are the root certificates your verifier is willing to trace an issuer back to. They are how you say "I accept credentials from these authorities, and no others".

This setting applies to the verifier only. It is optional to start the service, but it is the only thing that makes the verifier enforce which issuers it accepts — see the warning below.

Configuration

issuerTrustAnchors is a path to a directory, not a file:

"issuerTrustAnchors": "conf/issuer-trust-anchors"

Every *.pem file in that directory is loaded as a trust anchor at startup. Files with any other extension are ignored, so a .crt or .cer you drop in will be silently skipped — convert it to PEM and name it .pem.

The directory is read once, when the service starts. Adding or removing an anchor requires a restart.

As with the other paths in server.json, this one is relative to the container's working directory, /app. Mount the directory in alongside conf/:

volumes:
    - ./verifier/conf:/app/conf:ro

What they are used for

Trust anchors are used for PKIX certificate path validation. When the verifier receives a credential carrying a certificate chain, it builds a path from the presented leaf certificate up to one of these anchors and rejects the credential if no valid path exists. This applies to SD-JWT and mdoc alike.

Configure at least one anchor before facing real holders

Path validation is skipped when the setting is absent or its directory holds no *.pem files. The verifier still checks that a credential's signature matches the certificate it presents, so nothing tampered with gets through — but with no anchors it has nothing to compare that certificate against, so it cannot tell your issuer from any other.

A verifier started with no anchors logs a warning at startup. Check the log if you are unsure which mode a running verifier is in: results look the same either way. See Trust model.

A credential presenting no chain at all, such as a did:jwk: issuer, has no path to validate; these anchors are not consulted for it in any case.

One limit applies when validation does run: chains are limited to 10 certificates, and are rejected before validation if longer.

Validity periods are checked, so an expired certificate anywhere in the path fails it.

Choosing what to trust

Each anchor you add is a statement that you will accept any credential issued under it. Keep the set as small as the deployment allows:

  • For a closed ecosystem, the anchor is your own issuer's root — see Signing certificates.
  • For credentials from an external authority, use the root that authority publishes for the purpose, not an intermediate you happened to receive in a presentation.
  • Remove anchors when you stop accepting an issuer. Nothing expires them for you.

What's Next