Trust Lists
A trust list names the issuers you accept. EUDIPLO uses Lists of Trusted Entities (LoTE, ETSI TS 119 602) as signed JWTs: it publishes lists you manage and reads lists published by others. To accept qualified electronic attestations of attributes (QEAAs), it also reads ETSI TS 119 612 Trusted Lists in XML, directly or through a list of trusted lists such as the EU's (Trusted Lists for QEAAs); it does not publish them. For a complete walkthrough, follow chapter 3 of the cookbook, which publishes a trust list and verifies against it, and Accept only trusted issuers, which tests an untrusted issuer and an external list.
How a trust list is usedโ
Each trusted entity has an issuance certificate and a revocation certificate that signs its status lists. Lists you manage in EUDIPLO always include both; lists published by others may omit the revocation certificate. Services of a LoTE are read by the rules of the list's LoTEType (ETSI TS 119 602 V1.1.1), in every LoTE and also in wallet-provider lists (Service status and type); Trusted Lists have their own rules (Trusted Lists for QEAAs). A list without a valid NextUpdate, or whose NextUpdate has passed, is discarded as expired (ETSI TS 119 602 ยง6.3.15), in every position and also as a wallet-provider list; a closed list, whose NextUpdate is null, too. By then its publisher has issued a newer list, and an older one, though validly signed, may still name an issuer that the newer list removed or withdrew. For the same reason, a list numbered lower (LoTESequenceNumber) than one EUDIPLO already accepted from the same URL is discarded, even while its NextUpdate is ahead, and so is a list without a valid LoTESequenceNumber (TSLSequenceNumber for a Trusted List, Older versions of a list). The issuers of a discarded list are not trusted, while the other lists referenced with it still count. The log names each discarded list with its NextUpdate or its sequence number (Discarded outdated trust list(s) ..., or Discarded outdated or unavailable trust list(s) ... when a Trusted List reached through a list of trusted lists could not be loaded). Only when every list referenced together is discarded does the check fail as if no list could be loaded. When a credential is presented, EUDIPLO:
- loads every list of the credential query's
etsi_tlentry, checks its signature and discards it if it is outdated or older than a list accepted before, - builds a certificate path from the credential's
x5cchain to a certificate listed as a PID, Pub-EAA or EAA issuance service of a LoTE (http://uri.etsi.org/19602/SvcType/PID/Issuance,.../PubEAA/Issuanceor.../EAA/Issuance), or as a granted qualified service for the issuance of QEAAs of a Trusted List (http://uri.etsi.org/TrstSvc/Svctype/EAA/Q, Trusted Lists for QEAAs). Other service types are ignored for credentials: a credential under the.../WalletSolution/Issuanceor.../WRPAC/Issuancecertificate of an entity is rejected, even when the same entity is also listed as a PID provider, - if status checks are enabled, requires the status list of the credential (SD-JWT VC or mDOC) to be signed under a revocation certificate of the same entity whose type belongs to the matched issuance service:
.../PID/Revocationfor.../PID/Issuance,.../PubEAA/Revocationfor.../PubEAA/Issuanceand.../EAA/Revocationfor.../EAA/Issuance. If the entity lists no revocation service of that type, its.../EAA/Revocationservices count instead. The status list must be signed below that certificate if it is a CA, or with it if it is an end-entity certificate. An entity listed without such a revocation certificate must sign its status lists under the certificate the credential matched, in the same way; so must every QTSP of a Trusted List, since ETSI TS 119 612 defines no service for the status of attestations. A status list signed by any other key rejects the credential, also one under a revocation certificate of the same entity for another service, such as.../WalletSolution/Revocation. The chain comes from the status list'sx5cheader (SD-JWT VC) orx5chain(mDOC). Every certificate from the signer up to the listed one, included, must be within its validity period at verification time; otherwise the credential is rejected, also withstatusCheckMode: best_effort, because the list was fetched.
A credential's x5c (SD-JWT VC) or x5chain (mDOC), and the one of its status list or identifier list, may hold at most 10 certificates in total, a trust anchor included if it is sent; it should hold only the signing certificate and its intermediates. A longer chain is rejected before a certificate path is built from it; the path has its own size limits. A credential with such a chain fails with verification_error, also when no trust list is configured; the wallet and the session get the short message of verification_error, and the server log, and the session log when it is enabled, names the number, for example x5c holds 11 certificates; at most 10 are accepted. A credential whose status list carries such a chain fails too, also with statusCheckMode: best_effort: an mDOC with verification_error, an SD-JWT VC whose issuer matched a trust list with Status List JWT verification failed, as for a status list with another signer, while the server log names the number.
A listed CA certificate accepts every credential issued below it; a listed end-entity certificate only accepts credentials signed with exactly that certificate. Wallet-provider lists, used to trust wallet and key attestations during issuance, are described in Wallet and Key Attestation.
Service status and typeโ
A service whose ServiceStatus does not approve it is ignored, and so is an entity whose services are all ignored:
LoTEType | Service read when ServiceStatus is | Service ignored when ServiceStatus is |
|---|---|---|
EUPubEAAProvidersList (Annex H) | http://uri.etsi.org/19602/PubEAAProvidersList/SvcStatus/notified, or absent (with a warning, since Annex H requires it) | any other value, including .../SvcStatus/withdrawn |
EUPIDProvidersList (Annex D) | absent, or http://uri.etsi.org/19602/PidProvidersList/SvcStatus/notified, which PID lists in use set although Annex D says "The ServiceStatus component shall not be used" | any other value |
EUWalletProvidersList, EUWRPACProvidersList, EUWRPRCProvidersList, EURegistrarsAndRegistersList (Annexes E to G and I) | absent | any value: these profiles say "The ServiceStatus component shall not be used" |
any other, including EUEAAProvidersList and lists without LoTEType | absent, .../PubEAAProvidersList/SvcStatus/notified or http://uri.etsi.org/19602/commons/schemeApprovalGranted | any other value, including .../commons/schemeApprovalWithdrawn |
A status URI a scheme defines itself (ยง6.6.4) is not known to EUDIPLO, so services carrying it are ignored. So are services with an ETSI TS 119 612 type, such as http://uri.etsi.org/TrstSvc/Svctype/EAA/Q: only a Trusted List can grant a qualified status (Trusted Lists for QEAAs).
A service without ServiceTypeIdentifier is read only in a list where no service has a type (ยง6.6.0, NOTE 2). It then gets the issuance type of the list's profile: SvcType/PID/Issuance in a PID providers list, SvcType/WalletSolution/Issuance in a wallet providers list, SvcType/PubEAA/Issuance in a Pub-EAA providers list and SvcType/EAA/Issuance in an EUEAAProvidersList. NOTE 2 does not say which type that is; EUDIPLO assumes the providers' issuing services, which is what a list of one type lists. If a publisher lists only revocation services without a type, their certificates are trusted to sign credentials or attestations, so ask it to set ServiceTypeIdentifier. In a list whose other services have a type, or whose type implies none, it is ignored.
For each list, one warning in the log names the services ignored or read despite a missing status (at most ten of each, then a count), with entity, service type, status and reason: Trust list <url or ID>: left out N service(s): ..., Trust list <url or ID>: read N service(s) despite: ..., or both parts in one line. Lists managed in EUDIPLO always set the type and no status, so they produce no warning.
Size limitsโ
Every check reads all certificates of the lists it uses, and builds its certificate path from them. So that a list's publisher, or a tenant through a managed list, cannot decide how long a check takes on a shared instance, two limits apply:
- At most 1,000 certificates in the lists used together: the lists of a credential query's
etsi_tlentry, or thewalletProviderTrustListsthat wallet and key attestations are checked against. Every certificate of each entity EUDIPLO keeps from them counts, also those of the entity's other services: for credentials, an entity is kept when it has a PID, Pub-EAA or EAA issuance service; for attestations, when it has aWalletSolutionservice of any kind. Of a Trusted List, only the certificates of granted qualified QEAA services count, also for the national lists reached through a list of trusted lists. When the lists hold more, EUDIPLO uses none of them and does not load the lists after the one that goes over the limit. The check fails as when a list cannot be loaded: a presented credential withtrust_list_unavailable, a wallet or key attestation withWallet provider trust lists could not be loadedorAttestation proof x5c chain could not be validated. The server log names the list, for exampleTrust list https://trust.example.org/lists/pid.jwt brings the certificates of its source to 1001; at most 1000 are accepted, and such lists are not fetched again for one minute. Requests send such anetsi_tlentry as plain URLs (What the wallet receives). A managed list may still hold more certificates for others who read it. - At most 16 certificates and 64 signature checks per certificate path, from the certificate that signs a credential, status list or attestation to the certificate the path ends at, both included. For each certificate of the path, EUDIPLO checks its signature against the certificates of the
x5corx5chainand of the lists whose subject is that certificate's issuer, in turn, until one verifies; one whose Subject Key Identifier differs from the certificate's Authority Key Identifier is skipped without a check. A path past either limit is rejected: a presented SD-JWT VC withno_trust_chain_to_root, an mDOC withverification_error(orno_trust_chain_to_rootwhen only EUDIPLO's own check of the issuer's path, after the mDOC library's, goes past a limit), an SD-JWT VC whose status list has such a path withStatus List JWT verification failed, and a wallet or key attestation or its status list with... certificate chain is not valid: ...(Wallet and Key Attestation). The server log names the limit,Certificate path not found within 64 signature checksorCertificate path is longer than 16 certificates, and so does the session log when it is enabled, except for an SD-JWT VC's status list. A chain with the signing certificate and its intermediates, checked against lists whose CA certificates carry a Subject Key Identifier, needs a few checks. Lists that put many certificates with one subject name and no Subject Key Identifier before the one a path needs can make the path fail, also for the other lists used with them.
Older versions of a listโ
NextUpdate only limits how long an older version of a list stays usable: served again before its NextUpdate has passed, a validly signed older list would still name an issuer that the newer list removed or withdrew. EUDIPLO therefore also reads the list's LoTESequenceNumber, which its publisher raises with every list it issues and never lowers (ETSI TS 119 602 ยง6.3.2), or the TSLSequenceNumber of a Trusted List (ETSI TS 119 612 clause 5.3.2). This applies to every list, also to wallet-provider lists and to the national lists reached through a list of trusted lists:
- For each tenant and list URL, EUDIPLO remembers the highest number of a list it accepted. The numbers are kept in the database, so they hold after a restart and for every instance.
- A list numbered lower is discarded like an outdated list, and so is a list whose
LoTESequenceNumberorTSLSequenceNumberis missing or not a whole number from 1. The log names the numbers, for exampleDiscarded outdated trust list(s), using the current lists: https://trust.example.org/lists/pid.jwt (LoTESequenceNumber 3 is lower than 5 accepted before) .... A list with the same number as before is accepted. - A managed list of this EUDIPLO instance, referenced by
trustListIdor by a URL belowPUBLIC_URLorINTERNAL_URLsuch as<TENANT_URL>/trust-list/<id>, is compared with the number it has in storage instead, and nothing is remembered for it: that number is always the current one, also for a list that was deleted and created again, which starts at 1.
A publisher that numbers its list from 1 again breaks this rule, and the list stays discarded until its number is higher than the one remembered. Another EUDIPLO instance does this when one of its managed lists is created anew: deleted and created again, dropped by a replace import and added back later, or imported into an empty database. To accept such a list, call DELETE /api/cache/trust-list/sequence-numbers (role issuance:manage or presentation:manage): it forgets the numbers of your tenant and clears your tenant's trust list cache. The next list fetched from each URL then sets its number again, whichever version it is, so only do this once the publisher has confirmed the new numbering. Deleting a tenant deletes its numbers.
Publish a managed trust listโ
Create the list in the Web Client under Cryptographic Assets โ Trust Lists, or with POST /api/trust-list (role issuance:manage or presentation:manage):
{
"id": "membership-issuers",
"description": "Issuers of membership credentials",
"entities": [
{
"type": "internal",
"issuerKeyChainId": "<attestation key chain id>",
"revocationKeyChainId": "<status list key chain id>",
"info": {
"name": "Example Club",
"country": "DE",
"website": "https://club.example/"
}
},
{
"type": "external",
"issuerCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
"revocationCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
"info": {
"name": "Partner Club",
"website": "https://partner.example/",
"phone": "+49-30-1234567"
}
}
]
}
- Internal entities reference key chains of this tenant. EUDIPLO lists the last certificate of each chain, the root CA for internal and external CA chains, so the entry survives key rotation.
issuerKeyChainIdmust name a key chain with usage typeattestation, andrevocationKeyChainIdone withstatusListorattestation, since status lists are signed with the attestation key chain when they are pinned to it or the tenant has no status list key chain. OtherwisePOSTandPUTanswer400, with an entry per field inerrors(path["entities", <index>, "issuerKeyChainId"]orrevocationKeyChainId), and a configuration bundle or config folder is blocked withKEY_CHAIN_USAGE_MISMATCH. A key chain that the stored list already names in that field is still accepted, so lists saved before 10.0 can be updated: the plan only warns about it, as it does for a list the import skips, for example a detached one. EUDIPLO checks only the usage type: name the key chains that sign the issuer's credentials and its status lists, as wallets and verifiers check signatures against these certificates. A status list that is not pinned is signed by one of the tenant'sstatusListkey chains, else by one of itsattestationkey chains, without a defined order; with several key chains of that usage type, pin the issuer's status lists (keyChainId) to the key chain named inrevocationKeyChainId. In the Web Client, the Issuer Key Chain select offersattestationkey chains, and the Revocation Key Chain select offersstatusListkey chains and, after them,attestationones, with a hint on which status lists anattestationkey chain signs. Both selects mark a stored key chain of another usage type, or one that no longer exists. - External entities carry the certificates of issuers outside this tenant, as PEM or Base64 DER.
infodescribes the entity in the published list, as ETSI TS 119 602 requires:countryis an ISO 3166-1 alpha-2 code in capital letters (clause 6.1.5), withUKfor the United Kingdom,ELfor Greece andEUfor the European Union, and defaults toEU;langis an IETF RFC 5646 language tag in lower case (clause 6.1.4), for exampleenorde-at, and defaults toen, for the entity's name, postal address, electronic address and information URI. With another language, for examplede-at, the list publishes these texts in that language and again underenwith the same text, since every list supports English (clause 6.1.4); give the name in a form English readers recognize, such as the legal name. Service names are English labels and are published underenonly.uriis an absolute URI written as a URL parser serializes it, for example with spaces percent-encoded.contactUriandwebsiteare required, because clause 6.5.3.2 makes an e-mail address and a web site mandatory in the entity'sTEElectronicAddress:contactUriis one e-mail address in ASCII characters, bare ([email protected]) or as amailto:URI, published asmailto:[email protected];websiteis an absolutehttporhttpsURI in serialized form, for examplehttps://example.com/; the optionalphoneis a number in international form without spaces, for example+49-30-1234567ortel:+49-30-1234567, published as atel:URI. All three are published per language like the other texts.uriis published separately, asTEInformationURI. Other values, such ascountryde,GBorGermanyorlangEN, answer400with an entry at["entities", <index>, "info", <field>]inerrors, and the plan of a configuration bundle or config folder blocks the document; a missingcontactUriorwebsiteanswers the same way. Trust list files of format v1 (9.x) have nowebsitefield, so their upgrade on import always stops with the required inputTRUST_LIST_WEBSITE_MISSINGper entity: change$schematohttps://eudiplo.dev/schemas/v2/TrustListConfigFile.schema.json, addwebsiteand fix the other values the upgrade names:TRUST_LIST_CONTACT_URI_MISSINGorTRUST_LIST_CONTACT_URI_INVALIDfor the e-mail address,TRUST_LIST_COUNTRY_INVALIDorTRUST_LIST_LANGUAGE_INVALID, whose message names the value to write when only the case orGB/GRis wrong (for exampleUKforgb), orTRUST_LIST_URI_INVALID. The list carriesListIssueDateTimeandNextUpdatein whole UTC seconds, for example2026-11-06T12:00:00Z(clause 6.1.3).- The list is signed with the
trustListkey chain inkeyChainId. WithoutkeyChainId, a new list uses atrustListkey chain of the tenant, so create one first (Keys and Certificates), and an update keeps the key chain the list is signed with. That key chain must still have usage typetrustList: if a key chain import with its ID gave it another usage type, the update fails until it names atrustListkey chain inkeyChainId. The API answers409. In the Web Client, Any trust list key chain of the tenant (create) and Keep the current key chain (edit) leavekeyChainIdout; the form does not save while the signing key chain it names or keeps is gone or lacks usage typetrustList, or while a new list has notrustListkey chain to use. When the tenant has none, it links to create one. The plan of a configuration bundle or config folder blocks aTrustListdocument that would change such a list, or that names a key chain without usage typetrustListinkeyChainId, withKEY_CHAIN_USAGE_MISMATCH, so the import applies nothing; a startup import skips the tenant and logs the issue. The plan takes the usage type from aKeyChaindocument of the same bundle that the import writes, else from the stored key chain. A document that leaves the list unchanged gets the issue only as a warning, as the import does not write the list; it shows in a bundle plan (eudiplo config planor Plan and validate in the Web Client), not in the startup log.
POST and PUT check the whole body before they sign the list and answer 400 with an entry per refused field in errors, each with path, code and message. path is an array, for example ["keyChainId"] or ["entities", 0, "issuerKeyChainId"]. Entries at info itself follow only once no other field is refused. country, lang, uri, contactUri, website and phone that do not fit (see above) are refused earlier by the body schema, also with 400 at their path:
code | Field | Refused value |
|---|---|---|
key_chain_not_found | keyChainId, entities.<index>.issuerKeyChainId or revocationKeyChainId | a key chain the tenant does not have |
key_chain_usage_mismatch | the same fields | a key chain of another usage type, as described above |
invalid_certificate | entities.<index>.issuerCertPem or revocationCertPem | no X.509 certificate in PEM or Base64 DER |
invalid_entity_info | entities.<index>.info | values the LoTE format does not take that the body schema let through |
409 remains for a save that the stored state blocks: a POST without keyChainId when the tenant has no trustList key chain or the one EUDIPLO picks has no valid certificate, an update without keyChainId whose kept key chain lost usage type trustList, and an update that another update or a renewal overtook; name a trustList key chain in keyChainId for the first two. PUT /api/trust-list/{id}, GET /api/trust-list/{id}, GET /api/trust-list/{id}/export, GET /api/trust-list/{id}/versions and GET /api/trust-list/{id}/versions/{versionId} answer 404 for a list or version the tenant does not have.
EUDIPLO publishes the signed JWT at GET /issuers/{tenantId}/trust-list/{id} without authentication, so others can use your list.
| Task | Endpoint |
|---|---|
| Replace entities | PUT /api/trust-list/{id} with the complete body; publishes the next sequence number |
| Version history | GET /api/trust-list/{id}/versions, GET /api/trust-list/{id}/versions/{versionId} |
| List, read, export, delete | GET /api/trust-list, GET /api/trust-list/{id}, GET /api/trust-list/{id}/export, DELETE /api/trust-list/{id} |
DELETE refuses a list that configurations still use (Delete a trust list). In the Web Client, the page of a list shows the credential configurations (with issuance:manage) and the presentation configurations (with presentation:manage or presentation:request) that reference it, and the delete button (Delete list) says so instead of sending the request. The page does not show walletProviderTrustLists of the issuance configuration; check those as described in Wallet and Key Attestation.
To manage lists as files, put the same JSON into config/<tenant>/trust-lists/ (Configuration as Code). GET /api/trust-list/{id}/export returns a list in this format; Download configuration in the Web Client saves it as a document with $schema and spec (single resources).
Delete a trust listโ
DELETE /api/trust-list/{id} answers 409 while a configuration of the tenant still references the list, because that configuration would fail without it. The response names the configurations in message and lists them in references. Configurations the caller's roles cannot read are only counted, without ID and description: credential configs and the issuance configuration need issuance:manage, presentation configs presentation:manage or presentation:request.
{
"statusCode": 409,
"timestamp": "2026-10-11T12:00:00.000Z",
"path": "/api/trust-list/membership-issuers",
"code": "TRUST_LIST_IN_USE",
"message": "Trust list \"membership-issuers\" is still referenced by 1 presentation config (\"membership-check\") and the issuance configuration (wallet provider trust lists). Remove these references before deleting the trust list.",
"references": [
{ "kind": "PresentationConfig", "id": "membership-check", "description": "Verify a membership name and ID" },
{ "kind": "IssuanceConfig" }
]
}
These entries count as a reference. "The list URL" is <TENANT_URL>/trust-list/<id> or any URL that ends in /issuers/<tenant>/trust-list/<id> with the list's own tenant; a trailing slash, a query or a fragment is ignored:
- an
etsi_tlentry in thetrusted_authoritiesof a presentation config, bytrustListIdorurl, - an entry of
schemaMeta.trustedAuthoritiesin a credential config, bytrustListId, or withframeworkType: "etsi_tl"by avaluethat is the list URL or the bare list ID, - an entry of
walletProviderTrustListsin the issuance configuration, shared or of an authorization server, bytrustListIdorurl.
Remove these references, or point them to another list, then delete the list. Deleting an unknown ID answers 204. EUDIPLO does not see references from other tenants or other systems that fetch the list from its public URL.
A configuration bundle or a config folder imported in replace mode (CONFIG_IMPORT_MODE=replace at startup) deletes a list that it created and no longer contains. Its plan is blocked with TRUST_LIST_IN_USE on that list while a configuration that survives the import references it by the rules above: a stored configuration the import neither deletes nor rewrites, or a document of the bundle with its new content. A document the plan skips, for example a detached one, counts with its stored content. The message names the configurations; a document of the bundle that names the list by trustListId is also blocked with MISSING_RESOURCE_REFERENCE. Keep the list in the bundle, or remove the references (in the bundle or through the API), then plan again.
Validity and renewalโ
A managed list is valid for 30 days (NextUpdate). EUDIPLO renews it automatically in the last 10 days: it re-signs the unchanged entities with the next sequence number and a new NextUpdate, and keeps the previous version in the history. A renewal signs with the key chain the list is signed with, even one that no longer has usage type trustList; only an update refuses that key chain. The check runs every hour and at startup, so lists that expired while EUDIPLO was stopped are renewed when it starts. A managed list is checked like any other list when it is used: if its renewal keeps failing until its NextUpdate (the log shows Failed to renew trust list ...), it is discarded, and credentials and wallet and key attestations that only it covers are rejected.
Renewals and updates never publish the same sequence number twice. If a renewal or another update was published between reading and writing, PUT fails with 409; read the list again and retry. An import updates an existing list in the same way, with the next sequence number, or leaves it unchanged. A list that is created anew (deleted and created again, dropped by a replace import and added back later, or imported into an empty database) starts again at sequence number 1, so verifiers outside this instance that remember a higher number discard it (Older versions of a list).
Fieldsโ
| Field | Required | Type / allowed values | Description |
|---|---|---|---|
id | no | string | Optional trust list id. If omitted, one may be generated. |
description | no | string | Optional trust list description. |
keyChainId | no | string | Optional key chain id used to sign trust list payloads. |
entities | yes | array of one of 2 shapes | One or more entities included in this trust list. |
entities[].providerType | no | string: attestation-provider | wallet-provider | Provider role; defaults to attestation-provider. |
entities[].info | yes | object | Entity metadata. |
entities[].info.name | yes | string | Display name of the trusted entity. |
entities[].info.lang | no | string | Optional language of the entity's name, postal address, contact and information URI: an IETF RFC 5646 language tag in lower case, for example en or de-at (ETSI TS 119 602 clause 6.1.4). Defaults to en. With another language, the list publishes these texts in that language and again under en with the same text, since every list supports English (clause 6.1.4); service names are published in English only. |
entities[].info.locale | no | string | Optional locale identifier. |
entities[].info.uri | no | string | Optional absolute URI where relying parties find information about the entity, published as TEInformationURI. Write it as a URL parser serializes it, for example https://example.com/about with spaces percent-encoded. |
entities[].info.country | no | string | Optional country of the postal address: an ISO 3166-1 alpha-2 code in capital letters, with "UK" for the United Kingdom, "EL" for Greece and "EU" for the European Union (ETSI TS 119 602 clause 6.1.5). Defaults to EU. |
entities[].info.locality | no | string | Optional locality or city. |
entities[].info.postalCode | no | string | Optional postal code. |
entities[].info.streetAddress | no | string | Optional street address. |
entities[].info.contactUri | yes | string | E-mail address of the entity, for example [email protected] or mailto:[email protected], published as a mailto: URI in TEElectronicAddress (ETSI TS 119 602 clause 6.5.3.2). Use ASCII characters; write an internationalized domain in its xn-- form. |
entities[].info.website | yes | string | Web site of the entity, an absolute http or https URI published in TEElectronicAddress (ETSI TS 119 602 clause 6.5.3.2). Write it as a URL parser serializes it, for example https://example.com/. |
entities[].info.phone | no | string | Optional telephone number of the entity in international form, for example +49-30-1234567 or tel:+49-30-1234567, published as a tel: URI in TEElectronicAddress (ETSI TS 119 602 clause 6.5.3.2). |
entities[].type | yes | string: internal | Only when type is internal. internal references key chains of this tenant; external carries the certificates directly, as PEM or Base64 DER. |
entities[].issuerKeyChainId | yes | string | Only when type is internal. Key chain id for issuer certificate material. |
entities[].revocationKeyChainId | yes | string | Only when type is internal. Key chain id for revocation/status list certificate material. |
entities[].type | yes | string: external | Only when type is external. internal references key chains of this tenant; external carries the certificates directly, as PEM or Base64 DER. |
entities[].issuerCertPem | yes | string | Only when type is external. Issuer certificate as PEM or Base64 DER. |
entities[].revocationCertPem | yes | string | Only when type is external. Revocation/status certificate as PEM or Base64 DER. |
data | no | object | Optional additional custom payload data. |
data is accepted but ignored; EUDIPLO builds the list content from entities.
Use a trust list in a presentationโ
Reference trust lists in the trusted_authorities of a DCQL credential query:
{
"trusted_authorities": [
{
"type": "etsi_tl",
"values": [
{ "trustListId": "membership-issuers" },
{ "url": "https://trust.example.org/lists/pid.jwt", "verifierX509Der": "MIIB..." }
]
}
]
}
trustListIdreferences a managed list of this tenant. EUDIPLO fetches it from<INTERNAL_URL>/issuers/<tenant>/trust-list/<id>and pins the certificate that signs it.INTERNAL_URLdefaults tohttp://127.0.0.1:<PORT>; withTLS_ENABLED=trueor aPORTthat is not a number it has no default, and the list is fetched fromPUBLIC_URL. SetINTERNAL_URLif the backend reaches itself at another address.urlreferences an external LoTE JWT.verifierX509Der(base64 DER certificate) orverifierKey(public JWK) is required to check its signature; without them loading the list fails (trust_list_unavailable).<TENANT_URL>in the URL is replaced with<PUBLIC_URL>/issuers/<tenant>.- Put several lists into the
valuesof oneetsi_tlentry: only the firstetsi_tlentry of a credential query is used for verification.
Every credential query needs trusted_authorities; EUDIPLO rejects a presentation configuration without them. For development and interoperability tests, SKIP_TRUST_AUTHORITY=true allows such queries, which are then verified without checking who the issuer is. An mDOC's presented certificate chain is still checked: its signatures and the validity period of every certificate (certificate_expired).
Trusted Lists for QEAAsโ
A QEAA is trusted through the qualified service of the QTSP that issued it, as published in an ETSI TS 119 612 (V2.4.1) Trusted List (ARF Annex 2 OIA_13). Reference the list with format: "trusted-list" in the etsi_tl entry of the credential query that requests the QEAA:
{
"trusted_authorities": [
{
"type": "etsi_tl",
"values": [
{
"format": "trusted-list",
"url": "https://ec.europa.eu/tools/lotl/eu-lotl.xml",
"signingCertificates": ["MIIH...", "MIIH..."],
"schemeTerritories": ["DE", "FR"]
}
]
}
]
}
urlis a list of trusted lists (TSLType.../EUlistofthelists), such as the EU LOTL, or a Member State's Trusted List.<TENANT_URL>is replaced as for a LoTE.signingCertificates(base64 DER, required) are the certificates one of which must have signed the list: for a list of trusted lists, the signing certificates its operator publishes, for the EU LOTL the set the European Commission publishes in the Official Journal of the European Union; for a Member State's list, its scheme operator certificates. A list signed with another key fails like a LoTE with a bad signature (trust_list_unavailable).schemeTerritoriesis only read for a list of trusted lists: theSchemeTerritoryof the lists to follow, for exampleDE. Without it, every list it points to is followed.
A list of trusted lists names no QTSPs itself. EUDIPLO follows its pointers (OtherTSLPointer) to lists of TSLType .../EUgeneric, one level deep, and checks each of them against the certificates the list of trusted lists publishes in its pointer. Pointers to other lists of trusted lists are not followed, nor are pointers whose media type is not XML, such as the PDF versions of a list. A Trusted List and a LoTE can be named in the same etsi_tl entry; each still only adds the issuers of its own kind.
From each Trusted List, EUDIPLO trusts the certificates of every service whose ServiceTypeIdentifier is exactly http://uri.etsi.org/TrstSvc/Svctype/EAA/Q and whose current ServiceStatus is exactly http://uri.etsi.org/TrstSvc/TrustedList/Svcstatus/granted. Not trusted are:
- a withdrawn qualified service: the current status decides, so a QEAA its QTSP issued before the withdrawal is rejected too; the service history is not read,
- a service that is not qualified, such as
.../Svctype/EAAwith the status.../recognisedatnationallevel, and a service of any other type, such as.../Svctype/CA/QC, - a service identified only by its subject name or key identifier, without an
X509Certificate: a certificate path must end at a certificate.
Service information extensions, such as TakenOverBy or additional service information, are not read, also when they are marked critical, although ETSI TS 119 612 asks to reject what a critical extension it does not understand applies to. Of a service identity with several X509Certificate elements, such as a re-certified CA, only the first is a trust anchor.
The categories stay apart (ARF Annex 2, OIA_15 note): a Trusted List adds only QEAA issuers, and a LoTE never does. A LoTE service with an ETSI TS 119 612 type, such as .../Svctype/EAA/Q, is ignored with a warning (... an ETSI TS 119 612 service type, which only a Trusted List can grant). A QEAA issuer is never a PID issuer, so the rule for PIDs without status information (statusCheckMode) does not apply to its credentials: a QEAA without status information is accepted, as an EAA is. Which category a credential query accepts is chosen by the lists in its etsi_tl entry. The status list of a QEAA must be signed under the certificate its credential matched (How a trust list is used): ETSI TS 119 612 defines no service for the status of attestations.
Every list is checked on its own, the list of trusted lists and each list it points to: one whose NextUpdate has passed or is empty (a closed list), or whose TSLSequenceNumber is lower than one accepted before from the same URL (Older versions of a list), is discarded, and an outdated list of trusted lists takes the lists it points to with it. A list reached through a list of trusted lists that cannot be fetched or whose signature does not verify is discarded on its own as well, so an unreachable Member State list does not stop the QEAAs of the others; the log names it, for example Discarded outdated or unavailable trust list(s), using the current lists: https://tl.example/de.xml (could not be loaded: "..."). A list of trusted lists, or a Trusted List referenced directly, that cannot be loaded fails like a LoTE. When no list of the etsi_tl entry is left, presented credentials fail with trust_list_unavailable, and the lists are not fetched again for one minute. When another list of the entry is left, such as a LoTE, or a list of trusted lists has nothing to follow, for example because schemeTerritories names no territory it points to, QEAAs fail as not trusted (no_trust_chain_to_root or trust_chain_not_trusted). The lists are cached like LoTEs (Caching), up to the earliest NextUpdate of the list of trusted lists and the lists it points to.
Limits, besides the 1,000 certificates of a source: a Trusted List may be at most 10 MiB; a list with a document type declaration (<!DOCTYPE) is refused before it is parsed; before its signature is checked, a list is refused when its signature uses other transforms than the enveloped signature and canonicalization (ETSI TS 119 612 Annex B), when no reference of its signature covers the whole TrustServiceStatusList (URI="" or the Id of the list), or when a reference names anything else than the list or an element of its signature, such as its XAdES signed properties, with ... is refused before its signature is checked: ... in the log; and a list of trusted lists may point to at most 64 lists to follow. With more, EUDIPLO uses none of the lists of the etsi_tl entry, so every credential of the query fails with trust_list_unavailable, also one from a LoTE of the same entry; the log says ... points to N Trusted Lists to follow; at most 64 are followed, the lists are not fetched again for one minute, and schemeTerritories narrows the lists. Each followed list is fetched and its signature checked one after another whenever the cache is built, so name the territories you need.
What the wallet receivesโ
Wallets match credentials by key identifier, without fetching the list. EUDIPLO therefore replaces each etsi_tl entry in the request with an aki entry whose values are the base64url-encoded key identifiers of the listed PID, Pub-EAA and EAA issuance certificates, and of the granted qualified QEAA services of Trusted Lists: the Subject Key Identifier of every certificate, plus the Authority Key Identifier of end-entity certificates. If a list cannot be loaded, or an issuer certificate has no usable identifier (for example a self-signed certificate without Authority Key Identifier), the request additionally keeps an etsi_tl entry with the plain URL of that list. An outdated list is left out like in verification; only when every list of the entry is outdated are their URLs sent this way. When the lists of the entry hold more than 1,000 certificates of credential issuers together, or one of them does alone (Size limits), or a list of trusted lists among them points to more than 64 lists to follow, verification refuses every credential of the query, and the request sends only the plain URLs of all its lists, without key identifiers. Verification always uses the stored configuration. For a Trusted List, the plain URL names the list of trusted lists or the Trusted List as configured: a wallet matches it against every service of the lists it points to, of every type and territory, so it may offer a credential that verification then refuses, which accepts only granted QEAA services in the schemeTerritories.
Some wallets do not handle trusted_authorities yet. VP_REMOVE_TA=true removes it from all requests sent to wallets; EUDIPLO still verifies against the configured lists.
Cachingโ
Loaded trust lists are cached for five minutes, but not past the earliest NextUpdate of the lists loaded together: then they are fetched again. An outdated list next to current ones is fetched again with them when the cache expires; when all lists loaded together are outdated or, reached through a list of trusted lists, unavailable, hold more than 1,000 certificates (Size limits), or a list of trusted lists among them points to more than 64 lists (Trusted Lists for QEAAs), they are not fetched again for one minute. A managed list of this instance is fetched again as soon as it has a new sequence number, after an update or a renewal. After changing another list, clear the cache with DELETE /api/cache/trust-list (it also clears the OpenID Federation cache, but keeps the sequence numbers accepted before) to use it immediately; GET /api/cache/stats shows the cached status lists. With issuance:manage or presentation:manage, GET /api/cache/stats shows only the status lists your tenant used, and the DELETE endpoints clear only your tenant's trust lists and the status lists and OpenID Federation resolutions it used. Status lists and resolutions are shared, so another tenant that uses one you cleared fetches it again too. With tenants:manage, they cover all tenants. Fetching a list times out after four seconds, a Trusted List after ten. Outside NODE_ENV=production, the TLS certificate of the list's host is not checked; the list signature always is. Lists outside EUDIPLO's own PUBLIC_URL and INTERNAL_URL must pass the outbound URL policy: HTTPS and public addresses only, unless OUTBOUND_URL_ALLOW_HTTP or OUTBOUND_URL_ALLOW_PRIVATE_NETWORK is set. The same applies to the status lists named in presented credentials and wallet attestations. EUDIPLO caches a status list for its ttl, five minutes without one, at most one hour and not past its exp; DELETE /api/cache/status-list clears the status lists your tenant used.