Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Credential verifier configuration

The credential verifier reads one TOML configuration file at startup. This page lists every configuration key, its type, its default, and its effect.

Configuration file discovery

The server searches for the configuration file in two locations, in this order.

Search orderLocation
1credential-server.toml in the current working directory.
2config.toml in the platform configuration directory.

The platform configuration directory depends on the operating system:

PlatformDirectory
Linux$XDG_CONFIG_HOME/ewQwe/Credential Server/ or $HOME/.config/ewQwe/Credential Server/
macOS$HOME/Library/Application Support/ewQwe/Credential Server/
Windows%APPDATA%\ewQwe\Credential Server\

The server reads the first file that exists. The server stops with a configuration error when it finds no file.

Relative paths

The server resolves every relative path against the directory that contains the configuration file. An absolute path is used as written.

These keys accept a relative path:

  • tls_params.server_private_key
  • tls_params.server_certificate
  • tls_params.server_ca_chain
  • tls_params.client_ca_cert_chain
  • openid4vp_config.haip_config.x509_cert_path
  • openid4vp_config.haip_config.x509_key_path
  • issuers_cas_dir
  • attestation_issuer_certificate
  • attestation_issuer_key
  • journal_config.path for the sqlite_file backend

Server parameters

The table below lists the top-level keys of the configuration file.

KeyTypeRequiredDefaultDescription
host_namestringYes—IP address or host name to bind.
host_portintegerYes—TCP port to bind.
tls_paramstableYes—TLS listener settings. See TLS and mutual TLS.
openid4vp_configtableYes—OpenID4VP service settings.
default_usernamestringNo—Accepted for compatibility. The server does not read this value.
public_root_urlstringNo—Public base URL of the server.
issuers_cas_dirstringNoissuers_casDirectory of trusted credential issuer CA files.
attestation_issuer_certificatestringNotls_params.server_certificatePEM certificate for attestation signing.
attestation_issuer_keystringNotls_params.server_private_keyPEM private key for attestation signing.
disable_authenticationbooleanNofalseBypass client certificate authentication.
disabled_authentication_userstringNotestUsername inserted when authentication is disabled.
rust_logstringNo—Log filter string.
tracing_configtableNoSee belowLogging settings.
journal_configtableNoJournal disabledVerification journal settings. See Verification journal.
verifier_uitableNoApp disabledEmbedded verifier app. See the Verifier app reference.

Public root URL

The public_root_url value is the public base URL of the server. The server uses it to build the wallet callback URIs response_uri and request_uri.

The server chooses the base URL in this order:

PrioritySource
1verifier_ui.qr_code_callback_url
2public_root_url
3The URL inferred from the request

Set public_root_url when the server runs behind a reverse proxy or a NAT, or when the bind address is not reachable by wallets.

Credential issuer CA directory

The issuers_cas_dir value is the directory that holds the trusted credential issuer CA files. The server loads every *.pem file in the directory at startup and caches the result. The directory is not reloaded while the server runs, so a restart applies changes.

The default directory is issuers_cas next to the configuration file. When the directory holds no PEM file, no issuer CA is trusted and every presentation reports issuer_trusted = false.

Attestation issuer

The attestation_issuer_certificate value is the PEM certificate whose public key verifies signed attestation JWTs. The Subject Common Name (CN) of the certificate becomes the iss claim. The server publishes the public key and its key identifier at the JWKS endpoint.

The attestation_issuer_key value is the PEM private key that signs attestation JWTs. The key must match attestation_issuer_certificate.

When both keys are omitted, the server uses tls_params.server_certificate and tls_params.server_private_key.

Authentication bypass

The disable_authentication value controls the local-development authentication bypass. When the value is true, the server does not require a client certificate on the relying-party endpoints. The disabled_authentication_user value is the username that the server inserts into the request context in that case. The default username is test.

See TLS and mutual TLS for the full authentication behaviour.

Warning

Do not set disable_authentication = true in production. The value removes the client certificate requirement from every relying-party endpoint.

TLS parameters

The [tls_params] table configures the TLS listener.

KeyTypeRequiredDefaultDescription
server_private_keystringYes—Server private key in PKCS#8 PEM format.
server_certificatestringYes—Server X.509 certificate in PEM format.
server_ca_chainstringYes—CA chain in PEM format.
client_ca_cert_chainstringNoserver_ca_chainCA chain that validates client certificates.
tls_cipher_suitesstringNoMozilla intermediate v5Colon-separated list of TLS cipher suites to enable.

The full field reference is on the TLS and mutual TLS page.

OpenID4VP configuration

The [openid4vp_config] table configures the OpenID4VP service.

KeyTypeRequiredDefaultDescription
transaction_ttl_secsintegerNo300Transaction lifetime in seconds.
haip_configtableNo—JAR signing settings for the HAIP profile.
transaction_storetableNosqlite_memoryTransaction store backend. See below.

When transaction_ttl_secs is omitted, the server uses 300 seconds.

HAIP configuration

The [openid4vp_config.haip_config] table enables the HAIP profile. The server ignores the table for non-HAIP profiles.

KeyTypeRequiredDescription
x509_cert_pathstringYesCertificate chain PEM (leaf first) used to sign authorization requests.
x509_key_pathstringYesPrivate key PEM that signs authorization requests.

The leaf certificate of the chain must carry the DNS subject alternative name (SAN) that the server uses in the x509_san_dns: client identifier.

Transaction store

The [openid4vp_config.transaction_store] table selects the backend that stores OpenID4VP transactions.

backend valueRequired keysPersistenceNotes
sqlite_memoryNoneNoDefault. No file is created.
sqlite_filepathYesPersists across restarts.
KeyTypeRequiredDescription
pathstringFor sqlite_fileFilesystem path to the SQLite database file.

The example below shows both backends. Uncomment the block that matches the deployment.

# SQLite in-memory — default, no keys required
[openid4vp_config.transaction_store]
backend = "sqlite_memory"

# SQLite file — single instance with persistence
# [openid4vp_config.transaction_store]
# backend = "sqlite_file"
# path    = "/var/lib/ewqwe/transactions.db"

Verification journal configuration

The [journal_config] table configures the verification journal. The journal is disabled by default.

KeyTypeRequiredDefaultDescription
enabledbooleanNofalseTurn journaling on or off.
backendstringNosqlite_memoryJournal storage backend.
pathstringFor sqlite_file—Filesystem path to the SQLite journal file.
urlstringFor postgres—PostgreSQL connection URL.
backend valuePersistenceMulti-instance
sqlite_memoryNoNo
sqlite_fileYesNo
postgresYesYes

See the Verification journal page for the entry schema and the journal HTTP API.

Logging

The server configures logging from two sources. The top-level rust_log key is a shortcut for the tracing_config.rust_log key. When both keys are present, tracing_config.rust_log wins. When neither key is set, the server uses the RUST_LOG environment variable.

The [tracing_config] table holds two keys.

KeyTypeDefaultDescription
rust_logstring—Log filter string. Overrides the top-level rust_log and RUST_LOG.
with_ansi_colorsbooleanfalseEnable ANSI color codes in stdout logs.

The server writes its logs to standard output.

Full example

The example below enables mutual TLS, a persistent transaction store, the HAIP profile, and journaling to PostgreSQL.

host_name = "0.0.0.0"
host_port = 9443
public_root_url = "https://verifier.example.com"

issuers_cas_dir = "issuer_cas"
attestation_issuer_certificate = "certs/attestation.cert.pem"
attestation_issuer_key = "certs/attestation.key.pem"

rust_log = "info,ewqwe_credential_verifier_server=debug"

[tls_params]
server_private_key   = "certs/server.key.pem"
server_certificate   = "certs/server.cert.pem"
server_ca_chain      = "certs/ca.chain.pem"
client_ca_cert_chain = "certs/client-ca.pem"

[openid4vp_config]
transaction_ttl_secs = 300

[openid4vp_config.transaction_store]
backend = "sqlite_file"
path    = "/var/lib/ewqwe/transactions.db"

[openid4vp_config.haip_config]
x509_cert_path = "certs/server.fullchain.pem"
x509_key_path  = "certs/server.key.pem"

[journal_config]
enabled = true
backend = "postgres"
url     = "postgres://ewqwe:ewqwe@localhost/ewqwe"

[tracing_config]
with_ansi_colors = false

Startup validation

The server validates the configuration at startup. The server stops with a configuration error in these cases:

  • The configuration file is missing or cannot be parsed.
  • A TLS key or certificate file cannot be read or parsed.
  • The OpenID4VP service cannot initialize, for example when a HAIP certificate file is missing.
  • The configured transaction store or journal backend cannot be reached.
  • verifier_ui.session_secret is shorter than 8 characters when the verifier app is enabled.