Learn how to set up a RICAL
Introduction
The purpose of a Reader Identity Certificate Authority List (RICAL) is to enable holder applications (wallets) in a digital ecosystem to verify the identity of relying parties (verifiers) from a single authoritative source. It is the counterpart to a VICAL: where a VICAL distributes trusted issuer roots, a RICAL distributes trusted verifier roots.
ISO/IEC 18013-5 uses the term reader for the entity that requests data from an mDoc. Throughout this documentation we use verifier or relying party for the same role. Certificate names defined by the standard (for example, Reader Root Certificate) keep their ISO terminology.
This guide will walk you through setting up a RICAL and publishing a list of trusted Reader Root Certificates. Each step can be completed either through the Portal or via the MATTR VII API. Select the tab that matches how you want to work.
Prerequisites
- Make sure you understand the concepts of a RICAL and how it relates to a Digital Trust Service (DTS).
- You need access to an existing MATTR VII tenant with either the
DTS ProviderorAdminrole. Refer to the Getting started with the Portal tutorial to learn how to create a tenant and assign roles. - To use the API, you also need to obtain a bearer access token
to include in the
Authorizationheader of each request.
Guide overview
Publishing a RICAL comprises the following steps:
- Create an Ecosystem: This is the overarching entity that holds participants together. Only required if you don't already have an ecosystem on your tenant.
- Create participants and add verifier certificates: These are the relying parties (verifiers) that will be part of the RICAL. Each participant includes a Reader Root Certificate that anchors its verifier requests.
- Set up the RICAL signing certificate chain: Establish the DTS root CA and RICAL Signer Certificate used to sign the RICAL, using either a 2-tier or 3-tier model.
- Manually publish a RICAL: Configure the RICAL provider, then generate and publish a RICAL that includes your trusted Reader Root Certificates.
- Configure RICAL auto-generation and publishing (optional): Set the RICAL to automatically generate and publish on a daily or weekly schedule.
- View previously published RICALs (optional): Review the history of previously published RICALs and download their files.
- Delete a RICAL (optional): Remove a specific published RICAL from the ecosystem using its version identifier.
Create an Ecosystem
Creating an Ecosystem is a one-time step per tenant. It is only required if you don't already have an ecosystem on your tenant. If you already have an ecosystem (for example, because you created one when setting up a VICAL), you will not see the option to create a new one (in the Portal) and should skip directly to the next step. A single ecosystem is shared across both your VICAL and RICAL.
Perform the following steps to create an Ecosystem:
- Log in to the MATTR Portal.
- Navigate to the Ecosystem page under the Digital Trust Service section.
- Enter a name for your Ecosystem, such as "My Digital Trust Service".
- Select the Create button.
Create participants and add verifier certificates
Participants in a RICAL are the relying parties (verifiers) whose Reader Root Certificates you want holders to trust. For each participant, you upload a Reader Root Certificate (referred to as a Verifier CA in MATTR VII) that anchors the chain used to sign that verifier's requests.
Unlike an issuer participant in a VICAL, a verifier participant in a RICAL does not declare
credential types (docTypes). A trusted Reader Root Certificate is treated as authoritative for the
ecosystem rather than scoped to specific credential types. Authorization of what a verifier may
request is conveyed separately through the verifier's signed request and the holder's consent flow.
Perform the following steps to create a participant and add its verifier certificate:
-
Select the Participants page under the Digital Trust Service section (this page is only visible if you have an existing ecosystem. If you don't have an ecosystem, you will need to return to step 1 above and create it first).
-
Select the Create new button.
The Create participant form appears, starting from Step 1 (Details). -
Insert a meaningful Name for the participant (e.g. "Montcliff Police").
-
Use the Country dropdown list to select the participant's country (optional). When selected, this value must match the Country value in the verifier certificate associated with this participant.
-
If you select a country, a State or Province dropdown list is displayed. You can use it to select the participant's state or province (optional). When selected, this value must match the
stateOrProvinceNamevalue in the verifier certificate associated with this participant. -
Insert the participant's Address and Phone number (optional).
-
Use the Status radio button to set the participant as Active.
-
Select the Next button.
You are directed to Step 2 (Certificates). -
Select the Create button to create the participant.
-
Select the Verifier certificates tab.
-
Select the Add new button to add a verifier certificate for the participant.
The Add verifier certificate form appears. -
Paste/upload the PEM-encoded Reader Root Certificate into the Certificate PEM file field.
-
Use the Status radio button to set the certificate to Active.
-
(Optional) To maintain trust continuity when rotating a participant's Reader Root Certificate, expand the Link Certificate section and add this certificate as a successor to a previously uploaded certificate (refer to Linked certificates):
- Use the Predecessor certificate dropdown to select the previous certificate that this new one succeeds. The dropdown lists the participant's existing certificates because the predecessor must already exist on your tenant before you can link to it.
- Upload the link certificate into the Link Certificate PEM file field. The link certificate is the participant's proof that they own both the predecessor and the new certificate, which is what lets you accept the new one while preserving trust in the previous one.
This option is only available once at least one certificate has been added for the participant.
-
Select the Add button.
Repeat the above steps for each relying party (verifier) you want to include in your RICAL.
Set up the RICAL signing certificate chain
Each RICAL must be signed by a RICAL Signer Certificate (RSC) that chains back to a DTS root CA via a chain of trust. This chain is what consuming wallets use as the trust anchor to validate the authenticity and integrity of the RICAL.
If you already have an existing active DTS root CA that you want to use as the trust anchor for your RICAL, you can skip this step.
MATTR VII supports both managed and unmanaged (external) DTS certificates. Select the option that matches how you want to manage your certificate infrastructure.
With managed DTS certificates, MATTR VII provisions and maintains the DTS root CA and the signer certificates for you. You create and activate the DTS root CA, and MATTR VII automatically creates a signer (and its certificate) and uses it to sign trust lists as required. Managed DTS certificates always use the 2-tier model.
- Navigate to the Certificates page under the Platform Management section.
- Select the Create new button.
The New certificate form appears. - Use the Type dropdown list to select DTS CA.
- Use the Management method radio button to select MATTR managed.
- Enter a meaningful name in the Organization field to identify the organization operating the DTS.
- Use the Country dropdown list to select the country where the organization is located.
- Select the Create button.
The DTS root CA is created in an inactive state. - Scroll down and use the Status radio button to select Active.
- Select the Update button to activate the DTS root CA.
Once a managed DTS root CA is activated, MATTR VII automatically creates and uses a signer to sign trust lists as required.
Manually Publish a RICAL
After you have created your participants and set up the signing certificate chain, you can publish a RICAL that includes the trusted Reader Root Certificates. When you publish the RICAL, MATTR VII signs a list that includes the information you provided for each Reader Root Certificate.
- Navigate to the Trust lists page under the Digital Trust Service section.
- Select the RICAL (Trusted verifiers) tab.
- Enter a meaningful Provider name to identify the provider of the RICAL. This is included in the RICAL metadata and used by wallets to identify the source of the RICAL.
- Select the Create button.
- Review the preview area where you can see all Reader Root Certificates included in the RICAL.
- Select Generate & Publish when you are ready.
The RICAL is now generated and published, and a modal is displayed where you can:- Use the Download button to download the RICAL file (CBOR).
- Use the Copy button to copy a link to the public endpoint where wallets can access the RICAL.
Configure RICAL auto-generation and publishing (optional)
You can optionally set up auto-generation of your RICAL so it is generated and published on a schedule.
- Return to the Trust lists page under the Digital Trust Service section.
- Select the RICAL (Trusted verifiers) tab.
- Expand the RICAL configuration panel.
- Use the Generation method radio button to select Auto generate.
- Use the Auto generate frequency dropdown list to select how often you want the RICAL to be automatically generated and published (daily/weekly).
- Select the Update button.
- Review the preview area where you can see all Reader Root Certificates included in the RICAL.
Note that the RICAL is not generated and published yet. It will only be generated and published automatically based on the frequency you selected in step 5 above. If you want to generate and publish the RICAL immediately, you can select the Generate & Publish button.
View Previously Published RICALs (optional)
- Return to the Trust lists page under the Digital Trust Service section.
- Select the RICAL (Trusted verifiers) tab.
- Scroll down and select the View Previously Published button to open the Previously generated RICAL view, which lists each RICAL with its Issue ID, Generated at time, File name, Trigger method, and Status.
- Use the Download button to download any previously published RICAL.
Delete a RICAL (optional)
You can delete a specific published RICAL from your ecosystem using its version identifier
(ricalIssueId). This is useful if a RICAL was published in error or is no longer required.
Deleting a RICAL also deletes the verifier policy that was published from it, if one exists. Wallets that fetch the latest RICAL will then receive the most recent remaining RICAL instead. Make sure you no longer need the RICAL before you delete it, as this action cannot be undone.
Deleting a specific published RICAL is currently only available through the MATTR VII API.
First, if you do not already have the ricalIssueId, make a request of the following structure to
retrieve all RICALs and find the one you want to
delete:
GET /v1/ecosystems/{ecosystemId}/ricals/publicThen, make a request of the following structure to delete a RICAL using its version identifier:
DELETE /v1/ecosystems/{ecosystemId}/ricals/{ricalIssueId}ecosystemId: Replace with theidvalue of your ecosystem.ricalIssueId: Replace with the value of thericalIssueIDfield returned when you list or retrieve the RICAL you want to delete.
A successful request returns a 204 No Content response.
Next steps
Now that you have published your RICAL, you can share the public endpoint with wallet providers so they can consume the RICAL and establish trust in the verifiers included in it. Refer to the RICAL consumption guide to learn how wallets can retrieve, validate and use a RICAL.
How would you rate this page?
Last updated on