JavaScriptKotlinSwift

Revoking Verifiable Credentials

Revoking verifiable credentials (VCs) is a crucial aspect of maintaining their integrity and trustworthiness. In this guide, we will explore the mechanisms and best practices for revoking verifiable credentials, ensuring they remain accurate and reliable over time.

Create a Status List Credential

A Status List Credential is a specialized type of verifiable credential created by VC issuers to maintain a list of the statuses of other credentials, specifically focusing on those that have been revoked. This list is hosted online to allow verifiers to quickly determine the validity of a credential.

JavaScript

Kotlin

Swift

Example of Status List Credential

{
  "vcDataModel": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://w3id.org/vc/status-list/2021/v1"
    ],
    "type": [
      "VerifiableCredential",
      "StatusList2021Credential"
    ],
    "id": "https://example.com/credentials/status/1",
    "issuer": "did:dht:9yiocuhw16grn1ityjcij3g4qrkwq65oh3x8qptbduybgaymbmoo",
    "issuanceDate": "2024-07-26T01:41:06Z",
    "credentialSubject": {
      "id": "https://example.com/credentials/status/1",
      "type": "StatusList2021",
      "statusPurpose": "revocation",
      "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
    }
  }
}

Issue a Revocable Credential

Verifiable credentials are immutable, so an issuer cannot change the content of the VC after it is issued. However, the issuer can include a credentialStatus property when issuing the credential. This links the credential to its entry in the status list, allowing issuers to update its status at any time and verifiers to check the credential's status.

JavaScript

Kotlin

Swift

Properties of credentialStatus

• id: URL that identifies the status information associated with the verifiable credential. It must not be the URL for the status list itself, but rather a unique identifier for the status entry within the status list​.

• type: The type of status entry, which must be StatusList2021Entry, indicating it follows the Status List 2021 standard.

• statusPurpose: The purpose of the status entry. Common values are revocation for permanently invalidating a credential and suspension for temporarily invalidating it.

• statusListIndex: An integer value (expressed as a string) identifying the bit position in the status list's bitstring that corresponds to the credential's status. A bit value of 0 means the credential is valid, while a bit value of 1 indicates it has been revoked. This efficient encoding allows for quick status checks by verifiers.

• statusListCredential: URL pointing to the Status List Credential, which contains the bitstring encoding the status of multiple credentials. This URL allows verifiers to retrieve and check the status list.

Example of Revocable VC

{
  "vcDataModel": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://w3id.org/vc/status-list/2021/v1"
    ],
    "type": [
      "VerifiableCredential",
      "StreetCred"
    ],
    "id": "urn:uuid:fddff3ca-cdee-403c-95d0-70608fc0b3d9",
    "issuer": "did:dht:9yiocuhw16grn1ityjcij3g4qrkwq65oh3x8qptbduybgaymbmoo",
    "issuanceDate": "2024-07-26T01:41:06Z",
    "credentialSubject": {
      "id": "did:dht:phaphcrybzdkxttu74nsuu9hyjxe19bzwymn8g18gac7ci1ifuoo",
      "streetCred": "high",
      "legit": true
    },
    "credentialStatus": {
      "id": "https://example.com/credentials/status/1#94567",
      "type": "StatusList2021Entry",
      "statusPurpose": "revocation",
      "statusListIndex": "94567",
      "statusListCredential": "https://example.com/credentials/status/1"
    }
  }
}

Revoking a VC

To revoke a Verifiable Credential, the issuer must add the credential to a StatusListCredential. To do this, the issuer must create a new StatusListCredential with an updated list of their revoked credentials, then upload this updated StatusListCredential to the same URL as the previous one.

JavaScript

Kotlin

Swift

Note the encodedList holds the compressed bitstring.

Example of Updated Status List Credential

{
  "vcDataModel": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://w3id.org/vc/status-list/2021/v1"
    ],
    "type": [
      "VerifiableCredential",
      "StatusList2021Credential"
    ],
    "id": "https://example.com/credentials/status/1",
    "issuer": "did:dht:9yiocuhw16grn1ityjcij3g4qrkwq65oh3x8qptbduybgaymbmoo",
    "issuanceDate": "2024-07-26T01:41:06Z",
    "credentialSubject": {
      "id": "https://example.com/credentials/status/1",
      "type": "StatusList2021",
      "statusPurpose": "revocation",
      "encodedList": "H4sIAAAAAAAAA-3OMQ0AAAgDsOHfNBp2kZBWQRMAAAAAAAAAAAAAAL6Z6wAAAAAAtQVQdb5gAEAAAA"
    }
  }
}

Check VC Status

To check the status of a verifiable credential, the verifier can do the following:

1. Parse the presented verifiable credential to get the credentialStatus object.
2. Fetch the StatusListCredential from the URI in the object to retrieve the credential.
3. Pass the presented credential and the StatusListCredential to the validateCredentialInStatusList() method as shown below. It will return true if revoked.

JavaScript

Kotlin

Swift