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:
| Reader | Starting point |
|---|---|
| System operator | Run the verifier app and Install and run the server |
| Relying Party developer | HTTP API and Verify a credential |
| Product developer | Develop your own relying-party UI |
| Security architect | Verification process and Security model |
| Standards engineer | OpenID4VP 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.
Related components
The credential verifier depends on three crates of this repository:
crates/ewqwe-openid4vpbuilds and validates OpenID4VP requests and matches DCQL queries.crates/ewqwe-digital-credentialbuilds and verifies mDoc and SD-JWT VC credentials.crates/ewqwe-credential-verifier-uiis 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.
| Component | Location | License |
|---|---|---|
| Credential verifier server and crates | crates/ | EUPL-1.2 |
| Verifier app (embedded SPA) | crates/ewqwe-credential-verifier-ui | EUPL-1.2 |
| Shared TypeScript library | typescript/ewqwe-digital-identity | MIT |
| Demo webapp | typescript/demo-webapp | MIT |
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
| Symptom | Cause | Action |
|---|---|---|
Every /api/v1 route returns 404 | The app is disabled. | Add the [verifier_ui] section with enabled = true, then restart. |
| The root URL returns 404 or a blank page | The SPA is not built, or the path is wrong. | Build the SPA and correct ui_dist_path. Check the server log. |
Bootstrap returns 409 Conflict | An administrator already exists. | Sign in instead of bootstrapping a second administrator. |
| The session ends after each restart | session_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
- The verifier app running, with an operator signed in. See Run the verifier app.
- A wallet that holds a Proof of Age credential. To set up a wallet, see Test with the age verification app or Test with the EUDI wallet.
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
| Status | Meaning |
|---|---|
pending | The wallet has not answered the request. |
received | The wallet returned a presentation. |
verified | The credential passed verification. |
failed | The credential failed verification. |
error | The transaction failed with an error. |
expired | The 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
| Symptom | Cause | Action |
|---|---|---|
The badge stays pending | The wallet did not scan the code. | Scan the code again, or generate a new code. |
| The QR code expires before the scan | The transaction passed its time to live. | Generate a new QR code. |
The result is failed | The credential failed a check. | Read the errors. An untrusted issuer is the common cause. |
QR generation returns 400 | The credential type is not allowed. | Check allowed_credential_types and the per-user types. |
| The wallet rejects the request | The 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 order | Location |
|---|---|
| 1 | credential-server.toml in the current working directory. |
| 2 | config.toml in the platform configuration directory. |
The platform configuration directory depends on the operating system:
| Platform | Directory |
|---|---|
| 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_keytls_params.server_certificatetls_params.server_ca_chaintls_params.client_ca_cert_chainopenid4vp_config.haip_config.x509_cert_pathopenid4vp_config.haip_config.x509_key_pathissuers_cas_dirattestation_issuer_certificateattestation_issuer_keyjournal_config.pathfor thesqlite_filebackend
Server parameters
The table below lists the top-level keys of the configuration file.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
host_name | string | Yes | — | IP address or host name to bind. |
host_port | integer | Yes | — | TCP port to bind. |
tls_params | table | Yes | — | TLS listener settings. See TLS and mutual TLS. |
openid4vp_config | table | Yes | — | OpenID4VP service settings. |
default_username | string | No | — | Accepted for compatibility. The server does not read this value. |
public_root_url | string | No | — | Public base URL of the server. |
issuers_cas_dir | string | No | issuers_cas | Directory of trusted credential issuer CA files. |
attestation_issuer_certificate | string | No | tls_params.server_certificate | PEM certificate for attestation signing. |
attestation_issuer_key | string | No | tls_params.server_private_key | PEM private key for attestation signing. |
disable_authentication | boolean | No | false | Bypass client certificate authentication. |
disabled_authentication_user | string | No | test | Username inserted when authentication is disabled. |
rust_log | string | No | — | Log filter string. |
tracing_config | table | No | See below | Logging settings. |
journal_config | table | No | Journal disabled | Verification journal settings. See Verification journal. |
verifier_ui | table | No | App disabled | Embedded 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:
| Priority | Source |
|---|---|
| 1 | verifier_ui.qr_code_callback_url |
| 2 | public_root_url |
| 3 | The 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 = truein production. The value removes the client certificate requirement from every relying-party endpoint.
TLS parameters
The [tls_params] table configures the TLS listener.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
server_private_key | string | Yes | — | Server private key in PKCS#8 PEM format. |
server_certificate | string | Yes | — | Server X.509 certificate in PEM format. |
server_ca_chain | string | Yes | — | CA chain in PEM format. |
client_ca_cert_chain | string | No | server_ca_chain | CA chain that validates client certificates. |
tls_cipher_suites | string | No | Mozilla intermediate v5 | Colon-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.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
transaction_ttl_secs | integer | No | 300 | Transaction lifetime in seconds. |
haip_config | table | No | — | JAR signing settings for the HAIP profile. |
transaction_store | table | No | sqlite_memory | Transaction 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.
| Key | Type | Required | Description |
|---|---|---|---|
x509_cert_path | string | Yes | Certificate chain PEM (leaf first) used to sign authorization requests. |
x509_key_path | string | Yes | Private 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 value | Required keys | Persistence | Notes |
|---|---|---|---|
sqlite_memory | None | No | Default. No file is created. |
sqlite_file | path | Yes | Persists across restarts. |
| Key | Type | Required | Description |
|---|---|---|---|
path | string | For sqlite_file | Filesystem 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.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
enabled | boolean | No | false | Turn journaling on or off. |
backend | string | No | sqlite_memory | Journal storage backend. |
path | string | For sqlite_file | — | Filesystem path to the SQLite journal file. |
url | string | For postgres | — | PostgreSQL connection URL. |
backend value | Persistence | Multi-instance |
|---|---|---|
sqlite_memory | No | No |
sqlite_file | Yes | No |
postgres | Yes | Yes |
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.
| Key | Type | Default | Description |
|---|---|---|---|
rust_log | string | — | Log filter string. Overrides the top-level rust_log and RUST_LOG. |
with_ansi_colors | boolean | false | Enable 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_secretis 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.
| Class | Endpoints | Client certificate |
|---|---|---|
| Relying party | /ewqwe_api/verify, /ewqwe_api/openid4vp/init, /ewqwe_api/openid4vp/status/{id}, /ewqwe_api/journal/*, /ewqwe_api/.well-known/issuer_certs | Required |
| Wallet | /ewqwe_api/openid4vp/direct_post, /ewqwe_api/openid4vp/request/{id}, /ewqwe_api/openid4vp/.well-known/jwks.json | Not required |
| Public | /version | Not 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
| Setting | Value |
|---|---|
| Maximum request payload | 1,000,000 bytes |
| Maximum JSON payload | 1,000,000 bytes |
| Keep-alive timeout | 120 seconds |
| Client request timeout | 10 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.
| Condition | Status | Body |
|---|---|---|
| Invalid request parameter | 400 | JSON string error message |
| Missing or failed authentication | 401 | JSON string error message |
| Any other failure | 500 | JSON string error message |
The OpenID4VP endpoints return a JSON object with an error field and these status codes.
| Condition | Status | Body |
|---|---|---|
| Unknown transaction | 404 | { "error": "<message>" } |
| Expired transaction | 410 | { "error": "<message>", "status": "expired" } |
| Invalid request | 400 | { "error": "<message>" } |
| Cryptographic failure | 500 | { "error": "Internal crypto error" } |
| Configuration failure | 500 | { "error": "credential verifier configuration: <message>" } |
| Internal failure | 500 | { "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.
| Field | Type | Required | Description |
|---|---|---|---|
vp_token | string | Yes | The VP token from the wallet. |
state | string | No | Transaction state used to look up the stored nonce and request context. |
client_id | string | No | Relying-party identifier used as the attestation audience. |
presentation_submission | object | No | Presentation 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.
| Field | Type | Present | Description |
|---|---|---|---|
success | boolean | Always | The verification result. |
message | string | Always | Human-readable result message. |
attestation | string | Always | Signed attestation JWT. See Attestations. |
verification_details | object | Always | Verification breakdown. See below. |
errors | array | On failure | Human-readable failure reasons. |
The verification_details object holds three boolean fields.
| Field | Type | Description |
|---|---|---|
signature_valid | boolean | The presentation signature is valid. |
not_expired | boolean | The credential is within its validity period. |
issuer_trusted | boolean | The issuer chain terminates at a trusted CA. |
Status codes
| Status | Condition |
|---|---|
200 | The server processed the presentation. Check success for the result. |
400 | The vp_token is malformed, the client_id disagrees with the transaction, the mDoc state is missing, or an mDoc check fails. |
401 | No authenticated user is present. |
500 | An 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.
| Field | Type | Required | Description |
|---|---|---|---|
dcql_query | object | No | Digital Credentials Query Language query. A default age query is used when omitted. |
nonce | string | No | Request nonce. The server generates one when omitted. |
state | string | No | Client state value. The server generates one when omitted. |
profile | string | No | Protocol profile, haip or annex-a. |
credential_type | string | No | Credential shorthand: mdl, national-id, proof-of-age, or france-identite-numerique. |
client_metadata | object | No | Relying-party metadata shown by the wallet. |
transaction_data | array | No | Base64url-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
| Field | Type | Present | Description |
|---|---|---|---|
transaction_id | string | Always | Identifier used for later status polling. |
client_id | string | Always | Constructed client identifier. |
client_id_scheme | string | Always | Client identifier scheme, for example x509_san_dns. |
request_uri | string | Always | URI where the wallet fetches the authorization request. |
authorization_request_uri | string | Always | Full authorization request URI for a QR code or deep link. |
expires_in | integer | Always | Seconds until the transaction expires. |
profile | string | Always | Selected protocol profile. |
qr_code_data_url | string | Cross-device | QR code as an image/svg+xml data URL. |
Status codes
| Status | Condition |
|---|---|
200 | The transaction was created. |
400 | The request body is invalid. |
401 | No authenticated user is present. |
500 | A 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.
| Parameter | Required | Description |
|---|---|---|
vp_token | For a plain response | The VP token. |
state | For a plain response | Transaction state echoed by the wallet. |
presentation_submission | No | Presentation submission string. |
response | For a JWE response (direct_post.jwt) | Encrypted authorization response. |
error | For a wallet error response | OpenID4VP error code. |
error_description | No | Human-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
| Status | Condition |
|---|---|
200 | The response was stored. |
400 | The body is malformed or the state is unknown. |
404 | No transaction matches the state. |
410 | The transaction has expired. |
500 | A 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
| Parameter | Type | Description |
|---|---|---|
id | string | The 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.
| Profile | Content type | Body |
|---|---|---|
| HAIP | application/oauth-authz-req+jwt | Signed JAR JWT. |
| Annex A | application/json | Plain authorization request JSON. |
Status codes
| Status | Condition |
|---|---|
200 | The request is returned. |
404 | The transaction is unknown. |
410 | The transaction has expired. |
500 | An internal failure occurred. |
GET /ewqwe_api/openid4vp/status/
Returns the status of a transaction. This endpoint requires a client certificate.
Path parameter
| Parameter | Type | Description |
|---|---|---|
id | string | The transaction identifier. |
Response body
| Field | Type | Present | Description |
|---|---|---|---|
status | string | Always | One of pending, received, verified, error, expired. |
expires_in | integer | When pending | Seconds until expiry. |
authorization_response | object | When received | The wallet authorization response. |
nonce | string | When received | Nonce from the original authorization request. |
transaction_data | array | When received | Transaction data from the original request. |
wallet_error | object | When the wallet returned an error | Wallet error code and description. |
error_message | string | On a server error | Server error description. |
The authorization_response object holds vp_token, state, and an optional presentation_submission.
The status value has the meanings below.
| Value | Meaning |
|---|---|
pending | Waiting for the wallet response. |
received | Wallet response received, not yet verified. |
verified | Credential verified successfully. |
error | Verification or processing failed. |
expired | Transaction TTL exceeded. |
Status codes
| Status | Condition |
|---|---|
200 | The status is returned. |
404 | The transaction is unknown. |
410 | The transaction has expired. |
500 | An 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.
| Key | Present | Purpose |
|---|---|---|
| JAR signing key | HAIP profile | Lets the wallet verify the signed authorization request. |
| Attestation verification key | Always | Lets 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
| Status | Condition |
|---|---|
200 | The 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
| Parameter | Type | Default | Description |
|---|---|---|---|
cert_pem | boolean | false | Include the PEM encoding of each certificate. |
Response body
| Field | Type | Description |
|---|---|---|
loaded | boolean | The server loaded at least one CA. |
count | integer | Number of trusted CA certificates. |
certs | array | One object per CA certificate. |
Each entry in certs holds these fields.
| Field | Type | Present | Description |
|---|---|---|---|
subject | string | Always | Certificate Subject Common Name. |
issuer | string | Always | Certificate Issuer Common Name. |
not_before | string | Always | Validity start. |
not_after | string | Always | Validity end. |
cert_pem | string | When cert_pem=true | Certificate in PEM encoding. |
Status codes
| Status | Condition |
|---|---|
200 | The certificate list is returned. |
401 | No 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 parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 20 | Maximum entries. The server caps the value at 1000. |
before | string | — | Return entries created strictly before this RFC 3339 timestamp. |
after | string | — | Return entries created strictly after this RFC 3339 timestamp. |
Each entry holds these fields.
| Field | Type | Description |
|---|---|---|
created_at | string | Entry creation time in RFC 3339 format. |
qrcode_app_user_email | string | Email of the verifier app user, when present. |
success | boolean | Whether the verification succeeded. |
claims | object | Flattened credential claims. |
GET /ewqwe_api/journal/{username}/verify
Recomputes every entry hash from the first entry and checks the chain.
| Field | Type | Description |
|---|---|---|
username | string | The journal owner. |
valid | boolean | true when every hash matches. |
entries_verified | integer | Number of entries checked. |
first_entry_hash | string | Hash of the first entry, when present. |
last_entry_hash | string | Hash of the current head, when present. |
error | string | Reason 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 parameter | Type | Default | Description |
|---|---|---|---|
before | string | — | Return entries created strictly before this RFC 3339 timestamp. |
after | string | — | Return entries created strictly after this RFC 3339 timestamp. |
limit | integer | All | Maximum entries. |
Unlike the /entries endpoint, the download returns the full journal entry, including the chain hash fields.
Journal status codes
| Status | Condition |
|---|---|
200 | The result is returned. |
401 | No authenticated user is present, or the username does not match. |
500 | The journal is disabled, or a storage failure occurred. |
GET /version
Returns the server version. This endpoint does not require a client certificate.
Response body
| Field | Type | Description |
|---|---|---|
version | string | The compiled credential verifier version. |
{
"version": "0.1.0"
}
Status codes
| Status | Condition |
|---|---|
200 | The 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.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
server_private_key | string | Yes | — | Server private key in PKCS#8 PEM format. |
server_certificate | string | Yes | — | Server X.509 certificate in PEM format. |
server_ca_chain | string | Yes | — | CA chain in PEM format. |
client_ca_cert_chain | string | No | server_ca_chain | CA chain that validates client certificates. |
tls_cipher_suites | string | No | Mozilla intermediate v5 | Colon-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 content | Minimum protocol version |
|---|---|
| TLS 1.3 suites only | TLS 1.3 |
| TLS 1.2 suites only | TLS 1.2 |
| Both groups | TLS 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
| Material | Encoding | Expected header |
|---|---|---|
| Private key | PKCS#8 PEM | -----BEGIN PRIVATE KEY----- |
| Certificate | X.509 PEM | -----BEGIN CERTIFICATE----- |
| CA chain | Concatenated X.509 PEM | One -----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.
| Order | Stage | Action |
|---|---|---|
| 1 | TLS handshake | Verify the client certificate chain against the client CA trust store. |
| 2 | Connection setup | Store the peer certificate on the connection. |
| 3 | SslAuth | Read the CN of the peer certificate and treat the CN as the username. |
| 4 | EnsureAuth | Require an authenticated username on a relying-party endpoint. |
| 5 | Handler | Read the username from the request context. |
The table below lists the outcomes.
| Condition | Result |
|---|---|
| Valid client certificate | Request proceeds with the username set to the certificate CN. |
| No client certificate on a relying-party endpoint | Status 401, unless disable_authentication is true. |
| Certificate not signed by a CA in the trust store | The TLS handshake fails. |
CN ends with * | Status 401. Wildcard usernames are rejected. |
| Certificate has no CN | Status 401. |
| CN is not valid UTF-8 | Status 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/.
| File | Purpose |
|---|---|
ewqwe.server.cert.pem | Server TLS certificate. CN ewqwe.acme.com. |
ewqwe.server.key.pem | Server TLS private key. |
ewqwe.server.fullchain.pem | Server leaf certificate and CA chain, used for the JAR x5c header. |
ewqwe.ca.pem | CA chain. The tests also use it as the client CA chain. |
ewqwe.root.key.pem | Root CA private key. |
ewqwe.user1.cert.pem | Client certificate for mutual TLS. CN user1.acme.com. |
ewqwe.user1.key.pem | Client private key that matches ewqwe.user1.cert.pem. |
ewqwe.user2.cert.pem | A 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/.
| File | Purpose |
|---|---|
ewqwe.signer.leaf.cert.pem | Attestation issuer certificate. CN ewqwe.acme.com. |
ewqwe.signer.leaf.key.pem | Attestation issuer private key. |
ewqwe.signer.leaf.fullchain.pem | Attestation issuer certificate and CA chain. |
ewqwe.signer.ca.pem | Attestation issuer CA certificate. |
ewqwe.signer.ca.key.pem | Attestation 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 = truesetting 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
| Header parameter | Value |
|---|---|
alg | ES256 |
kid | Base64url (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
| Claim | Type | Present | Description |
|---|---|---|---|
iss | string | Always | Issuer. The Subject Common Name (CN) of the attestation issuer certificate. |
sub | string | Always | Subject. The transaction identifier that triggered the attestation. |
aud | string | Always | Audience. The relying-party client_id. |
iat | integer | Always | Issued-at time as a Unix timestamp. |
exp | integer | Always | Expiration time as a Unix timestamp. |
nbf | integer | Always | Not-before time as a Unix timestamp. |
jti | string | Always | Unique attestation identifier in UUIDv4 format. |
verified | boolean | Always | The verification outcome. |
nonce | string | Optional | The nonce from the request. |
doc_type | string | Optional | The credential document type, for example org.iso.18013.5.1.mDL. |
namespace | string | Optional | The credential namespace, for example org.iso.18013.5.1. |
| credential claims | varies | Optional | The 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 thesuccessfield of the response as the authoritative verification result.
Validity
| Claim | Value |
|---|---|
iat | The time the server signs the attestation. |
exp | iat plus 300 seconds. |
nbf | iat 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.
| Part | Content |
|---|---|
| Protected header | The alg identifier and an optional key identifier. |
| Payload | The CBOR serialization of the attestation claims. |
| Signature | The 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.
| Format | Algorithm | Identifier | Description |
|---|---|---|---|
| JWT | ES256 | ES256 | ECDSA with the P-256 curve and SHA-256. |
| JWT | RS256 | RS256 | RSA PKCS#1 v1.5 with SHA-256. |
| COSE | ES256 | -7 | ECDSA with the P-256 curve and SHA-256. |
| COSE | RS256 | -257 | RSA PKCS#1 v1.5 with SHA-256. |
The POST /ewqwe_api/verify endpoint signs the attestation with ES256.
Signing keys
| Setting | Role |
|---|---|
attestation_issuer_certificate | The PEM certificate. Its CN becomes iss, and its public key verifies the attestation. |
attestation_issuer_key | The 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.
| Check | Action |
|---|---|
| Key retrieval | Fetch the JSON Web Key Set from GET /ewqwe_api/openid4vp/.well-known/jwks.json. |
| Key selection | Select the key whose kid matches the kid of the JWT header. |
| Signature | Verify the JWT signature with the public key of that key. |
| Audience | Compare the aud claim with the relying-party identifier. |
| Validity window | Compare the exp and nbf claims with the current time. |
| Claim extraction | Read 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:
| Value | Input |
|---|---|
attestation_signature_hash | The raw bytes of the attestation JWT. |
entry_hash | The 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.
| Backend | Persistence | Multi-instance | Notes |
|---|---|---|---|
sqlite_memory | No | No | Default. Useful for development and tests. |
sqlite_file | Yes | No | Single instance with persistence. |
postgres | Yes | Yes | Recommended 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.
| Order | Operation |
|---|---|
| 1 | Read the current head hash for the username. |
| 2 | Compute the entry hash from that head. |
| 3 | Append the entry, but only when the stored head still matches the value read in operation 1. |
Each backend serializes the read-check-write section.
| Backend | Serialization |
|---|---|
| SQLite | A process-level mutex, held across an exclusive database transaction. |
| PostgreSQL | A 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.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
enabled | boolean | No | false | Turn journaling on or off. |
backend | string | No | sqlite_memory | Storage backend. |
path | string | For sqlite_file | — | Filesystem path to the SQLite journal file. |
url | string | For 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.
| Field | Type | Description |
|---|---|---|
id | string | Surrogate primary key in UUIDv4 format. |
username | string | Authenticated username. The Common Name of the client certificate. |
previous_hash | string | Hash of the preceding entry. Absent for the first entry. |
entry_hash | string | Chain hash of this entry, hex-encoded SHA-256. |
attestation_signature_hash | string | SHA-256 of the raw attestation JWT bytes, hex-encoded. |
attestation_jti | string | The jti claim of the signed attestation. |
client_id | string | The relying-party client_id bound to the verification. |
doc_type | string | Credential document type, for example org.iso.18013.5.1.mDL. |
namespace | string | Credential namespace, for example org.iso.18013.5.1. |
qrcode_app_user_id | string | Verifier app user identifier, when the verifier app started the verification. |
qrcode_app_user_email | string | Verifier app user email, when the verifier app started the verification. |
verification_summary | object | JSON summary of the verification outcome. |
created_at | string | Creation 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.
| Method | Path | Description |
|---|---|---|
| GET | /ewqwe_api/journal/{username}/entries | List recent entries, newest first. |
| GET | /ewqwe_api/journal/{username}/verify | Verify the full chain integrity. |
| GET | /ewqwe_api/journal/{username}/download | Download 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.
| Field | Type | Description |
|---|---|---|
username | string | The journal owner. |
valid | boolean | true when every entry verifies from the first entry to the head. |
entries_verified | integer | Number of entries that the server checked. |
first_entry_hash | string | Hash of the first entry, when present. |
last_entry_hash | string | Hash of the current head, when present. |
error | string | Human-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/v1scope; - 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.
| Method | Path | Access | Description |
|---|---|---|---|
| GET | /api/v1/setup/status | public | Report whether the first administrator exists. |
| POST | /api/v1/setup/bootstrap | public | Create the first administrator account. |
| POST | /api/v1/auth/login | public | Sign in and set the session cookie. |
| POST | /api/v1/auth/logout | session | End the session. |
| GET | /api/v1/auth/me | session | Return the signed-in user profile. |
| GET | /api/v1/settings | public | Return the app name, the logo URL, and the allowed types. |
| POST | /api/v1/qr/generate | session | Start a transaction and return a QR code. |
| GET | /api/v1/qr/{id}/status | session | Return the status of a transaction. |
| GET | /api/v1/admin/users | admin | List user accounts. |
| POST | /api/v1/admin/users | admin | Create a user account. |
| PUT | /api/v1/admin/users/{id} | admin | Update a user account. |
| DELETE | /api/v1/admin/users/{id} | admin | Delete a user account. |
| GET | /api/v1/admin/journal | admin | List journal entries for the app users. |
| PUT | /api/v1/admin/settings | admin | Update the display settings. |
| GET | /api/v1/i18n | public | Return locale strings for one language. |
| GET | / | public | Serve the SPA entry page. |
| GET | /assets/* | public | Serve the bundled JavaScript and CSS assets. |
| GET | /logo.png | public | Serve 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
}
| Status | Meaning |
|---|---|
pending | The wallet has not answered the request. |
received | The wallet returned a presentation. |
verified | The credential passed verification. |
failed | The credential failed verification. |
error | The transaction failed with a processing error. |
expired | The 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.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true when the section exists | Serve the app. |
app_name | string | Verifier App | Display name in the header. |
logo_url | string | built-in logo | HTTPS URL or data: URL for the header logo. |
qr_code_callback_url | string | public_root_url | Base URL for the wallet callback URIs. |
allowed_credential_types | array of strings | all types | Credential types that this server allows. |
session_secret | string | random key at startup | Secret for signing session cookies. |
ui_dist_path | string | none | Directory that holds the built SPA. |
db | table | sqlite_memory | User 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.
| Backend | Persistence | Extra keys | Use |
|---|---|---|---|
sqlite_memory | none | none | Development and testing. |
sqlite_file | file | path | A single instance with persistence. |
Roles
| Role | Permissions |
|---|---|
admin | User management, settings, journal, and QR codes. |
verifier | QR 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 type | Profile | Document type |
|---|---|---|
proof-of-age | Annex A (EU age verification) | eu.europa.ec.av.1 |
mdl | HAIP | org.iso.18013.5.1.mDL |
national-id | HAIP | eu.europa.ec.eudi.pid.1 |
france-identite-numerique | HAIP | eu.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.
| Code | Language |
|---|---|
en | English |
de | German |
fr | French |
it | Italian |
es | Spanish |
sv | Swedish |
pl | Polish |
cs | Czech |
hr | Croatian |
Related pages
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
| Parameter | Required | Description | Value in the age verification profile |
|---|---|---|---|
response_type | Yes | Requests a verifiable presentation token. | vp_token |
client_id | Yes | Identifies the relying party. The value carries a scheme prefix. See Client identifier schemes. | redirect_uri: followed by the response URI |
nonce | Yes | A random value that binds the presentation to this one transaction. | A fresh random string for every request |
response_mode | Yes | Selects how the wallet returns the authorization response. See Response modes. | direct_post |
response_uri | Conditional | The endpoint that receives the wallet POST. Required when response_mode is direct_post. | An HTTPS URL on the relying party |
dcql_query | Conditional | The query for the credentials and claims. See DCQL queries. | A DCQL JSON object |
state | No | An opaque value that correlates the response with the request. | A random string, or omitted |
presentation_definition | Conditional | A DIF Presentation Exchange query. OpenID4VP accepts this field or dcql_query, but not both. | Not used |
client_metadata | No | Metadata about the relying party, such as a display name and the supported presentation formats. | Omitted |
scope | No | OpenID Connect scopes. | Not used |
redirect_uri | No | A 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
nonceandstatevalues 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.
| Scheme | Identifier format | Signed request | Trust mechanism | Profile |
|---|---|---|---|---|
redirect_uri: | The prefix plus the response URI, for example redirect_uri:https://rp.example.com/callback. | No | TLS and the web PKI | EU 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 header | The DNS subject alternative name of a certificate | HAIP (EUDI Wallet) |
x509_hash: | The prefix plus a certificate hash. | Yes, a JAR signed with an x5c header | The hash of an X.509 certificate | HAIP (EUDI Wallet) |
verifier_attestation: | The prefix plus an attested identifier, for example verifier_attestation:my-verifier. | Yes, a JAR signed with a jwt header | A JWT from a trusted attestation issuer | HAIP (optional) |
| No prefix (pre-registered) | The identifier alone. | Optional | Pre-configured in the wallet | Custom 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.
| Mode | Description | Use |
|---|---|---|
fragment | The wallet returns the VP token in the URL fragment. | Same-device flows. Not used by the age verification profile. |
direct_post | The wallet posts the VP token to the response_uri. | Cross-device flows. Required by the age verification profile. |
direct_post.jwt | The wallet posts an encrypted JWT to the response_uri. | Optional privacy extension. Used by HAIP. |
The av:// application link scheme
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:
| Parameter | Decoded value |
|---|---|
response_type | vp_token |
response_mode | direct_post |
client_id | redirect_uri:https://rp.example.com/ewqwe_api/openid4vp/direct_post |
response_uri | https://rp.example.com/ewqwe_api/openid4vp/direct_post |
nonce | tMQ3X8j5LwnKpZiHvRqCaA |
state | A7kB2mN9xYzL4pWqRsGtUj |
dcql_query | The 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.
| Parameter | Required | Description |
|---|---|---|
vp_token | Yes | Carries 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_submission | No | Maps the presentation to the request. The wallet does not send this field with a DCQL query. |
state | No | An echo of the state value from the request. |
Related pages
- For the query structure and examples, see DCQL queries.
- For the reasons behind the protocol choice, see Protocol modes.
- For recurring questions, see the OpenID4VP FAQ.
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.
| Field | Required | Description |
|---|---|---|
credentials | Yes | The list of credential queries. |
credential_sets | No | Groups of alternative credential queries. The wallet satisfies the query when it can satisfy one complete option. |
id | Yes | The identifier of one credential query. The authorization response uses this identifier as a key. |
format | Yes | The credential format. Age verification uses mso_mdoc, which means an ISO mobile document such as a mobile driving licence or a proof of age. |
meta | Yes for mso_mdoc | Format-specific metadata. An mso_mdoc query names the document type in doctype_value. |
claims | Yes | The claims to request from the credential. |
claim_sets | No | Alternative combinations of claims. A claim query needs an id only when a claim_sets entry references it. |
path | Yes | The location of one claim. The first element is the namespace and the second element is the claim name. |
values | No | The permitted values for a claim. The wallet returns the claim only when its value appears in this list. |
intent_to_retain | No | Whether 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.
| Namespace | Description | Document type |
|---|---|---|
eu.europa.ec.av.1 | The EU Age Verification namespace (proof of age). | eu.europa.ec.av.1 |
org.iso.18013.5.1 | The 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.
Related pages
- For the surrounding request parameters, see OpenID4VP authorization request parameters.
- For the credential types that the queries address, see Credential types.
- For how a wallet discloses only the requested claims, see Selective disclosure.
- For recurring questions, see the OpenID4VP FAQ.
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.
| Annex | Name | Transport | Wallet adoption |
|---|---|---|---|
| A | REST API (device retrieval) | HTTP POST with raw CBOR | None of the major wallets |
| B | OpenID4VP (online presentation) | openid4vp:// URIs, direct_post | All major EUDI wallets |
| C | W3C Digital Credentials API | navigator.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.
| Aspect | Detail |
|---|---|
| Invocation | HTTP POST directly to a wallet endpoint or a proxy |
| Request | CBOR DeviceRequest (ISO 18013-5) |
| Response | CBOR DeviceResponse |
| Encryption | Network-layer session encryption (no standardised protocol) |
| Trust | No global trust list; the verifier authenticates over TLS |
| Developer effort | CBOR parsing, COSE cryptography, and session key establishment at the network layer |
| Wallet support | None. 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
| Aspect | Detail |
|---|---|
| Invocation | Universal or deep links (openid4vp://), request_uri fetch, or an HTTP direct_post |
| Request | DCQL query (JSON); the legacy Presentation Exchange format is supported as a fallback |
| Response | A vp_token that carries an mDoc or an SD-JWT, optionally JWE-encrypted (direct_post.jwt) |
| Request signing | JAR (JWT Secured Authorization Request, RFC 9101) |
| Trust model | The verifier identity is proven by an X.509 certificate or by redirect URI matching |
| Developer effort | JWT and JWE handling, DCQL evaluation, and OpenID4VP state management |
| Wallet support | All 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
| Aspect | Detail |
|---|---|
| Invocation | Browser API: navigator.credentials.get({ digital: ... }) |
| Request payload | ["dcapi", { nonce, recipientPublicKey }] plus a CBOR DeviceRequest |
| Response payload | An HPKE-encrypted mDoc inside ["dcapi", { enc, cipherText }] |
| Encryption | HPKE (X25519, HKDF-SHA256, AES-128-GCM) |
| Transport | The browser and the operating system handle wallet invocation, including cross-device relay |
| Trust model | Trust is based on web origins and platform-verified app links |
| Developer effort | Low. The browser handles wallet discovery and session binding |
| Wallet support | All 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_urischeme, no JAR, and a plaindirect_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_dnsorx509_hash) and JWE-encrypted responses (direct_post.jwt).
References
- ISO/IEC 18013-5:2021 — mDL data model
- ISO/IEC 18013-7:2025 — mDoc online presentation
- OpenID4VP 1.0
- Full reference list
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.
| Property | mso_mdoc | dc+sd-jwt |
|---|---|---|
| DCQL format id | "mso_mdoc" | "dc+sd-jwt" |
| Type identifier | docType, a CBOR text string | vct, a URI claim |
| DCQL claim path | [namespace, claim name] | [claim name] |
| Encoding | CBOR (RFC 8949) | JSON |
| Signature type | COSE | JWS |
| Algorithm id | COSE integer, for example -7 for ES256 | JOSE string, for example "ES256" |
| DCQL metadata | meta.doctype_value | meta.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.
nameSpacesholds the disclosed claims asIssuerSignedItementries.issuerAuthis aCOSE_Sign1structure 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 acceptdeviceMac(aCOSE_Mac0value).
Verification steps
The verifier performs the following checks for an mDoc presentation, in order.
- Decode the Base64URL or Base64 value to CBOR, parse the
DeviceResponse, and select the firstDocument. - Extract
issuerAuth, verify thex5chaincertificate chain against the trusted issuer CAs, and verify the issuer signature over the MSO payload. - Parse the MSO, and check that the MSO
docTypematches theDocumentdocType. - For each disclosed
IssuerSignedItem, recompute the digest and compare it withvalueDigests[namespace][digestID]. - Reconstruct the
SessionTranscriptfromclient_id,nonce,response_uri, and the response mode. BuildDeviceAuthenticationBytes, and verifydeviceSignaturewith the MSO device key. - Check the MSO validity window (
validFromandvalidUntil) against the current time.
The COSE algorithms that the verifier supports for the mDoc signatures are listed below.
| COSE algorithm id | Name | Description |
|---|---|---|
-7 | ES256 | ECDSA with P-256 and SHA-256 |
-35 | ES384 | ECDSA with P-384 and SHA-384 |
-36 | ES512 | ECDSA with P-521 and SHA-512 |
-257 | RS256 | RSA with PKCS#1 v1.5 padding and SHA-256 |
-258 | RS384 | RSA with PKCS#1 v1.5 padding and SHA-384 |
-259 | RS512 | RSA 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.
- Split the string at each
~character into the issuer JWT, the disclosures, and the optional KB-JWT. - Read the issuer JWT header. Extract the leaf key from
x5c[0], and validate the certificate chain against the trusted issuer CAs. - Verify the issuer JWT signature with that key.
- For each presented disclosure, recompute the digest and check that it appears in the
_sdarray, recursively for nested objects. - Verify the KB-JWT signature with the holder key from
cnf.jwk. - Compare the KB-JWT
noncewith the nonce of the transaction, and check the validity time (exp).
Format comparison
The table below summarizes the differences between the two formats.
| Property | mso_mdoc | dc+sd-jwt |
|---|---|---|
| Container | DeviceResponse | JWT and disclosures joined by ~ |
| Encoding | CBOR, binary | JSON, base64url |
| Issuer signature | COSE_Sign1 | JWS |
| Issuer chain header | x5chain, label 33 | x5c |
| Selective disclosure | One salted digest per claim in the MSO | One salted digest per claim in _sd |
| Holder binding | deviceSignature over the session | KB-JWT |
| Session binding | SessionTranscript | nonce and aud in the KB-JWT |
| Credentials per presentation | One or more (documents array) | One |
| Primary standard | ISO/IEC 18013-5 | IETF SD-JWT VC |
Related topics
- Credential types describes the doc types, namespaces, and claims of the supported credentials.
- Selective disclosure explains the privacy effect of the disclosure mechanisms.
- DCQL queries describes how a request names a format and a type.
- Issue a test credential shows how to build a credential in either format.
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_queryfield of the transaction request. The query setsmeta.doctype_valueformso_mdocandmeta.vct_valuesfor SD-JWT VC. - A shorthand in the
credential_typefield of the transaction request. The verifier acceptsproof-of-age,mdl, andnational-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.
| Property | Value |
|---|---|
| docType | org.iso.18013.5.1.mDL |
| Namespace | org.iso.18013.5.1 |
| Format | mso_mdoc |
| Standard | ISO/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 identifier | Description | Presence | Encoding |
|---|---|---|---|
family_name | Current family name or surname | Mandatory | tstr, UTF-8, maximum 150 chars |
given_name | Current first name, including middle names | Mandatory | tstr |
birth_date | Date of birth | Mandatory | full-date, RFC 8943, tag 1004 |
portrait | Facial image of the holder | Mandatory | bstr, JPEG, ISO 19794-5 |
issue_date | Date of issuance | Mandatory | tdate or full-date |
expiry_date | Date of expiry | Mandatory | tdate or full-date |
issuing_authority | Authority that issued the document | Mandatory | tstr |
issuing_country | Country code, ISO 3166-1 alpha-2 | Mandatory | tstr |
document_number | Unique document identifier | Optional | tstr |
driving_privileges | Vehicle categories and restrictions | Mandatory | Complex type |
un_distinguishing_sign | UN distinguishing sign of the issuing country | Optional | tstr |
administrative_number | Administrative number for the document | Optional | tstr |
sex | Sex, 0 unknown, 1 male, 2 female, 9 not applicable | Optional | uint |
height | Height in centimetres | Optional | uint |
weight | Weight in kilograms | Optional | uint |
eye_colour | Eye colour | Optional | tstr |
hair_colour | Hair colour | Optional | tstr |
birth_place | Place of birth | Optional | tstr |
resident_address | Current address | Optional | tstr |
resident_city | City of residence | Optional | tstr |
resident_state | State or province of residence | Optional | tstr |
resident_postal_code | Postal code | Optional | tstr |
resident_country | Country of residence, ISO 3166-1 alpha-2 | Optional | tstr |
age_over_18 | Whether the holder is over 18 | Optional | bool |
age_over_21 | Whether the holder is over 21 | Optional | bool |
age_over_NN | Whether the holder is over NN years | Optional | bool |
age_in_years | Age in years | Optional | uint |
age_birth_year | Year of birth | Optional | uint |
nationality | Nationality | Optional | tstr |
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.
| Property | Value |
|---|---|
| docType | eu.europa.ec.eudi.pid.1 |
| Namespace | eu.europa.ec.eudi.pid.1 |
| vct | urn:eudi:pid:1 |
| Formats | mso_mdoc and dc+sd-jwt |
| Standard | CIR 2024/2977, EU ARF PID Rulebook |
Mandatory attributes
| Data identifier | ISO attribute id | SD-JWT claim | Description | Encoding (ISO) | Encoding (SD-JWT) |
|---|---|---|---|---|---|
family_name | family_name | family_name | Current surname | tstr | string |
given_name | given_name | given_name | Current first and middle names | tstr | string |
birth_date | birth_date | birthdate | Date of birth, YYYY-MM-DD | full-date | string, ISO 8601-1 |
birth_place | place_of_birth | place_of_birth | Place of birth | place_of_birth | JSON object |
nationality | nationality | nationalities | Nationality, ISO 3166-1 alpha-2 | nationalities | array of strings |
Optional attributes
| Data identifier | SD-JWT claim | Description | Encoding (ISO) | Encoding (SD-JWT) |
|---|---|---|---|---|
resident_address | address.formatted | Full current address | tstr | string |
resident_country | address.country | Country of residence | tstr | string |
resident_state | address.region | State or province | tstr | string |
resident_city | address.locality | City or town | tstr | string |
resident_postal_code | address.postal_code | Postal code | tstr | string |
resident_street | address.street_address | Street name | tstr | string |
resident_house_number | address.house_number | House number | tstr | string |
personal_administrative_number | personal_administrative_number | Unique PID number | tstr | string |
portrait | picture | Facial image, JPEG, ISO 19794-5 | bstr | data URL, base64 |
family_name_birth | birth_family_name | Surname at birth | tstr | string |
given_name_birth | birth_given_name | First name at birth | tstr | string |
sex | sex | Sex, 0 to 9, see ISO 5218 | uint | number |
email_address | email | Email address, RFC 5322 | tstr | string |
mobile_phone_number | phone_number | Mobile phone with country code | tstr | string |
Mandatory metadata
| Data identifier | SD-JWT claim | Description |
|---|---|---|
expiry_date | date_of_expiry | Administrative expiry date |
issuing_authority | issuing_authority | Issuing authority name |
issuing_country | issuing_country | Issuing country, ISO 3166-1 alpha-2 |
Optional metadata
| Data identifier | SD-JWT claim | Description |
|---|---|---|
document_number | document_number | PID document number |
issuing_jurisdiction | issuing_jurisdiction | Jurisdiction, ISO 3166-2 |
issuance_date | date_of_issuance | Date 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_18andage_over_21in 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.
| Property | Value |
|---|---|
| docType | eu.europa.ec.av.1 |
| Namespace | eu.europa.ec.av.1 |
| Format | mso_mdoc only |
| Standard | EU Age Verification Profile |
The table below lists the attributes of the eu.europa.ec.av.1 namespace.
| Attribute identifier | Description | Presence | Encoding |
|---|---|---|---|
age_over_18 | Whether the holder is over 18 | Mandatory | bool |
The proof of age attestation uses the following protocols.
| Step | Protocol | Detail |
|---|---|---|
| Issuance | OpenID for Verifiable Credential Issuance | Credential configuration id proof_of_age |
| Presentation, primary | W3C Digital Credentials API | ISO/IEC 18013-7 Annex C |
| Presentation, fallback | OpenID4VP with response_mode=direct_post | Annex 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.
Related topics
- Credential formats describes the structure and the verification steps of both formats.
- DCQL queries describes how a request names a credential type.
- Issue a test credential shows how to build a credential of these types.
- Glossary defines the abbreviations used on this page.
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.
| Question | Check |
|---|---|
| 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 storedclient_id,nonce, andresponse_uri, and for encrypted responses also from the JWK thumbprint of the encryption key. TheDeviceSignaturethen 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 format | Issuer check | Holder binding check |
|---|---|---|
| SD-JWT VC | The x5c header of the issuer JWT, missing is a rejection | The Key Binding JWT, verified with the key in cnf.jwk |
| mDoc | The IssuerAuth COSE_Sign1 and its x5chain | The 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.
| Party | Owns |
|---|---|
| User | Approves or denies each request on the wallet. |
| Wallet | Stores credentials and builds the presentation. |
| Relying party | Decides why it needs the proof and what to do with the result. |
| Credential verifier | Runs 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.
| Aspect | Age Verification App (Annex A) | EUDI Wallet (HAIP) |
|---|---|---|
| Profile | EU Age Verification Profile | High Assurance Interoperability Profile |
| Typical credentials | Proof of age | Personal identity data and mobile driving licence |
| Client identifier | The redirect URI of the verifier | A DNS name from the verifier certificate |
| Request signing | Not required | Required, as a signed JWT |
| Response mode | Plain direct_post | Encrypted direct_post.jwt |
| Trust model | The verifier is known by its callback | The 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://oreudi-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 = trueonly 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
deviceMacholder proof is rejected; onlydeviceSignatureis 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
| Aspect | W3C Digital Credentials API | OpenID4VP |
|---|---|---|
| Invocation | navigator.credentials.get() with the digital option | The av:// link scheme |
| Response delivery | A JavaScript promise inside the page | An HTTP POST to the response_uri |
| Cross-device support | Limited, and it needs a workaround | Native, through a QR code |
| Browser support | Chrome with a flag, limited | Universal, because the operating system handles the link scheme |
| Request format | Base64url CBOR per ISO/IEC 18013-7 | Query parameters with a DCQL JSON query |
| Response format | Base64url CBOR, encrypted with HPKE | A JWT or CBOR, with no encryption required |
| Primary use case | Same-device, browser-native | Cross-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.
| Property | Same-device flow | Cross-device flow |
|---|---|---|
| Devices | One device for the relying party and the wallet | Two devices, typically a desktop and a phone |
| Invocation | The user opens the av:// link directly | The user scans a QR code |
| Response delivery | An HTTP POST to the response_uri | An HTTP POST to the response_uri |
| Result notification | A redirect of the browser | Polling 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.
Related pages
- For the request parameters of the fallback, see OpenID4VP authorization request parameters.
- For the query that both protocols carry, see DCQL queries.
- To test the fallback against a wallet, see Test with the EUDI Wallet and Test with the age verification app.
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.
Related topics
- Credential formats lists the exact structures and the verification steps.
- Credential types lists the claims of each credential type.
- Issue a test credential shows how to build a credential for a test.
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
-
Build the server. Run the command from the
crates/ewqwe-credential-verifier-serverdirectory.cd crates/ewqwe-credential-verifier-server cargo build --releaseThe workspace writes the binary to
target/release/ewqwe_credential_verifier_serverat the repository root. -
Create the configuration file. Write a file named
credential-server.tomlin thecrates/ewqwe-credential-verifier-serverdirectory 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.
| Setting | Purpose |
|---|---|
host_name, host_port | The address and port on which the server listens. |
issuers_cas_dir | The directory of trusted issuer CA certificates. It must exist. |
attestation_issuer_certificate | The certificate whose common name becomes the iss claim. |
attestation_issuer_key | The 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.
-
Start the server. Run the built binary, or use Cargo.
cargo run --releaseTo use a configuration file at another location, pass its path as the first argument.
cargo run --release -- /etc/ewqwe/credential-server.tomlWhen you pass no path, the server searches these locations in order and uses the first file that exists.
./credential-server.tomlin the current directory.- The platform configuration directory:
$HOME/Library/Application Support/ewQwe/Credential Server/config.tomlon macOS,$XDG_CONFIG_HOME/ewQwe/Credential Server/config.tomlor$HOME/.config/ewQwe/Credential Server/config.tomlon Linux, and%APPDATA%\ewQwe\Credential Server\config.tomlon Windows.
-
Read the startup output. The server logs its progress when
rust_logis set toinfoor 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:9443The server also logs the whole loaded configuration as one structured line at info level. If the log shows a
Credentials issuers CA directory not founderror, the server stops before it binds the port. -
Check that the server answers. The
/versionendpoint does not require a client certificate.curl -sk https://localhost:9443/versionExpected output:
{ "version": "0.1.0" } -
Stop the server with
Ctrl+C. The server logsServer shut down gracefully.
Troubleshooting
- The server stops with
No configuration file found. Searched: .... Createcredential-server.tomlin 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 byissuers_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 fileor 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. Changehost_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
- Secure the listener with configure TLS.
- Choose the stores with configure storage.
- Send a request with verify a credential.
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
-
Prepare the three PEM files and note their paths. Each path is resolved against the directory that contains
credential-server.toml. -
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.
| Field | Required | Content |
|---|---|---|
server_private_key | Yes | The server private key, in PKCS#8 PEM format. |
server_certificate | Yes | The server certificate, in X.509 PEM format. |
server_ca_chain | Yes | The CA chain, as one or more PEM certificates. |
client_ca_cert_chain | No | The CA chain that signs client certificates, for mutual TLS. |
-
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 -
Test the server certificate. The
/versionendpoint requires no client certificate.curl -sk https://localhost:9443/versionExpected output:
{ "version": "0.1.0" }If
curlreports 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 providesdemo.ewqwe.local,localhost, and127.0.0.1.
Configure mutual TLS
-
Add the
client_ca_cert_chainfield 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 againstserver_ca_chaininstead. -
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" -
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/entriesExpected output, when the client owns no journal entries yet:
[] -
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_apithat 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.jsonrequire no client certificate, because a wallet has no certificate from the verifier client CA. - The
/versionendpoint 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_authenticationsetting 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
curlreports 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-kfor a local test.- The protected call returns
401 Unauthorizedwith the bodyAuthentication required. The request carried no client certificate anddisable_authenticationis false. Pass--certand--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 Unauthorizedwith 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 Unauthorizedwith 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
- Choose the transaction store and the journal backend in configure storage.
- Read the endpoint list in the HTTP API reference.
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].
| Backend | backend value | Persistence | Multi-instance | Use it for |
|---|---|---|---|---|
| SQLite in memory | sqlite_memory | No, lost on restart | No | Development and tests |
| SQLite file | sqlite_file | Yes | No | A single production instance |
-
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
pathis resolved against the directory that contains the configuration file. -
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 = 300Set 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.
| Backend | backend value | Persistence | Multi-instance |
|---|---|---|---|
| SQLite in memory | sqlite_memory | No, lost on restart | No |
| SQLite file | sqlite_file | Yes | No |
| PostgreSQL | postgres | Yes | Yes |
-
Add a
[journal_config]section and setenabled = 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
pathis resolved against the directory that contains the configuration file. -
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 disabledin 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.
-
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" -
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/verifyExpected output for an intact chain:
{ "username": "user1.acme.com", "valid": true, "entries_verified": 1, "first_entry_hash": "0000...", "last_entry_hash": "c2d9...", "error": null } -
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
pathdoes 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_memorybackend does not persist. Usesqlite_fileorpostgresto 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
- A running verifier with mutual TLS enabled. See install and run the server and configure TLS.
- A client certificate that the verifier trusts. The examples use
certificates/tls/ewqwe.user1.cert.pem. - A wallet that can present a credential to the verifier, such as the EUDI Wallet or the AV app. See test with the EUDI wallet or test with the AV app.
jqfor the JSON extraction steps.
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:
| Step | Endpoint | Who calls it | What it does |
|---|---|---|---|
| Create a transaction | POST /ewqwe_api/openid4vp/init | Relying party | Stores the nonce and the request. |
| Read the transaction | GET /ewqwe_api/openid4vp/status/{id} | Relying party | Returns the presentation from the wallet. |
| Verify the presentation | POST /ewqwe_api/verify | Relying party | Runs 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
-
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. Thestatevalue 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.jsonExpected 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" } -
Extract the transaction values for later steps.
TRANSACTION_ID="$(jq -r .transaction_id init.json)" CLIENT_ID="$(jq -r .client_id init.json)" -
Present the credential with a wallet. Give the wallet the
authorization_request_urifrom the previous response, as a QR code or as a deep link. The wallet sends the presentation to the verifierresponse_uri, and the verifier stores it in the transaction. Follow test with the EUDI wallet or test with the AV app for this step. -
Read the transaction status. Repeat this call until
statusisreceived.curl -sk --cert "$CERT" --key "$KEY" \ "$BASE/ewqwe_api/openid4vp/status/$TRANSACTION_ID" | tee status.jsonExpected 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
statusvalue ispendinguntil the wallet answers, and thenreceived. A wallet that sends an error response instead of a presentation sets the status toerror. -
Extract the presentation and the state.
STATE="$(jq -r .authorization_response.state status.json)" VP_TOKEN="$(jq -r .authorization_response.vp_token status.json)" -
Send the presentation for verification. The
statemust match the transaction, and theclient_idmust 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.jsonExpected 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
400with 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
200withsuccessfalse, 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"] } -
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
issclaim is the common name of the attestation signing certificate. Thejticlaim is unique to this attestation, so you can use it as an idempotency key. -
Verify the attestation signature. The JWKS endpoint is public and returns the attestation key together with the
kidthat appears in the JWT header.curl -sk "$BASE/ewqwe_api/openid4vp/.well-known/jwks.json"Select the key whose
kidequals thekidof the attestation, and verify the JWT signature with that key. For the claim list, see attestations. -
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
400withstate 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--certand--key. - The response is
404with{"error": "..."}. The transaction id is unknown, or you created the transaction against another server instance. - The response is
410 Gone. The transaction exceededtransaction_ttl_secsand expired. Create a new transaction. - The response is
400withclient_id does not match the transaction-bound request. Send theclient_idvalue from the init response. - The response is
400withstate is required for mDoc verification. An mDoc presentation needs the transaction, so includestate. - The response is
400with an untrusted-issuer message. The issuer CA of the credential is not inissuers_cas_dir. Add the CA file and restart the server, because the directory is read only at startup. - The response is
400with a decode message. Thevp_tokenis not a valid SD-JWT VC, mDocDeviceResponse, or direct JSON presentation. Check that you copied the value without truncation. successisfalsewith a nonce mismatch error. The presentation does not belong to the transaction thatstatenames. Use thevp_tokenand thestatefrom the same status response.- The status stays
pending. The wallet did not reach theresponse_uri. Check that the wallet can reachpublic_root_urland that the wallet trusts the server certificate. - The response is
500and the log shows a journal error. The checks passed but the journal write failed. See configure storage.
Next steps
- Read the endpoint reference in the HTTP API reference.
- Read the check sequence in the verification process.
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
- A running credential verifier. See Install and run the server.
- Node.js 18 or later and pnpm, to run the example.
- A wallet that holds a credential. See Test with the age verification app or Test with the EUDI wallet.
Choose an interface
| Interface | Use it when |
|---|---|
| The verifier app | You want the standard interface, with no extra development. |
| Your own UI, with the HTTP API | You want your own layout, integrated in your own product. |
| The example relying party | You 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.
- Start a transaction with the OpenID4VP init endpoint.
- 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.
- Receive the verifiable presentation. The wallet either posts the presentation directly, or your interface collects it and sends it to the verifier.
- Ask the credential verifier to verify the presentation. See Verify a credential.
- 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.
| Path | Contents |
|---|---|
typescript/demo-webapp/vite.config.ts | The Vite configuration and the reverse proxy. |
typescript/demo-webapp/index.html | The HTML entry page. |
typescript/demo-webapp/src/main.ts | The entry point that starts the application. |
typescript/demo-webapp/src/relying_party_app.ts | The relying-party application logic. |
typescript/demo-webapp/src/credentials.ts | The credential request and verification logic. |
typescript/demo-webapp/src/dc_api_service.ts | The W3C Digital Credentials API integration. |
typescript/demo-webapp/src/hpke.ts | The HPKE decryption helper for the Annex C flow. |
typescript/demo-webapp/src/debug.ts | The debug helpers. |
typescript/demo-webapp/package.json | The 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:
| Variable | Default | Purpose |
|---|---|---|
CREDENTIAL_VERIFIER_URL | https://127.0.0.1:9443 | The 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.
- 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.
- Bind each request to a transaction. Never invent the nonce in the browser. Read the nonce and the
statefrom the transaction that the verifier created, and send thatstateback with the presentation. - 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
expclaim. See Attestations. - 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. - Handle every status. A transaction can expire, and a presentation can fail a check.
Troubleshooting
| Symptom | Cause | Action |
|---|---|---|
| The dev server cannot reach the verifier | The verifier is not running, or the URL is wrong. | Start the verifier and check CREDENTIAL_VERIFIER_URL. |
| Every request returns 404 | The verifier does not serve the path. | Check the base URL of the verifier. |
| The verifier rejects the presentation | The nonce or the state does not match. | Read the nonce and the state from the stored transaction. |
| The browser shows a certificate warning | The development certificate is self-signed. | Accept the certificate for https://localhost:5174/. |
Related pages
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_urlvalue 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.
| Scheme | Hostname check | Trust method |
|---|---|---|
x509_san_dns | Yes | Certificate chain and leaf DNS name |
x509_san_hash | No | SHA-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_dnswith the hostnamedemo.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. Withx509_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.
-
Find the local network address of the machine that runs the verifier:
ipconfig getifaddr en0 # Example output: 192.168.1.42 -
Install and configure
dnsmasq. Replace192.168.1.42with 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 -
Verify the resolver on the same machine:
dig @127.0.0.1 demo.ewqwe.localExpected result: the answer is the local network address.
-
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_urlvalue 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.
-
Clone the repository:
git clone https://github.com/bgrieder/android-eudi-haip-wallet.git cd android-eudi-haip-wallet -
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.shThe script installs the system image, creates an Android Virtual Device (AVD) named
EUDI_Dev_Devicewith the Pixel 6 Pro profile, enables hardware keyboard input, starts the emulator with-writable-system, and mapsdemo.ewqwe.localto the host machine.Expected result: the emulator starts, and the Step 2 Option A mapping is already in place.
-
In Android Studio, open the project, select the
appmodule and theEUDI_Dev_Deviceemulator, and click Run.Expected result: the wallet installs and starts.
Option B: Install a pre-built APK
- 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.
- Open Chrome on the emulator and go to the EUDI Wallet releases page.
- Download an APK such as
app-demo-debug.apk, open the file, and tap Install. - 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:
-
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 -
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
mdlReaderAuthextended 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 missingmdlReaderAuthOID is the most common cause ofInvalidJarJwt(cause=Untrusted x5c). See Request parameters for the signing requirements.
Step 5: Load an mDL or a PID into the wallet
-
Open the wallet and create a PIN code when the wallet asks for one.
-
Tap the add icon (
+) and choose Add a Document from List. -
Select the issuer
https://euidw.devand choose mDL (MSO MDOC) or PID (MSO MDOC). -
When the wallet asks for the country, choose Form EU.
-
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
- Open the verifier app at the public URL of the verifier and sign in.
- On the home page, select the credential type from the dropdown:
- mDL requests the mobile driving licence.
- National ID requests the PID.
- Click Generate QR Code.
- On the Android device, open the EUDI Wallet and scan the QR code.
- 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_urlvalue 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.
| Aspect | AV app (Annex A) | EUDI wallet (HAIP) |
|---|---|---|
| Client identifier | redirect_uri | x509_san_dns or x509_san_hash |
| Signed request | Not required | Required |
| Response mode | direct_post | direct_post.jwt |
| Reader trust | Not required | Required |
| Credential | Proof 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.
-
Clone the repository:
git clone https://github.com/bgrieder/av-app-android-wallet-ui.git cd av-app-android-wallet-ui -
In Android Studio, open the project, select the
appmodule and theEUDI_Dev_Deviceemulator, select thedevDebugbuild 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
- 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.
- Open Chrome on the emulator and go to the AV App releases page.
- 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
- Open the AV app and create a PIN code when the app asks for one.
- 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
- Open the verifier app at the public URL of the verifier and sign in.
- On the home page, select Proof of Age as the credential type.
- Click Generate QR Code.
- On the Android device, open the AV app and scan the QR code.
- 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
adbis typically located at~/Library/Android/sdk/platform-tools/adbon macOS when installed through Android Studio. Add it to yourPATHfor 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
CredentialProviderServicewith the Android CredentialManager on this device. - Populated output: the wallets that implement a
CredentialProviderServiceappear here. Look for entries undercredential-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_CREDENTIALandandroidx.identitycredentials.action.GET_CREDENTIALS, instead of aCredentialProviderService. This approach does not appear indumpsys 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
CredentialProviderServiceimplementations, 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 a deep link or URL scheme
# 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/hostsor the system-level CA certificates.
Remount the system partition as writable
adb remount
Note
This is required after
adb rootto push files to system partitions such as/system/etc/security/cacerts/.
Quick reference by use case
| What you need | Command |
|---|---|
| See connected devices | adb devices |
| Install an APK | adb install /path/to/app.apk |
| Force reinstall | adb install -r /path/to/app.apk |
| Check W3C credential providers | adb shell dumpsys credential |
| Map demo domain in emulator | adb root && adb shell "echo '10.0.2.2 demo.ewqwe.local' >> /etc/hosts" |
| Push CA cert to Downloads | adb push cert.crt /sdcard/Downloads/ |
| Push CA cert to system store | adb root && adb remount && adb push cert.crt /system/etc/security/cacerts/ |
| Stream wallet logs | adb logcat --pid=$(adb shell pidof <package>) |
| Filter logcat by tags | adb logcat -s "Tag1" "Tag2" |
| Search logs for keywords | adb logcat | grep -iE "eudi|openid4vp" |
| Restart ADB server | adb kill-server && adb start-server |
| Check Android version | adb shell getprop ro.build.version.release |
| List installed packages | adb shell pm list packages | grep -i <keyword> |
| Open a deep link | adb shell am start -d "<url>" -a android.intent.action.VIEW |
| Force-stop an app | adb shell am force-stop <package> |
| Clear app data | adb shell pm clear <package> |
| Reboot device | adb reboot |
| Root the emulator | adb root |
| Remount system as writable | adb remount |
References
- Android Developers - ADB Command Reference
- Android Developers - Configure On-Device Developer Options
- Android Developers - Run Apps on a Hardware Device
- Chrome Remote Debugging
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
- A running verifier app. See Run the verifier app.
- A signed-in administrator account.
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_namesets the text in the header.logo_urlaccepts an HTTPS URL or adata:URL.qr_code_callback_urlsets the base URL for the wallet callback. When the value is absent, the app uses thepublic_root_urlof 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"
| Backend | Persistence | Extra keys | Use |
|---|---|---|---|
sqlite_memory | none | none | Development and testing. |
sqlite_file | file | path | A 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:
| Role | Permissions |
|---|---|
admin | User management, settings, journal, and QR codes. |
verifier | QR 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
| Symptom | Cause | Action |
|---|---|---|
| The config key has no effect | The app reads the value at startup. | Restart the server after a change to the configuration file. |
Every /api/v1 route returns 404 | The app is disabled. | Keep the [verifier_ui] section with enabled = true. |
| Accounts disappear after a restart | The database is sqlite_memory. | Configure sqlite_file. |
| Sessions end after a restart | session_secret is not set. | Set a stable session_secret value. |
| A user cannot request a type | The type is not allowed for that user. | Widen the per-user list or the allowed_credential_types list. |
Related pages
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
jqtool is installed, to read values from JSON responses. Read the values by hand ifjqis not available. - You can write to the
issuers_cas_dirdirectory of the verifier. The default directory isissuers_casnext 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.
| Field | Content |
|---|---|
ca_cert_pem | The self-signed CA certificate, in PEM form |
issuer_cert_der | The issuer leaf certificate, in DER form |
device_pubkey_jwk | The 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.
- Write the value of
issuer.ca_cert_pemto a.pemfile in theissuers_cas_dirdirectory. The program above writesissuers_cas/test-ca.pem. - If the verifier runs in another directory, move the file to the configured
issuers_cas_dirinstead. - 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.
| Builder | Type | Format | Claims |
|---|---|---|---|
build_eu_age_sd_jwt | EU Age Verification | SD-JWT VC | over_18 |
build_eudi_sd_jwt | EUDI PID | SD-JWT VC | given_name, family_name, birth_date, age_over_18 |
build_eudi_mdoc | EUDI PID | mso_mdoc | given_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
| Symptom | Cause | Fix |
|---|---|---|
"issuer_trusted": false | The issuer CA is not in the trusted directory, or no restart | Write the CA PEM, then restart the verifier. |
Nonce mismatch: presentation nonce does not match server nonce | The credential uses the nonce of a different transaction | Rebuild the credential with the nonce of the current transaction. |
state is required for mDoc verification | An mDoc presentation arrived without a state value | Add the state field of the transaction to the request body. |
issuer JWT is missing the required x5c header | The SD-JWT VC value did not come from this library | Build the credential with a build_* function of the library. |
deviceAuth.deviceMac is not supported by this verifier | The mDoc used a COSE_Mac0 value for the holder proof | Use a wallet that produces a deviceSignature. |
Credential has expired | The SD-JWT VC validity time of one hour passed | Run the program again to build a fresh credential. |
Related topics
- Credential formats describes the structure of both formats.
- Selective disclosure explains why a test credential reveals all of its claims.
- Verify a credential describes the verify endpoint in detail.
- HTTP API lists the endpoint fields and the response schema.
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.
What does the av:// link scheme do?
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 signaturesCOSE_Mac0— message authentication codesCOSE_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 Licenceeu.europa.ec.eudi.pid.1— EU Person Identification Dataeu.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
DeviceSignedblock containing aCOSE_Sign1overDeviceAuthenticationBytessigned with the device private key - In SD-JWT VC: the Key Binding JWT (KB-JWT) signed with the key in the
cnf.jwkclaim
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 additionseu.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 toresponse_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 Age Verification Profile (Annex A): https://ageverification.dev/Technical%20Specification/annexes/annex-A/annex-A-av-profile
- EU Age Verification “Architecture and Technical Specifications”: https://ageverification.dev/docs/architecture-and-technical-specifications.md
- EU Age Verification docs (User Journey anchor used in this book): https://ageverification.dev/av-doc-technical-specification/docs/architecture-and-technical-specifications/#23-user-journey
EU Digital Identity Framework (EUDI / eIDAS)
- eIDAS 2.0 Regulation (EU) 2024/1183 (EUR-Lex): https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1183
- European Digital Identity (EUDI) policy page: https://digital-strategy.ec.europa.eu/en/policies/eudi-regulation
EU ARF (architecture and rulebooks)
- EUDI Wallet Architecture and Reference Framework (ARF) (main repository): https://github.com/eu-digital-identity-wallet/eudi-doc-architecture-and-reference-framework
- ARF Annex 2.02 Topic 3 (PID Rulebook HLRs): https://github.com/eu-digital-identity-wallet/eudi-doc-architecture-and-reference-framework/blob/main/docs/annexes/annex-2/annex-2.02-high-level-requirements-by-topic.md#a232-topic-3---pid-rulebook
- Attestation Rulebooks Catalog (repository): https://github.com/eu-digital-identity-wallet/eudi-doc-attestation-rulebooks-catalog
- PID Rulebook (attribute encodings): https://github.com/eu-digital-identity-wallet/eudi-doc-attestation-rulebooks-catalog/blob/main/rulebooks/pid/pid-rulebook.md
- mDL Rulebook (attribute encodings): https://github.com/eu-digital-identity-wallet/eudi-doc-attestation-rulebooks-catalog/blob/main/rulebooks/mdl/mdl-rulebook.md
EU wallet apps
- the EUDI Wallet (HAIP reference implementation)
- the Age Verification Wallet (AVI reference implementation)
EU PID / mDL Regulation
- Commission Implementing Regulation (EU) 2024/2977 (CIR 2024/2977): https://data.europa.eu/eli/reg_impl/2024/2977/oj
W3C APIs (browser credential selection)
- W3C Digital Credentials API (TR): https://www.w3.org/TR/digital-credentials/
- WICG Digital Credentials (living draft): https://wicg.github.io/digital-credentials/
- W3C Credential Management Level 1: https://www.w3.org/TR/credential-management-1/
OpenID specifications
- OpenID for Verifiable Presentations 1.0 (OpenID4VP): https://openid.net/specs/openid-4-verifiable-presentations-1_0.html
- OpenID Connect Core 1.0 (standard claims): https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
- OpenID Connect for Identity Assurance 1.0: https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html
ISO standards
These ISO documents are typically paywalled; the links below are the official ISO catalog entries.
- ISO/IEC 18013-5:2021 (mDL / mDoc): https://www.iso.org/standard/69084.html
- ISO/IEC 18013-7:2025 (mDL add-on functions): https://www.iso.org/standard/91154.html
IETF drafts
- SD-JWT-based Verifiable Credentials (draft-ietf-oauth-sd-jwt-vc): https://datatracker.ietf.org/doc/draft-ietf-oauth-sd-jwt-vc/
IETF RFCs (crypto and data formats)
- HPKE (RFC 9180): https://www.rfc-editor.org/rfc/rfc9180
- CBOR (RFC 8949): https://www.rfc-editor.org/rfc/rfc8949
- COSE (RFC 9052): https://www.rfc-editor.org/rfc/rfc9052
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.
- Digital Credentials Query Language (DIF page): https://identity.foundation/credential-query-language/
Browser and platform references
These links are useful when validating feasibility and browser support status for the Digital Credentials API.
- Chrome Platform Status (Digital Credentials): https://chromestatus.com/feature/5139144021733376
- Chromium Issue Tracker (search): https://bugs.chromium.org/p/chromium/issues/list?q=digital%20credentials
- Chrome Extensions API reference: https://developer.chrome.com/docs/extensions/reference/
- Firefox Platform Status: https://platform-status.mozilla.org/
- Firefox Web API Standards Positions: https://mozilla.github.io/standards-positions/
- MDN Web Docs (Credential Management API): https://developer.mozilla.org/en-US/docs/Web/API/Credential_Management_API
Tooling (Deno)
- Deno installation guide: https://deno.land/manual/getting_started/installation