Revocation

Overview

Issuers might need to invalidate a previously issued digital credential before its expiry date. This might be required when a credential has been compromised, its status and/or claims have changed, or in cases when a credential is issued in error.

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

The implementation differs based on your chosen credential format:

• mDocs
• CWT credentials

mDocs

MATTR's implementation of mDocs revocation is based on Draft 14 of the IETF Token Status List specification. 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.

Status values

The following status values are available for revocable mDocs:

• Valid: The mDoc is valid. Valid mDocs can be updated to Invalid.
• 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: ⚠️ Deprecated ⚠️ 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 configured 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 : This field includes the information regarding the revocation status of this mDoc. It is added to the MSO payload of the mDoc when includeStatus is set to true in the credential configuration. Legacy credentials issued before the adoption of Draft 14 of the Token Status List specification use the _status field name which is now deprecated. The status field includes the following properties:
  • 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 bit string where each credential status is mapped to a position in the list. The number of bits per credential depends on the tenant configuration:

1-bit status lists (latest specification as per Draft 14 of the Token Status List specification):

• Each credential occupies one bit:
  • 0: Valid
  • 1: Invalid
• Each list can hold the status of up to 500,000 individual mDocs.

2-bit status lists (legacy format, deprecated with the adoption of Draft 14 of the Token Status List specification):

• Each credential occupies two bits:
  • 00: Valid
  • 01: Invalid
  • 10: Suspended
• Each list can hold the status of up to 500,000 individual mDocs.

The bit configuration is specified in the status list token's bits field and is determined by your tenant's configuration.

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.

Token header

The token header includes a typ (type) field that indicates the token's format:

• Latest specification: application/statuslist+cwt
• Legacy format: mattr-statuslist+cwt

Relying parties can use this field to automatically detect and handle both formats.

Token payload

The token payload includes the following information:

• iat (CBOR claim 6): Timestamp when the status list token was signed.
• sub (CBOR claim 2): The URI that was used to retrieve the token. This must match the uri from the mDoc status object.
• exp (CBOR claim 4): 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 (CBOR claim 65534 in latest specification, -65539 in legacy): 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 (CBOR claim 65533 in latest specification, -65538 in legacy):
  • bits: Details the number of bits each mDoc occupies in the list (1 for latest specification, 2 for legacy).
  • lst: Compressed zlib byte string containing the status of all mDocs included in this status list.

Token signature

Status list tokens are signed by Status list signers. By default, MATTR VII automatically creates and manages these signers. If you use unmanaged certificates, you are responsible for managing your own Status list signers and their certificates.

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).

When TTL configuration changes take effect

If you update the status list configuration to change the TTL or EXP values, these changes apply to the entire status list the next time it is signed.

The status list token is re-signed in the following scenarios:

• The current TTL expires
• A credential on the list is updated (e.g., revoked or suspended)
• A new credential is added to the list
• The status list configuration is updated

On the holder or verifier side, the updated status list token (with the new TTL/expiry values) is retrieved when:

• The current cached status list token's TTL expires
• The holder/verifier requests the status list after you have signed the new version

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.

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. The response format varies based on your tenant configuration. Relying parties must support both response formats for compatibility. MATTR SDKs automatically handle both formats:

Draft 14 Specification format:

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

Legacy format:

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

Status list signers

Status list tokens are signed by Status list signers. By default, MATTR VII automatically creates and manages these signers and their Status List Signer Certificates (SLSCs). If you use unmanaged certificates, you are responsible for managing your own Status list signers and their certificates.

Managed SLSCs may be revoked for reasons such as key compromise, role change, or decommissioning. Once revoked, the SLSC’s serial number is published in the Certificate Revocation List (CRL) referenced by its issuing IACA.

Verifiers that retrieve and process the CRL referenced in the IACA must treat a revoked SLSC, and any Status lists it signed, as invalid.

Backward compatibility

MATTR VII maintains backward compatibility between the legacy and Draft 14 Token Status List formats to ensure existing implementations continue to function while enabling adoption of the standardized specification.

Format selection

• Tenants can opt into the latest Token Status List specification via a feature flag. Contact us to enable this for your tenant.
• Legacy format continues to be supported for existing implementations.
• The format is determined at credential issuance time based on tenant configuration.
• Individual credentials cannot change formats after issuance.

Key differences between formats

The following table summarizes the differences between the legacy MATTR format and the latest Token Status List specification:

SDK and verifier compatibility

• MATTR SDKs automatically detect and handle both formats based on the token header typ field
• Verifiers must support both distribution endpoint response structures
• Status list tokens are self-describing - the typ header identifies the format

Migration considerations

When a tenant opts into the latest specification:

• All new credentials are issued using the new format
• Existing credentials continue to use their original format
• Both formats can coexist within the same tenant
• Status lists are maintained separately per format to prevent conflicts

CWT

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

A revocable CWT credential points to a revocation list which is managed by the credential`s issuer. The list contains the revocation status of many credentials, and the credential references the index of its status within a specific revocation list.

Revocation lists are automatically created and managed when you use your MATTR VII tenant to issue revocable credentials. They are publicly available and mainly consumed by external verifiers.

When a verifier requests a revocation list, the issuer cannot tell what credential they are checking the status for. This means the issuer does not know how often or to whom a credential is being presented, maintaining holder`s privacy.

credentialStatus object

When a CWT credential is set as revocable the credentialStatus object is added to the credential:

"status": {
      "index": 4,
      "url": "https://learn.vii.au01.mattr.global/v2/credentials/compact/revocation-lists/f91bbef3-6898-4930-bca3-cf0d4b63e939"
}

• index : This indicates the index of this specific credential within the revocation list.
• url : Every revocable credential will reference a Revocation List that is automatically created and held on the issuer's tenant. This list can be used by external verifiers to validate the credential status. The status.url property references the revocation list which holds the revocation status for this specific credential.