Learn how to set up a VICAL
Introduction
The purpose of a Verified Issuer Certificate Authority List (VICAL) is to enable different participants in a digital ecosystem to rely on a single trusted framework.
This guide will walk you through setting up a VICAL and publishing a policy that defines trusted participants and credential types. 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 VICAL 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 VICAL comprises the following steps:
- Create an Ecosystem: This is the overarching entity that holds participants and credential types together. Only required if you don't already have an ecosystem on your tenant.
- Create participants and add issuer certificates: These are the issuers that will be part of the VICAL. Each participant includes one or more IACA certificates and the credential types they are allowed to issue.
- Set up the VICAL signing certificate chain: Establish the DTS root CA and VICAL Signer Certificate used to sign the VICAL, using either a 2-tier or 3-tier model.
- Manually publish a VICAL: Configure the VICAL provider, then generate and publish a VICAL that includes your participants and their credential types.
- Configure VICAL auto-generation and publishing (optional): Set the VICAL to automatically generate and publish on a daily or weekly schedule.
- View previously published VICALs (optional): Review the history of previously published VICALs and download their policy files.
- Delete a VICAL (optional): Remove a specific published VICAL 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 RICAL), 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 issuer certificates
Participants are entities that represent issuers that will be included in the VICAL. For each participant, you will need to provide one or more IACA certificates that will be used as the trust anchor when signing mDocs, and define what credential types they are allowed to issue.
Perform the following steps to create a participant:
-
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 DMV").
-
Use the Country dropdown list to select the Participant’s country (optional). Note that when selected, this value must match the Country value in the IACA 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). Note that when selected, this value must match the StateOrProvinceName value in the IACA certificate associated with this participant.
-
Insert the participant’s Address (optional).
-
Insert the participant’s Phone number (optional).
-
Use the Status radio button to set the participant as Active.
-
Click the Next button.
You are directed to Step 2 (Certificates). -
Click the Create button to create the participant.
-
Select the Issuer certificates tab.
-
Select the Add new button to add an issuer certificate for the participant.
The Add issuer certificate form appears. -
Upload the PEM file you want to use as this participant’s identifier for issuing mDocs (this must be a valid IACA certificate and match any values set for Country and State or Province above).
You should now see the certificate summary and details. -
Use the Credential types valid for field to select the credential types that this participant will be allowed to issue.
- You can insert as many credential types as you want.
- You can use the pre-populated options (
org.iso.18013.5.1.mDLand/ororg.iso.23220.photoid.1) or insert custom credential types that are relevant to your ecosystem. - The credential type is just a string value and does not need to match any values in the certificate. It is only used to link the participant to the credential types they are allowed to issue.
-
Scroll down and use the Status dropdown list to set the certificate as Active.
-
(Optional) To maintain trust continuity when rotating a participant's IACA 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.
-
Click the Add button.
Repeat the above steps for each participant you want to include in your VICAL.
Set up the VICAL signing certificate chain
Each VICAL must be signed by a VICAL Signer Certificate (VSC) that chains back to a DTS root CA via a chain of trust. This chain is what consuming relying parties use as the trust anchor to validate the authenticity and integrity of the VICAL.
If you already have an existing active DTS root CA that you want to use as the trust anchor for your VICAL, 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 VICAL
After you have set up the signing certificate chain, you can publish a VICAL that includes your participants and their associated credential types. When you publish the VICAL, the MATTR VII platform will sign a VICAL that includes the information you provided for each participant, along with the PEM-encoded IACA certificate.
- Navigate to the Trust lists page under the Digital Trust Service section.
- Select the VICAL (Trusted issuers) tab.
- Enter a meaningful Provider name to identify the provider of the VICAL. This will be included in the VICAL metadata and used by relying parties to identify the source of the VICAL.
- Select the Create button.
- Review the preview area where you can see all participants and credential types included in the VICAL.
- Select Generate & Publish when you are ready.
The VICAL is now generated and published, and a modal is displayed where you can:- Use the Download button to download the VICAL policy file.
- Use the Copy button to copy a link to the public endpoint where relying parties can access the policy.
Configure VICAL auto-generation and publishing (optional)
You can optionally set up auto-generation of your VICAL so it is generated and published on a schedule.
- Return to the Trust lists page under the Digital Trust Service section.
- Select the VICAL (Trusted issuers) tab.
- Expand the VICAL 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 VICAL to be automatically generated and published (daily/weekly).
- Select the Update button.
- Review the preview area where you can see all participants and credential types included in the VICAL.
Note that the VICAL 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 VICAL immediately, you can select the Generate & Publish button.
View Previously Published VICALs (optional)
- Return to the Trust lists page under the Digital Trust Service section.
- Select the VICAL (Trusted issuers) tab.
- Scroll down and select the View Previously Published button to see all previously published VICALs.
- Use the Download button to download the policy file for any previously published VICAL displayed.
Delete a VICAL (optional)
You can delete a specific published VICAL from your ecosystem using its version identifier
(vicalIssueId). This is useful if a VICAL was published in error or is no longer required.
Deleting a VICAL also deletes the issuer policy that was published from it, if one exists. Relying parties that fetch the latest VICAL will then receive the most recent remaining VICAL instead. Make sure you no longer need the VICAL before you delete it, as this action cannot be undone.
Deleting a specific published VICAL is currently only available through the MATTR VII API.
First, if you do not already have the vicalIssueId, make a request of the following structure to
retrieve all VICALs and
find the one you want to delete:
GET /v1/ecosystems/{ecosystemId}/vicals/publicThen, make a request of the following structure to delete a VICAL using its version identifier:
DELETE /v1/ecosystems/{ecosystemId}/vicals/{vicalIssueId}ecosystemId: Replace with theidvalue of your ecosystem.vicalIssueId: Replace with the value of thevicalIssueIDfield returned when you list or retrieve the VICAL you want to delete.
A successful request returns a 204 No Content response.
Next steps
Now that you have published your VICAL, you can share the public endpoint with relying parties so they can consume the VICAL and establish trust in the issuers and credential types included in it. You can also refer to the VICAL consumption guide to learn how relying parties can consume, validate and use a VICAL.
How would you rate this page?
Last updated on