Copyright © 2023 the Contributors to the Status List 2021 Specification, published by the Credentials Community Group under the W3C Community Final Specification Agreement (FSA). A human-readable summary is available.
This specification describes a privacy-preserving, space-efficient, and high-performance mechanism for publishing status information such as suspension or revocation of Verifiable Credentials.
This specification was published by the Credentials Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Final Specification Agreement (FSA) other conditions apply. Learn more about W3C Community and Business Groups.
This document is experimental and is undergoing heavy development. It is inadvisable to implement the specification in its current form. An experimental implementation is available.
GitHub Issues are preferred for discussion of this specification. Alternatively, you can send comments to our mailing list. Please send them to public-credentials@w3.org (subscribe, archives).
This section is non-normative.
It is often useful for an issuer of verifiable credentials [VC-DATA-MODEL] to link to a location where a verifier can check to see if a credential has been suspended or revoked. There are a variety of privacy and performance considerations that are made when designing, publishing, and processing status lists.
One such privacy consideration happens when there is a one-to-one mapping between a verifiable credential and a URL where the status is published. This type of mapping enables the website that publishes the URL to correlate the holder, time, and verifier when the status is checked. This could enable the issuer to discover the type of interaction the holder is having with the verifier, such as providing an age verification credential when entering a bar. Being tracked by the issuer of a driver's license when entering an establishment violates a privacy expectation that many people have today.
Similarly, there are performance considerations that are explored when designing status lists. One such consideration is where the list is published and the burden it places from a bandwidth and processing perspective, both on the server and the client fetching the information. In order to meet privacy expectations, it is useful to bundle the status of large sets of credentials into a single list to help with herd privacy. However, doing so can place an impossible burden on both the server and client if the status information is as much as a few hundred bytes in size per credential across a population of hundreds of millions of holders.
The rest of this document proposes a highly compressible, bitstring-based status list mechanism with strong privacy-preserving characteristics, that is compatible with the architecture of the Web, is highly space-efficient, and lends itself well to content distribution networks. As an example of using this specification to achieve a number of beneficial privacy and performance goals, it is possible to create a status list that can be constructed for 100,000 verifiable credentials that is roughly 12,500 bytes in size in the worst case. In a case where a few hundred credentials have been revoked, the size of the list is less than a few hundred bytes while providing privacy in a herd of 100,000 individuals.
This section is non-normative.
This section outlines the core concept utilized by the status list mechanism described in this document. At the most basic level, status information for all verifiable credentials issued by an issuer are expressed as simple binary values. The issuer keeps a bitstring list of all verifiable credentials it has issued. Each verifiable credential is associated with a position in the list. If the binary value of the position in the list is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked.
One of the benefits of using a bitstring is that it is a highly compressible data format since, in the average case, large numbers of credentials will remain unrevoked. This will ensure long sections of bits that are the same value and thus highly compressible using run-length compression techniques such as GZIP [RFC1952]. The default bitstring size is 16KB (131,072 entries), and when only a handful of verifiable credentials are revoked, the compressed bitstring size is reduced down to a few hundred bytes.
Another benefit of using a bitstring is that it enables large numbers of verifiable credential statuses to be placed in the same list. This specification utilizes a minimum bitstring length of 131,072 (16KB). This population size ensures an adequate amount of herd privacy in the average case. If better herd privacy is required, the bitstring can be made to be larger.
This section is non-normative.
The following terms are used to describe concepts in this specification.
did:example:123456abcdef
.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, and MUST NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
The following sections outlines the data model for this document.
When an issuer desires to enable status information for a
verifiable credential, they MAY add a credentialStatus
property that uses the data model described in this specification.
Property | Description | ||||||
---|---|---|---|---|---|---|---|
id |
The constraints on the id property are listed in the
Verifiable Credentials Data Model specification [VC-DATA-MODEL]. The
value is expected to be a URL that identifies the status information associated
with the verifiable credential. It MUST NOT be the URL for the
status list.
|
||||||
type |
The type property MUST be StatusList2021Entry .
|
||||||
statusPurpose |
The purpose of the status entry MUST be a string. While the value of the
string is arbitrary, the following values MUST be used for their intended
purpose:
|
||||||
statusListIndex |
The statusListIndex property MUST be an arbitrary size integer
greater than or equal to 0, expressed as a string. The value identifies the bit
position of the status of the verifiable credential.
|
||||||
statusListCredential |
The statusListCredential property MUST be a URL to a
verifiable credential. When the URL is dereferenced, the resulting
verifiable credential MUST have type property that
includes the StatusList2021Credential value.
|
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://w3id.org/vc/status-list/2021/v1" ], "id": "https://example.com/credentials/23894672394", "type": ["VerifiableCredential"], "issuer": "did:example:12345", "issued": "2021-04-05T14:27:42Z", "credentialStatus": { "id": "https://example.com/credentials/status/3#94567" "type": "StatusList2021Entry", "statusPurpose": "revocation", "statusListIndex": "94567", "statusListCredential": "https://example.com/credentials/status/3" }, "credentialSubject": { "id": "did:example:6789", "type": "Person" }, "proof": { ... } }
When a status list is published, the result is a verifiable credential that encapsulates the status list. The following section describes the format of the verifiable credential that encapsulates the status list:
Property | Description | ||||||
---|---|---|---|---|---|---|---|
id |
The verifiable credential that contains the status list MAY
express an id property that matches the value specified in
statusListCredential for the corresponding
StatusList2021Entry (see 2.1 StatusList2021Entry).
|
||||||
type |
The verifiable credential that contains the status list MUST
express a type property that includes the
StatusList2021Credential value.
|
||||||
credentialSubject.type |
The type of the credential subject, which is the
status list, MUST be StatusList2021 .
|
||||||
credentialSubject.statusPurpose |
The purpose of the status entry MUST be a string. While the value of the
string is arbitrary, the following values MUST be used for their intended
purpose:
|
||||||
credentialSubject.encodedList |
The encodedList property of the credential subject MUST be
the GZIP-compressed [RFC1952], base-64 encoded [RFC4648] bitstring values
for the associated range of verifiable credential status values. The
uncompressed bitstring MUST be at least 16KB in size.
|
{ "@context": [ "https://www.w3.org/2018/credentials/v1", "https://w3id.org/vc/status-list/2021/v1" ], "id": "https://example.com/credentials/status/3", "type": ["VerifiableCredential", "StatusList2021Credential"], "issuer": "did:example:12345", "issued": "2021-04-05T14:27:40Z", "credentialSubject": { "id": "https://example.com/status/3#list", "type": "StatusList2021", "statusPurpose": "revocation", "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA" }, "proof": { ... } }
The following section outlines the algorithms that are used to generate and validate status lists as described by this document.
The following process, or one generating the exact output, MUST be followed when producing a StatusList2021Credential:
encodedList
property set.
encodedList
to compressed bitstring.
The following process, or one generating the exact output, MUST be followed when validating a verifiable credential that is contained in a StatusList2021Credential:
credentialStatus
entry that is a
StatusList2021Entry.
statusPurpose
in the credentialStatus
entry in the
credentialToValidate.
statusPurpose
value in the statusListCredential.
encodedList
property of the
StatusList2021Credential.
statusListIndex
property of the
StatusList2021Entry.
true
if status is 1, false
otherwise.
The following process, or one generating the exact output, MUST be followed when generating a status list bitstring. The algorithm takes a issuedCredentials list as input and returns a compressed bitstring as output.
statusListIndex
value in
a revoked credential in issuedCredentials, set the bit to
1 (one), otherwise set the bit to 0 (zero).
The following process, or one generating the exact output, MUST be followed when expanding a compressed status list bitstring. The algorithm takes a compressed bitstring as input and returns a uncompressed bitstring as output.
This section is non-normative.
This section details the general privacy considerations and specific privacy implications of deploying this specification into production environments.
This section is non-normative.
This document specifies a minimum revocation bitstring length of 131,072, or 16KB uncompressed. This is enough to give holders an adequate amount of herd privacy if the number of verifiable credentials issued is large enough. However, if the number of issued verifiable credentials is a small population, the ability to correlate an individual increases because the number of allocated slots in the bitstring is small. Correlating this information with, for example, where the geographic request came from can also help to correlate individuals that have received a credential from the same geographic region.
This section is non-normative.
It is possible for verifiers to increase the privacy of the holder whose verifiable credential is being checked by caching status lists that have been fetched from remote servers. By caching the content locally, less correlatable information can be inferred from verifier-based access patterns on the status list.
This section is non-normative.
The use of content distribution networks by issuers can increase the privacy of holders by reducing or eliminating requests for the status lists from the issuer. Often, a request for a revocation list will be served by an edge device and thus be faster and reduce the load on the server as well as cloaking verifiers and holders from issuers.
This section is non-normative.
There are a number of security considerations that implementers should be aware of when processing data described by this specification. Ignoring or not understanding the implications of this section can result in security vulnerabilities.
While this section attempts to highlight a broad set of security considerations, it is not a complete list. Implementers are urged to seek the advice of security and cryptography professionals when implementing mission critical systems using the technology outlined in this specification.
Write security considerations.
This section is non-normative.
There are a number of accessibility considerations implementers should be aware of when processing data described in this specification. As with any web standards or protocols implementation, ignoring accessibility issues makes this information unusable to a large subset of the population. It is important to follow accessibility guidelines and standards, such as [WCAG21], to ensure all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which have historically created problems for assistive technologies.
This section details the general accessibility considerations to take into account when utilizing this data model.
Write accessibility considerations.
This section is non-normative.
There are a number of internationalization considerations implementers should be aware of when publishing data described in this specification. As with any web standards or protocols implementation, ignoring internationalization makes it difficult for data to be produced and consumed across a disparate set of languages and societies, which would limit the applicability of the specification and significantly diminish its value as a standard.
This section outlines general internationalization considerations to take into account when utilizing this data model.
Write i18n considerations.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: