Procivis One Trust Registry

Learn how to manage trust lists with Procivis One.

Establish trust in interactions by using a trust registry.

What is Procivis One Trust Registry

As an issuer or verifier, it's important to build trust with wallet holders.

Procivis Trust Registry enables organizations to publish a list of DIDs authorized to issue or verify for their organization. This list is called a "trust anchor" and the DIDs on the list are called "trust entities". Administrators of the organization manage the list, ensuring that only the DIDs of authorized issuers or verifiers are published to the list.

Wallets can subscribe to lists that are trusted and then convey to the holder whether they are interacting with a trusted issuer or verifier. Trust entity registrations can also carry organizational metadata such as a logo, a website, and URLs for privacy policies and terms of service.

Scenario

The following is an example scenario depicting the use of Procivis Trust Registry to establish trust between holders and the issuers and verifiers with whom they interact.

Several banks publish their own trust anchors. These trust anchors represent their issuer and verifier agents and help others out in the world know whether they are dealing with their bank or an imposter.

Additionally, a banking consortium that helps establish common standards for the banks publishes a list of verified trust anchors of its members. Since the wallet maker trusts the consortium to give official trust anchor information for banks, the wallet automatically subscribes to all the trust anchors on the consortium's list.

For the wallet holder, this adds trust to each interaction with banks on the consortium's list. When dealing with an official issuer or verifier from the list, this information is conveyed through the wallet to the holder. Conversely, when the wallet holder encounters an issuer or verifier whose DID is not part of any subscribed trust anchor, the wallet is able to warn the holder.

Trust anchors

info

The instructions here describe creation and management of trust anchors in the Procivis One Desk and Desk API, which enforces roles and permissions.

The same trust management resources are available in the Core. If you are integrating the Core, keep in mind that it exposes all organizations and actions equally, has no admin role and enforces no organizational dividers, so some of these instructions will apply differently.

Related guide: Organizations

A trust anchor is a list of DIDs authorized to issue or verify for an organization. The following sections give guidance on how to create and manage trust anchors in Procivis One.

Only admin users can create and delete a trust anchor.

Create and delete a trust anchor

Admin users can create a trust anchor to register the DIDs of their issuers and verifiers. The anchor is published for external consumption.

The system supports the creation of one trust anchor per Core instance. This means a multi-tenant setup would have a single trust anchor and multiple trust entities.

For a Core instance to publish its trust anchor, the configuration parameter enablePublishing must be true.

To create a trust anchor

1. Call POST on the /api/trust-anchor/v1 endpoint with a request body specifying the following:

{
  "isPublisher": true,
  "name": "{NAME_OF_ANCHOR}",
  "type": "SIMPLE_TRUST_LIST" // Value from the configuration
}

Once created, the anchor is published for external consumption and the trust entities can be added. The publication URL is found in the publisherReference field when retrieving a trust anchor.

To delete a trust anchor

1. Call DELETE on /api/trust-anchor/v1/:id using the UUID of the trust anchor.

Trust entities

info

The instructions here describe creation and management of trust anchors in the Procivis One Desk and Desk API, which enforces roles and permissions.

The same trust management resources are available in the Core. If you are integrating the Core, keep in mind that it exposes all organizations and actions equally, has no admin role and enforces no organizational dividers, so some of these instructions will apply differently.

See the organizations guide for more.

A trust entity is a DID listed on a trust anchor as an authorized issuer or verifier. The following sections give guidance to on how to create and manage trust entities in Procivis One.

Managing trust entities

Keeping trust entities accurate and updated increases trust in interactions with wallet holders.

Both admin and non-admin users can manage a trust anchor by adding and removing trust entities, and by updating metadata of trust entities. The key differences between admin users and non-admin users when managing trust entities are:

• Admin users can create, access and manage trust entities across all organizations. Non-admin users can create, access and manage trust entities whose DIDs were created in the active organization of their session.
• Admin users can REMOVE entities while non-admin users can only WITHDRAW entities. A removed entity can only be activated to the anchor by an admin; a withdrawn entity can be activated to the anchor by both admin and non-admin users.

To create a trust entity

1. Call POST on the /api/trust-entity/v1 endpoint with a request body specifying the following:

{
  "didId": "{UUID_OF_DID}",
  "name": "{NAME_OF_ENTITY}",
  "role": "ISSUER", // One of: ISSUER, VERIFIER, BOTH
  "trustAnchorId": "{UUID_OF_ANCHOR}",
  "logo": "data:image/png;base64,YOUR_BASE64_ENCODED_IMAGE", // (Optional) maximum size = 50kb
  "privacyUrl": "https://example.com/privacy_policy", // (Optional)
  "termsUrl": "https://example.com/terms_of_service", // (Optional)
  "website": "https://example.com" // (Optional)
}

To update a trust entity

1. Call PATCH on the /api/trust-entity/v1/{id} endpoint with a request body specifying the following:

{
  "name": "{NAME_OF_ENTITY}",
  "role": "BOTH", // One of: ISSUER, VERIFIER, BOTH
  "logo": "data:image/png;base64,YOUR_BASE64_ENCODED_IMAGE", // (Optional), maximum size = 50kb
  "privacyUrl": "https://example.com/privacy_policy", // (Optional)
  "termsUrl": "https://example.com/terms_of_service", // (Optional)
  "website": "https://example.com" // (Optional)
}

To remove a trust entity

1. Call PATCH on the /api/trust-entity/v1/{id} endpoint with a request body specifying the following:

{
  "action": "REMOVE"
}

Once "removed", an entity can only be returned to a trust anchor by an admin.

To withdraw a trust entity

1. Call PATCH on the /api/trust-entity/v1/{id} endpoint with a request body specifying the following:

{
  "action": "WITHDRAW"
}

To reactivate a trust entity

A trust entity that has been removed by an admin can be reactivated by an admin.

A trust entity that has been withdrawn by a user can be reactivated by an admin or by a non-admin user whose active organization owns the related DID.

1. Call PATCH on the /api/trust-entity/v1/{id} endpoint with a request body specifying the following:

{
  "action": "ACTIVATE"
}

Subscribing to a trust anchor

While each Core instance publishes a trust anchor, verifiers and wallets subscribe to these trust anchors to get information on issuers and verifiers.

Verifiers subscribe to trust anchors so they know whether the credentials presented to them were issued by a trusted issuer.

Wallets subscribe to trust anchors so they know whether the issuers and verifiers they interact with are trusted.

To subscribe to a trust anchor

Subscribing to a trust anchor as a consumer requires creating a new trust anchor and specifying the publication URL via publisherReference.

1. Call POST on the /api/trust-anchor/v1 endpoint with a request body specifying the following:

{
  "name": "{NAME_OF_ANCHOR}",
  "type": "SIMPLE_TRUST_LIST", // Value from the configuration
  "publisherReference": "{URL_OF_TRUST_ANCHOR}"
}

The publisher reference URL takes the following form:

{CORE_URL}/ssi/trust/v1/{TRUST_ANCHOR_ID}

Mobile wallets and verifiers

Managing trust entities remotely

In addition to subscribing to trust anchors, mobile verifiers can exercise non-admin privileges to manage trust entities by using the remote trust entity endpoints:

Endpoint	Description
/api/trust-entity/remote/v1	POST to add a trust entity to a trust anchor from a mobile device. (SDK)
/api/trust-entity/remote/v1/{DID_ID}	GET to retrieve a trust entity from a remote trust anchor (SDK); PATCH to update a trust entity on a remote trust anchor (SDK).

These endpoints are used in the same way as the non-remote endpoints, but include logic that signs the authorization header with the private key of the mobile verifier's DID. Creating a trust entity remotely also adds the remote DID to the publisher's database.

Managing trust anchors

When mobile wallets and verifiers subscribe to a trust anchor, the anchor is retrieved from the web and stored in the cache. See the caching guide for more information.

Retrieving and displaying trust info for wallets

When a wallet uses the handle invitation endpoint, the Core also retrieves the issuer or verifier DID and checks it against the trust entities in the cache. For DIDs which are a trusted entity, use the GET trust entity by DID method to return display information such as entity logo and other metadata.

Exceptions

For verification, the Client ID Scheme of the proof request must be verifier_attestation in order to obtain and validate the verifier DID. Verifiers using other Client ID Schemes will always be considered "untrusted".