Publish a national trust list
This guide is for public bodies that will run their country's trust listA signed list of a country's root certificates, issuers and registered relying parties. Today trust in Tamga rests on these lists; a shared ledger comes later. (the list operator, TLSO (Trusted List Scheme Operator)The organisation that compiles, signs and publishes a national trust list. Today Tamga does this for Türkiye, provisionally on behalf of the state.) and for their technical teams.
When to read it:
- When a country joins Tamga Network, or takes over the list Tamga runs on its behalf.
- When your country already publishes its list in the ETSI format and you want Tamga wallets and verifiers to recognise it.
- First: Trust lists and Federation.
- The technical side of operating the list (keys, publisher, publication server, monitoring): GUIDE-0017.
How it works
Wallets and verifiers trust one thing: the root key of the Tamga LOTL (List of Trusted Lists)The signed list that points to the countries' trust lists, their signers and their recognition status.. The LOTL tells them each national list's address, its signer and what it may vouch for. Connecting a country's list to the network means getting that entry written into the LOTL. The list stays with the country; Tamga only brings the lists together (ADR-0036).
| Way | Format | In the LOTL | When |
|---|---|---|---|
| A. National list | Tamga format (tamga-tl+jwt, SPEC-TRUST-0001) | national_lists[] | The country is a Tamga Network member; issuers, verifiers and root certificates are in its own list |
| B. External list | ETSI TS 119 602 (LoTE (List of Trusted Entities)The ETSI TS 119 602 list format; Tamga publishes a LoTE view of its lists and can read external LoTE lists., JSON) | external_lists[] | An existing list of the country or the EU; it vouches for specific roles |
Today Tamga runs the Türkiye list (tl-tr.jws) on behalf of the national authority; the entries for the other members of the Organization of Turkic States are reserved (RESERVED). There is no external list in the LOTL yet.
A. National list
1. The LOTL entry
{
"state_code": "TR",
"status": "ACTIVE",
"membership": "TDT_MEMBER",
"list_url": "https://trust.tamga.network/tl-tr.jws",
"operator": { "name": "Tamga Network", "status": "provisional", "on_behalf_of": "TR national authority (to be designated)" },
"signing_certs": ["tl-signer-1"],
"roles": {
"registrar": { "status": "PROVISIONAL", "operated_by": "Tamga Network", "signing_certs": ["registrar-1"] },
"tlso": { "status": "PROVISIONAL", "operated_by": "Tamga Network" },
"pid_provider": { "status": "RESERVED" },
"access_ca": { "status": "PROVISIONAL", "operated_by": "Tamga Network" },
"national_root_ca": { "status": "ACTIVE", "cert": "root-ca", "operated_by": "Tamga Network (provisional)" }
},
"recognition": { "mode": "unilateral", "recognizes": ["TR"] }
}This is today's Türkiye entry. In a hand-over only operator, list_url and the signers change in the same entry.
| Role | What it does |
|---|---|
tlso | Signs and publishes the list |
registrar | Registers issuers and verifiers; signs every registration certificateA signed statement from the registrar listing which fields a relying party may request and for what purpose (valid up to 12 months). |
access_ca | Issues an access certificateThe X.509 certificate a relying party signs its requests with; its client identifier is derived from this certificate's hash. to each verifier |
national_root_ca | The root of issuer certificates |
pid_provider | Issues the national identity credential (PID (Person Identification Data)The core identity data a state issues at the highest assurance level. Tamga does not take this role; its identity credential is not a PID.); reserved today |
2. List rules
Your list is in the SPEC-TRUST-0001 format and follows these rules:
- Signature: ES256; the signer certificate matches
signing_certsin the LOTL entry. At least two rolling signers are recommended. - Version chain: each publication carries the hash of the previous one (
previous_version_hash); the version never goes back; rows are not deleted, their status changes. - Freshness:
next_updateat most 90 days ahead; changes are live within 24 hours. A stale list gives "could not be verified" at the verifier. - No personal data: the list, the anchor logA public, append-only log of hashes of signed lists, so anyone can check that a list was not silently changed. and the change log contain no personal data.
- Identifiers by the ledger formula:
issuer_id,ca_id,schema_idstay the same when the ledger opens (ADR-0009).
3. Registration and publishing tool
The list publisher is open source (apps/trust-publisher). It runs registration without hand-editing:
npm run trust:register -- issuer application.json # add an issuer (reports all missing fields at once)
npm run trust:register -- rp application.json # add a verifier
npm run trust:authorize -- <slug> <vct> # credential type authorisation (--revoke to end it)
npm run trust:status -- <slug> SUSPENDED --reason r
npm run trust:build # sign and publish (dist/)
npm run trust:verify # verify the publicationApplication formats: GUIDE-0007 and GUIDE-0008.
4. Recognition
recognition.mode and recognizes[] say which countries' institutions this country recognises. The verifier asks this in step C3 of SPEC-API-0001 (isRecognizedBy). Mutual recognition between countries is the member states' decision.
B. External list (ETSI)
If your country's or the EU's list is in the ETSI format, you do not need to move it; a pointer is added to the LOTL:
{
"list_id": "example-pid-list",
"territory": "TR",
"format": "etsi-lote-json",
"list_url": "https://example.org/lote/pid-providers.jws",
"signing_keys": [{ "fingerprint_sha256": "…", "status": "ACTIVE" }],
"operator": { "name": "…" },
"status": "ACTIVE",
"scope": {
"entity_kinds": ["pid_provider", "wallet_provider"],
"vct": ["urn:eudi:pid:1", "eu.europa.ec.eudi.pid.1"],
"category": "IDENTITY",
"assurance": "I3",
"class": "PUB",
"recognized_by": ["TR"],
"min_key_storage": "secure_enclave"
},
"approval": { "approved_at": "…", "ref": "…" }
}- Scope: an external list can vouch only for the roles in
scope.entity_kinds(wallet_provider,pid_provider,eaa_provider,access_ca) and the types inscope.vct; out-of-scope entries are ignored. - The signer is pinned: a list whose signer does not match the one in the LOTL is not loaded.
- Independence: if an external list is missing or stale, the Tamga lists are not affected; only questions that depend on that list answer "unknown".
- Format:
etsi-lote-json(ETSI TS 119 602) andetsi-tl-xml(ETSI TS 119 612, XAdES enveloped signature; packages 0.5.0) are read. The publisher's copy isexternal/<list_id>.jwsor.xml. - Copy: the publisher keeps a copy of the list at
trust.tamga.network/external/<list_id>.jws(npm run trust:external); the signature is always checked against the pinned signer. - Approval: adding, changing or removing an external list takes project management approval and is recorded in the
approvalfield; an entry containing placeholders is not published (FD4).
Hand-over
The roles Tamga holds on a state's behalf (list operator, registrar, root CA, provisional identity provider) are designed to be handed over. In a hand-over only the address and the signer change for credentials, wallets and verifiers; identifiers and issued credentials stay valid (ADR-0035 PO3). The ETSI TS 119 612 view of the national list that the EU expects will be added to the publisher before the state stage.
Rules
| Code | What it says |
|---|---|
| ADR-0036 FD1 | An external list is shown in the LOTL only with its address, pinned signer and scope |
| ADR-0036 FD2 | An external list cannot vouch for roles and types outside its scope |
| ADR-0036 FD3 | A problem with an external list does not affect the freshness of the Tamga lists |
| ADR-0035 PO3 | Roles held on a state's behalf can be handed over; only the address and the signer change |
| Unknown format | The reader stops on an unknown format version (ARCH-0003 CMP2) |
List operator rules: Tamga ARF — Tamga Rulebook, RB-OP.