Revocation

Overview

You can use MATTR VII to change the status of issued mDocs if you ever need to revoke or suspend them for any reason. Verifiers can then obtain the status of presented mDoc in a way that preserves holders’ privacy.

MATTR’s implementation of mDocs revocation is based on the IETF Token Status List draft. A revocable mDoc includes a reference to a status list which is managed by the issuer. The list contains the revocation status of multiple credentials, and each credential references the index of its status within a specific status list.

Status lists are automatically created and managed when you use your MATTR VII tenant to issue revocable mDocs. They are publicly available and mainly consumed by external verifiers to check the status of presented mDocs.

When a relying party retrieves a status list, the issuer cannot tell what specific mDoc they are checking the status for. This means the issuer does not know how often or to whom an mDoc is being presented, maintaining holder`s privacy.

As mDocs revocation is an emerging standard, relying parties are not enforced to implement it. As a result, relying parties which have not implemented revocation checks might assess a presented mDoc as valid, even when it was revoked by the issuer.

Status values

The following status are available for revocable mDocs:

Valid: The mDoc is valid. Valid mDocs can be updated to Invalid or Suspended.
Invalid: The mDoc is revoked. This state is irreversible - once an mDoc status was updated to Invalid, it cannot be updated to any other status. This value should be used for permanently revoking an mDoc.
Suspended: The mDoc is temporarily revoked. Suspended mDocs can be updated to Valid or Invalid. This value should be used for temporarily revoking an mDoc.

Revocable mDocs

By default signed mDocs are not revocable. To issue revocable mDocs and enable changing their status at a later date, the request payload must set includeStatus to true. This can be added when creating an mDoc credential configuration.

This results in the following:

The mDoc status is added to a status list.
The issued mDoc includes a status object in its MSO payload that references this status list:

"status": {
    "status_list": {
        "uri": "https://learn.vii.au01.mattr.global/v2/credentials/mobile/status-lists/f331c9be-f526-4577-bbac-ae93d6228f7a/token",
        "idx": 0
    }
}

status_list : References the status list that holds the status information for this mDoc.
uri: Relying parties can use this publicly available endpoint to retrieve the status list token.
idx: Indicates the index of the mDoc status within the referenced status list.

Status list

MATTR VII automatically creates and manages status lists when revocable mDocs are signed.

A status list is a string of characters which can be either 0 or 1. Each credential status is mapped to a position in the list and occupies two characters:

00: Valid.
01: Invalid.
10: Suspended.

Each list can hold the status of up to 500,000 individual mDocs.

Status list tokens

When a relying party attempts to retrieve a status list the response does not include the raw status list, but rather a signed version which is referred to as a status list token. This is a CBOR Web Token which includes the following information in its payload:

iat : Timestamp when the status list token was signed.
sub : The URI that was used to retrieve the token. This must match the uri from the mDoc status object.
exp : Timestamp at which the token expires and the relying party can no longer use it to check the mDoc status. This prevents relying parties from using locally cached tokens in their verification workflows for too long, and forces them to retrieve a new token with the most up-to-date mDocs status. Defaults to one week from when the token was signed but can be adjusted using a Status list configuration. Regardless of the Status list configuration, exp can never exceed the validity of the IACA used to sign the Status list token.
ttl (Time To Live): Recommended duration (in seconds) the relying party should use this token before retrieving a new one. This guides best practices for relying parties to ensure they are using the most up-to-date mDocs status in their verification workflows. Defaults to one day but can be adjusted using a Status list configuration. Regardless of the Status list configuration, ttl can never exceed exp.
status_list:
- bits : Details the number of bits each mDoc occupies in the list (currently two but might be adjusted in the future).
- lst : Compressed zlib byte string containing the status of all mDocs included in this status list.

Caching

Status list tokens are automatically managed by MATTR VII and cached for improved performance. Once a new Status list token is signed, it can be cached for a minimum time of 1 minute and up to a maximum of 24 hours. The cache is cleared and a new Status list token is signed in the following scenarios:

The Status list token has reached its maximal caching limit (24 hours).
The referenced Status list configuration is updated.
The status list is updated (e.g. the status of an mDoc that is included in the status list is changed).

IACA deletion

Status list tokens must be signed using the same IACA that was used to sign the mDocs that are included in the status list. If this IACA is deleted, all status lists signed by it are deleted as well, and relying parties will not be able to retrieve new Status list tokens that include the status of these mDocs. When attempting to manually retrieve the revocation status of these mDocs, the returned status will be Unknown.

When an IACA is deleted, relying parties can still use locally cached copies of Status list token signed by this IACA until they reach their set exp.

Status list configuration

Issuers can optionally create status list configurations to manually adjust the Status list ttl and exp values for a specific docType. This enables issuers to adjust the duration for which relying parties can use a status list token before being forced to retrieve a new copy.

Status list configurations are unique per docType per tenant and are referenced by the Status lists that include mDocs of this docType.

If no Status list configuration is available, MATTR VII will automatically create one when a new Status list is created based on the default ttl (one day) and exp (one week) values.

Status list distribution

Any relying party is able to retrieve an Issuer’s status lists and cache them locally to support offline verification workflows.

This is achieved by making a GET request to the distribution endpoint. This endpoint is public and does not require any authentication. It is referenced in the issuer’s IACA X509v3 extensions element under the 1.3.6.1.4.1.61546.100 OID, as shown in the following example:

X509v3 extensions:
    1.3.6.1.4.1.61546.100:
        https://learn.vii.au01.mattr.global/v2/credentials/mobile/status-lists/distribution

The response will include a status_lists array which details the URIs of the different Status list tokens that are available on this MATTR VII tenant, as shown in the following example:

JSON

{
    "status_lists": [
        {
            "uri": "https://learn.vii.au01.mattr.global/v2/credentials/mobile/status-lists/{id}/token"
        }
    ]
}

Status list tokens signed by expired IACAs are excluded from the response.

Additional resources

Guides

Create an mDoc credential configuration Revoke an mDoc credential

API Reference

Create an mDoc credential configuration Update an mDoc status

Verification workflows Structure to function