Skip to main content

Manage Your Organisation's Trust Anchors

Specifications:

In short​

  • A trust anchor is something your organisation trusts directly: an ETSI list, or CA certificates that you add. Every trust check of the iGrant.io Organisation Wallet Suite uses only the trust anchors that you choose.
  • Each trust anchor has one kind and one role, Used As. The kinds are ETSI LOTE (a List of Trusted Entities, ETSI TS 119 602), ETSI TL (a Trusted List, ETSI TS 119 612) and CA (X.509) (CA certificates in PEM).
  • You manage them on the Trust Anchors page of the dashboard (Issuer & Verifier > Trust Anchors) or with the Trust Sources API. The API calls a trust anchor a trust source.
  • For demos, interoperability tests and other non-production use, add the lists of the NXD Trust List. For production, add the official EU lists.

The Trust Anchors page​

  • Counters: Total, Current, Out of date, Expired and Not downloaded. Select a card to show only its trust anchors.
  • Search and filters: search by name, and filter by Kind and Used as.
  • Table: Name, Kind, Used As, State, Entries, Accepted By, Last Updated and Active.
    • State: select the i icon next to it to see what each state means.
    • Entries: for a list, how many entries of the list the trust anchor uses for its role, of all the entries of the list, for example 49 of 54. When it uses all the entries, the cell shows one number. For a CA (X.509) trust anchor, the number of its CA certificates.
      • Put the pointer on the number to read the roles of the other entries.
      • An amber 0 of 61 tells that no entry of the list has the role of the trust anchor, so the checks find no signer in it. Edit the trust anchor and choose a role of the list, or add the list again as a second trust anchor for the other role.
    • Accepted By: how many settings name the trust anchor in an accepted list. Select the number to see them.
  • Row menu: View the entries, Edit, Refresh the list (a list only) and Delete.

Each change saves at once.

A sandbox uses the trust anchors of its main organisation. A change in a sandbox changes them for the main organisation and all its sandboxes.

Add a trust anchor​

In the dashboard, select the add icon next to Trust Anchors, then fill in the form:

  1. Kind. Choose ETSI LOTE (List of Trusted Entities), ETSI TL (Trusted List) or CA (X.509). You cannot change the kind later.
  2. Name (optional).
    • A list defaults to its scheme name, or else the last part of its URL.
    • A CA (X.509) defaults to the common name (CN) of its first certificate.
    • Give a list a name of your own when its URL ends in a generic file name such as tl.xml.
  3. For a list:
    • List URL.
    • List signer certificate (optional). Take it from a source that you trust, for example the pointer to the list in a List of Trusted Lists.
  4. For a CA (X.509): the CA certificates in PEM, and optionally the CRLs of these CAs (-----BEGIN X509 CRL-----). Never paste a private key.
  5. Used as. Choose the one role that the checks use this trust anchor for. See Trust Roles.

The form reads the list before you add it. When the List URL field or the List signer certificate field loses the focus, the wallet reads the list, and saves nothing:

  • Above Used as, the form shows Roles of the list: each role that the list gives its entries, with the number of entries, for example PID provider (17). When the list names no role for some entries, No role gives their number. The edit form shows the roles of the stored copy of the list, until you change its URL or its signer certificate.
  • If you did not choose a role yet, the form selects the role that has the most entries.
  • Under Used as, a line tells how many entries of the list the trust anchor uses for the role that you chose. The line is amber when no entry has that role. You can still add the trust anchor, because the list can change, but the checks find no signer in it while no entry has the role. The role Status issuer is different: the wallet refuses a list that has no service with that role.
  • If the wallet cannot read the list as a list of the kind you chose, or its signature does not verify with the list signer certificate you gave, the form shows the reason at the List URL field.

Select Add. The wallet reads the list again, and the notification tells you the result. If the wallet cannot use the list, nothing is saved, and the form shows the reason at the List URL field.

With the API, call Add trust source. To read a list before you add it, call Preview trust source. An example of an add:

curl -X POST "https://demo-api.igrant.io/v4/config/ows/trust/sources" \
-H "Authorization: ApiKey $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "etsi_lote",
"name": "NXD Trust List: wallet providers",
"url": "https://trustlist.nxd.foundation/trust-lists/NXD-TL-WalletProviders.xml",
"usedFor": "wallet_provider"
}'

The API values of the kinds are etsi_lote, etsi_trusted_list and trust_anchor (CA (X.509)). A CA (X.509) takes certificates (PEM text) in place of url. A list takes the optional signerCertificates (PEM text).

Trust the NXD Trust List​

The NXD Foundation (NordXDataspace Foundation) publishes the NXD Trust List: one list for each role. iGrant.io uses it by default for demos, interoperability tests and all other non-production use. Add the lists that your checks need:

List URL (https://trustlist.nxd.foundation/trust-lists/ plus)KindUsed As
NXD-TL-WalletProviders.xmlETSI LOTEWallet provider
NXD-TL-PID.xmlETSI LOTEPID provider
NXD-TL-PubEAA.xmlETSI LOTEPuB-EAA provider
NXD-TL-QEAA.xmlETSI TLQEAA provider
NXD-TL-EAA.xmlETSI TLEAA provider
NXD-TL-WRPAC.xmlETSI LOTEAccess certificate provider
NXD-TL-WRPRC.xmlETSI LOTERegistration certificate provider (no check uses it yet)
  • Two lists cannot be added yet:
    • NXD-TL-WRPRC.xml has no entries today, and a list without entries is refused.
    • NXD-TL-Registrars.xml has no entries either, and no Used As role fits it.
  • XML, not JSON: the six lists of trusted entities are also published as JSON, but add the XML form. The signature of the JSON form does not verify yet; see Interoperability.
  • Signer certificate: all NXD lists are signed with the same NXD Foundation certificate. The WE BUILD List of Trusted Lists gives it in its pointers to NXD-TL-QEAA.xml and NXD-TL-EAA.xml.

Then add each trust anchor to the accepted list of the settings that should use it:

Keep a list current​

StateMeaning
CurrentThe wallet has a good copy, and the list is not past its next update. The checks use it.
Out of dateThe list is past its next update, and no new copy has come yet. For 3 more days the checks use the last copy as usual.
ExpiredThe list is more than 3 days past its next update. The checks still use the last copy, but each match has a warning.
Not downloadedThe wallet has no good copy of the list. The checks do not use it until a download works.
OffYou turned the trust anchor off. The checks do not use it.

A CA (X.509) trust anchor is Current while its CA certificates are valid, and Expired when one of them is past its end date.

  • Automatic refresh: the wallet downloads a list again at its next update, or 24 hours after the last download if that is earlier.
  • Refresh the list: in the row menu, or with Refresh trust source. You can refresh a list at most once every 5 minutes. An earlier refresh is refused with 429 and a Retry-After header.

Look at the entries​

View the entries (or a click on the row) opens the trust anchor:

  • List state: kind, state, list URL, list type, sequence number, last download, last change of the list, next update, next refresh and signature.
  • Accepted by: the settings that accept the trust anchor, also those of sandboxes, which carry the name of their sandbox. You can open a setting of the organisation that you are in.
  • Entries: all the entries of the list, with the provider, the service, the status and the certificate of each entry.
    • Search the entries, and filter them by status, and with All entries, Used or Not used.
    • When the trust anchor does not use all the entries, a line tells how many entries it uses and the roles of the other entries. The line is amber when it uses no entry. The Role column then shows the role that the list gives each entry. No role tells that the list names no role for the entry, so the entry has the role of the trust anchor. Not used marks an entry for another role: its tooltip names that role. See Trust Roles.
    • No certificate marks an entry whose list gives no certificate for its service, for example because the list names the key with a DID.

Select an entry to see its role, its provider, its service and the history of its status, its digital identities, and its certificate, which you can copy or download as PEM.

The same data is in the API: List trust source entries (with used=all for the entries that the trust anchor does not use) and Read trust source entry.

Change, turn off or delete a trust anchor​

  • Edit: change the name, the list URL, the list signer certificate, the CA certificates or the role. A new URL downloads the list again.
  • Active: turn a trust anchor off to stop the checks from using it without deleting it.
  • In use: a trust anchor that a setting accepts, or that a presentation definition names in etsi_tl, cannot be turned off or deleted, and its URL and role cannot change. Remove it from the accepted lists first. In the dashboard, a select of its Active switch shows the settings with Show Settings. In the API, Read trust source usage returns them, and a refused change returns trust_source.in_use.
  • Delete: asks you to type DELETE, then deletes the trust anchor.

API reference​

OperationAPI
Read a list before the add, and save nothingPreview trust source
AddAdd trust source
List and filter (by name, kind, role and state)List trust sources
ReadRead trust source
Change, turn on or offUpdate trust source
DeleteDelete trust source
Download a list againRefresh trust source
Where it is usedRead trust source usage
CountersRead trust source statistics
EntriesList trust source entries, Read trust source entry