Revocation Tutorial
Introduction
In this tutorial we will explore the concept of credential revocation, a critical feature that allows issuers to invalidate previously issued credentials, ensuring the integrity and security of the system. The tutorial comprises the following steps:
- Issue a revocable credential.
- Obtain a credential revocation status.
- Revoke an issued credential.
- Attempt to verify a revoked credential.
Prerequisites
- Complete the sign up form to get access to a MATTR VII trial tenant.
- Make sure you are comfortable with how to:
We recommend using the MATTR VII Postman collection in this tutorial. While this isn’t an explicit prerequisite, it can really speed things up.
Tutorial steps
Issue a revocable credential
The first thing you need to do is sign a new credential in a way that will enable you to revoke it later. This will differ slightly based on your selected credential format.
- Follow the tutorial to issue an mDoc via the OID4VCI protocol.
Obtain a credential revocation status
Now that the credential is issued, different relying parties might be interested in discovering its revocation status. In other words, they want to know whether or not the credential has been revoked by the issuer. MATTR VII supports two ways of achieving this:
- Query a protected MATTR VII endpoint to get the revocation status.
- Query public MATTR VII endpoints to get the revocation status.
Again, this process looks slightly different for different credential formats.
Protected endpoint
Request
Make a request of the following structure to retrieve the status of an mDoc:
GET /v2/credentials/mobile/{credentialId}/status
credentialId
: Replace with theid
of the mDoc you wish to check the status for.
You can retrieve the credentialId
by querying the
Retrieve all users credentials data
endpoint with the identifier of the user you issed the credential to, and retrieve the id
from the
response.
Response
{
"status": "valid"
}
status
: Indicates status for the mDoc. This it the expected value as we have only now issued this mDoc.
Public endpoint
MATTR VII enables relying parties to obtain the status of an mDoc in a privacy preserving manner, as the issuer has no way of knowing what specific mDoc’s status the relying party is requesting.
This is achieved by retrieving a publicly available Status list token, and then looking up a specific mDoc’s status using a reference index that is included in the mDoc itself. These Status lists are based on the IETF Token Status list draft.
Request
Make a GET request to the status.status_list.uri
element from the response obtained when signing
the mDoc:
GET https://learn.vii.au01.mattr.global/v2/credentials/mobile/status-lists/f331c9be-f526-4577-bbac-ae93d6228f7a/token
Response
The response includes an encoded Status list token which is a
CBOW Web Token. Relying parties can then decode the
list and use the mDoc’s status.status_list.idx
element to locate and check the
status of this specific mDoc.
Revoking an issued credential
Next we will learn how to revoke issued credentials. The process is very similar for different credential formats but uses different MATTR VII endpoints
Request
Make a request of the following structure to revoke an mDoc:
POST /v2/credentials/mobile/{credentialId}/status
credentialId
: Replace with theid
of the mDoc you wish to revoke.
Request body
{
"status": "suspended"
}
Response
{
"status": "suspended"
}
status
: This is now set tosuspended
, which means the mDoc should not be verified as valid.
Attempting to verify a revoked credential
The last step will be attempting to verify the revoked credential. This step is also similar across different credential formats, using different endpoints.
Request
Make a request of the following structure to verify a CWT credential:
POST /v2/credentials/compact/verify
Request body
{
"payload": "CSC:/1/2KCE3IQEJB5DCMSMGZITM5QBE2QFSALWVQAXQI3ENFSDU53FMI5GYZLBOJXC45TJNEXGC5JQGEXG2YLUORZC4Z3MN5RGC3AFDJSZE7YQHIAACAACOFBW65LSONSSAQ3SMVSGK3TUNFQWYBA2NFLDPEDENZQW2ZLPIVWW2YJAJJQW4ZJAKRQXG3LBMRRW6ZDFMZEFGLRSG44HCY3FOJ2GSZTJMNQXI2LPNZHGC3LFOJLW64TLNFXGOIDBOQQEQZLJM5UHI43SMNSXE5DJMZUWGYLUNFXW4TDFOZSWYZ2MMV3GK3BAGRVGS43TOVSXETTBNVSXQGCBMR3GC3TDMVSCAU3BMZSXI6JAKRZGC2LONFXGOZTFPBYGS4TZNIZDAMRWFUYDCLJQGE5AAAIAACRAEAYDPB2WQ5DUOBZTULZPNRSWC4TOFZ3GS2JOMF2TAMJONVQXI5DSFZTWY33CMFWC6Y3POJSS65RSF5RXEZLEMVXHI2LBNRZS6Y3PNVYGCY3UF5ZGK5TPMNQXI2LPNYWWY2LTORZS6OBYG5RWIMJUGAWWKNDEG4WTINJRHAWWENZQMYWTGMBVMIZDGNZXHA4DIOAH3BAFA3FHFPDIRRKK4SM3ZDTKQSRCPRCYIA7RFUZYQI3RIGDHIGLAODJ6K2F245DTLIIKXAD35TORFQ7MVRJCIEPH6SC6NGA4HRMK76H5V6GXP66FFNX7MNYC6MYVU7ZLLXYVLXBU",
"checkRevocation": true
}
payload
: Replace with theencoded
element from the response obtained when signing the credential.checkRevocation
: This is the property that makes this verification request check for the credential revocation status.
Response
{
"verified": false,
"reason": {
"type": "Revoked",
"message": "Credential has been revoked"
}
// Rest of response
}
verified
: As expected, the credential had failed verification.reason
: Details that the credential had failed verification since it has been revoked.
Revocation lists are cached for a certain amount of time, so you might need to wait a few minutes before verification would actually fail.
Summary
In this tutorial you learned how to manage credential revocation, including:
- How to issue a revocable credential.
- How to check the revocation status of a credential as an Issuer and as a relying party.
- How to revoke a credential.
You can now use integrate these capabilities into your solution to support this important feature.