Skip to main content

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:

  1. loads every list of the credential query's etsi_tl entry, checks its signature and discards it if it is outdated or older than a list accepted before,
  2. builds a certificate path from the credential's x5c chain 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/Issuance or .../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/Issuance or .../WRPAC/Issuance certificate of an entity is rejected, even when the same entity is also listed as a PID provider,
  3. 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/Revocation for .../PID/Issuance, .../PubEAA/Revocation for .../PubEAA/Issuance and .../EAA/Revocation for .../EAA/Issuance. If the entity lists no revocation service of that type, its .../EAA/Revocation services 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's x5c header (SD-JWT VC) or x5chain (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 with statusCheckMode: 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:

LoTETypeService read when ServiceStatus isService 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)absentany value: these profiles say "The ServiceStatus component shall not be used"
any other, including EUEAAProvidersList and lists without LoTETypeabsent, .../PubEAAProvidersList/SvcStatus/notified or http://uri.etsi.org/19602/commons/schemeApprovalGrantedany 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_tl entry, or the walletProviderTrustLists that 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 a WalletSolution service 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 with trust_list_unavailable, a wallet or key attestation with Wallet provider trust lists could not be loaded or Attestation proof x5c chain could not be validated. The server log names the list, for example Trust 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 an etsi_tl entry 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 x5c or x5chain and 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 with no_trust_chain_to_root, an mDOC with verification_error (or no_trust_chain_to_root when 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 with Status 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 checks or Certificate 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 LoTESequenceNumber or TSLSequenceNumber is missing or not a whole number from 1. The log names the numbers, for example Discarded 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 trustListId or by a URL below PUBLIC_URL or INTERNAL_URL such 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",
"contactUri": "[email protected]",
"website": "https://club.example/"
}
},
{
"type": "external",
"issuerCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
"revocationCertPem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
"info": {
"name": "Partner Club",
"contactUri": "mailto:[email protected]",
"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. issuerKeyChainId must name a key chain with usage type attestation, and revocationKeyChainId one with statusList or attestation, 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. Otherwise POST and PUT answer 400, with an entry per field in errors (path ["entities", <index>, "issuerKeyChainId"] or revocationKeyChainId), and a configuration bundle or config folder is blocked with KEY_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's statusList key chains, else by one of its attestation key 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 in revocationKeyChainId. In the Web Client, the Issuer Key Chain select offers attestation key chains, and the Revocation Key Chain select offers statusList key chains and, after them, attestation ones, with a hint on which status lists an attestation key 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.
  • info describes the entity in the published list, as ETSI TS 119 602 requires: country is an ISO 3166-1 alpha-2 code in capital letters (clause 6.1.5), with UK for the United Kingdom, EL for Greece and EU for the European Union, and defaults to EU; lang is an IETF RFC 5646 language tag in lower case (clause 6.1.4), for example en or de-at, and defaults to en, for the entity's name, postal address, electronic address and information URI. With another language, for example de-at, 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); give the name in a form English readers recognize, such as the legal name. Service names are English labels and are published under en only. uri is an absolute URI written as a URL parser serializes it, for example with spaces percent-encoded. contactUri and website are required, because clause 6.5.3.2 makes an e-mail address and a web site mandatory in the entity's TEElectronicAddress: contactUri is one e-mail address in ASCII characters, bare ([email protected]) or as a mailto: URI, published as mailto:[email protected]; website is an absolute http or https URI in serialized form, for example https://example.com/; the optional phone is a number in international form without spaces, for example +49-30-1234567 or tel:+49-30-1234567, published as a tel: URI. All three are published per language like the other texts. uri is published separately, as TEInformationURI. Other values, such as country de, GB or Germany or lang EN, answer 400 with an entry at ["entities", <index>, "info", <field>] in errors, and the plan of a configuration bundle or config folder blocks the document; a missing contactUri or website answers the same way. Trust list files of format v1 (9.x) have no website field, so their upgrade on import always stops with the required input TRUST_LIST_WEBSITE_MISSING per entity: change $schema to https://eudiplo.dev/schemas/v2/TrustListConfigFile.schema.json, add website and fix the other values the upgrade names: TRUST_LIST_CONTACT_URI_MISSING or TRUST_LIST_CONTACT_URI_INVALID for the e-mail address, TRUST_LIST_COUNTRY_INVALID or TRUST_LIST_LANGUAGE_INVALID, whose message names the value to write when only the case or GB/GR is wrong (for example UK for gb), or TRUST_LIST_URI_INVALID. The list carries ListIssueDateTime and NextUpdate in whole UTC seconds, for example 2026-11-06T12:00:00Z (clause 6.1.3).
  • The list is signed with the trustList key chain in keyChainId. Without keyChainId, a new list uses a trustList key 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 type trustList: if a key chain import with its ID gave it another usage type, the update fails until it names a trustList key chain in keyChainId. The API answers 409. In the Web Client, Any trust list key chain of the tenant (create) and Keep the current key chain (edit) leave keyChainId out; the form does not save while the signing key chain it names or keeps is gone or lacks usage type trustList, or while a new list has no trustList key chain to use. When the tenant has none, it links to create one. The plan of a configuration bundle or config folder blocks a TrustList document that would change such a list, or that names a key chain without usage type trustList in keyChainId, with KEY_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 a KeyChain document 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 plan or 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:

codeFieldRefused value
key_chain_not_foundkeyChainId, entities.<index>.issuerKeyChainId or revocationKeyChainIda key chain the tenant does not have
key_chain_usage_mismatchthe same fieldsa key chain of another usage type, as described above
invalid_certificateentities.<index>.issuerCertPem or revocationCertPemno X.509 certificate in PEM or Base64 DER
invalid_entity_infoentities.<index>.infovalues 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.

TaskEndpoint
Replace entitiesPUT /api/trust-list/{id} with the complete body; publishes the next sequence number
Version historyGET /api/trust-list/{id}/versions, GET /api/trust-list/{id}/versions/{versionId}
List, read, export, deleteGET /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_tl entry in the trusted_authorities of a presentation config, by trustListId or url,
  • an entry of schemaMeta.trustedAuthorities in a credential config, by trustListId, or with frameworkType: "etsi_tl" by a value that is the list URL or the bare list ID,
  • an entry of walletProviderTrustLists in the issuance configuration, shared or of an authorization server, by trustListId or url.

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โ€‹

FieldRequiredType / allowed valuesDescription
idnostringOptional trust list id. If omitted, one may be generated.
descriptionnostringOptional trust list description.
keyChainIdnostringOptional key chain id used to sign trust list payloads.
entitiesyesarray of one of 2 shapesOne or more entities included in this trust list.
entities[].providerTypenostring: attestation-provider | wallet-providerProvider role; defaults to attestation-provider.
entities[].infoyesobjectEntity metadata.
entities[].info.nameyesstringDisplay name of the trusted entity.
entities[].info.langnostringOptional 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.localenostringOptional locale identifier.
entities[].info.urinostringOptional 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.countrynostringOptional 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.localitynostringOptional locality or city.
entities[].info.postalCodenostringOptional postal code.
entities[].info.streetAddressnostringOptional street address.
entities[].info.contactUriyesstringE-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.websiteyesstringWeb 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.phonenostringOptional 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[].typeyesstring: internalOnly when type is internal. internal references key chains of this tenant; external carries the certificates directly, as PEM or Base64 DER.
entities[].issuerKeyChainIdyesstringOnly when type is internal. Key chain id for issuer certificate material.
entities[].revocationKeyChainIdyesstringOnly when type is internal. Key chain id for revocation/status list certificate material.
entities[].typeyesstring: externalOnly when type is external. internal references key chains of this tenant; external carries the certificates directly, as PEM or Base64 DER.
entities[].issuerCertPemyesstringOnly when type is external. Issuer certificate as PEM or Base64 DER.
entities[].revocationCertPemyesstringOnly when type is external. Revocation/status certificate as PEM or Base64 DER.
datanoobjectOptional 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..." }
]
}
]
}
  • trustListId references 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_URL defaults to http://127.0.0.1:<PORT>; with TLS_ENABLED=true or a PORT that is not a number it has no default, and the list is fetched from PUBLIC_URL. Set INTERNAL_URL if the backend reaches itself at another address.
  • url references an external LoTE JWT. verifierX509Der (base64 DER certificate) or verifierKey (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 values of one etsi_tl entry: only the first etsi_tl entry 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"]
}
]
}
]
}
  • url is 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).
  • schemeTerritories is only read for a list of trusted lists: the SchemeTerritory of the lists to follow, for example DE. 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/EAA with 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.