Status List exercises
Status list exercises and explanation
Prerequisites
In the below exercises we will be creating a status list and then managing individual status list entries. Please read the status list introduction page first that explains the concept of status lists.
The status lists are independent of any transport protocols, like OID4VC, DIDComm, VC API, hence why status list management has its own API endpoints. Obviously you can define which status list to use during issuance in for instance the W3C VC API or OID4VCI
StatusList
Exercise 1: Create a new status list
Please use the create-status-list API (docs) or
API (swaggerhub) to create a new OAuth/Token Status List
This means using type of "OAuthStatusList" and a proofFormat of "jwt".
We suggest the length to be at least 50K (50000). Reason is that we want to achieve herd privacy (read the status list introduction). Once individual status list entries will be created, they will have random indexes withing your length-range, to make guessing of status list indices impossible improving privacy.
bitsPerStatus value at 1 for OAuthStatusList. Although the API should support other values as well, full support in wallet and other components is not
there yetid and correlationId. Make sure your values are different, otherwise you might get results you are not
expecting, given the documentation instance is shared by everyone. So do not use the default values, as
others might be working on your objects whilst you are performing the exercise!The expected outcome should be an HTTP response with something like:
The above is a JWT encoded Status List example. This is what a Relying Party or Wallet will download whenever checking a credential.
lst object in the status_list object. That is the actual list
containing all the indices (in base64 en with compression)Exercise 2: Check a (hopefully) unused index value
We are now going to check an index value of your choosing from the newly created status list. Pick a random number between 0 and 10000. Make sure to take a note of the number because we will use it later as well.
In this exercise we are going to use an endpoint only suitable for the issuer of credentials. It normally should be protected, since it allows you to query by entry index or correlationId. Which would mean it would leak potential correlation information over time if it were to be used by wallets or Relying parties.
Please use the get-status-list-entry-by-id API (docs) or
API (swaggerhub) to get an individual entry by statusList id or correlation id and by status index or correlation id. This means you can choose how you want to lookup the value. We advice you to use correlation Ids for both the status list and for individual entries. This allows you to use business keys from your line of business system as identifiers. Making it easier to keep track of the relation ship between your data en the associated credential.
Since we will check for a random entry that is not yet saved, we will fetch the entry by status list index with the random value you have choosen.
This means using an statusListId:
- The id value of the previously created status list if you use query parameter
statusListIdTypewith valueStatusListId - The correlation Id value of the previously created status list if you use query parameter
statusListIdTypewith valueCorrelationId
We will use a entryId with:
- The random value (number) you have chosen. With query parameter
entryIdTypecontainingStatusListIndex
The expected outcome should be an HTTP response with something like:
Note that the value should be “0” meaning that the index is valid (not revoked).
Exercise 3: Revoke by index value
We are now going to revoke the index you have previously chosen.
Please use the update-credential-status API (docs) or
API (swaggerhub) to update the value.
We are going to use a value of “1” for the status, to indicate that the index is revoked (see the statuslist specification for details).
In the body of the revocation request there are 2 options to pick the correct status list
- The id value of the previously created status list if you will set the
statusListId - The correlation Id value of the previously created status list if you will set the
statusListCorrelationIdproperty
We will use a statusListIndex with:
- The random value (number) you have chosen
You can set a entryCorrelationId of your choosing, which normally would be a unique business key. This value will be stored internally, so you can later only use this value instead of the statusListIndex in case you want.
The expected outcome should be an HTTP response containing a new statuslist with something like:
Exercise 4: Repeat exercise 2 and get the entry index again
Repeat exercise 2.
This time around the outcome should be like below:
The expected outcome should be an HTTP response with something like below (note the status “1” instead of the previous “0”):
OID4VCI issuance with status lists
Now that we have seen how to create a new status list and how to update entries in a status list it is time to see it come together with a transport protocol, like the W3C VC API, DIDComm v2 or in these exercises with OpenID for Verifiable Credentials Issuance (OID4VCI).
Our OID4VCI REST API automatically assigns a status list and random status list index provided that:
- The credential payload contains a status list object with a valid status list URL that the agent manages. For instance for an
SD-JWTcredential that would be{"status": {"status_list": "https://statuslist.example.com/1" }} - The use the
statusListarray as part of the create offer payload, containing an object that references a status list the agent manages
Exercise 5: Create an offer with status list support
As mentioned above. Please make sure to have performed the OID4VCI exercises first!
Now we are going to issue a new credential that uses the status list you created above. We will let it automatically assign a random status list index to the credential once issued, to ensure herd privacy (see introduction)
Please use the create-credential-offer API (docs) or
API (swaggerhub) to create a simple so-called credential offer by value using a pre-authorized_code grant with qrCodeOpts.
This means using an offerMode of "VALUE" and a grants object containing an object of urn:ietf:params:oauth:grant-type:pre-authorized_code with a pre-authorized_code value of your choosing. Use a credential_configuration_id with value "PensionSdJwt" and add a "qrCodeOpts" object with value {"size": 400} and a statusList array looking like this:
Now you should get a response that looks like below:
Copy the entire value between quotes (excluding the quotes) of the qrCodeDataUri and paste that into your address bar in a new browser tab. You now should see a QR code.
You can now scan the QR code with your wallet or mobile device and you should get an additional credential issued to your wallet. This credential is like any other credential.
Exercise 6: Revoke by entry correlation id and check with the wallet
We are now going to revoke the entry you have previously chosen.
Please use the update-credential-status API (docs) or
API (swaggerhub) to update the value.
We are going to use a value of “1” for the status, to indicate that the index is revoked (see the statuslist specification for details).
In the body of the revocation request there are 2 options to pick the correct status list
- The id value of the previously created status list if you will set the
statusListId - The correlation Id value of the previously created status list if you will set the
statusListCorrelationIdproperty
We will use a entryCorrelationId with:
- The value you have provided in the previous exercise
The expected outcome should be an HTTP response containing a new statuslist with something like:
Now try to present your credential with the wallet to a Relying Party that can accept the credential. You should see that the Relying Party will not accept the credential because it is revoked.