Skip to main content

Trust Services

A digital credential ecosystem requires mechanisms for issuers, wallets, and verifiers to recognize and trust each other. This is called technical trust management. SIROS ID supports multiple trust frameworks to meet different regulatory and deployment requirements.

Go-Trust Abstraction Layer

For production deployments, we recommend using Go-Trust as a trust abstraction layer. Go-Trust provides a unified AuthZEN API that handles the complexity of ETSI TSL, OpenID Federation, and DID resolution, so your services don't need to implement trust logic directly.

Why Trust Matters​

When a verifier receives a credential, it needs to answer:

  1. Is the issuer legitimate? – Was this credential issued by an authorized entity?
  2. Is the credential valid? – Has it been revoked or expired?
  3. Is the wallet trusted? – Is the presenting wallet a recognized credential manager?

Trust services provide the infrastructure to answer these questions automatically.

Trust Architecture​

Supported Trust Frameworks​

ETSI Trust Status Lists (TSL 119 612)​

The EU standard for trust services. Used by eIDAS and the EU Digital Identity framework.

Use when:

  • Deploying in EU/EEA regulated contexts
  • Interoperating with government issuers
  • Requiring legal recognition under eIDAS

Configuration:

trust:
  etsi_tsl:
    enabled: true
    trust_list_url: "https://ec.europa.eu/tools/lotl/eu-lotl.xml"
    cache_duration: 3600
    accepted_schemes:
      - "http://uri.etsi.org/TrstSvc/TrustedList/schemerules/EUcommon"

OpenID Federation​

Dynamic trust management using OAuth 2.0 / OpenID Connect federation.

Use when:

  • Building multi-organizational ecosystems
  • Needing dynamic trust updates
  • Integrating with OpenID-based infrastructure

Configuration:

trust:
  openid_federation:
    enabled: true
    trust_anchors:
      - "https://federation.example.com"
    entity_configuration_path: "/.well-known/openid-federation"

DID:web​

Decentralized identifiers resolved via web infrastructure.

Use when:

  • Simpler trust requirements
  • Self-sovereign identity scenarios
  • Rapid prototyping

Configuration:

trust:
  did_web:
    enabled: true
    allowed_domains:
      - "*.example.com"
      - "issuer.trusted.org"

DID:webvh (Verifiable History)​

An extension of DID:web that adds cryptographic integrity through verifiable history. Each DID maintains a tamper-evident log of all changes, enabling:

  • Self-certifying identifiers (SCIDs) – The identifier is derived from initial content
  • Version history – Complete audit trail of DID document changes
  • Pre-rotation keys – Secure key rotation with hash commitments
  • Witness support – Third-party attestation of DID state

Use when:

  • You need verifiable history of DID changes
  • Key rotation security is critical (pre-rotation)
  • Compliance requires audit trails
  • Upgrading from DID:web with stronger guarantees

Configuration:

trust:
  did_webvh:
    enabled: true
    timeout: "30s"
    # Allow HTTP only for testing (HTTPS required in production)
    allow_http: false

How it works:

  1. The DID resolves to a JSON Lines log file at the web location
  2. Each entry contains the DID document state and a cryptographic proof
  3. Go-Trust verifies the entire chain from the first entry (which establishes the SCID)
  4. Key bindings are validated against the current DID document

Specification: did:webvh v1.0

X.509 Certificate Chains​

Traditional PKI-based trust using certificate chains.

Use when:

  • Integrating with existing PKI infrastructure
  • Requiring offline verification
  • Connecting to legacy systems

Configuration:

trust:
  x509:
    enabled: true
    root_certificates:
      - "/certs/root-ca.pem"
    allow_self_signed: false

URL Whitelist​

A file-based trust model where you maintain a list of trusted entity URLs. The whitelist registry also fetches and caches each entity's JWKS to perform cryptographic key validation.

Use when:

  • You have a known, stable set of trusted partners
  • You want simple, file-based trust management
  • Standard JWKS metadata discovery works for your entities

Configuration:

trust:
  whitelist:
    enabled: true
    config_file: "/config/trusted-entities.yaml"
    watch_file: true  # Auto-reload on changes

Whitelist file format:

lists:
  issuers:
    - "https://issuer1.example.com"
    - "https://issuer2.example.org"
  verifiers:
    - "https://verifier.example.com"
actions:
  credential-issuer: "issuers"
  credential-verifier: "verifiers"
tip

The whitelist registry performs full key validation by fetching each entity's JWKS and computing key fingerprints. See Go-Trust Whitelist Registry for details on JWKS discovery and configuration options.

Trust Configuration​

For Issuers​

Configure trust anchors that recognize your issuer:

  1. Obtain credentials from a trust list operator
  2. Configure your signing certificate chain
  3. Publish discovery metadata at well-known endpoints
issuer:
  trust:
    # Certificate chain for credential signing
    signing_chain_path: "/pki/issuer-chain.pem"
    
    # Your trust list registrations
    trust_list_entries:
      - scheme: "etsi"
        status_list_url: "https://tsl.example.eu/tsl.xml"

For Verifiers​

Configure which issuers to trust:

verifier_proxy:
  trust:
    # AuthZEN PDP URL — when set, operates in "default deny" mode
    pdp_url: "http://go-trust:6001"
    
    # Optional: restrict accepted signature algorithms
    allowed_signature_algorithms:
      - "ES256"
      - "ES384"
      - "EdDSA"

When pdp_url is configured, the verifier delegates all trust decisions to Go-Trust. When omitted, the verifier operates in "allow all" mode. Trust policies (which registries, ETSI service types, etc.) are configured in Go-Trust, not in the verifier itself.

For Wallet Providers​

Register your wallet with trust frameworks:

  1. Generate attestation key pair
  2. Obtain wallet attestation from an approved body
  3. Configure attestation in wallet backend
wallet:
  attestation:
    enabled: true
    key_path: "/keys/wallet-attestation.pem"
    attestation_endpoint: "https://attestation.siros.org"

Trust Evaluation Flow​

When verifying a credential:

Multi-Framework Support​

SIROS ID can use multiple trust frameworks simultaneously with priority ordering:

trust:
  frameworks:
    - type: "etsi_tsl"
      priority: 1
      # ... config
    - type: "openid_federation"
      priority: 2
      # ... config
    - type: "x509"
      priority: 3
      # ... config
  
  # How to handle multiple matches
  policy: "first_match"  # or "all_must_match", "any_match"

Testing Trust​

Development Mode​

For development, you can temporarily disable strict trust:

trust:
  development_mode: true  # ⚠️ Never use in production
  allow_self_signed: true

Troubleshooting​

"Issuer not trusted"​

  1. Check issuer certificate chain is complete
  2. Verify trust list URL is accessible
  3. Confirm issuer is active in trust list (not revoked)
  4. Check certificate validity dates

"Trust list fetch failed"​

  1. Verify network connectivity to trust list
  2. Check for certificate errors (CA trust)
  3. Increase timeout settings
  4. Enable trust list caching

"Certificate chain invalid"​

  1. Ensure intermediate certificates are included
  2. Verify certificate order (leaf → root)
  3. Check for expired certificates
  4. Validate against trust anchor

Best Practices​

  1. Enable caching: Trust lists don't change frequently
  2. Monitor expiry: Set alerts for certificate expiration
  3. Use multiple frameworks: Provide redundancy
  4. Audit trust decisions: Log all trust evaluations
  5. Regular updates: Keep trust list URLs current
  6. Use Go-Trust: Abstract trust complexity behind AuthZEN API

Next Steps​