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

Introduction

ewQwe Digital Identity is a software suite for digital identity based on the European Digital Identity (EUDI) standards. Its principal product is the ewQwe Credential Verifier, a server that a Relying Party uses to verify the credentials that a user presents from a digital wallet.

A Relying Party (RP) is a web application or service that needs a fact about a user, for example that the user is at least 18 years old. A wallet is the application that stores the user’s credentials and presents them. A credential is a signed document that an issuer, such as a government authority, has issued to the user.

The verifier performs the cryptographic work of verification, so a web application does not implement it. The Relying Party sends a Verifiable Presentation to the verifier. The verifier validates the presentation and returns a signed attestation that states the result.

What the credential verifier does

  • It accepts a Verifiable Presentation in the ISO/IEC 18013-5 mDoc format or the SD-JWT VC format.
  • It extracts the disclosed claims and checks the credential expiration.
  • It binds the presentation to the nonce that the server issued for the transaction, which prevents replay.
  • It verifies the issuer signature and the holder signature, using the trusted issuer certificate authorities that the operator configures.
  • It returns a signed attestation, in JWT or COSE/CBOR form, that states the verification result.
  • It records every verification in an append-only journal.

The server implements the W3C Digital Credentials API, OpenID for Verifiable Presentations 1.0 (OpenID4VP), and the EU Age Verification Profile. It supports the High Assurance Interoperability Profile (HAIP) additions for the EUDI Wallet.

The verifier app

The credential verifier ships with its own web application, the verifier app. An operator signs in, selects a credential type, and shows a QR code. The holder scans the QR code with a wallet, and the app shows the verification result. The verifier app is the standard user interface of the credential verifier and needs no other software.

The verifier also exposes an HTTP API, so a product can build a user interface of its own. The repository contains an example relying party in typescript/demo-webapp/ that shows one way to do this. See Develop your own relying-party UI.

Who this documentation is for

This documentation addresses the users of the credential verifier server:

ReaderStarting point
System operatorRun the verifier app and Install and run the server
Relying Party developerHTTP API and Verify a credential
Product developerDevelop your own relying-party UI
Security architectVerification process and Security model
Standards engineerOpenID4VP request parameters and Credential formats

How this documentation is organized

The book follows the Diataxis framework. Each section serves one need of the reader:

  • Tutorials teach the verifier app in a guided lesson.
  • Reference states the facts of the server: the configuration, the HTTP API, the attestations, the journal, the protocols, and the credential formats.
  • Explanation describes why the server works the way it does.
  • How-to guides give the steps for a specific task, such as deploying the server with TLS.
  • FAQ answers recurring questions and links to the page that holds the full answer.

The Glossary defines the terms that the documentation uses. The References page lists the external standards.

Note

The example relying party in typescript/demo-webapp/ is an advanced reference for building your own interface. It is not part of the credential verifier server, and it is not intended for production use as it stands.

The credential verifier depends on three crates of this repository:

  • crates/ewqwe-openid4vp builds and validates OpenID4VP requests and matches DCQL queries.
  • crates/ewqwe-digital-credential builds and verifies mDoc and SD-JWT VC credentials.
  • crates/ewqwe-credential-verifier-ui is the verifier app, the built-in web application that an operator uses to run age verifications.

The server returns a signed attestation, so a Relying Party can trust the result without performing the verification itself. See the HTTP API for the request and response of each endpoint.

Licenses

The components of this repository use two open-source licenses. The Rust server, its crates, and the verifier app are released under the European Union Public Licence v1.2 (EUPL-1.2). The TypeScript library typescript/ewqwe-digital-identity and the demo webapp typescript/demo-webapp are released under the MIT License.

ComponentLocationLicense
Credential verifier server and cratescrates/EUPL-1.2
Verifier app (embedded SPA)crates/ewqwe-credential-verifier-uiEUPL-1.2
Shared TypeScript librarytypescript/ewqwe-digital-identityMIT
Demo webapptypescript/demo-webappMIT

The full license texts are in the LICENSE file at the repository root and in the LICENSE file of each TypeScript package.

Some components are not part of this open-source repository. The enterprise add-ons are available under a separate commercial license. See the README and ewqwe.eu for the enterprise offering.

Run the verifier app

The credential verifier ships with its own web application, the verifier app. This tutorial builds that application, enables it, starts the server, and signs in as the first administrator. At the end, the verifier app shows the control page with the credential type selector and the Generate QR Code button.

The verifier app is the standard user interface of the credential verifier. Use it to start credential verification transactions and to read their results. The verifier also exposes an HTTP API, so you can build a user interface of your own. That path is described in Develop your own relying-party UI and is not needed for this tutorial.

What you need

  • A working credential verifier with TLS. See Install and run the server.
  • Node.js 18 or later, to build the single-page application.
  • An email address and a password of at least 12 characters for the first administrator.

How the verifier app works

The verifier app has two parts: a single-page application (SPA) that the server serves from the root URL, and a JSON API that the server mounts under /api/v1. An operator signs in, selects a credential type, and shows a QR code. The holder scans the QR code with a wallet, and the wallet sends a verifiable presentation to the credential verifier. The verifier app polls the transaction and shows the result.

A verifiable presentation is a signed set of credential claims that the holder chooses to share. A transaction is one credential request and its result.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
sequenceDiagram
    participant OP as Operator
    participant VA as Verifier app
    participant CV as Credential verifier
    participant WL as Wallet
    OP->>VA: Sign in and select a credential type
    VA->>CV: Start a transaction
    CV-->>VA: QR code and authorization request
    VA-->>OP: Show the QR code
    OP->>WL: Scan the QR code
    WL->>CV: Send the verifiable presentation
    VA->>CV: Poll the transaction
    CV-->>VA: Verification result
    VA-->>OP: Show the result

Steps

1. Build the single-page application

cd crates/ewqwe-credential-verifier-ui/ui
pnpm install
pnpm build

Expected: the build writes the SPA to crates/ewqwe-credential-verifier-ui/ui/dist/. Confirm the output:

ls crates/ewqwe-credential-verifier-ui/ui/dist

Expected: index.html and an assets directory.

2. Enable the app

Open the server configuration file and add this section:

[verifier_ui]
enabled = true
app_name = "My Age Verifier"
ui_dist_path = "../crates/ewqwe-credential-verifier-ui/ui/dist"

The path in ui_dist_path resolves relative to the directory that holds the configuration file. When the file is crates/ewqwe-credential-verifier-server/credential-server.toml, the value above points at the build output from step 1. See the verifier app reference for every key.

3. Start the credential verifier

cd crates/ewqwe-credential-verifier-server
RUST_LOG=info cargo run --release

Expected: the log shows Verifier App store enabled and Attestation Provider server listening on 0.0.0.0:9443. Leave the process running.

4. Create the first administrator

Open https://localhost:9443/ in a browser. The server uses a self-signed certificate, so the browser shows a warning. Accept the certificate and continue.

Because no user account exists yet, the app shows the bootstrap form. Enter an email address and a password of at least 12 characters, then submit the form.

Expected: the app signs you in and shows the control page with the Generate QR Code button. The bootstrap route accepts only the first call; every later call returns 409 Conflict.

What happened

The server built the SPA once, in step 1, and serves the built files. In step 3 it mounted the app under /api/v1 and enabled the app because the configuration file contains a [verifier_ui] section. In step 4 the app created the first account, stored the account in the user database, and set a session cookie named verifier_ui_session.

The default user database is SQLite in memory, so the account disappears when the server stops. To keep accounts across restarts, configure the database and the session secret. See Configure the verifier app.

Troubleshooting

SymptomCauseAction
Every /api/v1 route returns 404The app is disabled.Add the [verifier_ui] section with enabled = true, then restart.
The root URL returns 404 or a blank pageThe SPA is not built, or the path is wrong.Build the SPA and correct ui_dist_path. Check the server log.
Bootstrap returns 409 ConflictAn administrator already exists.Sign in instead of bootstrapping a second administrator.
The session ends after each restartsession_secret is not set.Set a stable session_secret value.

Next steps

Complete an age verification

This tutorial continues from Run the verifier app. With the verifier app running and an operator signed in, you generate a QR code, scan it with a wallet, and read the verified result.

What you need

Steps

1. Select the credential type

On the control page, open the credential type selector and choose the type that your wallet holds. The default type is Proof of Age.

When the server allows only one credential type, the app hides the selector and starts the transaction automatically.

2. Generate the QR code

Click Generate QR Code.

Expected: the page shows a QR code and a status badge with the value pending. The app polls the transaction every 2 seconds.

3. Scan the QR code

Open the wallet on the holder device, choose the option to present a credential, and scan the QR code. Approve the request.

Expected: the status badge changes from pending to verified.

4. Read the result

When the badge shows verified, the holder presentation passed verification. The page shows the verified claims, which for a Proof of Age credential is the boolean claim age_over_18. Click New Verification to start another transaction.

The status values

StatusMeaning
pendingThe wallet has not answered the request.
receivedThe wallet returned a presentation.
verifiedThe credential passed verification.
failedThe credential failed verification.
errorThe transaction failed with an error.
expiredThe transaction passed its time to live.

A failed result shows the errors that the verifier returned. The most common cause is an untrusted issuer. See the security model.

What happened

In step 2 the verifier app asked the credential verifier to start a transaction. The credential verifier created a random nonce, stored the transaction, and returned an OpenID4VP authorization request. The QR code carries that request.

In step 3 the wallet read the request, built a verifiable presentation from the stored credential, and sent the presentation to the credential verifier. The credential verifier read the nonce from its own transaction store, compared it with the nonce in the presentation, verified the issuer signature and the holder signature, and signed an attestation.

In step 4 the verifier app read the transaction status and showed the result. The verifier recorded the verification in its journal, when the journal is enabled.

Troubleshooting

SymptomCauseAction
The badge stays pendingThe wallet did not scan the code.Scan the code again, or generate a new code.
The QR code expires before the scanThe transaction passed its time to live.Generate a new QR code.
The result is failedThe credential failed a check.Read the errors. An untrusted issuer is the common cause.
QR generation returns 400The credential type is not allowed.Check allowed_credential_types and the per-user types.
The wallet rejects the requestThe wallet does not trust the verifier.Load the verifier CA certificate into the wallet trust store.

Next steps

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.

Credential verifier HTTP API

The credential verifier exposes an HTTP API over TLS. This page documents every endpoint, the request body, the response body, the status codes, and the error cases.

Base path and authentication

Every endpoint starts with /ewqwe_api. The server serves two further paths outside that prefix: GET /version and the verifier app single-page application at /.

The endpoints fall into three authentication classes.

ClassEndpointsClient certificate
Relying party/ewqwe_api/verify, /ewqwe_api/openid4vp/init, /ewqwe_api/openid4vp/status/{id}, /ewqwe_api/journal/*, /ewqwe_api/.well-known/issuer_certsRequired
Wallet/ewqwe_api/openid4vp/direct_post, /ewqwe_api/openid4vp/request/{id}, /ewqwe_api/openid4vp/.well-known/jwks.jsonNot required
Public/versionNot required

A relying-party endpoint requires a verified client certificate. The server uses the certificate Common Name (CN) as the authenticated username. See TLS and mutual TLS for the certificate requirements.

Request limits

SettingValue
Maximum request payload1,000,000 bytes
Maximum JSON payload1,000,000 bytes
Keep-alive timeout120 seconds
Client request timeout10 seconds

Error responses

The server returns two error-body shapes.

The credential verifier core returns the error message as a JSON string with these status codes.

ConditionStatusBody
Invalid request parameter400JSON string error message
Missing or failed authentication401JSON string error message
Any other failure500JSON string error message

The OpenID4VP endpoints return a JSON object with an error field and these status codes.

ConditionStatusBody
Unknown transaction404{ "error": "<message>" }
Expired transaction410{ "error": "<message>", "status": "expired" }
Invalid request400{ "error": "<message>" }
Cryptographic failure500{ "error": "Internal crypto error" }
Configuration failure500{ "error": "credential verifier configuration: <message>" }
Internal failure500{ "error": "Internal server error" }

POST /ewqwe_api/verify

Verifies a verifiable presentation (VP) token and returns a signed attestation. This endpoint requires a client certificate.

Request body

The request body is a JSON object.

FieldTypeRequiredDescription
vp_tokenstringYesThe VP token from the wallet.
statestringNoTransaction state used to look up the stored nonce and request context.
client_idstringNoRelying-party identifier used as the attestation audience.
presentation_submissionobjectNoPresentation submission. Usually absent for DCQL-based responses.

The vp_token value is a JSON string. The server accepts three presentation shapes:

  • A DCQL object whose keys are credential query identifiers and whose values are arrays of presentations.
  • An SD-JWT VC compact serialization, which contains the ~ separator.
  • A base64url-encoded mDoc DeviceResponse (CBOR).

The state field locates a stored OpenID4VP transaction. The server reads the nonce and the request context from that transaction and never from the request body. For mDoc verification the state field is required, because the server rebuilds the OpenID4VP handover from the stored context.

The client_id field is required when no stored transaction exists, for example in the same-device Digital Credentials API flow. When a stored transaction exists, the server rejects a client_id value that differs from the transaction value.

Response body

The response body is a JSON object. The server returns this shape with status 200 for both a successful and a failed verification.

FieldTypePresentDescription
successbooleanAlwaysThe verification result.
messagestringAlwaysHuman-readable result message.
attestationstringAlwaysSigned attestation JWT. See Attestations.
verification_detailsobjectAlwaysVerification breakdown. See below.
errorsarrayOn failureHuman-readable failure reasons.

The verification_details object holds three boolean fields.

FieldTypeDescription
signature_validbooleanThe presentation signature is valid.
not_expiredbooleanThe credential is within its validity period.
issuer_trustedbooleanThe issuer chain terminates at a trusted CA.

Status codes

StatusCondition
200The server processed the presentation. Check success for the result.
400The vp_token is malformed, the client_id disagrees with the transaction, the mDoc state is missing, or an mDoc check fails.
401No authenticated user is present.
500An internal failure occurred, for example a journal append failure.

Example

{
  "vp_token": "{\"proof_of_age\":[\"o2d2ZXJzaW9u...\"]}",
  "state": "f7c1a2e0-5b3d-4a9c-9f21-8d2e6b0a1c34",
  "client_id": "x509_san_dns:rp.example.com"
}
{
  "success": true,
  "message": "Credential verified successfully",
  "verification_details": {
    "signature_valid": true,
    "not_expired": true,
    "issuer_trusted": true
  },
  "attestation": "eyJhbGciOiJFUzI1NiIsImtpZCI6..."
}

POST /ewqwe_api/openid4vp/init

Starts a new OpenID4VP transaction. This endpoint requires a client certificate.

Request body

The request body is a JSON object.

FieldTypeRequiredDescription
dcql_queryobjectNoDigital Credentials Query Language query. A default age query is used when omitted.
noncestringNoRequest nonce. The server generates one when omitted.
statestringNoClient state value. The server generates one when omitted.
profilestringNoProtocol profile, haip or annex-a.
credential_typestringNoCredential shorthand: mdl, national-id, proof-of-age, or france-identite-numerique.
client_metadataobjectNoRelying-party metadata shown by the wallet.
transaction_dataarrayNoBase64url-encoded transaction data entries.

The server builds the response_uri and the request_uri from public_root_url, or from the incoming request when public_root_url is not set. See Credential verifier configuration.

Response body

FieldTypePresentDescription
transaction_idstringAlwaysIdentifier used for later status polling.
client_idstringAlwaysConstructed client identifier.
client_id_schemestringAlwaysClient identifier scheme, for example x509_san_dns.
request_uristringAlwaysURI where the wallet fetches the authorization request.
authorization_request_uristringAlwaysFull authorization request URI for a QR code or deep link.
expires_inintegerAlwaysSeconds until the transaction expires.
profilestringAlwaysSelected protocol profile.
qr_code_data_urlstringCross-deviceQR code as an image/svg+xml data URL.

Status codes

StatusCondition
200The transaction was created.
400The request body is invalid.
401No authenticated user is present.
500A configuration or internal failure occurred.

POST /ewqwe_api/openid4vp/direct_post

Receives the wallet authorization response. This endpoint does not require a client certificate.

Request body

The server accepts two content types.

For application/x-www-form-urlencoded, the server reads these form parameters.

ParameterRequiredDescription
vp_tokenFor a plain responseThe VP token.
stateFor a plain responseTransaction state echoed by the wallet.
presentation_submissionNoPresentation submission string.
responseFor a JWE response (direct_post.jwt)Encrypted authorization response.
errorFor a wallet error responseOpenID4VP error code.
error_descriptionNoHuman-readable error description.

For application/json, the server reads the same fields as a JSON object.

When the wallet sends an error parameter, the server records a wallet error and does not expect a VP token.

Response body

On success the server returns status 200, the content type application/json, and an empty JSON object {}.

Status codes

StatusCondition
200The response was stored.
400The body is malformed or the state is unknown.
404No transaction matches the state.
410The transaction has expired.
500A cryptographic, configuration, or internal failure occurred.

GET and POST /ewqwe_api/openid4vp/request/

Returns the authorization request for a transaction. The wallet fetches this URI from the request_uri value. This endpoint does not require a client certificate.

Path parameter

ParameterTypeDescription
idstringThe transaction identifier.

Response body

The response body is either a signed JAR (JWT-secured authorization request) or a plain JSON object, depending on the profile.

ProfileContent typeBody
HAIPapplication/oauth-authz-req+jwtSigned JAR JWT.
Annex Aapplication/jsonPlain authorization request JSON.

Status codes

StatusCondition
200The request is returned.
404The transaction is unknown.
410The transaction has expired.
500An internal failure occurred.

GET /ewqwe_api/openid4vp/status/

Returns the status of a transaction. This endpoint requires a client certificate.

Path parameter

ParameterTypeDescription
idstringThe transaction identifier.

Response body

FieldTypePresentDescription
statusstringAlwaysOne of pending, received, verified, error, expired.
expires_inintegerWhen pendingSeconds until expiry.
authorization_responseobjectWhen receivedThe wallet authorization response.
noncestringWhen receivedNonce from the original authorization request.
transaction_dataarrayWhen receivedTransaction data from the original request.
wallet_errorobjectWhen the wallet returned an errorWallet error code and description.
error_messagestringOn a server errorServer error description.

The authorization_response object holds vp_token, state, and an optional presentation_submission.

The status value has the meanings below.

ValueMeaning
pendingWaiting for the wallet response.
receivedWallet response received, not yet verified.
verifiedCredential verified successfully.
errorVerification or processing failed.
expiredTransaction TTL exceeded.

Status codes

StatusCondition
200The status is returned.
404The transaction is unknown.
410The transaction has expired.
500An internal failure occurred.

GET /ewqwe_api/openid4vp/.well-known/jwks.json

Returns the public JSON Web Key Set (JWKS). This endpoint does not require a client certificate.

Response body

The response content type is application/jwk-set+json. The body holds a keys array with up to two groups of keys.

KeyPresentPurpose
JAR signing keyHAIP profileLets the wallet verify the signed authorization request.
Attestation verification keyAlwaysLets the relying party verify a signed attestation JWT.

The attestation verification key is an EC P-256 key with alg set to ES256. The key carries the fields kty, crv, use, alg, kid, x, y, and x5c. The kid value is the base64url (no padding) SHA-256 fingerprint of the certificate. The same kid appears in the header of every attestation JWT.

Status codes

StatusCondition
200The key set is returned.

GET /ewqwe_api/.well-known/issuer_certs

Returns the trusted credential issuer CA certificates. This endpoint requires a client certificate.

Query parameters

ParameterTypeDefaultDescription
cert_pembooleanfalseInclude the PEM encoding of each certificate.

Response body

FieldTypeDescription
loadedbooleanThe server loaded at least one CA.
countintegerNumber of trusted CA certificates.
certsarrayOne object per CA certificate.

Each entry in certs holds these fields.

FieldTypePresentDescription
subjectstringAlwaysCertificate Subject Common Name.
issuerstringAlwaysCertificate Issuer Common Name.
not_beforestringAlwaysValidity start.
not_afterstringAlwaysValidity end.
cert_pemstringWhen cert_pem=trueCertificate in PEM encoding.

Status codes

StatusCondition
200The certificate list is returned.
401No authenticated user is present.

Journal endpoints

The journal endpoints return the append-only verification journal of the authenticated user. Each endpoint requires a client certificate, and the authenticated username must match the {username} path parameter. When the journal is disabled, the journal store is absent and a request to these paths returns an internal server error.

See the Verification journal page for the entry schema.

GET /ewqwe_api/journal/{username}/entries

Returns the recent journal entries of the user, newest first, as human-readable views.

Query parameterTypeDefaultDescription
limitinteger20Maximum entries. The server caps the value at 1000.
beforestring—Return entries created strictly before this RFC 3339 timestamp.
afterstring—Return entries created strictly after this RFC 3339 timestamp.

Each entry holds these fields.

FieldTypeDescription
created_atstringEntry creation time in RFC 3339 format.
qrcode_app_user_emailstringEmail of the verifier app user, when present.
successbooleanWhether the verification succeeded.
claimsobjectFlattened credential claims.

GET /ewqwe_api/journal/{username}/verify

Recomputes every entry hash from the first entry and checks the chain.

FieldTypeDescription
usernamestringThe journal owner.
validbooleantrue when every hash matches.
entries_verifiedintegerNumber of entries checked.
first_entry_hashstringHash of the first entry, when present.
last_entry_hashstringHash of the current head, when present.
errorstringReason when valid is false.

GET /ewqwe_api/journal/{username}/download

Returns the matching journal entries as a JSON file. The server sets the header Content-Disposition: attachment with the file name journal_{username}.json.

Query parameterTypeDefaultDescription
beforestring—Return entries created strictly before this RFC 3339 timestamp.
afterstring—Return entries created strictly after this RFC 3339 timestamp.
limitintegerAllMaximum entries.

Unlike the /entries endpoint, the download returns the full journal entry, including the chain hash fields.

Journal status codes

StatusCondition
200The result is returned.
401No authenticated user is present, or the username does not match.
500The journal is disabled, or a storage failure occurred.

GET /version

Returns the server version. This endpoint does not require a client certificate.

Response body

FieldTypeDescription
versionstringThe compiled credential verifier version.
{
  "version": "0.1.0"
}

Status codes

StatusCondition
200The version is returned.

TLS and mutual TLS

The credential verifier serves every endpoint over TLS. A relying-party endpoint additionally requires a client certificate. This page documents the TLS parameters, the certificate formats, the client identifier, and the authentication flow.

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.
[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"

All paths are relative to the configuration file directory. See Configuration for the path resolution rule.

Protocol versions and cipher suites

When tls_cipher_suites is omitted, the server builds the listener from the Mozilla intermediate v5 profile and allows TLS 1.2 through TLS 1.3.

When tls_cipher_suites is set, the server builds the listener from the Mozilla modern v5 profile and applies the given list. The server splits the list into TLS 1.3 suites and TLS 1.2 suites.

List contentMinimum protocol version
TLS 1.3 suites onlyTLS 1.3
TLS 1.2 suites onlyTLS 1.2
Both groupsTLS 1.2

The TLS 1.3 suites that the server recognizes are TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_CCM_SHA256, and TLS_AES_128_CCM_8_SHA256.

Certificate formats

MaterialEncodingExpected header
Private keyPKCS#8 PEM-----BEGIN PRIVATE KEY-----
CertificateX.509 PEM-----BEGIN CERTIFICATE-----
CA chainConcatenated X.509 PEMOne -----BEGIN CERTIFICATE----- block per certificate, root last.

The server loads the server private key with PKey::private_key_from_pem, the server certificate with X509::from_pem, and each CA chain with X509::stack_from_pem. A file that fails to parse stops the server at startup with a configuration error.

Mutual TLS

The server always configures client certificate verification. The server builds an X.509 trust store from the client_ca_cert_chain file. When client_ca_cert_chain is absent, the server uses server_ca_chain.

The server sets the OpenSSL verify mode to PEER. In this mode the server requests a client certificate during the TLS handshake and verifies the certificate when the client presents one. The handshake still completes when the client presents no certificate. The credential verifier then enforces authentication at the application layer, so an unauthenticated request to a relying-party endpoint receives status 401.

Relying-party authentication

The server authenticates a relying party with the Common Name (CN) of the client certificate. The table below describes the authentication stages.

OrderStageAction
1TLS handshakeVerify the client certificate chain against the client CA trust store.
2Connection setupStore the peer certificate on the connection.
3SslAuthRead the CN of the peer certificate and treat the CN as the username.
4EnsureAuthRequire an authenticated username on a relying-party endpoint.
5HandlerRead the username from the request context.

The table below lists the outcomes.

ConditionResult
Valid client certificateRequest proceeds with the username set to the certificate CN.
No client certificate on a relying-party endpointStatus 401, unless disable_authentication is true.
Certificate not signed by a CA in the trust storeThe TLS handshake fails.
CN ends with *Status 401. Wildcard usernames are rejected.
Certificate has no CNStatus 401.
CN is not valid UTF-8Status 401.

Client certificates must meet these requirements:

  • The certificate is signed by a CA in the client CA trust store.
  • The Subject field contains a Common Name.
  • The certificate is within its validity period.

The CN is any UTF-8 string. The server recommends a value such as ewqwe-client-01.

Test client certificate

The included test client certificate has the Subject CN=user1.acme.com and the Issuer CN=acme.com. Use it to send a request to a relying-party endpoint during development.

The x509_san_dns client identifier

For the HAIP profile, the server builds the client_id value as x509_san_dns:<san_dns_name>. The server reads san_dns_name from the DNS subject alternative name (SAN) of the leaf certificate in openid4vp_config.haip_config.x509_cert_path. The same client_id value appears in the signed authorization request.

The wallet checks that the host part of the client_id matches the DNS SAN of the server certificate. The server certificate must therefore carry the DNS name that the wallet uses to reach the server.

The included test TLS certificate has these SAN entries: DNS:demo.ewqwe.local, DNS:localhost, and IP:127.0.0.1. With this certificate the server builds the client identifier x509_san_dns:demo.ewqwe.local.

Test certificates

Warning

Never use the test certificates in production.

The test certificates are in the certificates/ directory at the repository root.

TLS certificates

The TLS certificates are in certificates/tls/.

FilePurpose
ewqwe.server.cert.pemServer TLS certificate. CN ewqwe.acme.com.
ewqwe.server.key.pemServer TLS private key.
ewqwe.server.fullchain.pemServer leaf certificate and CA chain, used for the JAR x5c header.
ewqwe.ca.pemCA chain. The tests also use it as the client CA chain.
ewqwe.root.key.pemRoot CA private key.
ewqwe.user1.cert.pemClient certificate for mutual TLS. CN user1.acme.com.
ewqwe.user1.key.pemClient private key that matches ewqwe.user1.cert.pem.
ewqwe.user2.cert.pemA second client certificate.

The server certificate carries the SAN entries DNS:demo.ewqwe.local, DNS:localhost, and IP:127.0.0.1.

Attestation signing certificates

The attestation signing certificates are in certificates/signer/.

FilePurpose
ewqwe.signer.leaf.cert.pemAttestation issuer certificate. CN ewqwe.acme.com.
ewqwe.signer.leaf.key.pemAttestation issuer private key.
ewqwe.signer.leaf.fullchain.pemAttestation issuer certificate and CA chain.
ewqwe.signer.ca.pemAttestation issuer CA certificate.
ewqwe.signer.ca.key.pemAttestation issuer CA private key.

Credential issuer CA certificates

The trusted credential issuer CA certificates are in certificates/issuers_cas/. The directory holds the age-verification issuer CA, the EU PID issuer CA, and public root CAs such as dc4eu.pem, isrg_root_x1.pem, and isrg_root_x2.pem.

Disabling authentication

The disable_authentication key turns off the client certificate requirement. When the value is true, the EnsureAuth middleware inserts disabled_authentication_user as the authenticated username on every request that has no certificate. The default username is test.

Warning

The disable_authentication = true setting removes authentication from every relying-party endpoint. Use it only for local development and tests.

Attestations

The credential verifier returns a signed attestation after it processes a presentation. This page documents the attestation format, the signing algorithms, and every claim.

Purpose

An attestation is the verifier’s signed statement about a verification event. It records the verification result, the credential metadata, and the verified credential claims. The relying party verifies the attestation signature and then reads the claims it needs.

JWT format

The POST /ewqwe_api/verify endpoint returns the attestation in the attestation field of its response. See the HTTP API page for the full response.

The attestation is a JSON Web Token (JWT) in compact serialization. It has three dot-separated parts: a header, a payload, and a signature.

Header parameterValue
algES256
kidBase64url (no padding) SHA-256 fingerprint of the signing certificate DER.

The kid value matches the kid of the attestation verification key in the published JSON Web Key Set (JWKS). The relying party uses this value to select the correct key.

Claims

ClaimTypePresentDescription
issstringAlwaysIssuer. The Subject Common Name (CN) of the attestation issuer certificate.
substringAlwaysSubject. The transaction identifier that triggered the attestation.
audstringAlwaysAudience. The relying-party client_id.
iatintegerAlwaysIssued-at time as a Unix timestamp.
expintegerAlwaysExpiration time as a Unix timestamp.
nbfintegerAlwaysNot-before time as a Unix timestamp.
jtistringAlwaysUnique attestation identifier in UUIDv4 format.
verifiedbooleanAlwaysThe verification outcome.
noncestringOptionalThe nonce from the request.
doc_typestringOptionalThe credential document type, for example org.iso.18013.5.1.mDL.
namespacestringOptionalThe credential namespace, for example org.iso.18013.5.1.
credential claimsvariesOptionalThe verified credential claims, flattened into the payload.

The credential claims are not fixed fields. The server flattens the verified claims of the presentation into the top level of the payload. A relying party reads a claim such as age_over_18 or given_name directly from the payload.

When the request carries no transaction, the server generates a fresh UUID for the sub claim. The nonce claim is present when the presentation or the stored transaction provides a nonce.

Note

The server returns an attestation in both the success and the failure response of POST /ewqwe_api/verify. Treat the success field of the response as the authoritative verification result.

Validity

ClaimValue
iatThe time the server signs the attestation.
expiat plus 300 seconds.
nbfiat minus 5 seconds.

The 5-second allowance before iat absorbs clock skew between the server and the relying party.

Example payload

{
  "iss": "ewqwe.acme.com",
  "sub": "f7c1a2e0-5b3d-4a9c-9f21-8d2e6b0a1c34",
  "aud": "x509_san_dns:rp.example.com",
  "exp": 1770000300,
  "iat": 1770000000,
  "nbf": 1769999995,
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  "verified": true,
  "nonce": "8f14e45fceea167a5a36dedd4bea2543",
  "doc_type": "eu.europa.ec.av.1",
  "namespace": "eu.europa.ec.av.1",
  "age_over_18": true
}

COSE and CBOR format

The library also supports a CBOR-based attestation that has the same claim set. The format is a COSE_Sign1 structure as defined by RFC 8152.

PartContent
Protected headerThe alg identifier and an optional key identifier.
PayloadThe CBOR serialization of the attestation claims.
SignatureThe signature over the Sig_structure of the COSE_Sign1 structure.

The ECDSA signature uses the fixed-length format of COSE: the r and s values, each 32 bytes for the P-256 curve. The RSA signature uses PKCS#1 v1.5 with SHA-256.

A verifier parses the CBOR bytes, rebuilds the Sig_structure, checks the signature with the public key, and then deserializes the payload into the claim set.

Signing algorithms

The table below lists the algorithms of the two signer types.

FormatAlgorithmIdentifierDescription
JWTES256ES256ECDSA with the P-256 curve and SHA-256.
JWTRS256RS256RSA PKCS#1 v1.5 with SHA-256.
COSEES256-7ECDSA with the P-256 curve and SHA-256.
COSERS256-257RSA PKCS#1 v1.5 with SHA-256.

The POST /ewqwe_api/verify endpoint signs the attestation with ES256.

Signing keys

SettingRole
attestation_issuer_certificateThe PEM certificate. Its CN becomes iss, and its public key verifies the attestation.
attestation_issuer_keyThe PEM private key that signs the attestation.

When both settings are omitted, the server uses tls_params.server_certificate and tls_params.server_private_key. See Configuration for the defaults.

The server reads the private key from disk for each signature operation.

Verification by the relying party

The relying party verifies an attestation against these checks.

CheckAction
Key retrievalFetch the JSON Web Key Set from GET /ewqwe_api/openid4vp/.well-known/jwks.json.
Key selectionSelect the key whose kid matches the kid of the JWT header.
SignatureVerify the JWT signature with the public key of that key.
AudienceCompare the aud claim with the relying-party identifier.
Validity windowCompare the exp and nbf claims with the current time.
Claim extractionRead the credential claims from the payload.

The JWKS endpoint returns the attestation key as an EC P-256 key with alg set to ES256. The key includes the x5c certificate chain, so a relying party can also verify the key against a trusted certificate.

Verification journal

The verification journal is an append-only record of every successful verification. This page documents its purpose, its hash chain, its storage backends, its configuration, and its HTTP API.

Purpose

The journal gives each authenticated user a tamper-evident audit log of the credentials that the verifier accepted. The journal has these properties:

  • Non-repudiation: the journal records every accepted verification.
  • Tamper detection: a change to any entry breaks the hash chain.
  • Per-user scoping: each username has an independent chain.
  • Access control: a user can read only the user’s own journal over mutual TLS.

The server records an entry after a successful verification. A failed verification does not produce an entry.

Hash chaining

Each entry stores a hash that links it to the previous entry in the same user chain. The server computes two hashes.

attestation_signature_hash = hex(SHA-256(attestation_jwt_bytes))
entry_hash                 = hex(SHA-256(username_bytes || previous_hash_bytes || attestation_signature_hash_bytes))

The definitions of the two values are:

ValueInput
attestation_signature_hashThe raw bytes of the attestation JWT.
entry_hashThe username bytes, then the previous hash bytes, then the attestation hash bytes.

The server includes the username in the entry_hash input, so the hash of an entry is bound to its owner. This binding prevents a hash collision between two different users.

For the first entry of a chain, the previous_hash value is absent and the server substitutes an empty byte sequence.

When an entry has no signed attestation, for example a verifier app entry, the server substitutes the string qr:<username>:<entry_id> for the JWT bytes. This substitution keeps the attestation_signature_hash unique across users.

All hashes use SHA-256 and are stored as lowercase hexadecimal strings.

Storage backends

The backend key of the [journal_config] table selects the backend.

BackendPersistenceMulti-instanceNotes
sqlite_memoryNoNoDefault. Useful for development and tests.
sqlite_fileYesNoSingle instance with persistence.
postgresYesYesRecommended for high-availability deployments.

The SQLite backend creates the tables journal_entries and journal_heads. The tables include a unique index on entry_hash and an index on (username, created_at).

Concurrent append behaviour

The server appends with an optimistic compare-and-swap (CAS) on the per-user chain head. An append performs these operations in order.

OrderOperation
1Read the current head hash for the username.
2Compute the entry hash from that head.
3Append the entry, but only when the stored head still matches the value read in operation 1.

Each backend serializes the read-check-write section.

BackendSerialization
SQLiteA process-level mutex, held across an exclusive database transaction.
PostgreSQLA SELECT ... FOR UPDATE row lock inside a database transaction.

When a concurrent writer changes the head first, the append detects a stale head and retries. The server retries up to 5 times. When the retries are exhausted, the append fails with a hard error and the server reports the failure. The server does not silently drop an entry, because a missing entry would break the audit chain.

Configuration

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

KeyTypeRequiredDefaultDescription
enabledbooleanNofalseTurn journaling on or off.
backendstringNosqlite_memoryStorage backend.
pathstringFor sqlite_file—Filesystem path to the SQLite journal file.
urlstringFor postgres—PostgreSQL connection URL.

The example below enables journaling with the SQLite file backend.

[journal_config]
enabled = true
backend = "sqlite_file"
path    = "/var/lib/ewqwe/journal.db"

The example below enables journaling with the PostgreSQL backend.

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

The path value is relative to the configuration file directory. See Configuration for the path resolution rule.

Entry schema

The table below documents a full journal entry. The /download endpoint returns this shape.

FieldTypeDescription
idstringSurrogate primary key in UUIDv4 format.
usernamestringAuthenticated username. The Common Name of the client certificate.
previous_hashstringHash of the preceding entry. Absent for the first entry.
entry_hashstringChain hash of this entry, hex-encoded SHA-256.
attestation_signature_hashstringSHA-256 of the raw attestation JWT bytes, hex-encoded.
attestation_jtistringThe jti claim of the signed attestation.
client_idstringThe relying-party client_id bound to the verification.
doc_typestringCredential document type, for example org.iso.18013.5.1.mDL.
namespacestringCredential namespace, for example org.iso.18013.5.1.
qrcode_app_user_idstringVerifier app user identifier, when the verifier app started the verification.
qrcode_app_user_emailstringVerifier app user email, when the verifier app started the verification.
verification_summaryobjectJSON summary of the verification outcome.
created_atstringCreation time in RFC 3339 format, in UTC.

The verification_summary object holds the success boolean and the credential_claims object.

The /entries endpoint returns a smaller, human-readable view instead of the full entry. See the HTTP API page for the view fields and the query parameters.

Journal HTTP API

All journal endpoints start with /ewqwe_api/journal/{username}. Each endpoint requires a client certificate, and the authenticated username must equal the {username} path parameter.

MethodPathDescription
GET/ewqwe_api/journal/{username}/entriesList recent entries, newest first.
GET/ewqwe_api/journal/{username}/verifyVerify the full chain integrity.
GET/ewqwe_api/journal/{username}/downloadDownload entries as a JSON file.

The HTTP API page documents the query parameters, the response bodies, and the status codes of each endpoint.

When the journal is disabled, the journal store is absent and a request to these paths returns an internal server error.

Chain verification

The /verify endpoint recomputes every entry_hash from the first entry and compares the result with the stored values. The response holds these fields.

FieldTypeDescription
usernamestringThe journal owner.
validbooleantrue when every entry verifies from the first entry to the head.
entries_verifiedintegerNumber of entries that the server checked.
first_entry_hashstringHash of the first entry, when present.
last_entry_hashstringHash of the current head, when present.
errorstringHuman-readable reason when valid is false.

The verifier app

The verifier app is a web application that the credential verifier serves. It gives an operator a browser interface to start credential verification transactions and to read their results. The app has two parts: a single-page application (SPA) and a JSON API. The credential verifier serves the SPA from the root URL (/) and mounts the JSON API under /api/v1.

An operator signs in, selects a credential type, and shows a QR code. The holder scans the QR code with a wallet. The wallet sends a verifiable presentation to the credential verifier. A verifiable presentation is a signed set of credential claims that the holder chooses to share. The verifier app polls the transaction and shows the result.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
flowchart LR
    subgraph ACTORS["Operator and holder"]
        direction TB
        SP1[" "]
        OPE["Operator browser"]
        WAL["Wallet app"]
        SP1 ~~~ OPE
    end
    subgraph VA["Verifier app routes"]
        direction TB
        SP2[" "]
        SPA["SPA served from the root URL"]
        API["JSON API under /api/v1"]
        SP2 ~~~ SPA
    end
    subgraph CV["Credential verifier"]
        direction TB
        SP3[" "]
        OID["OpenID4VP service under /ewqwe_api"]
        SP3 ~~~ OID
    end
    OPE --> SPA
    OPE --> API
    API --> OID
    WAL --> OID
    OID --> WAL
    classDef cExt fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a;
    classDef cMgmt fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af;
    classDef cCtrl fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e;
    class OPE,WAL cExt;
    class SPA,API cMgmt;
    class OID cCtrl;
    style SP1 fill:none,stroke:none
    style SP2 fill:none,stroke:none
    style SP3 fill:none,stroke:none

Relation to the credential verifier

The verifier app runs inside the credential verifier process. The crate crates/ewqwe-credential-verifier-ui/ holds the routes, the user store, the locale files, and the SPA sources. The credential verifier:

  • mounts the app routes under the /api/v1 scope;
  • serves the SPA from the directory named by ui_dist_path;
  • shares its OpenID4VP service with the app, so that the app can start wallet transactions;
  • writes journal entries for successful verifications.

The app is disabled when the [verifier_ui] section is absent from the server configuration file. When the section is present, the app is enabled unless enabled = false. When the app is disabled, every /api/v1 route returns 404 and the server does not serve the SPA. See Credential verifier configuration.

HTTP routes

All routes use JSON request and response bodies. A POST or PUT request must send Content-Type: application/json. Sessions use an HttpOnly cookie named verifier_ui_session. In the table, {id} is a transaction identifier or a user identifier, depending on the route.

MethodPathAccessDescription
GET/api/v1/setup/statuspublicReport whether the first administrator exists.
POST/api/v1/setup/bootstrappublicCreate the first administrator account.
POST/api/v1/auth/loginpublicSign in and set the session cookie.
POST/api/v1/auth/logoutsessionEnd the session.
GET/api/v1/auth/mesessionReturn the signed-in user profile.
GET/api/v1/settingspublicReturn the app name, the logo URL, and the allowed types.
POST/api/v1/qr/generatesessionStart a transaction and return a QR code.
GET/api/v1/qr/{id}/statussessionReturn the status of a transaction.
GET/api/v1/admin/usersadminList user accounts.
POST/api/v1/admin/usersadminCreate a user account.
PUT/api/v1/admin/users/{id}adminUpdate a user account.
DELETE/api/v1/admin/users/{id}adminDelete a user account.
GET/api/v1/admin/journaladminList journal entries for the app users.
PUT/api/v1/admin/settingsadminUpdate the display settings.
GET/api/v1/i18npublicReturn locale strings for one language.
GET/publicServe the SPA entry page.
GET/assets/*publicServe the bundled JavaScript and CSS assets.
GET/logo.pngpublicServe the logo image.

Start a transaction

POST /api/v1/qr/generate accepts an optional body:

{
  "credential_type": "proof-of-age",
  "claims": ["age_over_18"]
}

The credential_type value is proof-of-age (the default), mdl, national-id, or france-identite-numerique. The claims array selects the claim names to request; an empty, absent, or null value uses the default claims of the credential type. The response contains the QR code and the identifiers that the app uses to poll the transaction:

{
  "transaction_id": "...",
  "qr_code_data_url": "data:image/svg+xml;base64,...",
  "authorization_request_uri": "av://?client_id=...&response_type=vp_token&...",
  "expires_in": 300
}

Poll a transaction

GET /api/v1/qr/{id}/status returns the transaction status:

{
  "status": "pending",
  "expires_in": 287
}
StatusMeaning
pendingThe wallet has not answered the request.
receivedThe wallet returned a presentation.
verifiedThe credential passed verification.
failedThe credential failed verification.
errorThe transaction failed with a processing error.
expiredThe transaction passed its time to live.

When the credential verifier verifies the presentation in process, a verified response also contains age_over_18 and verified_claims, and a failed response contains errors.

Configuration

The [verifier_ui] section of the server configuration file controls the app. A path resolves relative to the directory that contains the configuration file.

KeyTypeDefaultDescription
enabledbooleantrue when the section existsServe the app.
app_namestringVerifier AppDisplay name in the header.
logo_urlstringbuilt-in logoHTTPS URL or data: URL for the header logo.
qr_code_callback_urlstringpublic_root_urlBase URL for the wallet callback URIs.
allowed_credential_typesarray of stringsall typesCredential types that this server allows.
session_secretstringrandom key at startupSecret for signing session cookies.
ui_dist_pathstringnoneDirectory that holds the built SPA.
dbtablesqlite_memoryUser account store.

The allowed_credential_types value accepts proof-of-age, mdl, national-id, and france-identite-numerique. An empty list allows all types. The session_secret value must contain at least 8 characters. The server derives the cookie signing key from the value, so the same value keeps the sessions valid across restarts. When the value is absent, the server generates a random key, and every server restart ends all active sessions.

The qr_code_callback_url value overrides the public_root_url of the server. Set it only when the wallet callback must use a different URL from the rest of the server.

Database backends

The app stores user accounts in the backend named by the [verifier_ui.db] table.

BackendPersistenceExtra keysUse
sqlite_memorynonenoneDevelopment and testing.
sqlite_filefilepathA single instance with persistence.

Roles

RolePermissions
adminUser management, settings, journal, and QR codes.
verifierQR code generation and status polling.

The first account that setup/bootstrap creates is an administrator with is_superadmin = true. A superadmin cannot be deleted through the interface. A password must contain at least 12 characters.

Each user can also have a list of allowed credential types. An empty list means that the user inherits the server setting. A user restriction narrows the server setting; it never widens it.

Credential types and profiles

The credential type selects the OpenID4VP profile and the credential document type. The document type, also called the namespace, groups the claims of one credential format.

Credential typeProfileDocument type
proof-of-ageAnnex A (EU age verification)eu.europa.ec.av.1
mdlHAIPorg.iso.18013.5.1.mDL
national-idHAIPeu.europa.ec.eudi.pid.1
france-identite-numeriqueHAIPeu.europa.ec.eudi.pid.1

See Protocol modes and Credential types.

Languages

GET /api/v1/i18n?lang={code} returns the locale strings for the requested language. The app detects the browser language and uses the closest supported language. A user can override the language on the Settings page. The browser stores the preference under the key verifier_ui_lang.

CodeLanguage
enEnglish
deGerman
frFrench
itItalian
esSpanish
svSwedish
plPolish
csCzech
hrCroatian

OpenID4VP authorization request parameters

OpenID for Verifiable Presentations (OpenID4VP) is an OpenID specification that lets a relying party ask a wallet for a verifiable presentation. A verifiable presentation is a credential that the wallet presents for its holder, together with cryptographic proof that the holder approved the presentation.

The relying party encodes an OpenID4VP authorization request as a set of URL parameters. The wallet reads the parameters, asks the user for consent, and returns an authorization response. This page lists the request parameters, the client identifier schemes, the response modes, and the application link scheme. The EU Age Verification Profile fixes the value of several of these parameters.

A relying party can also send the same request to the W3C Digital Credentials API instead of a URL. For the comparison between the two protocols, see Protocol modes.

Authorization request parameters

ParameterRequiredDescriptionValue in the age verification profile
response_typeYesRequests a verifiable presentation token.vp_token
client_idYesIdentifies the relying party. The value carries a scheme prefix. See Client identifier schemes.redirect_uri: followed by the response URI
nonceYesA random value that binds the presentation to this one transaction.A fresh random string for every request
response_modeYesSelects how the wallet returns the authorization response. See Response modes.direct_post
response_uriConditionalThe endpoint that receives the wallet POST. Required when response_mode is direct_post.An HTTPS URL on the relying party
dcql_queryConditionalThe query for the credentials and claims. See DCQL queries.A DCQL JSON object
stateNoAn opaque value that correlates the response with the request.A random string, or omitted
presentation_definitionConditionalA DIF Presentation Exchange query. OpenID4VP accepts this field or dcql_query, but not both.Not used
client_metadataNoMetadata about the relying party, such as a display name and the supported presentation formats.Omitted
scopeNoOpenID Connect scopes.Not used
redirect_uriNoA fallback redirect after the response is delivered.Not used with direct_post

Either presentation_definition or dcql_query must be present, but not both. The EU Age Verification Profile requires dcql_query.

Note

The nonce and state values are 22-character base64url strings in this system. They carry 128 bits of entropy, which is equivalent to a UUID version 4, and the specification does not require the UUID format.

Client identifier schemes

The client_id parameter starts with a scheme prefix. The prefix tells the wallet how to interpret the identifier and how much trust to place in it. Different profiles require different schemes.

SchemeIdentifier formatSigned requestTrust mechanismProfile
redirect_uri:The prefix plus the response URI, for example redirect_uri:https://rp.example.com/callback.NoTLS and the web PKIEU Age Verification Profile (Annex A)
x509_san_dns:The prefix plus a DNS name, for example x509_san_dns:rp.example.com.Yes, a JAR signed with an x5c headerThe DNS subject alternative name of a certificateHAIP (EUDI Wallet)
x509_hash:The prefix plus a certificate hash.Yes, a JAR signed with an x5c headerThe hash of an X.509 certificateHAIP (EUDI Wallet)
verifier_attestation:The prefix plus an attested identifier, for example verifier_attestation:my-verifier.Yes, a JAR signed with a jwt headerA JWT from a trusted attestation issuerHAIP (optional)
No prefix (pre-registered)The identifier alone.OptionalPre-configured in the walletCustom deployment

The redirect_uri scheme

The client_id value equals the response_uri, as in client_id=redirect_uri:https://rp.example.com/ewqwe_api/openid4vp/direct_post. The request is unsigned. It carries no JWT-secured authorization request (JAR), no x5c header, and no cryptographic verification. Trust rests on TLS and the web PKI. This scheme is the simplest to implement and is the one that the EU Age Verification Profile mandates.

The x509_san_dns scheme

The client_id value is a DNS name that matches a subject alternative name (SAN) in an X.509 certificate, as in client_id=x509_san_dns:rp.example.com. The request must be signed as a JAR (RFC 9101), and the x5c JOSE header carries the certificate chain. The wallet validates the certificate against its reader trust store, so the root certificate authority of the relying party must be trusted by the wallet.

Other schemes

The x509_hash scheme identifies the relying party by the hash of its certificate instead of by a DNS name. The verifier_attestation scheme identifies the relying party by an identifier that a trusted attestation issuer attests. The verifier_attestation scheme needs a published trust framework with designated attestation issuers, and no such framework exists for general age verification. The pre-registered scheme uses a plain identifier that the wallet holds in its configuration.

Response modes

The response_mode parameter selects how the wallet returns the authorization response.

ModeDescriptionUse
fragmentThe wallet returns the VP token in the URL fragment.Same-device flows. Not used by the age verification profile.
direct_postThe wallet posts the VP token to the response_uri.Cross-device flows. Required by the age verification profile.
direct_post.jwtThe wallet posts an encrypted JWT to the response_uri.Optional privacy extension. Used by HAIP.

The relying party builds the request URL with the av:// scheme for a same-device flow. The operating system opens the age verification application that registered the scheme. The wallet then returns the response through direct_post, which is a separate HTTP POST to the response_uri.

Complete example authorization request

The following URL is a complete authorization request for a same-device flow. All parameters appear by value in the URL.

av://?response_type=vp_token&response_mode=direct_post&client_id=redirect_uri%3Ahttps%3A%2F%2Frp.example.com%2Fewqwe_api%2Fopenid4vp%2Fdirect_post&response_uri=https%3A%2F%2Frp.example.com%2Fewqwe_api%2Fopenid4vp%2Fdirect_post&nonce=tMQ3X8j5LwnKpZiHvRqCaA&state=A7kB2mN9xYzL4pWqRsGtUj&dcql_query=%7B%22credentials%22%3A%5B%7B%22id%22%3A%22eu_av_proof%22%2C%22format%22%3A%22mso_mdoc%22%2C%22meta%22%3A%7B%22doctype_value%22%3A%22eu.europa.ec.av.1%22%7D%2C%22claims%22%3A%5B%7B%22path%22%3A%5B%22eu.europa.ec.av.1%22%2C%22age_over_18%22%5D%7D%5D%7D%5D%7D

The same request, with the parameters decoded:

ParameterDecoded value
response_typevp_token
response_modedirect_post
client_idredirect_uri:https://rp.example.com/ewqwe_api/openid4vp/direct_post
response_urihttps://rp.example.com/ewqwe_api/openid4vp/direct_post
noncetMQ3X8j5LwnKpZiHvRqCaA
stateA7kB2mN9xYzL4pWqRsGtUj
dcql_queryThe JSON object shown below

The decoded dcql_query value:

{
  "credentials": [
    {
      "id": "eu_av_proof",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_18"]
        }
      ]
    }
  ]
}

Authorization response parameters

The wallet sends the authorization response to the response_uri as an application/x-www-form-urlencoded body.

ParameterRequiredDescription
vp_tokenYesCarries the verifiable presentation. With a DCQL query, the token is a JSON object whose keys are credential identifiers and whose values are arrays of presentations.
presentation_submissionNoMaps the presentation to the request. The wallet does not send this field with a DCQL query.
stateNoAn echo of the state value from the request.

DCQL queries

The Digital Credentials Query Language (DCQL) is defined in Section 6 of the OpenID4VP 1.0 specification. A relying party uses DCQL to state which credentials and which claims it requires from a wallet. The credential verifier evaluates the query against the presentations that the wallet returns.

A DCQL query is a JSON object. The query travels in the dcql_query parameter of an authorization request. For the surrounding request parameters, see OpenID4VP authorization request parameters.

Query structure

A query holds one or more credential queries. The fields below belong to two nested objects. A credential query holds id, format, meta, claims, and the optional claim_sets. A claim query holds path, values, and the optional id and intent_to_retain.

FieldRequiredDescription
credentialsYesThe list of credential queries.
credential_setsNoGroups of alternative credential queries. The wallet satisfies the query when it can satisfy one complete option.
idYesThe identifier of one credential query. The authorization response uses this identifier as a key.
formatYesThe credential format. Age verification uses mso_mdoc, which means an ISO mobile document such as a mobile driving licence or a proof of age.
metaYes for mso_mdocFormat-specific metadata. An mso_mdoc query names the document type in doctype_value.
claimsYesThe claims to request from the credential.
claim_setsNoAlternative combinations of claims. A claim query needs an id only when a claim_sets entry references it.
pathYesThe location of one claim. The first element is the namespace and the second element is the claim name.
valuesNoThe permitted values for a claim. The wallet returns the claim only when its value appears in this list.
intent_to_retainNoWhether the relying party intends to keep the claim. The field is omitted in this system, which is equivalent to false, the safe default.

Namespaces

A claim path starts with the namespace of the credential. Age verification uses two namespaces.

NamespaceDescriptionDocument type
eu.europa.ec.av.1The EU Age Verification namespace (proof of age).eu.europa.ec.av.1
org.iso.18013.5.1The ISO mobile driving licence namespace.org.iso.18013.5.1.mDL

Age verification query examples

Minimal age over 18

The simplest age verification request asks only for age_over_18 from a proof of age.

{
  "credentials": [
    {
      "id": "proof_of_age",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_18"]
        }
      ]
    }
  ]
}

Age over 21

For a jurisdiction that requires age 21 or older, request age_over_21 instead.

{
  "credentials": [
    {
      "id": "proof_of_age",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_21"]
        }
      ]
    }
  ]
}

Value matching

Add a values list to accept the claim only when its value matches. The example below accepts the presentation only when age_over_18 is true.

{
  "credentials": [
    {
      "id": "proof_of_age",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_18"],
          "values": [true]
        }
      ]
    }
  ]
}

mDL fallback

If the user holds a mobile driving licence instead of a proof of age, request the same claim from the ISO mobile driving licence namespace.

{
  "credentials": [
    {
      "id": "age_from_mdl",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "org.iso.18013.5.1.mDL"
      },
      "claims": [
        {
          "path": ["org.iso.18013.5.1", "age_over_18"]
        }
      ]
    }
  ]
}

Multiple credential options

A credential_sets list lets the wallet choose between alternatives. Each option is an array of credential identifiers, and the wallet satisfies the set when it can satisfy one complete option. The example below accepts a proof of age or a mobile driving licence.

{
  "credentials": [
    {
      "id": "eu_age_proof",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "eu.europa.ec.av.1"
      },
      "claims": [
        {
          "path": ["eu.europa.ec.av.1", "age_over_18"]
        }
      ]
    },
    {
      "id": "mdl_age_proof",
      "format": "mso_mdoc",
      "meta": {
        "doctype_value": "org.iso.18013.5.1.mDL"
      },
      "claims": [
        {
          "path": ["org.iso.18013.5.1", "age_over_18"]
        }
      ]
    }
  ],
  "credential_sets": [
    {
      "options": [["eu_age_proof"], ["mdl_age_proof"]]
    }
  ]
}

The vp_token response

The wallet returns the presentation in the vp_token parameter. With a DCQL query, the token is a JSON object whose keys are the credential identifiers from the query. Each value is an array of presentations.

{
  "proof_of_age": ["base64url encoded DeviceResponse"]
}

An mso_mdoc presentation is a CBOR-encoded device response as defined in ISO/IEC 18013-5. The wallet does not send a presentation_submission field with a DCQL query.

ISO/IEC 18013-7 — mDoc online presentation

This reference covers ISO/IEC 18013-7, the standard for presenting mobile driving licences (mDLs) and generic mDocs over the internet, and its relationship with the OpenID4VP profiles used in the EUDI ecosystem.

Overview

ISO/IEC 18013-7 extends the proximity-based protocols of ISO/IEC 18013-5 to remote presentation over the internet. It defines three annexes, each with a different transport and invocation mechanism.

AnnexNameTransportWallet adoption
AREST API (device retrieval)HTTP POST with raw CBORNone of the major wallets
BOpenID4VP (online presentation)openid4vp:// URIs, direct_postAll major EUDI wallets
CW3C Digital Credentials APInavigator.credentials.get()All major EUDI wallets

Note

In the France Identité ecosystem and other national mDL deployments, “ISO 18013-7 (Annex B)” is used as an umbrella term for the entire online mDoc presentation flow. Annex C defines the ["dcapi", ...] CBOR wrapper that carries the DeviceRequest and DeviceResponse inside the browser API. It is the encoding layer, not a standalone profile.

Annex A: REST API (device retrieval)

Pure HTTP-based remote device retrieval. The verifier sends a CBOR-encoded DeviceRequest with an HTTP POST to a wallet endpoint or a proxy server, and receives a CBOR DeviceResponse in the HTTP response.

AspectDetail
InvocationHTTP POST directly to a wallet endpoint or a proxy
RequestCBOR DeviceRequest (ISO 18013-5)
ResponseCBOR DeviceResponse
EncryptionNetwork-layer session encryption (no standardised protocol)
TrustNo global trust list; the verifier authenticates over TLS
Developer effortCBOR parsing, COSE cryptography, and session key establishment at the network layer
Wallet supportNone. France Identité, EUDI Wallet DE, IT Wallet, and Spanish EUDIW do not implement Annex A

Implementation status in ewQwe: not implemented. No wallet supports Annex A.

Annex B: OpenID4VP (online presentation)

Annex B standardises mDoc presentation over the OAuth 2.0 and OpenID Connect framework. The verifier acts as an OAuth 2.0 client and builds an authorization request URI that the wallet processes.

Flow

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
sequenceDiagram
    participant RP as Relying Party
    participant Wallet as Wallet
    RP->>Wallet: openid4vp:// URI, by QR code or link
    Note over Wallet: The user selects the credential and consents to release it
    Wallet-->>RP: POST direct_post with the VP Token, optionally encrypted
    Note over RP: Validate the signatures and the nonce
    Note over RP: Read the disclosed claims
AspectDetail
InvocationUniversal or deep links (openid4vp://), request_uri fetch, or an HTTP direct_post
RequestDCQL query (JSON); the legacy Presentation Exchange format is supported as a fallback
ResponseA vp_token that carries an mDoc or an SD-JWT, optionally JWE-encrypted (direct_post.jwt)
Request signingJAR (JWT Secured Authorization Request, RFC 9101)
Trust modelThe verifier identity is proven by an X.509 certificate or by redirect URI matching
Developer effortJWT and JWE handling, DCQL evaluation, and OpenID4VP state management
Wallet supportAll major EUDI wallets

Profiles that use Annex B

Two profiles use the Annex B transport. See Protocol modes for the comparison.

Annex C: W3C Digital Credentials API (DC API)

Annex C moves the request mechanism into the client-side browser with navigator.credentials.get(). The browser and the operating system handle wallet invocation.

Flow

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
sequenceDiagram
    participant RP as Relying Party browser
    participant Wallet as Wallet at the operating system level
    RP->>Wallet: navigator.credentials.get with a digital credential request
    Note over Wallet: The user selects the credential and consents to release it
    Wallet-->>RP: Resolve with the HPKE-encrypted DeviceResponse
    Note over RP: Decrypt the response and verify the signatures
    Note over RP: Read the disclosed claims
AspectDetail
InvocationBrowser API: navigator.credentials.get({ digital: ... })
Request payload["dcapi", { nonce, recipientPublicKey }] plus a CBOR DeviceRequest
Response payloadAn HPKE-encrypted mDoc inside ["dcapi", { enc, cipherText }]
EncryptionHPKE (X25519, HKDF-SHA256, AES-128-GCM)
TransportThe browser and the operating system handle wallet invocation, including cross-device relay
Trust modelTrust is based on web origins and platform-verified app links
Developer effortLow. The browser handles wallet discovery and session binding
Wallet supportAll major EUDI wallets, which wrap the OpenID4VP request as dc_api.jwt

Annex C request format

The request is two base64url-encoded CBOR blobs.

encryptionInfo tells the wallet how to encrypt the response:

["dcapi", { nonce: bstr, recipientPublicKey: COSE_Key }]

deviceRequest states what to present, per ISO 18013-5:

{
  "version": "1.0",
  "docRequests": [{
    "docType": "eu.europa.ec.av.1",
    "itemsRequest": {
      "nameSpaces": {
        "eu.europa.ec.av.1": { "age_over_18": true }
      }
    }
  }]
}

Annex C response format

The wallet returns an HPKE-encrypted response:

["dcapi", { "enc": "<base64url>", "cipherText": "<base64url>" }]

The relying party decrypts the response with its private key and obtains the CBOR DeviceResponse.

OpenID4VP profiles

Two profiles use the Annex B transport.

  • EU Age Verification (EU-AV) blueprint — privacy-preserving age checks driven by the Digital Services Act. It uses Annex B as a fallback with the redirect_uri scheme, no JAR, and a plain direct_post. The primary method is Annex C (DC API).
  • High Assurance Interoperability Profile (HAIP) — high-security credential exchange for a PID and an mDL. It requires strict JAR signing with X.509 certificates (x509_san_dns or x509_hash) and JWE-encrypted responses (direct_post.jwt).

References

Credential formats

A digital credential is a signed set of claims about a subject, such as a person. The issuer signs the credential, the holder stores it, and the verifier checks it. A claim is a single fact, for example age_over_18. A presentation is the message that the holder sends to the verifier.

The credential verifier accepts two credential formats:

  • mso_mdoc — the format of ISO/IEC 18013-5. The format uses CBOR encoding and COSE signatures.
  • dc+sd-jwt — the SD-JWT VC format. The format uses JSON encoding and JWS signatures.

Both formats support selective disclosure (the holder reveals only some claims) and holder binding (the holder proves control of a private key). For the privacy effect of selective disclosure, see Selective disclosure.

The verifier detects the format from the presentation itself. An mDoc presentation is a Base64URL-encoded CBOR structure. An SD-JWT VC presentation contains the ~ separator character. For the types that the verifier can request, see Credential types.

Format identifiers

The two formats appear in a DCQL query with the identifiers that the table below lists.

Propertymso_mdocdc+sd-jwt
DCQL format id"mso_mdoc""dc+sd-jwt"
Type identifierdocType, a CBOR text stringvct, a URI claim
DCQL claim path[namespace, claim name][claim name]
EncodingCBOR (RFC 8949)JSON
Signature typeCOSEJWS
Algorithm idCOSE integer, for example -7 for ES256JOSE string, for example "ES256"
DCQL metadatameta.doctype_valuemeta.vct_values

mso_mdoc

The mso_mdoc format is defined in ISO/IEC 18013-5. The format is also called mDoc. The Mobile Security Object (MSO) is the signed data structure at the core of the format.

Structure

An mDoc presentation is a CBOR map called DeviceResponse. The DeviceResponse holds one or more Document entries. Each Document holds a docType value, the issuer-signed data, and the device-signed data.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
flowchart TD
    DR["DeviceResponse"]
    DR --> DOC["documents, one or more Document entries"]
    DR --> ST["status, 0 means OK"]
    DOC --> DT["docType, the credential type"]
    DOC --> IS["issuerSigned"]
    DOC --> DS["deviceSigned"]
    IS --> NS["nameSpaces, the disclosed claim values"]
    IS --> IA["issuerAuth, a COSE_Sign1 over the MSO"]
    DS --> DNS["nameSpaces, device name spaces"]
    DS --> DA["deviceAuth, the deviceSignature COSE_Sign1"]

    classDef cData fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#065f46;
    classDef cSec fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b;
    classDef cExt fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a;
    class DR,ST cExt;
    class DOC,DT,NS,DNS cData;
    class IS,IA,DS,DA cSec;

The outer structure has the following fields.

DeviceResponse = {
  "version": tstr,          ; "1.0"
  "documents": [ Document ],
  "status": 0               ; 0 means OK
}

Document = {
  "docType": tstr,          ; for example "org.iso.18013.5.1.mDL"
  "issuerSigned": IssuerSigned,
  "deviceSigned": DeviceSigned
}

Issuer-signed data

The issuerSigned field carries the issuer-authenticated data in two parts.

  • nameSpaces holds the disclosed claims as IssuerSignedItem entries.
  • issuerAuth is a COSE_Sign1 structure whose payload is the MSO.

The MSO does not contain claim values. The MSO contains one digest per claim and the public key of the device.

MobileSecurityObject = {
  "version": tstr,
  "digestAlgorithm": tstr,            ; "SHA-256"
  "valueDigests": {
    namespace => { digestID => bstr } ; one SHA-256 digest per claim
  },
  "deviceKeyInfo": { "deviceKey": COSE_Key },
  "docType": tstr,
  "validityInfo": { "signed": tdate, "validFrom": tdate, "validUntil": tdate }
}

The issuer signature is a COSE_Sign1 structure. The protected header carries the algorithm, and the unprotected header carries the issuer certificate chain in the x5chain header (label 33).

issuerAuth = [
  protected:   bstr .cbor { 1: alg },  ; for example alg = -7 (ES256)
  unprotected: { 33: [ x5chain ] },    ; issuer certificate chain
  payload:     bstr .cbor MobileSecurityObject,
  signature:   bstr
]

The x5chain header holds the issuer leaf certificate and, when present, the issuer CA certificate. The verifier checks the chain against the trusted issuer CAs. For the configuration of those CAs, see Configuration.

Disclosures

Each claim is an IssuerSignedItem. The value carries a random salt, so two encodings of the same claim value have different digests.

IssuerSignedItemBytes = #6.24(bstr .cbor IssuerSignedItem)

IssuerSignedItem = {
  "digestID": uint,           ; matches the entry in the MSO valueDigests
  "random": bstr,             ; random salt, at least 16 bytes
  "elementIdentifier": tstr,  ; claim name, for example "given_name"
  "elementValue": any         ; the claim value
}

The digest in the MSO is the SHA-256 hash of the complete IssuerSignedItemBytes encoding, including the Tag(24) wrapper:

digest = SHA-256( cbor( #6.24( bstr( cbor(IssuerSignedItem) ) ) ) )

A presentation discloses a claim when its IssuerSignedItem appears in nameSpaces. The MSO stays unchanged and signed. The verifier recomputes the digest of each disclosed item and compares the result with the matching valueDigests entry.

Key binding

The deviceSigned field proves that the presenter controls the device key that the MSO names. The field has two parts: nameSpaces, which is usually empty, and deviceAuth, which holds the deviceSignature.

DeviceSigned = {
  "nameSpaces": #6.24(bstr .cbor DeviceNameSpaces),
  "deviceAuth": { "deviceSignature": COSE_Sign1 }
}

DeviceAuthentication = [
  "DeviceAuthentication",
  SessionTranscript,       ; binds the signature to one presentation session
  DocType,
  DeviceNameSpacesBytes
]

DeviceAuthenticationBytes = #6.24(bstr .cbor DeviceAuthentication)

The deviceSignature uses DeviceAuthenticationBytes as a detached payload. The device key from deviceKeyInfo.deviceKey signs those bytes. The Tag(24) wrapper is part of the signed bytes.

For an OpenID4VP presentation, the SessionTranscript binds the presentation to the request:

SessionTranscript = [
  null,             ; DeviceEngagementBytes, absent for OpenID4VP
  null,             ; EReaderKeyBytes, absent for OpenID4VP
  OID4VPHandover
]

OID4VPHandover = [ "OpenID4VPHandover", SHA-256( cbor(OID4VPHandoverInfo) ) ]

OID4VPHandoverInfo = [
  clientId,
  nonce,
  jwkThumbprint,    ; verifier encryption key thumbprint, or null
  responseUri
]

The jwkThumbprint is present only in an encrypted response, for example direct_post.jwt. For an unencrypted response, the value is CBOR null.

Note

The verifier accepts deviceSignature. The verifier does not accept deviceMac (a COSE_Mac0 value).

Verification steps

The verifier performs the following checks for an mDoc presentation, in order.

  1. Decode the Base64URL or Base64 value to CBOR, parse the DeviceResponse, and select the first Document.
  2. Extract issuerAuth, verify the x5chain certificate chain against the trusted issuer CAs, and verify the issuer signature over the MSO payload.
  3. Parse the MSO, and check that the MSO docType matches the Document docType.
  4. For each disclosed IssuerSignedItem, recompute the digest and compare it with valueDigests[namespace][digestID].
  5. Reconstruct the SessionTranscript from client_id, nonce, response_uri, and the response mode. Build DeviceAuthenticationBytes, and verify deviceSignature with the MSO device key.
  6. Check the MSO validity window (validFrom and validUntil) against the current time.

The COSE algorithms that the verifier supports for the mDoc signatures are listed below.

COSE algorithm idNameDescription
-7ES256ECDSA with P-256 and SHA-256
-35ES384ECDSA with P-384 and SHA-384
-36ES512ECDSA with P-521 and SHA-512
-257RS256RSA with PKCS#1 v1.5 padding and SHA-256
-258RS384RSA with PKCS#1 v1.5 padding and SHA-384
-259RS512RSA with PKCS#1 v1.5 padding and SHA-512

SD-JWT VC

SD-JWT VC is the Selective Disclosure JSON Web Token format for Verifiable Credentials. The format is defined in the IETF SD-JWT VC specification.

Structure

An SD-JWT VC presentation is a single string. The issuer-signed JWT comes first. Zero or more disclosures follow, and an optional Key Binding JWT (KB-JWT) comes last. The elements are separated by the ~ character.

<issuer-signed JWT>~<disclosure 1>~<disclosure 2>~...~<KB-JWT>
%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
flowchart TD
    SJ["SD-JWT VC string"]
    SJ --> IJ["issuer-signed JWT"]
    SJ --> DIS["zero or more disclosures"]
    SJ --> KB["optional Key Binding JWT"]
    IJ --> HDR["header with alg, typ, and the x5c chain"]
    IJ --> PAY["payload with vct, cnf.jwk, and the digest array"]
    DIS --> DD["base64url array with salt, claim name, and claim value"]
    KB --> KBP["payload with nonce, aud, and sd_hash"]

    classDef cData fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#065f46;
    classDef cSec fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b;
    classDef cExt fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a;
    class SJ cExt;
    class IJ,PAY,DIS,DD cData;
    class KB,KBP,HDR cSec;

Issuer-signed data

The issuer-signed JWT is a standard JSON Web Signature. The protected header carries the algorithm, the type vc+sd-jwt, and the x5c certificate chain of the issuer.

{
  "alg": "ES256",
  "typ": "vc+sd-jwt",
  "x5c": [
    "<issuer leaf certificate, base64 DER>",
    "<issuer CA certificate, base64 DER>"
  ]
}

The payload carries the standard claims (iss, iat, exp), the credential type (vct), the holder public key (cnf.jwk), and the selective-disclosure structure. A claim that uses selective disclosure is replaced by a digest in the _sd array. A claim that does not use selective disclosure stays in the payload as clear text.

{
  "iss": "https://issuer.example.com",
  "iat": 1700000000,
  "exp": 1800000000,
  "vct": "eu.europa.ec.eudi.pid.1",
  "cnf": { "jwk": { "kty": "EC", "crv": "P-256" } },
  "_sd_alg": "sha-256",
  "_sd": ["<digest of disclosure 1>", "<digest of disclosure 2>"]
}

The verifier requires the x5c header. The verifier rejects a presentation whose issuer JWT has no x5c header.

Disclosures

A disclosure is a base64url-encoded JSON array with three elements: the salt, the claim name, and the claim value.

Disclosure = BASE64URL( JSON([ salt, claim_name, claim_value ]) )

Example, before encoding:
[ "dX23abc_SALT_VALUE", "given_name", "Elton" ]

The digest in the issuer payload is:
digest = BASE64URL( SHA-256( ASCII(Disclosure) ) )

The holder reveals a claim when the holder includes the matching disclosure in the presentation. The verifier recomputes the digest of each disclosure and compares the result with the _sd array. Nested objects use a nested _sd array inside the object.

Key binding

The KB-JWT proves that the presenter controls the private key that cnf.jwk names. The holder key signs the KB-JWT.

{
  "alg": "ES256",
  "typ": "kb+jwt"
}
.
{
  "iat": 1700000100,
  "aud": "<client_id of the verifier>",
  "nonce": "<nonce from the authorization request>",
  "sd_hash": "<BASE64URL(SHA-256(issuer-jwt ~ disclosures))>"
}
.
<holder signature>

The sd_hash binds the KB-JWT to the exact set of disclosures in the presentation. The nonce binds the presentation to one transaction, and the aud value is the client_id of the verifier.

Verification steps

The verifier performs the following checks for an SD-JWT VC presentation, in order.

  1. Split the string at each ~ character into the issuer JWT, the disclosures, and the optional KB-JWT.
  2. Read the issuer JWT header. Extract the leaf key from x5c[0], and validate the certificate chain against the trusted issuer CAs.
  3. Verify the issuer JWT signature with that key.
  4. For each presented disclosure, recompute the digest and check that it appears in the _sd array, recursively for nested objects.
  5. Verify the KB-JWT signature with the holder key from cnf.jwk.
  6. Compare the KB-JWT nonce with the nonce of the transaction, and check the validity time (exp).

Format comparison

The table below summarizes the differences between the two formats.

Propertymso_mdocdc+sd-jwt
ContainerDeviceResponseJWT and disclosures joined by ~
EncodingCBOR, binaryJSON, base64url
Issuer signatureCOSE_Sign1JWS
Issuer chain headerx5chain, label 33x5c
Selective disclosureOne salted digest per claim in the MSOOne salted digest per claim in _sd
Holder bindingdeviceSignature over the sessionKB-JWT
Session bindingSessionTranscriptnonce and aud in the KB-JWT
Credentials per presentationOne or more (documents array)One
Primary standardISO/IEC 18013-5IETF SD-JWT VC

Credential types

A credential type identifies the schema and the meaning of a set of claims. In the mso_mdoc format, the docType field names the credential type. In the SD-JWT VC format, the vct claim names the credential type. For the definition of the formats, see Credential formats.

This page describes the three credential types that are relevant to age verification, and the claims of each type.

How the verifier selects a type

The credential verifier does not hold a fixed list of allowed credential types. It verifies the type that the operator requests, provided the issuer certificate chains to a trusted issuer CA.

The operator names the requested type in one of two ways.

  • A full DCQL query in the dcql_query field of the transaction request. The query sets meta.doctype_value for mso_mdoc and meta.vct_values for SD-JWT VC.
  • A shorthand in the credential_type field of the transaction request. The verifier accepts proof-of-age, mdl, and national-id, and builds a default query for that type.

For the request fields, see Request parameters. For the query structure, see DCQL queries.

Mobile driver’s license (mDL)

The mobile driver’s license is a digital driving licence. The type uses the mso_mdoc format only. The 4th Driving Licence Regulation requires the ISO/IEC 18013-5 data model, so an mDL must not use the SD-JWT VC format.

PropertyValue
docTypeorg.iso.18013.5.1.mDL
Namespaceorg.iso.18013.5.1
Formatmso_mdoc
StandardISO/IEC 18013-5

The mDL supports the age attributes age_over_18, age_over_21, and age_over_NN for age verification. These attributes are optional.

mDL attributes

The table below lists the attributes of the org.iso.18013.5.1 namespace.

Attribute identifierDescriptionPresenceEncoding
family_nameCurrent family name or surnameMandatorytstr, UTF-8, maximum 150 chars
given_nameCurrent first name, including middle namesMandatorytstr
birth_dateDate of birthMandatoryfull-date, RFC 8943, tag 1004
portraitFacial image of the holderMandatorybstr, JPEG, ISO 19794-5
issue_dateDate of issuanceMandatorytdate or full-date
expiry_dateDate of expiryMandatorytdate or full-date
issuing_authorityAuthority that issued the documentMandatorytstr
issuing_countryCountry code, ISO 3166-1 alpha-2Mandatorytstr
document_numberUnique document identifierOptionaltstr
driving_privilegesVehicle categories and restrictionsMandatoryComplex type
un_distinguishing_signUN distinguishing sign of the issuing countryOptionaltstr
administrative_numberAdministrative number for the documentOptionaltstr
sexSex, 0 unknown, 1 male, 2 female, 9 not applicableOptionaluint
heightHeight in centimetresOptionaluint
weightWeight in kilogramsOptionaluint
eye_colourEye colourOptionaltstr
hair_colourHair colourOptionaltstr
birth_placePlace of birthOptionaltstr
resident_addressCurrent addressOptionaltstr
resident_cityCity of residenceOptionaltstr
resident_stateState or province of residenceOptionaltstr
resident_postal_codePostal codeOptionaltstr
resident_countryCountry of residence, ISO 3166-1 alpha-2Optionaltstr
age_over_18Whether the holder is over 18Optionalbool
age_over_21Whether the holder is over 21Optionalbool
age_over_NNWhether the holder is over NN yearsOptionalbool
age_in_yearsAge in yearsOptionaluint
age_birth_yearYear of birthOptionaluint
nationalityNationalityOptionaltstr

The driving_privileges attribute is an array with the following structure.

driving_privileges = [ * DrivingPrivilege ]

DrivingPrivilege = {
  "vehicle_category_code": tstr,
  ? "issue_date": full-date,
  ? "expiry_date": full-date,
  ? "codes": [ * Code ]
}

Code = {
  "code": tstr,
  ? "sign": tstr,
  ? "value": tstr
}

EUDI person identification data (PID)

Person identification data is the EU digital identity credential. The PID is available in both formats. The attributes are defined in Commission Implementing Regulation (CIR) 2024/2977 and the EU ARF PID Rulebook.

PropertyValue
docTypeeu.europa.ec.eudi.pid.1
Namespaceeu.europa.ec.eudi.pid.1
vcturn:eudi:pid:1
Formatsmso_mdoc and dc+sd-jwt
StandardCIR 2024/2977, EU ARF PID Rulebook

Mandatory attributes

Data identifierISO attribute idSD-JWT claimDescriptionEncoding (ISO)Encoding (SD-JWT)
family_namefamily_namefamily_nameCurrent surnametstrstring
given_namegiven_namegiven_nameCurrent first and middle nameststrstring
birth_datebirth_datebirthdateDate of birth, YYYY-MM-DDfull-datestring, ISO 8601-1
birth_placeplace_of_birthplace_of_birthPlace of birthplace_of_birthJSON object
nationalitynationalitynationalitiesNationality, ISO 3166-1 alpha-2nationalitiesarray of strings

Optional attributes

Data identifierSD-JWT claimDescriptionEncoding (ISO)Encoding (SD-JWT)
resident_addressaddress.formattedFull current addresststrstring
resident_countryaddress.countryCountry of residencetstrstring
resident_stateaddress.regionState or provincetstrstring
resident_cityaddress.localityCity or towntstrstring
resident_postal_codeaddress.postal_codePostal codetstrstring
resident_streetaddress.street_addressStreet nametstrstring
resident_house_numberaddress.house_numberHouse numbertstrstring
personal_administrative_numberpersonal_administrative_numberUnique PID numbertstrstring
portraitpictureFacial image, JPEG, ISO 19794-5bstrdata URL, base64
family_name_birthbirth_family_nameSurname at birthtstrstring
given_name_birthbirth_given_nameFirst name at birthtstrstring
sexsexSex, 0 to 9, see ISO 5218uintnumber
email_addressemailEmail address, RFC 5322tstrstring
mobile_phone_numberphone_numberMobile phone with country codetstrstring

Mandatory metadata

Data identifierSD-JWT claimDescription
expiry_datedate_of_expiryAdministrative expiry date
issuing_authorityissuing_authorityIssuing authority name
issuing_countryissuing_countryIssuing country, ISO 3166-1 alpha-2

Optional metadata

Data identifierSD-JWT claimDescription
document_numberdocument_numberPID document number
issuing_jurisdictionissuing_jurisdictionJurisdiction, ISO 3166-2
issuance_datedate_of_issuanceDate of issuance

The place_of_birth and nationalities attributes have the following structure in the mso_mdoc format.

place_of_birth = {
  ? "country": tstr,   ; ISO 3166-1 alpha-2 country code
  ? "region": tstr,    ; state, province, or district
  ? "locality": tstr   ; municipality, city, town, or village
}
; At least one of country, region, or locality must be present.

nationalities = [ + CountryCode ]
CountryCode = tstr     ; ISO 3166-1 alpha-2 country code

Important

The PID does not carry age attributes. The EU ARF PID Rulebook removed age_over_18 and age_over_21 in version 1.1, in line with CIR 2024/2977. For age verification, use an mDL or a Proof of Age attestation.

EU Age Verification proof of age

The proof of age attestation is the dedicated credential of the EU Age Verification Profile. The attestation carries one claim, age_over_18. The attestation holds no identity data.

PropertyValue
docTypeeu.europa.ec.av.1
Namespaceeu.europa.ec.av.1
Formatmso_mdoc only
StandardEU Age Verification Profile

The table below lists the attributes of the eu.europa.ec.av.1 namespace.

Attribute identifierDescriptionPresenceEncoding
age_over_18Whether the holder is over 18Mandatorybool

The proof of age attestation uses the following protocols.

StepProtocolDetail
IssuanceOpenID for Verifiable Credential IssuanceCredential configuration id proof_of_age
Presentation, primaryW3C Digital Credentials APIISO/IEC 18013-7 Annex C
Presentation, fallbackOpenID4VP with response_mode=direct_postAnnex A

A DCQL query that requests this attestation has the following form.

{
  "credentials": [
    {
      "id": "proof_of_age",
      "format": "mso_mdoc",
      "meta": { "doctype_value": "eu.europa.ec.av.1" },
      "claims": [{ "path": ["eu.europa.ec.av.1", "age_over_18"] }]
    }
  ]
}

Other credential types

The verifier accepts other credential types when the operator configures them. Any credential whose issuer chains to a trusted CA is verified, provided the DCQL query requests its docType or vct. For example, the relying-party example in typescript/demo-webapp/ also configures a Health ID credential, which uses the SD-JWT VC format. To request a type that is not one of the three above, supply a full dcql_query in the transaction request.

The verification process

A relying party (RP) asks the credential verifier to decide whether a presentation is trustworthy. A presentation arrives from a wallet over the network, so the verifier treats it as untrusted input and repeats every check that a security decision needs. The result of those checks is a signed attestation.

This page explains what the verifier checks, in the order in which the checks depend on each other, and why each check exists. For the exact request and response fields, see the HTTP API reference.

Why the verifier repeats the checks

The relying party cannot see inside a presentation, and the browser that hosts the relying party must not hold verification keys. The verifier therefore owns the checks and reports only the outcome. Each check answers one separate question.

QuestionCheck
Is the message well formed?Parse the VP Token.
Which claims does the holder disclose?Extract the disclosed claims.
Is the credential still valid?Compare the expiry with the current time.
Does this presentation answer this request?Bind the nonce and the request context.
Was the credential issued by a party we trust?Validate the issuer certificate chain.
Did the issuer sign this credential?Verify the issuer signature.
Does the holder control the key bound to the credential?Verify the holder binding signature.

The checks build on each other. A signature check is meaningless without the certificate chain that identifies the issuer, and the chain check is meaningless without a credential that parses. The verifier stops at the first check that fails and reports the reason.

The verifier and the surrounding components

The diagram below shows the order of the exchange during one verification. The relying party owns the wallet interaction and the verifier owns the checks.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
sequenceDiagram
    participant RP as Relying party
    participant CV as Credential verifier
    participant TS as Transaction store
    participant CA as Trusted issuer CAs
    RP->>CV: Send the VP Token with state and client_id
    CV->>TS: Read the transaction for this state
    TS-->>CV: Stored nonce, client_id, and response_uri
    CV->>CV: Parse the VP Token
    CV->>CV: Extract the disclosed claims
    CV->>CV: Compare the expiry with the current time
    CV->>CV: Bind the presentation nonce to the stored request
    CV->>CA: Validate the issuer certificate chain
    CA-->>CV: Trusted or untrusted
    CV->>CV: Verify the issuer signature
    CV->>CV: Verify the holder binding signature
    CV->>TS: Consume the transaction
    CV->>CV: Sign the attestation JWT with ES256
    CV-->>RP: Return the result and the attestation

Parsing the presentation and extracting the claims

A presentation reaches the verifier as a VP Token. The verifier accepts the DCQL response shape, in which credential query identifiers are the keys of a JSON object, and it also accepts a direct JSON presentation. Inside a DCQL entry, a value that contains a ~ separator is an SD-JWT VC, and a base64url value is an mDoc DeviceResponse in CBOR.

After parsing, the verifier reads the claims that the wallet disclosed. An SD-JWT VC carries clear-text claims in the issuer JWT payload and selectively disclosed claims in the Disclosures. An mDoc carries disclosed elements inside one or more namespaces. The verifier never sees a claim that the wallet did not disclose, which is the mechanism described in selective disclosure.

Checking the expiry

A credential can be valid at issuance and invalid at presentation. The verifier reads the exp claim of an SD-JWT VC, or the validity window of the mDoc MobileSecurityObject, and rejects the presentation when the current time falls outside that window.

Binding the nonce to the stored transaction

A recorded presentation could be sent again unless the presentation is bound to a fresh value. The verifier solves this with a nonce, which is a single-use random value.

The relying party creates a transaction before it invokes the wallet. The transaction holds the nonce, the client_id, and the response_uri that the verifier used for that specific request. When the relying party later sends the VP Token, it sends the state value, and the verifier reads the transaction for that state. The verifier compares the stored context with the proof inside the presentation:

  • For an SD-JWT VC, the wallet binds the nonce into the Key Binding JWT, and the verifier compares that nonce with the stored nonce.
  • For an mDoc, the wallet binds the request into the SessionTranscript. The verifier rebuilds the transcript from the stored client_id, nonce, and response_uri, and for encrypted responses also from the JWK thumbprint of the encryption key. The DeviceSignature then verifies against that rebuilt transcript.

The nonce never travels in the verification request body. A request that carried its own nonce could choose a value that matches a recorded presentation, so the verifier takes the nonce from its own store instead.

Some same-device flows deliver the presentation through the browser interface without a server-side transaction. In that case the verifier has no stored nonce, so it requires the client_id in the request body and uses the nonce that the presentation carries. An mDoc presentation always needs state, because the verifier cannot rebuild the session transcript without the stored request.

A successful verification consumes the stored transaction. An mDoc presentation then cannot be verified a second time, because the verifier rebuilds the session transcript from the stored request and has nothing left to rebuild it from. For an SD-JWT VC the verifier compares the stored nonce with the presentation nonce whenever a stored transaction exists; the security model states the limit of that binding.

Verifying the issuer and the holder

Two signatures protect an mDoc and an SD-JWT VC, and they prove different things. The issuer signature proves that the credential came from the named issuer. The holder binding signature proves that the party who presents the credential controls the private key that the credential names. Without the second signature, a copied credential would be as good as the original.

Credential formatIssuer checkHolder binding check
SD-JWT VCThe x5c header of the issuer JWT, missing is a rejectionThe Key Binding JWT, verified with the key in cnf.jwk
mDocThe IssuerAuth COSE_Sign1 and its x5chainThe DeviceSignature COSE_Sign1 over DeviceAuthenticationBytes

For both formats the verifier validates the certificate chain against the trusted issuer CA directory. A certificate that stops at an intermediate CA in that directory is sufficient; the chain does not have to reach a root in the directory. An mDoc must also match every disclosed element against the SHA-256 digest in the MobileSecurityObject, which proves that the disclosed value is the value the issuer signed and not a modified copy. Only the deviceSignature proof is supported; a presentation that carries deviceMac instead is rejected.

For the supported algorithms and the exact fields, see credential formats.

Signing the attestation

When all checks pass, the verifier signs an attestation, which is a JWT that states the outcome for one relying party. The attestation binds the result to the request:

  • The issuer is the common name of the attestation signing certificate.
  • The audience is the relying party client_id.
  • The subject is the transaction identifier.
  • The nonce, the credential document type, and the namespace are included when known.
  • The verified credential claims are flattened into the token, and they appear only when verification succeeded.

The verifier signs with ES256 and sets a key identifier in the token header, so the relying party can select the matching public key from the JWKS endpoint. The default validity is five minutes. For the full claim list, see attestations.

When a presentation parses but fails a check, the answer depends on the format. For an SD-JWT VC, the verifier returns an unsuccessful result together with an attestation that records the failure and carries no claims. For an mDoc, the verifier returns a request error instead, because the mDoc checks do not produce a partial result. The exact status codes are listed in the HTTP API reference.

What the relying party does next

The relying party verifies the attestation signature with the public key from the JWKS endpoint and then reads the verified claim and the credential claims. Verification is complete at that point; the relying party does not contact the wallet again. The relying party then uses the claims for its own decision, such as granting access or starting a session.

The verifier records each successful event in the verification journal when journaling is enabled.

The user journey

This page follows one person who proves an age to a website, from the first click to the result. The journey spans four parties: the user, the relying party (RP), the wallet, and the credential verifier.

A wallet is the application that stores the user’s credentials and presents them. The relying party is the website or service that needs the proof. The credential verifier is the backend service that decides whether the proof is trustworthy. A credential is a signed statement about the user, such as “this person is over 18”.

The parties and what each one owns

Each party owns a different part of the journey, and the split exists for security and for privacy.

PartyOwns
UserApproves or denies each request on the wallet.
WalletStores credentials and builds the presentation.
Relying partyDecides why it needs the proof and what to do with the result.
Credential verifierRuns the cryptographic checks and signs the result.

The user consents on the wallet, so the relying party never sees a credential that the user did not approve. The relying party never holds a verification key, so it cannot forge a result.

Two wallets and two profiles

The European Digital Identity ecosystem defines two profiles for presentation, and each profile has its own wallet implementation. The relying party chooses a profile from the wallets that it needs to support.

AspectAge Verification App (Annex A)EUDI Wallet (HAIP)
ProfileEU Age Verification ProfileHigh Assurance Interoperability Profile
Typical credentialsProof of agePersonal identity data and mobile driving licence
Client identifierThe redirect URI of the verifierA DNS name from the verifier certificate
Request signingNot requiredRequired, as a signed JWT
Response modePlain direct_postEncrypted direct_post.jwt
Trust modelThe verifier is known by its callbackThe verifier is known by its certificate

The Annex A profile is simple to integrate because the request is plain query parameters. The HAIP profile provides higher assurance because the wallet authenticates the verifier through a certificate chain. Both profiles use OpenID4VP as the exchange protocol, and the difference between them is described in protocol modes.

Same device and cross device

The protocol steps do not change with the physical arrangement of the devices. Only the way in which the wallet receives the request changes.

  • On the same device, the relying party opens a deep link that the wallet app registers, such as a link with an av:// or eudi-openid4vp:// scheme.
  • Across devices, the relying party displays a QR code, and the user scans it with the wallet on a second device.

Both arrangements return the presentation to the verifier, because the verifier owns the callback address. The Annex A profile and the HAIP profile each use their own response mode for that return.

The journey in order

The diagram shows the shared journey. The wallet interaction in the middle is the same for both profiles; the verifier decides the exact request parameters from the profile.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
sequenceDiagram
    participant User
    participant RP as Relying party
    participant Wallet
    participant CV as Credential verifier
    User->>RP: Ask to prove an age
    RP->>CV: Create a verification transaction
    CV-->>RP: Transaction identifier and authorization request
    RP->>User: Show a QR code or open a wallet link
    User->>Wallet: Read the request and approve it
    Wallet->>Wallet: Select a matching credential and disclose only the requested claims
    Wallet->>CV: Send the VP Token to the response address
    CV-->>Wallet: Acknowledge the receipt
    RP->>CV: Poll the transaction status
    CV-->>RP: The received VP Token and the transaction nonce
    RP->>CV: Send the VP Token for verification
    CV-->>RP: Signed attestation
    RP->>User: Show the result

What happens at each boundary

The relying party creates the transaction before the user acts. A transaction holds the purpose of the request, the requested claims, a fresh nonce, and the addresses that the wallet must use. The nonce makes each presentation unique, so a recorded presentation cannot be replayed.

The wallet receives the authorization request and matches it against the credentials that it stores. The wallet then shows a consent screen, and the user decides. On approval, the wallet builds a presentation that contains only the claims named in the request, signs it with the holder key, and sends it to the verifier.

The verifier receives the presentation at the callback address and stores it in the transaction. The relying party learns that the presentation arrived by polling the transaction status. The relying party then sends the presentation to the verification endpoint, and the verifier performs the checks described in the verification process.

The verifier returns a signed attestation. The relying party verifies the attestation signature, reads the outcome, and uses the claims for its own decision. The wallet is no longer involved after it sends the presentation, and the verifier consumes the transaction so the presentation is single use.

How the user experiences the journey

The user sees three things. The user sees the request, which names the relying party and the claims that the relying party wants. The user sees a consent screen from the wallet, where the user can approve or refuse. The user then sees the result from the relying party, such as a confirmation that access is granted.

The user never sees a birth date leave the wallet unless the user approves that claim. A well-formed age request asks for a derived claim such as age_over_18, so the wallet answers “true” or “false” without revealing the date of birth. This behaviour follows from selective disclosure and is a property of the credential format, not of this server.

Security model

The credential verifier makes a trust decision for a relying party. This page explains where the trust boundaries sit, why the checks live behind those boundaries, and which data the verifier handles.

A trust boundary is a line beyond which the verifier no longer trusts the input. Data that crosses a boundary is validated before it influences a decision.

The trust boundaries

Three environments take part, and the verifier trusts only the innermost one.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
flowchart TB
    subgraph Client["Client environment that the verifier does not trust"]
        direction TB
        SP1[" "]
        User["User"]
        Wallet["Wallet"]
        Browser["Browser"]
        SP1 ~~~ User
        User --> Wallet
        User --> Browser
    end
    subgraph Server["Server environment that the verifier controls"]
        direction TB
        SP2[" "]
        RP["Relying party application"]
        CV["Credential verifier"]
        TS[("Transaction store")]
        JN[("Verification journal")]
        CADIR["Trusted issuer CA directory"]
        SP2 ~~~ RP
        RP --> CV
        CV --> TS
        CV --> JN
        CV --> CADIR
    end
    Browser -->|"TLS"| RP
    RP -->|"TLS or mutual TLS"| CV
    classDef cExt fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a;
    classDef cSec fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b;
    classDef cMgmt fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af;
    classDef cData fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#065f46;
    class User,Wallet,Browser cExt;
    class RP,CV cSec;
    class TS,JN cData;
    class CADIR cMgmt;
    style SP1 fill:none,stroke:none;
    style SP2 fill:none,stroke:none;

The client environment holds the user, the wallet, and the browser. The verifier treats everything from this environment as untrusted, including a presentation that the user approved. The server environment holds the relying party, the verifier, and the stores that the verifier owns.

Why verification runs on a backend

The verifier runs the checks outside the browser for three reasons.

  • The verification keys and the CA directory must never reach the client. A key in a browser can be read by the browser’s user.
  • One service can serve many relying parties, so every relying party shares one correct implementation of the checks.
  • The audit record stays with the service, so an operator can prove which presentations were accepted.

A relying party that verified a presentation in the browser would have to trust code that the user can modify. The delegation keeps that trust inside the boundary that the operator controls.

Transport security

Every connection to the verifier uses TLS, so a network observer cannot read or modify a presentation in transit. The server certificate and the CA chain are named in the [tls_params] section of the configuration file. The full procedure is in configure TLS.

For the endpoints that a relying party calls, the verifier can also require a client certificate, which is mutual TLS. The verifier then reads the common name of the client certificate and uses it as the authenticated username. A wildcard common name is rejected, because a wildcard could match many callers. The journal uses this username to scope each chain of records to one owner.

The wallet-facing endpoints do not require a client certificate, because a wallet has no certificate from the verifier’s client CA. A wallet authenticates the verifier instead, and the HAIP profile does so through the verifier’s certificate chain.

Warning

Set disable_authentication = true only for local development and tests. That setting removes the client-certificate requirement and attributes every request to the configured user.

Replay prevention

A presentation is valid for the request that created it and for no other request. The verifier enforces this with a nonce and with single-use transactions.

The verifier stores a fresh nonce in the transaction when the relying party creates it. The wallet binds that nonce into the holder binding proof, and the verifier compares the bound nonce with the stored nonce whenever the stored transaction is present. The nonce never appears in the verification request body, because a request that supplied its own nonce could match a recorded presentation. A successful verification consumes the transaction, and an mDoc request then fails because the verifier needs the stored request to rebuild the session transcript.

The verifier also rejects a request whose client_id does not match the client_id that the stored transaction holds, when that transaction exists. That check stops a presentation from being redirected to a different relying party.

The full sequence is in the verification process.

The trusted issuer CA directory

A signature proves only that some key signed a credential. The verifier must also know which issuers it trusts. The issuers_cas_dir setting names a directory of PEM files, and the verifier loads every *.pem file in that directory at startup.

The verifier accepts a chain that terminates at any certificate in the directory, including an intermediate CA. A credential whose chain does not reach the directory is marked as untrusted, and the verifier does not accept it for an attestation.

Important

The directory is read once at startup and cached. Restart the server after you add or remove a certificate. A missing directory stops the server at startup.

Trust that is limited to a static directory has known limits. OpenID4VP defines several trust mechanisms, including ETSI Trusted Lists and OpenID Federation, and the type definitions for those mechanisms exist in the protocol crate. This server uses the static directory only, so an operator must maintain it from a trusted source.

Data minimization

The verifier handles only what the relying party asked for.

  • The asked-for claims are fixed in the request before the wallet acts, so the verifier receives disclosures that match the request.
  • The attestation carries the verified claims and nothing else.
  • The transaction store holds the wallet response only until the transaction expires or is consumed.
  • The journal stores a hash of the attestation, a summary of the outcome, and the credential metadata. It does not store the raw presentation.

The journal never leaves the boundary that the operator controls, and a client can read only its own journal. Details are in the verification journal.

Known limits

The current implementation has these limits.

  • The nonce binding for an SD-JWT VC depends on a live transaction. After the verifier consumes the transaction, no stored nonce remains for the comparison, so the verifier cannot reject a repeated SD-JWT presentation from its own state alone.
  • The verifier does not check credential revocation, so a credential that an issuer revoked is still accepted while it is otherwise valid.
  • The trusted issuer list is a static directory, not a dynamic trust source.
  • An mDoc that carries a deviceMac holder proof is rejected; only deviceSignature is supported.
  • The test certificates in the repository are for development only and must not be used in production.

Protocol modes

A relying party reaches a wallet with one of two protocols. The first protocol is the W3C Digital Credentials API, which the browser provides. The second protocol is OpenID for Verifiable Presentations (OpenID4VP), which uses plain web links and HTTP. This page explains why the system supports both protocols, how the same-device and cross-device flows differ, and how the fallback strategy selects between them.

The EU Age Verification Profile, Annex A, Section A.5, names the W3C Digital Credentials API as the primary method and OpenID4VP as the fallback. For the parameters of an OpenID4VP request, see OpenID4VP authorization request parameters.

The W3C Digital Credentials API

The W3C Digital Credentials API extends navigator.credentials.get() with support for digital identity credentials. The relying party calls the browser API, the browser mediates the request and shows a credential chooser, and the wallet returns the response inside the same page through the returned promise. The browser never stores credentials. It only mediates between the relying party and the wallet.

The request and the response use base64url-encoded CBOR, as defined by ISO/IEC 18013-7 Annex C. The wallet encrypts the response to the relying party with HPKE (RFC 9180).

The native API gives the smoothest user experience, but it has practical limits. Not all browsers implement the API. A user preference or an enterprise policy can disable it.

OpenID4VP

OpenID4VP is an OpenID specification for presentation requests. The relying party encodes the request in a URL with query parameters, a nonce, and a DCQL query. The URL uses the av:// scheme, so the operating system opens the age verification application. The wallet returns the response with an HTTP POST to the response_uri of the relying party. The response uses the direct_post response mode.

OpenID4VP works in every browser, because the operating system handles the URL scheme and the wallet posts over HTTP. It needs no browser API support. The cost is a reachable HTTPS endpoint on the relying party and a correlation step, because the response arrives in a separate HTTP request.

Comparison of the two protocols

AspectW3C Digital Credentials APIOpenID4VP
Invocationnavigator.credentials.get() with the digital optionThe av:// link scheme
Response deliveryA JavaScript promise inside the pageAn HTTP POST to the response_uri
Cross-device supportLimited, and it needs a workaroundNative, through a QR code
Browser supportChrome with a flag, limitedUniversal, because the operating system handles the link scheme
Request formatBase64url CBOR per ISO/IEC 18013-7Query parameters with a DCQL JSON query
Response formatBase64url CBOR, encrypted with HPKEA JWT or CBOR, with no encryption required
Primary use caseSame-device, browser-nativeCross-device, mobile wallets

Same-device and cross-device flows

In a same-device flow, the relying party and the wallet run on one device. The user clicks a link, the operating system opens the wallet, the user approves the presentation, the wallet posts the response, and the relying party redirects the browser to the result page.

In a cross-device flow, the relying party and the wallet run on different devices. The relying party shows a QR code that encodes the av:// URL. The user scans the code with a phone, the mobile wallet asks for consent, and the wallet posts the response to the response_uri. The device that showed the QR code learns about the completion through polling or a WebSocket connection, and then shows the result.

PropertySame-device flowCross-device flow
DevicesOne device for the relying party and the walletTwo devices, typically a desktop and a phone
InvocationThe user opens the av:// link directlyThe user scans a QR code
Response deliveryAn HTTP POST to the response_uriAn HTTP POST to the response_uri
Result notificationA redirect of the browserPolling or WebSocket on the first device

The cross-device flow is the reason for the direct_post response mode. A URL fragment cannot carry a response from a different device, but an HTTP POST to a public endpoint can.

The fallback strategy

The system attempts the native API first, because the EU Age Verification Profile names it as the primary method. When the browser does not provide the API, or when no provider is registered, the attempt fails and the system falls back to OpenID4VP.

The decision diagram below shows how the system selects a protocol and a flow.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
flowchart TD
    NEED["Relying party needs an age proof"]
    NATIVE{"Native API available with a registered provider?"}
    DC["W3C Digital Credentials API"]
    OID["OpenID4VP fallback"]
    DEVICE{"Relying party and wallet on the same device?"}
    LINK["Same-device flow: open the av link"]
    QR["Cross-device flow: show a QR code"]
    PASS["Wallet sends the verifiable presentation to the verifier"]
    DONE["Verifier checks the presentation and signs an attestation"]

    NEED --> NATIVE
    NATIVE -->|"Yes"| DC
    NATIVE -->|"No"| OID
    OID --> DEVICE
    DEVICE -->|"Yes"| LINK
    DEVICE -->|"No"| QR
    DC --> PASS
    LINK --> PASS
    QR --> PASS
    PASS --> DONE

    classDef cExt fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a;
    classDef cCtrl fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e;
    classDef cMgmt fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af;
    classDef cData fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#065f46;
    classDef cSec fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b;
    classDef cObs fill:#faf5ff,stroke:#8b5cf6,stroke-width:2px,color:#5b21b6;

    class NEED cExt;
    class NATIVE,DEVICE cCtrl;
    class DC,OID cMgmt;
    class LINK,QR cData;
    class PASS cSec;
    class DONE cObs;

The fallback is a supported path, not an error path. The EU Age Verification Profile requires the fallback whenever the native API is unavailable, and the OpenID4VP path carries the same nonce binding and the same DCQL query as the native path.

Selective disclosure

Selective disclosure lets a holder reveal a subset of the claims in a credential. The verifier still checks the issuer signature, so the verifier trusts the revealed claims as much as it trusts the whole credential.

This page explains why selective disclosure exists, how each format implements it, and what the mechanism means for privacy. For the exact data structures, see Credential formats.

Why selective disclosure is needed

A verifier usually needs one fact. An age check needs to know whether the holder is over 18. The credential that proves this fact often contains much more: a name, a birth date, a portrait, and an address.

Without selective disclosure, the holder must give the verifier the complete credential, so the verifier learns every claim. Selective disclosure separates the claims, so the holder reveals only the claims that the request needs. The signature of the issuer stays valid for the revealed subset.

How the mechanism works

Both formats use the same idea. The issuer commits to every claim at issuance with a salted hash. The salt is a random value that the issuer adds to each claim. Later, the holder reveals a claim by sending its salt and its value. The verifier rebuilds the hash and compares it with the signed commitment.

The salt has two purposes. First, two credentials with the same claim value produce different hashes. Second, a verifier cannot guess an undisclosed value, because the verifier does not know the salt.

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
flowchart TD
    subgraph ISSUE["At issuance"]
        direction TB
        SP1[" "]
        I1["The issuer salts every claim"]
        I2["The issuer computes one digest per claim"]
        I3["The issuer signs the credential with all digests"]
        SP1 ~~~ I1
        I1 --> I2
        I2 --> I3
    end

    subgraph PRESENT["At presentation"]
        direction TB
        SP2[" "]
        P1["The holder selects the claims to reveal"]
        P2["The holder sends the salt and the value of each selected claim"]
        P3["The verifier hashes each revealed claim and compares it with the signed digest"]
        SP2 ~~~ P1
        P1 --> P2
        P2 --> P3
    end

    I3 --> P1

    classDef cData fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#065f46;
    classDef cSec fill:#fef2f2,stroke:#ef4444,stroke-width:2px,color:#991b1b;
    classDef cMgmt fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af;
    class I1,I2,P1,P2 cData;
    class I3 cSec;
    class P3 cMgmt;
    style SP1 fill:none,stroke:none
    style SP2 fill:none,stroke:none

Selective disclosure in mso_mdoc

In the mso_mdoc format, the issuer signs a Mobile Security Object (MSO) that holds one digest per claim. The digest covers a structure that holds the claim name, the value, and the salt. The claim values themselves are not in the MSO.

A presentation carries one IssuerSignedItem per revealed claim. Each item holds the claim name, the value, and the salt. The MSO keeps its signature and stays unchanged. The verifier recomputes the digest of each presented item and compares it with the matching digest in the MSO.

A claim that the holder does not reveal has no IssuerSignedItem in the presentation, so the verifier never sees the value. The MSO holds only opaque digests, so the verifier learns nothing about the values that the holder did not reveal.

Selective disclosure in SD-JWT VC

In the SD-JWT VC format, the issuer puts a digest of each disclosable claim in the _sd array of the issuer JWT. The original value is removed from the payload and replaced by that digest.

A disclosure is a small base64url-encoded array that holds the salt, the claim name, and the claim value. A presentation lists the disclosures for the claims that the holder reveals. The verifier recomputes the digest of each disclosure and checks that it appears in the _sd array.

A claim that the issuer does not protect with a digest stays in the JWT payload as clear text. Such a claim is always visible to every verifier.

What it means for privacy

Selective disclosure gives the holder control over the data that a verifier receives. The following points describe the effect.

  • The verifier learns only the disclosed claims. Undisclosed claims stay hidden, including their names, because the digest hides the content.
  • The salted hashing prevents a verifier from guessing an undisclosed value. A guessed value produces a different hash unless the verifier also knows the salt.
  • The issuer signature still covers the disclosed claims, so the verifier does not need to trust the holder for the claim values.
  • Holder binding stops the replay of a stolen credential. The holder must sign the presentation with the private key that the credential names.
  • The nonce binds the presentation to one transaction, so a verifier cannot reuse a presentation later.

For age verification, the Proof of Age attestation shows the full benefit. The attestation carries only age_over_18. A verifier learns one bit of information and no identity data. An mDL can also disclose age_over_18 alone, without the birth date or the portrait, when the wallet supports selective disclosure.

Selective disclosure in the test credentials

The ewqwe_digital_credential library builds test credentials with every claim in visible form. The build_eu_age_sd_jwt and build_eudi_sd_jwt functions place claims in the issuer JWT payload as clear text and add no disclosures. The build_eudi_mdoc function places every claim in the nameSpaces of the presentation. A test credential therefore reveals all the claims that it contains. For the builder API, see Issue a test credential.

Install and run the server

This guide builds the credential verifier from source, gives it a minimal configuration, and starts it. When you finish, the server answers requests at https://127.0.0.1:9443.

Prerequisites

  • Rust 1.92.0 or later. Check with rustc --version.
  • A C toolchain, because the OpenSSL dependency is built from source.
  • A trusted issuer CA directory. The repository provides one at certificates/issuers_cas.

Steps

  1. Build the server. Run the command from the crates/ewqwe-credential-verifier-server directory.

    cd crates/ewqwe-credential-verifier-server
    cargo build --release
    

    The workspace writes the binary to target/release/ewqwe_credential_verifier_server at the repository root.

  2. Create the configuration file. Write a file named credential-server.toml in the crates/ewqwe-credential-verifier-server directory with the content below. The paths point at the test certificates in this repository, so do not use them in production.

    host_name = "127.0.0.1"
    host_port = 9443
    default_username = "demo-user"
    rust_log = "info"
    
    issuers_cas_dir = "../certificates/issuers_cas"
    attestation_issuer_certificate = "../certificates/signer/ewqwe.signer.leaf.cert.pem"
    attestation_issuer_key = "../certificates/signer/ewqwe.signer.leaf.key.pem"
    
    [tls_params]
    server_private_key = "../certificates/tls/ewqwe.server.key.pem"
    server_certificate = "../certificates/tls/ewqwe.server.cert.pem"
    server_ca_chain = "../certificates/tls/ewqwe.ca.pem"
    client_ca_cert_chain = "../certificates/tls/ewqwe.ca.pem"
    
    [openid4vp_config]
    transaction_ttl_secs = 300
    
    [openid4vp_config.haip_config]
    x509_cert_path = "../certificates/signer/ewqwe.signer.leaf.fullchain.pem"
    x509_key_path = "../certificates/signer/ewqwe.signer.leaf.key.pem"
    

    The table below explains the settings that matter at startup.

SettingPurpose
host_name, host_portThe address and port on which the server listens.
issuers_cas_dirThe directory of trusted issuer CA certificates. It must exist.
attestation_issuer_certificateThe certificate whose common name becomes the iss claim.
attestation_issuer_keyThe private key that signs the attestations.
[tls_params]The server key, certificate, CA chain, and optional client CA chain.
[openid4vp_config.haip_config]The certificate chain and key that sign authorization requests.

Every relative path in the file is resolved against the directory that contains the configuration file.

  1. Start the server. Run the built binary, or use Cargo.

    cargo run --release
    

    To use a configuration file at another location, pass its path as the first argument.

    cargo run --release -- /etc/ewqwe/credential-server.toml
    

    When you pass no path, the server searches these locations in order and uses the first file that exists.

    1. ./credential-server.toml in the current directory.
    2. The platform configuration directory: $HOME/Library/Application Support/ewQwe/Credential Server/config.toml on macOS, $XDG_CONFIG_HOME/ewQwe/Credential Server/config.toml or $HOME/.config/ewQwe/Credential Server/config.toml on Linux, and %APPDATA%\ewQwe\Credential Server\config.toml on Windows.
  2. Read the startup output. The server logs its progress when rust_log is set to info or higher.

    INFO ewqwe_credential_verifier_server: Starting ewQwe Credential Verifier
    INFO ewqwe_credential_verifier_server: Loaded configuration from /path/to/credential-server.toml
    INFO ewqwe_credential_verifier_server: Server will listen on https://127.0.0.1:9443
    INFO ewqwe_openid4vp::service: OpenID4VP service initialized san=<dns-name> ttl_secs=300
    INFO ewqwe_credential_verifier_server::server::start: Verification journal disabled
    INFO ewqwe_credential_verifier_server::server::start: Loaded credential issuer CAs at startup; restart required to reload count=<number>
    INFO ewqwe_credential_verifier_server::server::start: Attestation Provider server listening on 127.0.0.1:9443
    

    The server also logs the whole loaded configuration as one structured line at info level. If the log shows a Credentials issuers CA directory not found error, the server stops before it binds the port.

  3. Check that the server answers. The /version endpoint does not require a client certificate.

    curl -sk https://localhost:9443/version
    

    Expected output:

    { "version": "0.1.0" }
    
  4. Stop the server with Ctrl+C. The server logs Server shut down gracefully.

Troubleshooting

  • The server stops with No configuration file found. Searched: .... Create credential-server.toml in the current directory, or pass an explicit path as the first argument.
  • The server stops with Credentials issuers CA directory not found. Create the directory named by issuers_cas_dir, or point the setting at an existing directory. An empty directory is valid, but then no issuer is trusted.
  • The server stops with Failed to read server private key file or a PEM parse error. Check that each path in [tls_params] exists relative to the configuration file, and that the key is in PKCS#8 PEM format.
  • The server stops with Address already in use. Another process holds the port. Change host_port, or stop the other process.
  • The server stops while it initialises the transaction store or the journal. Check the database URL and that the database is reachable. See configure storage.
  • The server starts but ignores a setting. A misspelled key is silently ignored. Compare the key against the configuration reference.

Next steps

Configure TLS

This guide configures the TLS listener of the credential verifier and, optionally, mutual TLS. Mutual TLS means the server also requires a client certificate, so the server can identify the calling relying party.

TLS encrypts every connection. Mutual TLS adds authentication of the caller, and the verifier uses that authentication to scope the verification journal to one owner.

Prerequisites

  • A running server. See install and run the server.
  • A server private key in PKCS#8 PEM format, a server certificate in X.509 PEM format, and a CA chain as concatenated PEM certificates.
  • For mutual TLS, a CA chain that signs the client certificates of your relying parties.

Configure server TLS

  1. Prepare the three PEM files and note their paths. Each path is resolved against the directory that contains credential-server.toml.

  2. Add or edit the [tls_params] section.

    [tls_params]
    server_private_key = "../certificates/tls/ewqwe.server.key.pem"
    server_certificate = "../certificates/tls/ewqwe.server.cert.pem"
    server_ca_chain = "../certificates/tls/ewqwe.ca.pem"
    

    The table below describes each field.

FieldRequiredContent
server_private_keyYesThe server private key, in PKCS#8 PEM format.
server_certificateYesThe server certificate, in X.509 PEM format.
server_ca_chainYesThe CA chain, as one or more PEM certificates.
client_ca_cert_chainNoThe CA chain that signs client certificates, for mutual TLS.
  1. Restart the server and check the startup output.

    INFO ewqwe_credential_verifier_server: Server will listen on https://127.0.0.1:9443
    INFO ewqwe_credential_verifier_server::server::start: Attestation Provider server listening on 127.0.0.1:9443
    
  2. Test the server certificate. The /version endpoint requires no client certificate.

    curl -sk https://localhost:9443/version
    

    Expected output:

    { "version": "0.1.0" }
    

    If curl reports a certificate error rather than a JSON response, the host name in the request does not match a DNS subject alternative name of the server certificate. The test certificate provides demo.ewqwe.local, localhost, and 127.0.0.1.

Configure mutual TLS

  1. Add the client_ca_cert_chain field to [tls_params].

    [tls_params]
    server_private_key = "../certificates/tls/ewqwe.server.key.pem"
    server_certificate = "../certificates/tls/ewqwe.server.cert.pem"
    server_ca_chain = "../certificates/tls/ewqwe.ca.pem"
    client_ca_cert_chain = "../certificates/tls/ewqwe.ca.pem"
    

    When you omit client_ca_cert_chain, the server verifies client certificates against server_ca_chain instead.

  2. Restart the server. The server logs one line for each loaded client CA.

    INFO ewqwe_credential_verifier_server::tls::openssl_config: Client CA cert subject: "CN=acme.com"
    
  3. Call an endpoint that requires authentication, and present a client certificate.

    curl -sk \
      --cert certificates/tls/ewqwe.user1.cert.pem \
      --key certificates/tls/ewqwe.user1.key.pem \
      https://localhost:9443/ewqwe_api/journal/user1.acme.com/entries
    

    Expected output, when the client owns no journal entries yet:

    []
    
  4. Inspect the handshake when a call fails.

    openssl s_client -connect localhost:9443 \
      -cert certificates/tls/ewqwe.user1.cert.pem \
      -key certificates/tls/ewqwe.user1.key.pem \
      -CAfile certificates/tls/ewqwe.ca.pem -brief
    

How the verifier uses the client certificate

The verifier reads the Common Name (CN) of the client certificate and uses it as the authenticated username. The journal then uses that username to scope each entry and to check ownership.

  • Every endpoint under /ewqwe_api that a relying party calls requires a client certificate: /verify, /.well-known/issuer_certs, /openid4vp/init, /openid4vp/status/{id}, and the three journal endpoints.
  • The wallet-facing endpoints /openid4vp/direct_post, /openid4vp/request/{id}, and /openid4vp/.well-known/jwks.json require no client certificate, because a wallet has no certificate from the verifier client CA.
  • The /version endpoint requires no client certificate.

A request without a client certificate to a protected endpoint returns 401 Unauthorized. A client certificate whose CN ends with * is rejected, because a wildcard could match many callers.

Warning

The disable_authentication setting removes the client-certificate requirement. Use it only for local development and tests.

Limit the cipher suites

Set tls_cipher_suites to a colon-separated list to restrict the accepted cipher suites. When you set this field, the server enables only the listed suites and selects the TLS versions that they require. When you omit the field, the server uses the Mozilla intermediate profile with TLS 1.2 as the minimum version.

[tls_params]
server_private_key = "../certificates/tls/ewqwe.server.key.pem"
server_certificate = "../certificates/tls/ewqwe.server.cert.pem"
server_ca_chain = "../certificates/tls/ewqwe.ca.pem"
tls_cipher_suites = "TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256"

The names TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, TLS_AES_128_CCM_SHA256, and TLS_AES_128_CCM_8_SHA256 are TLS 1.3 suites. Any other name is treated as a TLS 1.2 suite.

Troubleshooting

  • curl reports a certificate verify error on /version. The host name does not match a DNS subject alternative name of the server certificate. Use a name from the certificate, or add -k for a local test.
  • The protected call returns 401 Unauthorized with the body Authentication required. The request carried no client certificate and disable_authentication is false. Pass --cert and --key, or create a client certificate from the CA.
  • The TLS handshake fails when a client certificate is presented. The client certificate is not signed by a CA in client_ca_cert_chain. Check the issuer of the client certificate.
  • The protected call returns 401 Unauthorized with a wildcard message. The client certificate has a CN that ends with *. Use a CN without a wildcard.
  • The server stops with a PEM parse error. Confirm that the key is PKCS#8 PEM (-----BEGIN PRIVATE KEY-----), that the certificate is X.509 PEM, and that the CA chain holds only PEM certificates.
  • The journal call returns 401 Unauthorized with an access-denied message. The CN of the client certificate does not equal the {username} in the path. The path must name the authenticated user.

Next steps

Configure storage

The credential verifier uses two independent stores. The transaction store holds the short-lived state of each OpenID4VP request. The verification journal is an append-only audit log of successful verifications. This guide shows how to configure both stores for your deployment.

The choice of backend depends on the deployment shape. A single server instance can use a file or an in-memory store. Several server instances that share traffic must use a shared backend, so that any instance can serve any request.

Prerequisites

  • A running server. See install and run the server.
  • For a PostgreSQL journal backend, a reachable PostgreSQL database and a connection URL.

Configure the transaction store

The transaction store keeps the nonce and the request context between the moment the relying party creates a transaction and the moment the wallet responds. Configure it under [openid4vp_config.transaction_store].

Backendbackend valuePersistenceMulti-instanceUse it for
SQLite in memorysqlite_memoryNo, lost on restartNoDevelopment and tests
SQLite filesqlite_fileYesNoA single production instance
  1. Add the backend section. The in-memory backend is the default and needs no section.

    # SQLite in memory: the default, and no section is required.
    # [openid4vp_config.transaction_store]
    # backend = "sqlite_memory"
    
    # SQLite file: a single instance that must survive a restart.
    [openid4vp_config.transaction_store]
    backend = "sqlite_file"
    path = "transactions.db"
    

    A relative SQLite path is resolved against the directory that contains the configuration file.

  2. Set the transaction lifetime. A transaction expires after this many seconds, and an expired transaction can no longer be verified. The default is 300 seconds.

    [openid4vp_config]
    transaction_ttl_secs = 300
    

    Set the value high enough for the user to complete the wallet interaction, and low enough to limit the value of a stolen VP Token. Restart the server after you change the value.

Configure the verification journal

The journal records each successful verification in a per-user chain. Every entry holds a SHA-256 hash of the attestation and a link to the previous entry, so a modification to any entry breaks the chain. The journal is disabled by default.

Backendbackend valuePersistenceMulti-instance
SQLite in memorysqlite_memoryNo, lost on restartNo
SQLite filesqlite_fileYesNo
PostgreSQLpostgresYesYes
  1. Add a [journal_config] section and set enabled = true.

    [journal_config]
    enabled = true
    backend = "sqlite_file"
    path = "journal.db"
    

    The commented alternatives below select the other backends.

    # SQLite in memory: development and smoke tests.
    # [journal_config]
    # enabled = true
    # backend = "sqlite_memory"
    
    # PostgreSQL: multi-instance deployments.
    # [journal_config]
    # enabled = true
    # backend = "postgres"
    # url     = "postgres://ewqwe:ewqwe@localhost/ewqwe"
    

    As with the transaction store, a relative path is resolved against the directory that contains the configuration file.

  2. Restart the server and check the startup output.

    INFO ewqwe_credential_verifier_server::server::start: Verification journal enabled (backend: SqliteFile { path: "/path/to/journal.db" })
    

    The server prints Verification journal disabled in place of that line when the journal is not enabled.

Read the journal through the API

The journal endpoints require mutual TLS, and a client can read only its own journal. The {username} path segment must equal the Common Name of the client certificate.

  1. List the newest entries.

    curl -sk \
      --cert certificates/tls/ewqwe.user1.cert.pem \
      --key certificates/tls/ewqwe.user1.key.pem \
      "https://localhost:9443/ewqwe_api/journal/user1.acme.com/entries?limit=20"
    
  2. Check the chain integrity.

    curl -sk \
      --cert certificates/tls/ewqwe.user1.cert.pem \
      --key certificates/tls/ewqwe.user1.key.pem \
      https://localhost:9443/ewqwe_api/journal/user1.acme.com/verify
    

    Expected output for an intact chain:

    {
      "username": "user1.acme.com",
      "valid": true,
      "entries_verified": 1,
      "first_entry_hash": "0000...",
      "last_entry_hash": "c2d9...",
      "error": null
    }
    
  3. Download the entries as a file.

    curl -sk \
      --cert certificates/tls/ewqwe.user1.cert.pem \
      --key certificates/tls/ewqwe.user1.key.pem \
      -o "journal_user1.acme.com.json" \
      "https://localhost:9443/ewqwe_api/journal/user1.acme.com/download"
    

For the entry fields and the chain formula, see the verification journal.

Troubleshooting

  • The server stops while it initialises a store. The database URL is wrong or the database is unreachable. Check the URL, the credentials, and the network path.
  • The server stops with a journal storage error on a SQLite file. The directory of path does not exist or is not writable. Create the directory, or use an absolute path.
  • A verification succeeds but the journal write fails. The response reports an error even though the checks passed. A concurrent append changed the chain head and the retries were exhausted. Retry the request, or move the journal to a backend suited to the load.
  • The journal endpoints return 401 Unauthorized. The request carried no client certificate, or the Common Name of the certificate does not match the {username} in the path.
  • The journal is empty after a restart. The sqlite_memory backend does not persist. Use sqlite_file or postgres to keep entries across restarts.
  • Several instances do not see each other’s transactions. The SQLite backends do not share state. Run one instance, or use a shared store when it is available.

Verify a credential

This guide sends a verification request to the credential verifier and reads the signed attestation that comes back. You create a transaction, let a wallet present a credential, and then ask the verifier to check the presentation.

The example uses the Annex A profile and a proof-of-age credential.

Prerequisites

Run the commands from the repository root, so that the relative certificate paths resolve.

Understand the request pattern

The verifier separates the wallet interaction from the check. You set up a transaction first, the wallet answers that transaction, and you then send the presentation for verification. Three endpoints carry the pattern:

StepEndpointWho calls itWhat it does
Create a transactionPOST /ewqwe_api/openid4vp/initRelying partyStores the nonce and the request.
Read the transactionGET /ewqwe_api/openid4vp/status/{id}Relying partyReturns the presentation from the wallet.
Verify the presentationPOST /ewqwe_api/verifyRelying partyRuns the checks and signs the attestation.

Set up shared values for the commands below.

CERT=certificates/tls/ewqwe.user1.cert.pem
KEY=certificates/tls/ewqwe.user1.key.pem
BASE=https://localhost:9443

Steps

  1. Create the transaction. The server builds the wallet callback URL from public_root_url, so that value must be reachable by the wallet and must match a DNS subject alternative name of the server certificate. The state value is yours to choose; the verifier binds it to the transaction and expects it again at verification.

    curl -sk --cert "$CERT" --key "$KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "profile": "annex-a",
        "credential_type": "proof-of-age",
        "state": "demo-state-0001"
      }' \
      "$BASE/ewqwe_api/openid4vp/init" | tee init.json
    

    Expected output:

    {
      "transaction_id": "6f1c8a2e-...",
      "client_id": "redirect_uri:https://localhost:9443/ewqwe_api/openid4vp/direct_post",
      "client_id_scheme": "redirect_uri",
      "request_uri": "https://localhost:9443/ewqwe_api/openid4vp/request/6f1c8a2e-...",
      "authorization_request_uri": "av://?client_id=...&response_type=vp_token&...",
      "expires_in": 300,
      "profile": "annex-a"
    }
    
  2. Extract the transaction values for later steps.

    TRANSACTION_ID="$(jq -r .transaction_id init.json)"
    CLIENT_ID="$(jq -r .client_id init.json)"
    
  3. Present the credential with a wallet. Give the wallet the authorization_request_uri from the previous response, as a QR code or as a deep link. The wallet sends the presentation to the verifier response_uri, and the verifier stores it in the transaction. Follow test with the EUDI wallet or test with the AV app for this step.

  4. Read the transaction status. Repeat this call until status is received.

    curl -sk --cert "$CERT" --key "$KEY" \
      "$BASE/ewqwe_api/openid4vp/status/$TRANSACTION_ID" | tee status.json
    

    Expected output when the wallet has answered:

    {
      "status": "received",
      "authorization_response": {
        "vp_token": "{\"proof_of_age\":[\"b3JnLmlzby4x...\"]}",
        "presentation_submission": null,
        "state": "demo-state-0001"
      },
      "nonce": "X9d2..."
    }
    

    The status value is pending until the wallet answers, and then received. A wallet that sends an error response instead of a presentation sets the status to error.

  5. Extract the presentation and the state.

    STATE="$(jq -r .authorization_response.state status.json)"
    VP_TOKEN="$(jq -r .authorization_response.vp_token status.json)"
    
  6. Send the presentation for verification. The state must match the transaction, and the client_id must match the value from the init response.

    jq -n --arg vp "$VP_TOKEN" --arg st "$STATE" --arg cid "$CLIENT_ID" \
      '{vp_token: $vp, presentation_submission: null, state: $st, client_id: $cid}' \
      > verify_request.json
    
    curl -sk --cert "$CERT" --key "$KEY" \
      -H "Content-Type: application/json" \
      --data @verify_request.json \
      "$BASE/ewqwe_api/verify" | tee verify_response.json
    

    Expected output when the checks pass:

    {
      "success": true,
      "message": "Credential verified successfully",
      "verification_details": {
        "signature_valid": true,
        "not_expired": true,
        "issuer_trusted": true
      },
      "attestation": "eyJhbGciOiJFUzI1NiIsImtpZCI6..."
    }
    

    Expected output when a check fails. An mDoc presentation returns HTTP 400 with the reason as a JSON string, because the verifier cannot return a partial result for an mDoc.

    "bad request: mDoc issuerAuth certificate chain is not trusted: the issuer CA is not in the trusted certificates directory"
    

    An SD-JWT VC behaves differently. The endpoint returns HTTP 200 with success false, and the attestation records the failure without the claims.

    {
      "success": false,
      "message": "Credential verification failed",
      "verification_details": {
        "signature_valid": false,
        "not_expired": true,
        "issuer_trusted": false
      },
      "attestation": "eyJhbGciOiJFUzI1NiIsImtpZCI6...",
      "errors": ["Issuer certificate does not chain to a trusted CA"]
    }
    
  7. Read the attestation. Decode the payload of the JWT to inspect the verified claims.

    ATTESTATION="$(jq -r .attestation verify_response.json)"
    
    python3 -c "import base64, json, sys; p = sys.argv[1].split('.')[1]; print(json.dumps(json.loads(base64.urlsafe_b64decode(p + '=' * (-len(p) % 4))), indent=2))" "$ATTESTATION"
    

    Expected payload for a successful proof-of-age verification. The exact values depend on the credential and the transaction.

    {
      "iss": "ewqwe.acme.com",
      "sub": "6f1c8a2e-...",
      "aud": "redirect_uri:https://localhost:9443/ewqwe_api/openid4vp/direct_post",
      "iat": 1770000000,
      "nbf": 1769999995,
      "exp": 1770000300,
      "jti": "550e8400-e29b-41d4-a716-446655440000",
      "verified": true,
      "nonce": "X9d2...",
      "doc_type": "eu.europa.ec.av.1",
      "namespace": "eu.europa.ec.av.1",
      "age_over_18": true
    }
    

    The iss claim is the common name of the attestation signing certificate. The jti claim is unique to this attestation, so you can use it as an idempotency key.

  8. Verify the attestation signature. The JWKS endpoint is public and returns the attestation key together with the kid that appears in the JWT header.

    curl -sk "$BASE/ewqwe_api/openid4vp/.well-known/jwks.json"
    

    Select the key whose kid equals the kid of the attestation, and verify the JWT signature with that key. For the claim list, see attestations.

  9. Confirm that the transaction is consumed. Send the same request body again.

    curl -sk --cert "$CERT" --key "$KEY" \
      -H "Content-Type: application/json" \
      --data @verify_request.json \
      "$BASE/ewqwe_api/verify"
    

    An mDoc presentation now returns 400 with state is required for mDoc verification, because the verifier consumed the stored transaction and no longer has the request context to rebuild the session transcript.

Troubleshooting

  • The response is 401 Unauthorized. The request carried no client certificate. Add --cert and --key.
  • The response is 404 with {"error": "..."}. The transaction id is unknown, or you created the transaction against another server instance.
  • The response is 410 Gone. The transaction exceeded transaction_ttl_secs and expired. Create a new transaction.
  • The response is 400 with client_id does not match the transaction-bound request. Send the client_id value from the init response.
  • The response is 400 with state is required for mDoc verification. An mDoc presentation needs the transaction, so include state.
  • The response is 400 with an untrusted-issuer message. The issuer CA of the credential is not in issuers_cas_dir. Add the CA file and restart the server, because the directory is read only at startup.
  • The response is 400 with a decode message. The vp_token is not a valid SD-JWT VC, mDoc DeviceResponse, or direct JSON presentation. Check that you copied the value without truncation.
  • success is false with a nonce mismatch error. The presentation does not belong to the transaction that state names. Use the vp_token and the state from the same status response.
  • The status stays pending. The wallet did not reach the response_uri. Check that the wallet can reach public_root_url and that the wallet trusts the server certificate.
  • The response is 500 and the log shows a journal error. The checks passed but the journal write failed. See configure storage.

Next steps

Develop your own relying-party UI

This guide shows how to add credential verification to a user interface of your own. The credential verifier already ships with a standard user interface, the verifier app. Build your own interface only when you need to embed verification in your own product, with your own layout and your own session.

The repository contains an example relying party in typescript/demo-webapp/. The example is an advanced, working reference that shows one way to build such an interface. It is not part of the credential verifier and is not a supported deployment.

Goal

Build a user interface that requests a credential from a wallet, sends the presentation to the credential verifier, and shows the result.

Prerequisites

Choose an interface

InterfaceUse it when
The verifier appYou want the standard interface, with no extra development.
Your own UI, with the HTTP APIYou want your own layout, integrated in your own product.
The example relying partyYou want a working reference to start from.

The verifier app is described in Run the verifier app. This guide covers the other two rows.

What your interface must do

A relying-party interface performs five steps. The credential verifier performs the cryptography; your interface drives the flow and shows the result.

  1. Start a transaction with the OpenID4VP init endpoint.
  2. Present the authorization request to the wallet. Use the W3C Digital Credentials API when the browser provides it, and the OpenID4VP redirect or QR-code flow otherwise. See Protocol modes.
  3. Receive the verifiable presentation. The wallet either posts the presentation directly, or your interface collects it and sends it to the verifier.
  4. Ask the credential verifier to verify the presentation. See Verify a credential.
  5. Show the result, which is the signed attestation that the verifier returns.

The request parameters and the DCQL query are described in OpenID4VP request parameters and DCQL queries.

The example relying party

The example lives in typescript/demo-webapp/. It uses TypeScript, Vite, and Tailwind CSS, without a front-end framework.

PathContents
typescript/demo-webapp/vite.config.tsThe Vite configuration and the reverse proxy.
typescript/demo-webapp/index.htmlThe HTML entry page.
typescript/demo-webapp/src/main.tsThe entry point that starts the application.
typescript/demo-webapp/src/relying_party_app.tsThe relying-party application logic.
typescript/demo-webapp/src/credentials.tsThe credential request and verification logic.
typescript/demo-webapp/src/dc_api_service.tsThe W3C Digital Credentials API integration.
typescript/demo-webapp/src/hpke.tsThe HPKE decryption helper for the Annex C flow.
typescript/demo-webapp/src/debug.tsThe debug helpers.
typescript/demo-webapp/package.jsonThe scripts and the dependencies.

Run the example from the TypeScript workspace root.

cd typescript
pnpm install
pnpm --filter @ewqwe/digital-identity build
pnpm --filter @ewqwe/demo-webapp dev

Open https://localhost:5174/. The Vite dev server serves the interface and forwards each /ewqwe_api/ request to the credential verifier. Vite generates a development certificate on the first run, so the browser shows a warning; accept the certificate and continue.

The Vite server reads one environment variable:

VariableDefaultPurpose
CREDENTIAL_VERIFIER_URLhttps://127.0.0.1:9443The base URL of the credential verifier.

The dev server forwards every /ewqwe_api/ request to the credential verifier, so the browser talks to one origin and no client certificate is needed in the browser. In a production deployment, terminate the client certificate at your own proxy or web server.

Incorporate verification in your own interface

Use the example as a template and keep the following points.

  1. Keep the verifier call on your backend. The browser must not hold the client certificate, and the verifier must not be reachable without one in production.
  2. Bind each request to a transaction. Never invent the nonce in the browser. Read the nonce and the state from the transaction that the verifier created, and send that state back with the presentation.
  3. Verify the attestation that the verifier returns before you trust the result. Fetch the public key from the JWKS endpoint and check the signature and the exp claim. See Attestations.
  4. Request only the claims that your product needs. An age check asks for the derived claim age_over_18, not the birth date. See Selective disclosure.
  5. Handle every status. A transaction can expire, and a presentation can fail a check.

Troubleshooting

SymptomCauseAction
The dev server cannot reach the verifierThe verifier is not running, or the URL is wrong.Start the verifier and check CREDENTIAL_VERIFIER_URL.
Every request returns 404The verifier does not serve the path.Check the base URL of the verifier.
The verifier rejects the presentationThe nonce or the state does not match.Read the nonce and the state from the stored transaction.
The browser shows a certificate warningThe development certificate is self-signed.Accept the certificate for https://localhost:5174/.

Test the credential verifier with the EUDI wallet

This guide shows how to present a mobile driving licence (mDL) or a Personal Identification Data (PID) credential to the ewQwe Credential Verifier from the EUDI Wallet. The EUDI Wallet is the reference wallet of the European Commission. Use this guide when the verifier runs the High Assurance Interoperability Profile (HAIP) and you want to test the verification path with a real wallet.

A mobile driving licence (mDL) is a digital driving licence in the ISO/IEC 18013-5 mDoc format. A Personal Identification Data (PID) credential is the EU digital identity document. A Verifiable Presentation is the data that a wallet sends to the verifier to prove claims from a stored credential. OpenID4VP is the OpenID for Verifiable Presentations protocol that the wallet and the verifier use to exchange the presentation. The credential verifier is the server that validates the presentation and returns a signed attestation.

At the end of this guide, the wallet presents the credential to the verifier, and the verifier reports the verification result.

Prerequisites

  • The credential verifier is installed and running over HTTPS. See Install and run the credential verifier and Configure TLS.
  • The verifier app is enabled on the verifier. See Run the verifier app.
  • The verifier trusts the certificate authority (CA) that issued the test credential, so that the verifier reports the issuer as trusted. See Configuration.
  • Android Studio is installed, or you have a physical Android device with Android 10 (API level 29) or higher.
  • You know the public hostname and port of the verifier. This is the public_root_url value in the verifier configuration.

How the test setup fits together

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
flowchart TB
    subgraph HOST["Verifier host"]
        direction TB
        SP1[" "]
        VERIFIER["Credential verifier on port 9443"]
        APPUI["Verifier app QR page"]
        SP1 ~~~ VERIFIER
        VERIFIER --- APPUI
    end

    subgraph DEVICE["Android emulator or device"]
        direction TB
        SP2[" "]
        WALLET["EUDI wallet with an mDL or a PID"]
        SP2 ~~~ WALLET
    end

    APPUI -->|"1- Generate a QR code"| WALLET
    WALLET -->|"2- Present the credential"| VERIFIER

    classDef cMgmt fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af;
    classDef cCtrl fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e;
    classDef cExt fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a;

    class VERIFIER cMgmt;
    class APPUI cCtrl;
    class WALLET cExt;
    style SP1 fill:none,stroke:none;
    style SP2 fill:none,stroke:none;

The verifier app generates a QR code that carries an OpenID4VP authorization request. The wallet reads the QR code, fetches the request from the verifier, and returns the credential. The verifier validates the credential and shows the result.

Step 1: Choose the client identifier scheme

The EUDI Wallet accepts only two client identifier schemes: x509_san_dns and x509_san_hash. A client identifier scheme is the rule that the wallet uses to identify the verifier. The wallet rejects the redirect_uri scheme that the EU Age Verification profile uses. To test that profile, use Test the credential verifier with the AV app instead.

SchemeHostname checkTrust method
x509_san_dnsYesCertificate chain and leaf DNS name
x509_san_hashNoSHA-256 hash of the leaf certificate

The verifier selects the scheme from its configuration. For the parameters, see Request parameters.

  • If the verifier uses the bundled ewQwe test certificates, it uses x509_san_dns with the hostname demo.ewqwe.local. The ewQwe wallet fork already trusts the ewQwe test CA. Continue with Step 2.
  • If the verifier uses your own certificate, choose x509_san_hash. With x509_san_hash, the wallet does not check the hostname, so you can skip Step 2. The wallet must still reach the verifier.

Step 2: Make the verifier reachable from the device

The wallet must reach the verifier over HTTPS. With x509_san_dns, the wallet also requires the verifier hostname to resolve on the device. The examples below use the hostname demo.ewqwe.local. Replace it with the hostname in your verifier configuration.

Option A: Android emulator

The Android emulator reaches the host machine through the special address 10.0.2.2. The ewQwe setup script in Step 3 adds this mapping automatically. To add the mapping to a running emulator manually, run:

adb root
adb shell "echo '10.0.2.2  demo.ewqwe.local' >> /etc/hosts"

Expected result: the emulator resolves demo.ewqwe.local to the host machine.

Verify the mapping with:

adb shell cat /etc/hosts

Expected result: the output lists 10.0.2.2 demo.ewqwe.local.

Option B: Physical Android device on a local network

Use dnsmasq on the machine that runs the verifier. dnsmasq is a small DNS server that answers name queries for a local network.

  1. Find the local network address of the machine that runs the verifier:

    ipconfig getifaddr en0
    # Example output: 192.168.1.42
    
  2. Install and configure dnsmasq. Replace 192.168.1.42 with the address from the previous command:

    brew install dnsmasq
    echo "address=/demo.ewqwe.local/192.168.1.42" >> /opt/homebrew/etc/dnsmasq.conf
    sudo brew services restart dnsmasq
    
  3. Verify the resolver on the same machine:

    dig @127.0.0.1 demo.ewqwe.local
    

    Expected result: the answer is the local network address.

  4. Point the Android device at this resolver. On the device, open Settings, open Wi-Fi, long-press your network, choose Modify network, open Advanced, set IP settings to Static, and set DNS 1 to the local network address.

The device needs no root access. Every device on the same Wi-Fi network that uses this resolver resolves demo.ewqwe.local correctly.

Note

If you regenerate the test certificates with a different DNS name, update the public_root_url value in the verifier configuration and use the same hostname in the DNS setup.

Step 3: Install the EUDI wallet on the emulator

Option A: Build the ewQwe fork

The ewQwe fork of the EUDI Wallet trusts the ewQwe test CA in debug builds, so it accepts requests and TLS connections from the bundled test certificates.

  1. Clone the repository:

    git clone https://github.com/bgrieder/android-eudi-haip-wallet.git
    cd android-eudi-haip-wallet
    
  2. Create and start the emulator. The script requires a rootable system image, which is a Google APIs image and not a Play Store image:

    ./start_ewqwe_eudi_emulator.sh
    

    The script installs the system image, creates an Android Virtual Device (AVD) named EUDI_Dev_Device with the Pixel 6 Pro profile, enables hardware keyboard input, starts the emulator with -writable-system, and maps demo.ewqwe.local to the host machine.

    Expected result: the emulator starts, and the Step 2 Option A mapping is already in place.

  3. In Android Studio, open the project, select the app module and the EUDI_Dev_Device emulator, and click Run.

    Expected result: the wallet installs and starts.

Option B: Install a pre-built APK

  1. Enable Developer Mode on the emulator. In Settings, open About phone, tap Build number seven times, and enter the device PIN if the device asks for it.
  2. Open Chrome on the emulator and go to the EUDI Wallet releases page.
  3. Download an APK such as app-demo-debug.apk, open the file, and tap Install.
  4. If the device asks about Install unknown apps, allow Chrome to install apps and try again.

You can also install the APK over ADB:

adb install app-demo-debug.apk

Important

The pre-built APK from the upstream project does not contain the ewQwe test CA. Use this option only when the verifier certificate chains to a CA that the stock wallet already trusts. Otherwise use Option A and add your CA in Step 4.

Step 4: Trust the verifier certificate in the wallet

Skip this step if the verifier uses the bundled ewQwe test certificates, because the ewQwe fork already trusts the ewQwe test CA.

The wallet validates the request certificate chain against a reader trust store, which is a list of trusted certificate authorities inside the wallet. Add your root CA certificate and rebuild the wallet:

  1. Copy the root CA file into the wallet resources:

    cp your-root-ca.pem resources-logic/src/main/assets/ewqwe_dev_cas/your-root-ca.pem
    
  2. Build and install the wallet:

    ./gradlew :app:installDemoDebug
    

Expected result: the wallet accepts requests that your verifier CA signs, and the error InvalidJarJwt(cause=Untrusted x5c) no longer appears.

Important

The leaf certificate of the verifier must contain the mdlReaderAuth extended key usage object identifier (OID) 1.0.18013.5.1.6, a Subject Key Identifier, and an Authority Key Identifier. The certificate must use ECDSA signing and a validity period of at most 1 187 days. A missing mdlReaderAuth OID is the most common cause of InvalidJarJwt(cause=Untrusted x5c). See Request parameters for the signing requirements.

Step 5: Load an mDL or a PID into the wallet

  1. Open the wallet and create a PIN code when the wallet asks for one.

  2. Tap the add icon (+) and choose Add a Document from List.

  3. Select the issuer https://euidw.dev and choose mDL (MSO MDOC) or PID (MSO MDOC).

  4. When the wallet asks for the country, choose Form EU.

  5. Fill in the test form, submit it, and authorize the issuance.

Expected result: the credential appears in the wallet.

Step 6: Present the credential to the verifier

  1. Open the verifier app at the public URL of the verifier and sign in.
  2. On the home page, select the credential type from the dropdown:
    • mDL requests the mobile driving licence.
    • National ID requests the PID.
  3. Click Generate QR Code.
  4. On the Android device, open the EUDI Wallet and scan the QR code.
  5. Review the authorization request in the wallet. The wallet shows the verifier name from the common name (CN) of the certificate, and a trusted badge when the certificate chain validates. Approve the request with your biometric confirmation.

Expected result: the status badge in the verifier app changes from pending to verified.

For the full set of status values and their meanings, see The verifier app.

Troubleshooting

The wallet reports InvalidJarJwt with an untrusted x5c error

The wallet does not trust the request certificate chain, or the leaf certificate does not meet the profile. Add the root CA to the reader trust store and rebuild the wallet. Confirm that the leaf certificate contains the mdlReaderAuth OID 1.0.18013.5.1.6 and that the Subject Key Identifier and Authority Key Identifier are present.

The wallet reports that the trust anchor is not found

The root CA is absent from both the reader trust store and the request certificate chain. Include the root CA in the certificate chain, and add it to the reader trust store.

The wallet cannot reach the verifier

Check the hostname mapping from Step 2, confirm that the verifier port is open in the firewall, and confirm that both devices use the same Wi-Fi network. Some access points block communication between clients, which is also known as client isolation.

The wallet rejects the request with a client identifier mismatch

With x509_san_dns, the hostname in the client_id value must equal the DNS name in the leaf certificate of the request chain and the hostname of the response_uri. Make all three hostnames equal.

The TLS handshake fails

The verifier presents a self-signed or privately rooted certificate that the wallet does not trust. Use a certificate from a publicly trusted CA, or a wallet build that trusts your CA.

Note

To inspect wallet errors, use Logcat in Android Studio and filter by the wallet package name, or run adb logcat -s OpenId4VpManager PresentationManager WalletCore.

Next steps

Test the credential verifier with the AV app

This guide shows how to present a Proof of Age to the ewQwe Credential Verifier from the EU Age Verification (AV) app. The AV app is the official wallet of the EU Age Verification Solution. Use this guide when the verifier runs the Annex A profile and you want to test age verification with a real wallet.

A Proof of Age is an attestation that states only whether the holder is over an age threshold. It does not reveal the exact birth date. Annex A is the EU Age Verification profile. The AV app stores a Proof of Age credential in the mDoc format and presents it over OpenID4VP, which is the OpenID for Verifiable Presentations protocol. The credential verifier is the server that validates the presentation and returns a signed attestation.

At the end of this guide, the AV app presents the Proof of Age, and the verifier reports the verification result.

Prerequisites

  • The credential verifier is installed and running over HTTPS. See Install and run the credential verifier and Configure TLS.
  • The verifier app is enabled on the verifier. See Run the verifier app.
  • The verifier trusts the certificate authority (CA) that issued the test credential, so that the verifier reports the issuer as trusted. See Configuration.
  • Android Studio is installed, or you have a physical Android device with Android 10 (API level 29) or higher.
  • You know the public hostname and port of the verifier. This is the public_root_url value in the verifier configuration.

How the test setup fits together

%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'mainBkg': '#ffffff', 'clusterBkg': '#ffffff', 'clusterBorder': '#cbd5e1', 'lineColor': '#334155', 'primaryColor': '#ffffff', 'secondaryColor': '#ffffff', 'tertiaryColor': '#ffffff', 'primaryTextColor': '#0f172a', 'secondaryTextColor': '#0f172a', 'tertiaryTextColor': '#0f172a', 'edgeLabelBackground': '#ffffff' }}}%%
flowchart TB
    subgraph HOST["Verifier host"]
        direction TB
        SP1[" "]
        VERIFIER["Credential verifier on port 9443"]
        APPUI["Verifier app QR page"]
        SP1 ~~~ VERIFIER
        VERIFIER --- APPUI
    end

    subgraph DEVICE["Android emulator or device"]
        direction TB
        SP2[" "]
        AVA["Age Verification app with a Proof of Age credential"]
        SP2 ~~~ AVA
    end

    APPUI -->|"1- Generate a Proof of Age QR code"| AVA
    AVA -->|"2- Present the Proof of Age"| VERIFIER

    classDef cMgmt fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e40af;
    classDef cCtrl fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e;
    classDef cExt fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a;

    class VERIFIER cMgmt;
    class APPUI cCtrl;
    class AVA cExt;
    style SP1 fill:none,stroke:none;
    style SP2 fill:none,stroke:none;

The verifier app generates a QR code that carries an OpenID4VP authorization request. The AV app reads the QR code and returns the Proof of Age. The verifier validates the credential and shows the result.

Step 1: Confirm the verifier profile

The AV app uses the Annex A profile. In this profile, the wallet identifies the relying party by its redirect_uri and does not require a signed authorization request or a reader trust store. Because of this, you do not add any certificate to the AV app trust store.

The Proof of Age credential type in the verifier app selects the Annex A profile and the namespace eu.europa.ec.av.1. The table below contrasts the two profiles.

AspectAV app (Annex A)EUDI wallet (HAIP)
Client identifierredirect_urix509_san_dns or x509_san_hash
Signed requestNot requiredRequired
Response modedirect_postdirect_post.jwt
Reader trustNot requiredRequired
CredentialProof of Age (eu.europa.ec.av.1)mDL or PID

For the parameters of the request, see Request parameters.

Step 2: Make the verifier reachable from the device

The wallet must reach the public URL of the verifier over HTTPS. If the verifier uses the demo hostname demo.ewqwe.local, set up the hostname mapping as described in Test the credential verifier with the EUDI wallet. You can use the same emulator and the same mapping for both wallet apps.

If the verifier uses an address that the device can reach directly, no mapping is necessary.

Step 3: Install the AV app

Option A: Build the ewQwe fork

The ewQwe fork of the AV app trusts all TLS certificates in debug builds. This lets the app reach the self-signed test certificate of the verifier.

  1. Clone the repository:

    git clone https://github.com/bgrieder/av-app-android-wallet-ui.git
    cd av-app-android-wallet-ui
    
  2. In Android Studio, open the project, select the app module and the EUDI_Dev_Device emulator, select the devDebug build variant under Build, Select Build Variant, and click Run.

    Expected result: the AV app installs and starts.

You can also build and install from the command line:

./gradlew :app:installDevDebug

Warning

The trust-all behaviour disables TLS verification. It exists only for local development. Never use it in a production build.

Option B: Install a pre-built APK

  1. Enable Developer Mode on the emulator. In Settings, open About phone, tap Build number seven times, and enter the device PIN if the device asks for it.
  2. Open Chrome on the emulator and go to the AV App releases page.
  3. Download an APK such as app-dev-debug.apk, open the file, and tap Install.

Important

The pre-built APK from the upstream project does not contain the trust-all behaviour. Use this option only when the verifier certificate chains to a CA that the stock app already trusts. Otherwise use Option A.

Step 4: Obtain a Proof of Age credential

  1. Open the AV app and create a PIN code when the app asks for one.
  2. Obtain a Proof of Age credential from the development issuer at https://test.issuer.dev.ageverification.dev.

Expected result: the Proof of Age credential appears in the app.

Step 5: Present the Proof of Age to the verifier

  1. Open the verifier app at the public URL of the verifier and sign in.
  2. On the home page, select Proof of Age as the credential type.
  3. Click Generate QR Code.
  4. On the Android device, open the AV app and scan the QR code.
  5. Approve the credential sharing in the app.

Expected result: the status badge in the verifier app changes from pending to verified.

For the full set of status values and their meanings, see The verifier app.

Troubleshooting

The TLS handshake fails

The verifier presents a self-signed certificate that the app does not trust. Use the ewQwe fork, which trusts all certificates in debug builds, or use a certificate from a publicly trusted CA.

The app does not open from the QR code

The QR code must contain a URI that the AV app registers. The AV app registers the schemes av://, avsp://, and openid4vp://, among others. Confirm that the verifier generates an Annex A request, and open the deep link directly if the camera scan does not start the app.

The wallet cannot reach the verifier

Check the hostname mapping from Step 2, confirm that the verifier port is open in the firewall, and confirm that both devices use the same Wi-Fi network.

The verifier rejects the presentation

The verifier does not trust the CA that issued the Proof of Age credential. Add the issuer CA to the verifier configuration and restart the verifier. See Configuration.

Note

The AV app does not require the verifier CA in a trust store. Annex A identifies the relying party by its redirect URI, not by a certificate.

Next steps

ADB troubleshooting reference for wallet testing

A reference of adb commands used when testing digital wallets (EUDI Wallet, France Identité, and others) with the ewQwe Credential Verifier.

Note

adb is typically located at ~/Library/Android/sdk/platform-tools/adb on macOS when installed through Android Studio. Add it to your PATH for convenience.


Device and connection management

List connected devices

# List all connected devices and emulators
adb devices

# List only emulator devices
adb devices -e

# List only physical (USB) devices
adb devices -d

Restart the ADB server

adb kill-server
adb start-server

Use this when adb devices shows no devices even though an emulator is running or a device is connected through USB.

Connect to a specific device

# Use -s with the device serial for single-target commands
adb -s <device_serial> install app.apk

# Use -e for an emulator
adb -e install app.apk

# Use -d for a physical device (USB)
adb -d install app.apk

Install and manage APKs

Install an APK

# Basic install
adb install /path/to/your-app.apk

# Reinstall (overwrite the existing app, keep the data)
adb install -r /path/to/your-app.apk

# Install to an emulator
adb -e install /path/to/your-app.apk

# Install to a specific device
adb -s <device_serial> install /path/to/your-app.apk

Uninstall an app

adb uninstall <package_name>

# Example: EUDI Wallet
adb uninstall eu.europa.ec.euidiw

# Example: France Identité
adb uninstall fr.gouv.interieur.franceidentite

List installed packages

# List all packages
adb shell pm list packages

# Filter by keyword
adb shell pm list packages | grep -i eudi
adb shell pm list packages | grep -i france
adb shell pm list packages | grep -i identite

W3C Digital Credentials API provider registration

Check registered credential providers

# List all credential providers registered with Android CredentialManager
adb shell dumpsys credential

Interpretation:

  • Empty or missing output: no wallet has registered as a CredentialProviderService with the Android CredentialManager on this device.
  • Populated output: the wallets that implement a CredentialProviderService appear here. Look for entries under credential-services.

Important

Some wallets, including the EUDI Wallet, implement Annex C Sub-protocol B with an Activity intent filter on their MainActivity, for the actions androidx.credentials.registry.provider.action.GET_CREDENTIAL and androidx.identitycredentials.action.GET_CREDENTIALS, instead of a CredentialProviderService. This approach does not appear in dumpsys credential.

This Activity-based approach does not work with Chrome on Android 14 and later. Chrome delegates to the Android CredentialManager, which dispatches only to CredentialProviderService implementations, and never to Activities with intent filters. The Digital Credentials API request never reaches the wallet.


DNS and network configuration

Map demo.ewqwe.local to the host machine (emulator)

For the Android emulator, the host machine is reachable at 10.0.2.2. Map the demo domain inside the emulator:

adb root && adb shell "echo '10.0.2.2  demo.ewqwe.local' >> /etc/hosts"

Warning

This command requires adb root, which works only on an emulator or a rooted device. Start the emulator with -writable-system.

Verify the hosts file

adb shell cat /etc/hosts

Verify network connectivity from the emulator

# Ping the host machine from the emulator
adb shell ping 10.0.2.2

# Test DNS resolution inside the emulator
adb shell ping demo.ewqwe.local

Transfer files (CA certificates, APKs, and others)

Push files to the device

# Push a CA certificate to Downloads
adb push /path/to/ewqwe-ca.crt /sdcard/Downloads/ewqwe-ca.crt

Push a CA certificate to the system trust store (rooted emulator)

adb root
adb remount
adb push /path/to/ewqwe-ca.crt /system/etc/security/cacerts/ewqwe-ca.crt
adb reboot

Pull files from the device

adb pull /sdcard/Download/some-file.txt /local/path/

View wallet logs (logcat)

Filter by process ID (EUDI Wallet)

# Stream logs for the EUDI Wallet process only
adb logcat --pid=$(adb shell pidof eu.europa.ec.euidiw)

Filter by log tags

# Show only specific wallet log tags
adb logcat -s "OpenId4VpManager" "PresentationManager" "WalletCore"

Note

For France Identité, substitute the package name or the tags that France Identité uses.

Search the logs for wallet keywords

adb logcat | grep -iE "eudi|openid4vp|presentation|mdoc|wallet"
adb logcat | grep -iE "france|identite|annex_b|dcapi"

Clear logcat

adb logcat -c

System information and debugging

Check the Android version

adb shell getprop ro.build.version.release

Check whether WebView supports W3C Digital Credentials

# Check the Chrome version on the device
adb shell dumpsys package com.android.chrome | grep versionName

Grant permissions to a wallet app

adb shell pm grant <package_name> android.permission.BLUETOOTH
adb shell pm grant <package_name> android.permission.BLUETOOTH_ADMIN
# Open an openid4vp deep link on the device
adb shell am start -d "openid4vp://?client_id=..." -a android.intent.action.VIEW

# Open a generic URL
adb shell am start -d "https://example.com" -a android.intent.action.VIEW

Force-stop an app and clear its data

adb shell am force-stop <package_name>
adb shell pm clear <package_name>

Reboot the emulator or device

adb reboot

Test certificates

Inspect a certificate chain

openssl x509 -in your_fullchain.pem -noout -issuer
openssl x509 -in your_cert.pem -noout -subject -issuer

Download root CA certificates (for example, Let’s Encrypt)

curl -s https://letsencrypt.org/certs/isrgrootx1.pem -o isrg_root_x1.pem
curl -s https://letsencrypt.org/certs/isrg-root-x2.pem -o isrg_root_x2.pem

Android emulator commands

Cold boot

Use this when the emulator is unresponsive or has stale state. In Android Studio, open Device Manager, right-click the device, and select Cold Boot Now.

Enable the hardware keyboard

In the Android Studio emulator settings, enable “Hardware keyboard present” to use the keyboard of your computer.

Grant superuser (root)

adb root

Note

This works only on emulator images or rooted devices. It is required to modify /etc/hosts or the system-level CA certificates.

Remount the system partition as writable

adb remount

Note

This is required after adb root to push files to system partitions such as /system/etc/security/cacerts/.


Quick reference by use case

What you needCommand
See connected devicesadb devices
Install an APKadb install /path/to/app.apk
Force reinstalladb install -r /path/to/app.apk
Check W3C credential providersadb shell dumpsys credential
Map demo domain in emulatoradb root && adb shell "echo '10.0.2.2 demo.ewqwe.local' >> /etc/hosts"
Push CA cert to Downloadsadb push cert.crt /sdcard/Downloads/
Push CA cert to system storeadb root && adb remount && adb push cert.crt /system/etc/security/cacerts/
Stream wallet logsadb logcat --pid=$(adb shell pidof <package>)
Filter logcat by tagsadb logcat -s "Tag1" "Tag2"
Search logs for keywordsadb logcat | grep -iE "eudi|openid4vp"
Restart ADB serveradb kill-server && adb start-server
Check Android versionadb shell getprop ro.build.version.release
List installed packagesadb shell pm list packages | grep -i <keyword>
Open a deep linkadb shell am start -d "<url>" -a android.intent.action.VIEW
Force-stop an appadb shell am force-stop <package>
Clear app dataadb shell pm clear <package>
Reboot deviceadb reboot
Root the emulatoradb root
Remount system as writableadb remount

References

Configure the verifier app

This guide shows how to configure the verifier app after it runs. It covers the display settings, the allowed credential types, the session, the user database, and the user accounts.

Goal

Configure the verifier app for a deployment: set the display name and logo, restrict the credential types, keep sessions across restarts, choose the user database, and manage the accounts.

Prerequisites

Configure the display

Set the display keys in the [verifier_ui] section of the server configuration file:

[verifier_ui]
enabled = true
app_name = "City of Example Age Check"
logo_url = "https://example.com/logo.svg"
ui_dist_path = "../crates/ewqwe-credential-verifier-ui/ui/dist"
  • app_name sets the text in the header.
  • logo_url accepts an HTTPS URL or a data: URL.
  • qr_code_callback_url sets the base URL for the wallet callback. When the value is absent, the app uses the public_root_url of the server, or derives the base URL from the incoming request.

An administrator can also change the display name and the logo on the Settings page. A value in the configuration file sets the start value; a value on the Settings page overrides it and is stored in the user database.

Restrict the credential types

The allowed_credential_types key limits the types that any user can request:

[verifier_ui]
allowed_credential_types = ["proof-of-age", "mdl"]

The accepted values are proof-of-age, mdl, national-id, and france-identite-numerique. An empty list allows every type. A per-user list narrows the server setting for one user; it never widens it.

To restrict one user, open the Users page as an administrator, edit the user, and select the allowed types.

Keep sessions across restarts

The app signs the session cookie with session_secret. When the value is absent, the server generates a random key at startup, and every restart ends all sessions. To keep sessions, generate a secret and set it:

openssl rand -hex 64
[verifier_ui]
session_secret = "<the generated value>"

The value must contain at least 8 characters. The server derives the cookie signing key from the value, so the same value keeps the sessions valid across restarts.

Choose the user database

The app stores the user accounts in the backend named by the [verifier_ui.db] table.

[verifier_ui.db]
backend = "sqlite_file"
path = "/var/lib/ewqwe/verifier_ui.db"
BackendPersistenceExtra keysUse
sqlite_memorynonenoneDevelopment and testing.
sqlite_filefilepathA single instance with persistence.

The path value resolves relative to the directory that holds the configuration file. The default backend is sqlite_memory.

Manage users and roles

Open the Users page as an administrator to create, update, and delete accounts. Each account has one role:

RolePermissions
adminUser management, settings, journal, and QR codes.
verifierQR code generation and status polling.

The first account that the bootstrap route creates is an administrator with is_superadmin = true. A superadmin cannot be deleted through the interface. A password must contain at least 12 characters.

Troubleshooting

SymptomCauseAction
The config key has no effectThe app reads the value at startup.Restart the server after a change to the configuration file.
Every /api/v1 route returns 404The app is disabled.Keep the [verifier_ui] section with enabled = true.
Accounts disappear after a restartThe database is sqlite_memory.Configure sqlite_file.
Sessions end after a restartsession_secret is not set.Set a stable session_secret value.
A user cannot request a typeThe type is not allowed for that user.Widen the per-user list or the allowed_credential_types list.

Issue a test credential

This guide builds a signed test credential with the ewqwe_digital_credential library and presents it to a running credential verifier. Use this procedure to test the verifier without a real wallet or a real issuer.

Goal

Produce a credential of a supported type, trust its issuer in the verifier, and submit it to the /ewqwe_api/verify endpoint.

Before you start

  • The credential verifier runs and answers on a known URL. See Install and run.
  • The Rust toolchain with Cargo is installed.
  • The jq tool is installed, to read values from JSON responses. Read the values by hand if jq is not available.
  • You can write to the issuers_cas_dir directory of the verifier. The default directory is issuers_cas next to the configuration file. See Configuration.
  • You know the type of credential to build. See Credential types.

The library signs with ES256 (ECDSA with P-256 and SHA-256). The library keeps all private keys in memory, and a test credential is valid for one hour in the SD-JWT VC format and for one year in the mDoc format.

1. Create the program

Create a new Cargo project, and add the library and serde_json as dependencies.

[package]
name = "test-credential"
version = "0.1.0"
edition = "2021"

[dependencies]
ewqwe_digital_credential = { path = "../crates/ewqwe-digital-credential" }
serde_json = "1"

Put the following code in src/main.rs. The program generates the issuing authority, stores the CA certificate, builds one credential, and writes the request body for the verify endpoint.

use ewqwe_digital_credential::CredentialIssuer;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create an ephemeral authority: a CA, an issuer leaf key, and a device key.
    let issuer = CredentialIssuer::generate()?;

    // 2. Write the public CA certificate to the trusted CA directory of the verifier.
    std::fs::write("credentials_cas/test-ca.pem", &issuer.ca_cert_pem)?;

    // 3. Read the values of one OpenID4VP transaction.
    let auth_request: serde_json::Value =
        serde_json::from_slice(&std::fs::read("auth-request.json")?)?;
    let nonce = auth_request["nonce"].as_str().ok_or("missing nonce")?.to_string();
    let client_id = auth_request["client_id"].as_str().ok_or("missing client_id")?.to_string();
    let response_uri = auth_request["response_uri"].as_str().ok_or("missing response_uri")?.to_string();
    let state = auth_request["state"].as_str().ok_or("missing state")?.to_string();

    // 4. Build the credential. Select one of the three lines below.
    //    The EU Age Verification profile, vct eu.europa.ec.av.1, claim over_18.
    let credential = issuer.build_eu_age_sd_jwt(&nonce, &client_id);
    // The EUDI PID as an SD-JWT VC, vct eu.europa.ec.eudi.pid.1.
    // let credential = issuer.build_eudi_sd_jwt(&nonce, &client_id);
    // The EUDI PID as an ISO/IEC 18013-5 mDoc. This line also uses response_uri.
    // let credential = issuer.build_eudi_mdoc(&nonce, &client_id, &response_uri);

    // 5. Wrap the credential as a DCQL VP token, and write the verify request body.
    let vp_token = serde_json::json!({ "eu_age_credential": [credential] }).to_string();
    let body = serde_json::json!({
        "vp_token": vp_token,
        "state": state,
        "client_id": client_id,
    });
    std::fs::write("verify-request.json", serde_json::to_vec_pretty(&body)?)?;

    println!("wrote verify-request.json");
    Ok(())
}

2. Generate the issuing authority

The CredentialIssuer::generate call creates three P-256 key pairs and the matching X.509 certificates. The call returns the issuer object with the following fields.

FieldContent
ca_cert_pemThe self-signed CA certificate, in PEM form
issuer_cert_derThe issuer leaf certificate, in DER form
device_pubkey_jwkThe device public key, as a JWK

The library writes the issuer leaf certificate and the CA certificate into each credential automatically. The verifier reads the two certificates from the credential.

3. Trust the issuer certificate

The verifier trusts an issuer only when the issuer certificate chains to a CA in the trusted CA directory.

  1. Write the value of issuer.ca_cert_pem to a .pem file in the issuers_cas_dir directory. The program above writes issuers_cas/test-ca.pem.
  2. If the verifier runs in another directory, move the file to the configured issuers_cas_dir instead.
  3. Restart the credential verifier. The verifier loads the directory at startup only, so a new file needs a restart.

Expected result: the log line Loaded credential issuer CAs at startup reports a count of at least one.

Note

A test credential is rejected when its issuer CA is missing from the directory. The verify response then reports "issuer_trusted": false.

4. Start a transaction and read its parameters

The credential must bind to the nonce and the client_id of one transaction, and an mDoc must also bind to the response_uri. Start a transaction, and save the response in a file.

# Start a transaction. Save the response.
curl --cacert ca.pem --cert client.pem --key client.key \
  -H 'Content-Type: application/json' \
  -d '{"profile":"annex-a","credential_type":"proof-of-age"}' \
  https://localhost:9443/ewqwe_api/openid4vp/init > init-response.json

# Read the transaction id. The examples use jq to read JSON.
TRANSACTION_ID=$(jq -r .transaction_id init-response.json)

# Fetch the authorization request. Save it where the program reads it.
curl --cacert ca.pem --cert client.pem --key client.key \
  -H 'Accept: application/json' \
  "https://localhost:9443/ewqwe_api/openid4vp/request/$TRANSACTION_ID" > auth-request.json

Expected result: init-response.json holds the transaction_id value, and auth-request.json holds the values state, nonce, client_id, and response_uri. The program reads those four values from auth-request.json in the next step.

For the Annex A profile, the verifier derives client_id as redirect_uri: followed by the response_uri. The response_uri is the public_root_url followed by /ewqwe_api/openid4vp/direct_post.

The credential_type value shapes the authorization request for a real wallet. This guide bypasses the wallet, so the value does not restrict the credential that you build in the next step.

Important

Use the values from one transaction only. The verifier rejects a presentation whose nonce or session data belongs to a different transaction.

The verifier requires mutual TLS by default. Replace ca.pem, client.pem, and client.key with the certificate files of your setup. For the details, see Configure TLS and TLS authentication.

5. Build and run the program

Run the program. It builds the credential and writes the file verify-request.json.

Run the program and the curl commands from the same directory, so that the files auth-request.json and verify-request.json resolve.

cargo run

Expected result: the line wrote verify-request.json.

BuilderTypeFormatClaims
build_eu_age_sd_jwtEU Age VerificationSD-JWT VCover_18
build_eudi_sd_jwtEUDI PIDSD-JWT VCgiven_name, family_name, birth_date, age_over_18
build_eudi_mdocEUDI PIDmso_mdocgiven_name, family_name, birth_date, age_over_18

The credential appears in the vp_token field of verify-request.json. An SD-JWT VC presentation starts with a JWT and ends with the KB-JWT, and the two parts are separated by ~. An mDoc presentation is a Base64URL-encoded CBOR value.

6. Submit the credential to the verifier

Send the request body to the verify endpoint.

curl --cacert ca.pem --cert client.pem --key client.key \
  -H 'Content-Type: application/json' \
  --data @verify-request.json \
  https://localhost:9443/ewqwe_api/verify

Expected result, in the success case:

{
  "success": true,
  "message": "Credential verified successfully",
  "verification_details": {
    "signature_valid": true,
    "not_expired": true,
    "issuer_trusted": true
  },
  "attestation": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The attestation value is a signed JWT. The claims of the credential appear in the attestation payload when the verification succeeds.

Troubleshooting

SymptomCauseFix
"issuer_trusted": falseThe issuer CA is not in the trusted directory, or no restartWrite the CA PEM, then restart the verifier.
Nonce mismatch: presentation nonce does not match server nonceThe credential uses the nonce of a different transactionRebuild the credential with the nonce of the current transaction.
state is required for mDoc verificationAn mDoc presentation arrived without a state valueAdd the state field of the transaction to the request body.
issuer JWT is missing the required x5c headerThe SD-JWT VC value did not come from this libraryBuild the credential with a build_* function of the library.
deviceAuth.deviceMac is not supported by this verifierThe mDoc used a COSE_Mac0 value for the holder proofUse a wallet that produces a deviceSignature.
Credential has expiredThe SD-JWT VC validity time of one hour passedRun the program again to build a fresh credential.

Questions about the server

This page answers recurring questions about the credential verifier. Each answer links to the page that holds the full explanation.

What does the credential verifier do?

The verifier accepts a Verifiable Presentation (VP Token) from a relying party, checks the presentation, and returns a signed attestation that states the outcome. The full sequence of checks is described in the verification process.

Does the verify endpoint require a client certificate?

Yes. The verification endpoint requires mutual TLS, so the caller must present a client certificate signed by a CA in client_ca_cert_chain. The setup is described in configure TLS.

Does the verifier need a Redis server?

No, not by default. The transaction store defaults to SQLite in memory, and Redis is one of several selectable backends. See configure storage.

Why does the verifier report issuer_trusted as false?

The issuer certificate chain does not terminate at a certificate in the trusted issuer CA directory. Add the issuer CA file to that directory and restart the server, because the directory is read only at startup. See the security model.

Why does the verify endpoint return HTTP 200 with success false?

For an SD-JWT VC, the presentation was well formed but one of the checks failed. The errors array names the failing checks, and the attestation records the failure. See verify a credential.

Why does the verify endpoint return HTTP 400?

The request is malformed, refers to a transaction that does not match, or presents an mDoc that fails a check, such as an untrusted issuer. The response body states the reason. See the HTTP API reference.

How does the verifier prevent a replay of a presentation?

The verifier reads the nonce from its own transaction store, never from the request body, and compares it with the nonce bound into the presentation. A successful verification consumes the stored transaction, which removes the context that an mDoc presentation needs. See the security model for the limits of this binding.

Does the verifier reveal the user’s birth date?

Only if the relying party asks for the birth date claim. An age request normally asks for the derived claim age_over_18, which reveals a boolean and not a date. See selective disclosure.

How long is a transaction valid?

A transaction lives for transaction_ttl_secs, which defaults to 300 seconds. An expired transaction cannot be verified. See configure storage.

How long is an attestation valid?

An attestation is valid for 300 seconds by default. The relying party should verify the exp claim before it uses the result. See attestations.

How do I verify the signature of an attestation?

Fetch the public key from the JWKS endpoint and select the key whose kid matches the kid in the attestation JWT header. See attestations.

What is the verification journal?

The journal is an append-only, hash-chained audit log of successful verifications, scoped per authenticated user. The verifier disables it by default. See the verification journal.

Can I run the verifier without TLS?

No. The listener always uses TLS, so the server always needs a private key, a certificate, and a CA chain. See install and run the server.

How do I turn off authentication for local tests?

Set disable_authentication = true and name the test user in disabled_authentication_user. Use this setting only on a local test machine. See configuration.

How do I test the server with a real wallet?

Use the step-by-step guides for the wallet that you have. See test with the EUDI wallet or test with the AV app.

Questions about OpenID4VP

What is OpenID4VP?

OpenID for Verifiable Presentations (OpenID4VP) is an OpenID specification that lets a relying party ask a wallet for a verifiable presentation. The relying party encodes the request in a URL, and the wallet returns the presentation over HTTP. See OpenID4VP authorization request parameters.

Why does the system use OpenID4VP at all?

The EU Age Verification Profile names the W3C Digital Credentials API as the primary method and OpenID4VP as the fallback for browsers that do not provide that API. See Protocol modes.

Does the verifier need a signed authorization request?

No. The age verification profile uses the redirect_uri client identifier scheme, which forbids a signed request. Trust rests on TLS and the web PKI instead of a trust list of relying parties. See Client identifier schemes.

Which client identifier scheme should I use?

Use redirect_uri for a proof of age from the age verification app, and use x509_san_dns for a mobile driving licence or a national identity from the EUDI Wallet. The scheme must match the target wallet, because the EUDI Wallet rejects the redirect_uri scheme. See Client identifier schemes.

What is the difference between direct_post and fragment?

With direct_post, the wallet posts the presentation to the response_uri of the relying party, which enables cross-device flows. With fragment, the wallet returns the presentation in the URL fragment, which only works on one device. The age verification profile requires direct_post. See Response modes.

Why does the response arrive as an HTTP POST instead of a redirect?

The cross-device flow needs a response channel that does not depend on the device that started the request. An HTTP POST to a public response_uri reaches the relying party from any phone that scanned the QR code. See Protocol modes.

What is DCQL, and why does it replace presentation_definition?

DCQL is the Digital Credentials Query Language, defined in Section 6 of OpenID4VP 1.0. It expresses the required credentials and claims, and the age verification profile mandates it in place of the older DIF Presentation Exchange presentation_definition. See DCQL queries.

How do I request age over 21 instead of age over 18?

Change the claim name in the query path from age_over_18 to age_over_21. The document type and the namespace stay the same. See Age verification query examples.

Can I accept either a proof of age or a driving licence?

Yes. Add one credential query for each option and group them in a credential_sets entry, so the wallet can satisfy the query with either credential. See Multiple credential options.

How does the system prevent replay attacks?

The relying party generates a fresh random nonce for every request, stores it, and rejects any presentation that carries a different nonce. The wallet echoes the nonce in the presentation, which binds the presentation to one transaction. See OpenID4VP authorization request parameters.

Do I need to send client_metadata?

No. The age verification profile does not require client_metadata, and the system omits it to keep the request URL short for QR codes. See OpenID4VP authorization request parameters.

Does the wallet send a presentation_submission with a DCQL query?

No. With a DCQL query, the vp_token itself maps credential identifiers to presentations, so the wallet does not send presentation_submission. That field belongs to the older presentation_definition queries. See The vp_token response.

The av:// link scheme lets the operating system open the age verification application on the device. The wallet then returns the response with an HTTP POST, not through the link itself. See The av:// application link scheme.

Why must I send the request parameters by value instead of using a request_uri?

The profile forbids a JWT-secured authorization request by reference, because that mechanism protects the request only when a trust list of relying parties exists. For age verification no such trust list exists, so the profile requires all parameters inline in the URL. See Protocol modes.

What is the difference between the same-device and cross-device flows?

In the same-device flow, the relying party and the wallet run on one device and the browser redirects to the result. In the cross-device flow, the wallet runs on a second device that scans a QR code, and the first device learns about the result through polling or a WebSocket. See Same-device and cross-device flows.

Questions about credentials

This page answers common questions about credential formats and credential building. Each answer links to the page that holds the full explanation.

Which credential formats does the verifier accept?

The verifier accepts mso_mdoc (ISO/IEC 18013-5) and dc+sd-jwt (SD-JWT VC). See Credential formats.

How does the verifier detect the credential format?

The verifier reads the presentation itself. A value with the ~ separator is an SD-JWT VC, and any other value is parsed as a Base64URL-encoded CBOR mDoc. See Credential formats.

What is the difference between mso_mdoc and SD-JWT VC?

The mso_mdoc format uses CBOR encoding and COSE signatures, and the SD-JWT VC format uses JSON and JWS signatures. Both formats support selective disclosure and holder binding. See Credential formats.

Which credential types can the verifier verify?

The verifier has no fixed list of types. It verifies the type that the operator requests in the DCQL query, provided the issuer chains to a trusted CA. See Credential types.

Which credential type should I use for age verification?

Use an mDL or a Proof of Age attestation. The Proof of Age attestation carries only age_over_18 and no identity data. See Credential types.

Does the EUDI PID carry an age attribute?

No. The EU ARF PID Rulebook removed the age attributes from the PID, and age_over_18 is not a valid PID attribute. See Credential types.

Can an mDL use the SD-JWT VC format?

No. The 4th Driving Licence Regulation requires the ISO/IEC 18013-5 data model, so an mDL uses the mso_mdoc format only. See Credential types.

What does selective disclosure do?

Selective disclosure lets a holder reveal a subset of the claims in a credential while the verifier still checks the issuer signature. See Selective disclosure.

Why does a verified credential show only some of its claims?

The holder revealed only those claims. Each format commits to every claim with a salted hash, so the holder chooses which claims to disclose. See Selective disclosure.

What is holder binding?

Holder binding is the proof that the presenter controls the private key that the credential names. An mDoc uses the deviceSignature, and an SD-JWT VC uses the Key Binding JWT. See Credential formats.

How do I build a test credential?

Use the CredentialIssuer type of the ewqwe_digital_credential library. The type generates an ephemeral issuing authority and builds a signed credential in either format. See Issue a test credential.

Must a test credential use the nonce of the current transaction?

Yes. The verifier compares the nonce of the presentation with the nonce of the stored transaction, and rejects a mismatch. See Request parameters.

Why does an mDoc presentation need a state value?

The verifier rebuilds the OpenID4VP session transcript from the stored transaction to verify the deviceSignature. Without the state value, the verifier cannot find the transaction. See Verify a credential.

Which signature algorithms does the verifier accept?

For mDoc, the verifier accepts the COSE algorithms ES256, ES384, ES512, RS256, RS384, and RS512. For SD-JWT VC, the verifier accepts the JWS algorithms that the issuer JWT names, which are ES256, ES384, RS256, RS384, and RS512. See Credential formats.

Glossary

This glossary defines acronyms and terminology used across the ewQwe Age Verification project and the broader EU digital identity ecosystem.


A

ARF — Architecture and Reference Framework The EU Commission’s technical blueprint for the European Digital Identity Wallet ecosystem. Defines the architecture, roles, and interoperability requirements for all EUDI components.

Attestation A digitally-signed document issued by a trusted authority that asserts facts about a subject (e.g. “this person is over 18”). The general term used in the EU ARF for any credential or verifiable document, whether mDL, PID, or any other type.

AVI — Age Verification App Instance Term used in the EU Age Verification Profile for the wallet-side component that stores and presents Proof of Age attestations.


B

Binding Proof — see Holder Binding Proof.


C

CBOR — Concise Binary Object Representation (RFC 7049 / RFC 8949) A binary data serialization format, similar to JSON but more compact. Used extensively in mDoc/mDL credentials. All mso_mdoc structures are CBOR-encoded.

CDDL — Concise Data Definition Language (RFC 8610) A schema language for describing CBOR data structures. Used in ISO 18013-5 to formally define mDoc structures.

CIR — Commission Implementing Regulation EU regulatory acts that specify technical details of the EUDI Wallet framework. CIR 2024/2977 defines the PID attribute set.

client_id In OpenID4VP, the identifier of the Relying Party (Verifier). The identifier carries a scheme prefix:

  • redirect_uri:https://rp.example.com/cb — RP identified by its redirect URI (AnnexA profile)
  • x509_san_dns:rp.example.com — RP identified by a DNS SAN in its X.509 certificate (HAIP profile)

cnf — Confirmation Claim (RFC 7800) A JWT claim that contains the holder’s public key (usually as a jwk). Used in SD-JWT VCs to bind the credential to a specific cryptographic key, enabling holder binding.

COSE — CBOR Object Signing and Encryption (RFC 8152 / RFC 9052) The CBOR equivalent of JOSE (JSON Object Signing and Encryption). Defines:

  • COSE_Sign1 — single-signer signatures
  • COSE_Mac0 — message authentication codes
  • COSE_Encrypt0 / COSE_Encrypt — encryption structures

COSE_Sign1 A COSE structure for a signed object with a single signer. Used for MSO (issuer auth) and device signatures in mso_mdoc. Structure: [protected_header, unprotected_header, payload, signature].


D

DC API — Digital Credentials API A W3C browser API (navigator.credentials.get()) that enables web pages to request verifiable credentials from wallets. Replaces the earlier WebAuthn-based flow for identity credentials.

DCQL — Digital Credentials Query Language A JSON-based query language used in OpenID4VP dcql_query parameter to specify which credential types and claims are requested. More expressive than Presentation Exchange (PE).

DeviceAuthentication An mDL CBOR structure that the device (holder) signs to prove session binding. Contains: ["DeviceAuthentication", SessionTranscript, DocType, DeviceNameSpacesBytes]. The signed bytes are DeviceAuthenticationBytes = Tag(24, bstr(cbor(DeviceAuthentication))).

DeviceSigned The part of an mDoc Document that contains the device-generated signature (DeviceAuth) and any device-disclosed namespaces. Proves the holder controls the credential’s device key.

Disclosure (SD-JWT) A base64url-encoded JSON array [salt, claim_name, claim_value] that reveals a single selectively-disclosed claim. The holder includes chosen Disclosures in a presentation.

docType The CBOR text string identifier for an mDoc credential type. Examples:

  • org.iso.18013.5.1.mDL — Mobile Driver’s Licence
  • eu.europa.ec.eudi.pid.1 — EU Person Identification Data
  • eu.europa.ec.av.1 — EU Age Verification (Proof of Age)

E

EUDI Wallet — European Union Digital Identity Wallet The EU-standardised digital wallet app (Android/iOS) for holding and presenting European Digital Identity documents. Governed by the EU ARF.

EC — Elliptic Curve Cryptographic scheme used for compact key sizes and signatures. Common curves in this project:

  • P-256 (secp256r1): used for ES256 signatures, JWK thumbprints
  • P-384 (secp384r1): used for ES384 signatures

H

HAIP — High Assurance Interoperability Profile An OpenID4VP profile requiring JARM (response_mode=direct_post.jwt) and X.509-based RP authentication (client_id_scheme=x509_san_dns). Provides higher security guarantees than the basic profile.

Holder The entity (person, organisation) who possesses a credential and presents it to verifiers. In this project, corresponds to the wallet / AVI.

Holder Binding Proof Proof that the holder of a credential controls the private key bound to it. This prevents credential theft — a stolen credential is useless without the binding key.

  • In mso_mdoc: the DeviceSigned block containing a COSE_Sign1 over DeviceAuthenticationBytes signed with the device private key
  • In SD-JWT VC: the Key Binding JWT (KB-JWT) signed with the key in the cnf.jwk claim

See OpenID4VP §5.3.


I

ISO 18013-5 The ISO standard defining the Mobile Driver’s Licence (mDL) data model and presentation protocol. Basis for the mso_mdoc credential format and the COSE-based signing scheme used across EU digital credentials.

Issuer A trusted authority that issues credentials (attests facts about a subject). Signs the MSO (mDL) or the JWT (SD-JWT VC).

IssuerSigned The part of an mDoc Document containing the issuer-authenticated claims and the MSO (COSE_Sign1). Enables selective disclosure — only the chosen IssuerSignedItem entries are revealed.

IssuerSignedItem A single disclosed claim in an mso_mdoc document. Contains: digestID, random (salt), elementIdentifier (claim name), elementValue (claim value). Encoded as Tag(24, bstr(cbor(IssuerSignedItem))).


J

JARM — JWT Secured Authorization Response Mode An extension of OAuth 2.0 that wraps authorization responses in a JWT. In OpenID4VP, response_mode=direct_post.jwt uses JWE/JWS to encrypt/sign the VP Token response from wallet to RP. Required by the HAIP profile.

JWE — JSON Web Encryption (RFC 7516) A standard for encrypting data as a JSON structure. Used in JARM to encrypt the VP Token when response_mode=direct_post.jwt.

JWK — JSON Web Key (RFC 7517) A JSON representation of a cryptographic key (EC or RSA). The verifier’s JWK is used to encrypt JARM responses; its thumbprint is included in the SessionTranscript for HAIP flows.

JWK Thumbprint (RFC 7638) A SHA-256 hash of the canonical JSON representation of a JWK. Used in the OID4VPHandoverInfo to bind the session transcript to the verifier’s encryption key.

JWS — JSON Web Signature (RFC 7515) A standard for signing data as a JSON structure. The basis for standard JWTs and SD-JWT VC issuer signatures.

JWT — JSON Web Token (RFC 7519) A compact, URL-safe representation of claims signed (and optionally encrypted) as JSON.


K

KB-JWT — Key Binding JWT The trailing JWT in an SD-JWT presentation that proves the holder controls the key in cnf.jwk. Contains aud, nonce, iat, and sd_hash. Required for holder binding in SD-JWT VC presentations.


M

mDL — Mobile Driver’s Licence A digital driving licence defined by ISO/IEC 18013-5. Uses the mso_mdoc credential format with docType org.iso.18013.5.1.mDL.

mDoc / mso_mdoc Short for “Mobile Document” / “Mobile Security Object + mDoc”. The credential format defined in ISO 18013-5 using CBOR encoding and COSE signing. Used for mDL, EU PID, EU Age Verification, and other digital documents.

MSO — Mobile Security Object The signed CBOR data structure embedded in an mDoc’s issuerAuth COSE_Sign1. Contains SHA-256 digests of each claim (rather than the values themselves), enabling selective disclosure while maintaining issuer authenticity.


N

Namespace In mDL/mDoc, claims are grouped into namespaces (CBOR text strings). Examples:

  • org.iso.18013.5.1 — Core mDL attributes (given_name, birth_date, etc.)
  • org.iso.18013.5.1.aamva — North American additions
  • eu.europa.ec.eudi.pid.1 — EU PID attributes

nonce A random value included in an Authorization Request to prevent replay attacks. Bound into the SessionTranscript (mDL) or KB-JWT (SD-JWT VC) of the presentation.


O

OID4VP / OpenID4VP — OpenID for Verifiable Presentations The protocol used to request and receive Verifiable Presentations from a wallet. Builds on OAuth 2.0 authorization flows. Supports both mso_mdoc and SD-JWT VC credential formats. Key specs versions: 1.0 (current stable).

OID4VCI / OpenID4VCI — OpenID for Verifiable Credential Issuance The companion protocol to OID4VP for issuing credentials into wallets.


P

PE — Presentation Exchange An older query language for specifying credential requirements in OID4VP, defined by the Decentralized Identity Foundation (DIF). Being superseded by DCQL in newer profiles.

PID — Person Identification Data The EU digital identity credential containing core identity attributes (name, birth date, nationality, etc.). Specified in CIR 2024/2977. Available in both mso_mdoc and SD-JWT VC formats.

Presentation / VP A holder-constructed object that packages one or more credentials (or selective disclosures from them) together with holder binding proof, for transmission to a verifier. In OpenID4VP the main artifact is called the VP Token.

Proof of Age (PoA) / Age Verification Attestation A credential or derived presentation that proves an age threshold (e.g. “over 18”) without revealing exact birth date. Core use case of this project.


R

RP — Relying Party The service or application that requests and verifies credentials. Also called Verifier. In this project, corresponds to the typescript/demo-webapp/ component.

response_mode OpenID4VP parameter controlling how the wallet returns the VP Token:

  • fragment — appended to redirect URI as URL fragment (same-device, cross-origin)
  • direct_post — wallet POSTs to response_uri (cross-device or CORS-friendly)
  • direct_post.jwt — wallet POSTs a JWE/JWS-wrapped VP Token (HAIP/JARM)
  • dc_api — delivered via browser DC API (no redirect needed)
  • dc_api.jwt — DC API with JARM wrapping

response_uri The URL to which the wallet POSTs the VP Token in direct_post and direct_post.jwt modes.


S

Salted Hashing The mechanism used for selective disclosure in both mDL and SD-JWT. Each claim is combined with a random salt before hashing. This prevents a verifier from guessing undisclosed claim values by brute-forcing the hash.

SAN — Subject Alternative Name An X.509 certificate extension field listing alternative identities for the certificate subject (DNS names, IP addresses, email). Used in x509_san_dns client_id scheme to identify RPs.

SD-JWT VC — Selective Disclosure JWT for Verifiable Credentials A credential format combining standard JWTs with selective disclosure via SHA-256 commitments. Defined in IETF SD-JWT VC.

SessionTranscript An mDL CBOR structure that ties a device signature to a specific presentation session. For OID4VP flows it contains the OID4VPHandover, which commits to the client_id, nonce, response_uri, and (for HAIP) the verifier’s JWK thumbprint.

_sd The JSON array in an SD-JWT VC issuer JWT that holds base64url-encoded SHA-256 digests of the Disclosures. The holder reveals values by including the matching Disclosures in the presentation.

_sd_alg The hash algorithm used for Disclosure digests in SD-JWT VCs. Currently always sha-256.


T

Tag(24) — #6.24(bstr) A CBOR semantic tag applied to a byte string to indicate that its content is CBOR-encoded. Extensively used in mDL:

  • IssuerSignedItemBytes = #6.24(bstr .cbor IssuerSignedItem)
  • DeviceAuthenticationBytes = #6.24(bstr .cbor DeviceAuthentication)
  • DeviceNameSpacesBytes = #6.24(bstr .cbor DeviceNameSpaces)

The full Tag(24, bstr(...)) encoding must be hashed/signed, not just the inner bytes.


V

VC / Verifiable Credential A tamper-evident credential whose authorship can be cryptographically verified. The W3C Verifiable Credentials Data Model provides a general framework; mso_mdoc and SD-JWT VC are two concrete serialisations.

Verifiable Presentation / VP A holder-generated package wrapping one or more Verifiable Credentials and a binding proof. Transmitted to a verifier (RP) in response to a presentation request.

Verifier — see RP.

VP Token The OpenID4VP parameter name for the value carrying the Verifiable Presentation. For mso_mdoc it is the base64url-encoded DeviceResponse; for SD-JWT VC it is the SD-JWT string.

vct — Verifiable Credential Type A URI in SD-JWT VC that identifies the type/schema of the credential. E.g. https://credentials.example.com/identity_credential.


W

W3C DC API — see DC API.

Wallet The software that stores, manages, and presents digital credentials on behalf of the holder. Examples are the EUDI Wallet and the EU Age Verification app.


X

x5chain (COSE header label 33) An unprotected COSE header containing a DER-encoded X.509 certificate chain. Used in mDL issuerAuth to carry the issuer certificate for chain verification.

x5c (JOSE header) The JSON/JWT equivalent of x5chain. An array of base64-encoded DER X.509 certificates. Used in JAR (JWT Authorization Request) to carry the RP’s certificate for x509_san_dns verification.

References

This chapter centralizes external references used throughout this documentation.

EU age verification (primary use case)

EU Digital Identity Framework (EUDI / eIDAS)

EU ARF (architecture and rulebooks)

EU wallet apps

EU PID / mDL Regulation

W3C APIs (browser credential selection)

OpenID specifications

ISO standards

These ISO documents are typically paywalled; the links below are the official ISO catalog entries.

IETF drafts

IETF RFCs (crypto and data formats)

DCQL (additional reading)

Note: In this project, DCQL is used as defined by OpenID4VP (Section 6). The link below is included as additional ecosystem context.

Browser and platform references

These links are useful when validating feasibility and browser support status for the Digital Credentials API.

Tooling (Deno)