A registry-based revocation mechanism for Verifiable Credentials

Copyright © 2022 Named editors and Spherity.

This specification describes a decentralized, registry-based revocation mechanism for Verifiable Credentials on Ethereum. It is based on the EIP-5539 standard draft and leverages its described revocation registry smart contract in which revocation information can be stored and modified in an unlimited amount of revocation lists residing in namespaces.

Comments regarding all aspects of this document are welcome. Please file issues directly on GitHub.

Introduction

The Verifiable Credentials specification describes revocation as one of the key parts of the Verifiable Credentials lifecycle. It allows issuers of credentials to revoke them when appropriate in a way that is transparent to potential verifiers in the future. The VC specification however does not describe a revocation method and only focuses on the general idea with some general requirements and considerations.

Those considerations mainly include privacy concerns in the form of possible deanonymization attacks by an issuer when a verifier checks the revocation status of a credential with it. In the worst case, an issuer might figure out what credential holder presented which credential to which verifier and when. This especially holds true for revocation methods storing the revocation list on an issuer-owned and centralized revocation service. Revocation methods like Status List 2021 leverage such an infrastructure but try to minimize privacy concerns by using revocation lists encoded in a bitstring. Following this pattern, a verifier verifies a credential by retrieving the full revocation list from the issuers server and reading the credential's status from the correct position in the bitstring. For most applications, this approach is sufficient from a privacy perspective but falls short in other critical points.

The largest problem with traditional revocation lists is the centralized aspect of them. Most of them rely on HTTP servers as well as caching and are therefore vulnerable to known attack vectors, which include unavailability or illegal modification of the revocation list. Depending on the ecosystem, an unavailable and untrustworthy revocation list may make verifications impossible for an undefined timespan and therefore present an unacceptable business risk. Other noteworthy aspects are historical preservation of revocation information, the burden of owning and maintaining revocation infrastructure, and inflexibility in terms of revocation list management features (e.g. delegation).

The rest of the document proposes a new revocation method based on the EIP-5539 standard draft that leverages a decentralized revocation registry inside an Ethereum smart contract. It allows any Ethereum address to manage an unlimited number of revocation lists in its namespace, where each list can hold an unlimited amount of revocation keys. Because revocation lists are hosted on the blockchain, issuers can't correlate sensitive information anymore, like at what moment a verifier retrieves revocation information. Other positive aspects are the increased herd privacy due to huge namespaces and revocation lists, the infrastructure being always available, infrastructure does not have to be maintained by issuers, and the ability to program smart management features into the registry itself (meta transactions, ownerchanges, delegation, ...).

Terminology

Concept

This section describes the core concepts of this specification. Revocations are stored in revocation lists as a key-value pair of a bytes32 string to a boolean value. The boolean value indicates the status of the revocation keywhere true is revoked. Revocation lists are identified by a bytes32 string key that are part of a namespace. Namespaces are represented by Ethereum addresses and can, due to the bytes32 size of revocation list keys, can contain an unlimited amount of revocation lists that are implicitly owned by the namespaces address. The described behaviour can be seen in figure 1.
diagram showing how multiple namespace nodes are connected to a registry< node. Each namespace node points to multiple revocation list nodes that point to multiple revocation key nodes. Each revocation key node has a revoked status inside its node that represents the revocation status of that particular revocation key.
A visual depiction of the concepts.
This architecture enables a decentralized and general-purpose revocation registry that can be used by any Ethereum address without any previous deployment of smart contracts or self-managed infrastructure. Due to amount of Ethereum addresses and the key type of bytes32 for revocation lists and revocation keys , there is an infinite amount of revocation lists and revocation keys that can be stored in the registry. Due to the nature of the underlying data structures used in the registry, all possible namespaces and their revocation lists and revocation keys are already initialized with zero values. This means that there is no writing action needed when issuing a revocable credential with this method. Only when a credential needs to be revoked, data is written to the chain. Consequently, revocation information of a credential is only recorded on-chain when its status is changed. The underlying registry also provides multiple management features for namespace owners. These features include:

Data Model

When a credential issuer wants to issue a revocable credential, it MAY embed a credentialStatus property to credential. The following table defines the data model for this specification.

Value Description
id The id property MUST be a URL that uniquely identifies the status information associated with the revocable credential.
type The type property MUST be EthrRevocationRegistry2022.
registry The registry property MUST be an Ethereum address that uniquely identifies the registry that contains all revocation information.
chainId The chainId property MUST be a number that represents the chain id of the Ethereum network where the registry is deployed to.
namespace The namespace property MUST be a string that represents the Ethereum address of the namespace that the revocation list is part of. In most cases, this is the issuers Ethereum address.
revocationList The revocationList property MUST be a bytes32 string that represents the key of the revocation list that the revocation key is part of. The Keccak256 hashing algorithm CAN be used to generate a fitting value.
revocationKey The revocationKey property MUST be a bytes32 string that represents the key that is used to check the revocation status of the credential. The Keccak256 hashing algorithm CAN be used to generate a fitting value.

The above defined properties are needed to resolve the credentials status on the registry. An example usage of those properties can be seen in example 1 below.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://w3id.org/vc/status-list/2021/v1"
    "https://spherity.github.io/vc-ethr-revocation-registry/schemas/ethr-revocation-registry.jsonld"
  ],
  "id": "https://example.com/credentials/1",
  "type": ["VerifiableCredential"],
  "issuer": "did:example:12345",
  "issued": "2022-03-26T14:27:42Z",
  "credentialStatus": {
    "id": "https://example.com/credentials/1/status"
    "type": "EthrRevocationRegistry2022",
    "registry": "0x534b89b798e45929A24a217d7324EAd0EAF9413E",
    "chainId": 1,
    "namespace": "0x0000000000000000000000000000000000000000",
    "revocationList": "0x3458b9bfc7963978b7d40ef225177c45193c2889902357db3b043a4e319a9628",
    "revocationKey": "0x89343794d2fb7dd5d0fba9593a4bb13beaff93a61577029176d0117b0c53b8e6"
  },
  "credentialSubject": {
    "id": "did:example:6789",
    "type": "Person"
  },
  "proof": { ... }
}

Privacy Considerations

Write privacy considerations.