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 required: the service will not start without it.

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, and must exist by then — a missing directory stops the service at startup. 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.

An empty directory rejects every issuer

The service starts when the directory holds no *.pem files, but it then has nothing to build a path to, so every credential is rejected. Add the root of each issuer you accept before verifying. See Trust model.

One limit applies: 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.

An anchor applies to every verification the service performs. When a single request should accept a narrower set of issuers than the deployment does, pin the certificate authority in that request's DCQL query instead — see Restricting which issuers you accept. That check compares key identifiers, so it narrows what the anchors already established rather than replacing it.

What's Next