Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
This specification describes a privacy-preserving, space-efficient, and high-performance mechanism for publishing status information such as suspension or revocation of Verifiable Credentials through use of bitstrings.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Verifiable Credentials Working Group as a Working Draft using the Recommendation track.
Publication as a Working Draft does not imply endorsement by W3C and its Members.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 03 November 2023 W3C Process Document.
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.
Our definition of credential differs from, NIST's definitions of credential.
did:example:123456abcdef
.
verifiableCredential
or proof
. These properties
result in separate graphs that contain all claims defined in the
corresponding JSON objects.
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, MUST NOT, and SHOULD 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 |
An optional identifier for the status list entry. The constraints on the
id property are listed in the Verifiable Credentials Data Model
specification [VC-DATA-MODEL]. If present, 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. The value is
not used during the verification or validation process, and does not need to be
related to the statusListCredential value. If necessary, the value can be
used to uniquely identify the BitstringStatusListEntry object, such as when it is
stored in a database.
|
||||||
type |
The type property MUST be BitstringStatusListEntry .
|
||||||
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
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 BitstringStatusListCredential value.
|
{ "@context": [ "https://www.w3.org/ns/credentials/v2" ], "id": "https://example.com/credentials/23894672394", "type": ["VerifiableCredential"], "issuer": "did:example:12345", "validFrom": "2021-04-05T14:27:42Z", "credentialStatus": [ { "id": "https://example.com/credentials/status/3#94567" "type": "BitstringStatusListEntry", "statusPurpose": "revocation", "statusListIndex": "94567", "statusListCredential": "https://example.com/credentials/status/3" }, { "id": "https://example.com/credentials/status/4#23452" "type": "BitstringStatusListEntry", "statusPurpose": "suspension", "statusListIndex": "23452", "statusListCredential": "https://example.com/credentials/status/4" } ], "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
BitstringStatusListEntry (see 2.1 BitstringStatusListEntry).
|
||||||||
type |
The verifiable credential that contains the status list MUST
express a type property that includes the
BitstringStatusListCredential value.
|
||||||||
validFrom | The earliest point in time at which the status list is valid. This property is defined in the Verifiable Credentials Data Model specification in Section 4.6: Validity Period. | ||||||||
validUntil | The latest point in time at which the status list is valid. This property is defined in the Verifiable Credentials Data Model specification in Section 4.6: Validity Period. | ||||||||
credentialSubject.type |
The type of the credential subject, which is the
status list, MUST be BitstringStatusList .
|
||||||||
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. The bitstring MUST be
encoded such that the first index, with a value of zero
(0 ), is located at the left-most bit in the bitstring and the
last index, with a value of one less than the length of the bitstring
(bitstring_length - 1 ), is located at the right-most bit in the
bitstring. Further information on bitstring encoding can be found in Section
5.1 Bitstring Encoding.
|
||||||||
credentialSubject.ttl |
The ttl indicates the "time to live" in milliseconds.
This property MAY be present. If not present, implementers MUST
use a value of 300000 for this property. A verifier
MUST NOT use a cached BitstringStatusListCredential that was
cached for more than the ttl duration prior to the
start of verification operation on a verifiable credential.
Implementations that publish the status list SHOULD align
any protocol-specific caching information, such as the
HTTP Cache-Control header, with the value in this field.
|
||||||||
credentialSubject.size |
The size indicates the size of the status entry in bits.
size MAY be provided. If size is not present
as a property of the credentialStatus , then size
MUST be processed as 1 . size MUST be an integer greater than zero.
If size is provided and is greater than 1 , then the property
credentialStatus.statusMessages MUST be present, and the number of
status messages must equal the number of possible values.
|
||||||||
credentialSubject.statusMessages |
The statusMessages property MUST be an array. If present,
the length of the array must equal the number of possible status states
indicated by size . statusMessages MAY be present if
size is 1 . statusMessages MUST be present if
size is greater than 1 . If not present, the message value
associated with the bit value of 0 is "unset" and the bit
value of 1 is "set".
If present, elements in the statusMessages array MUST contain at
minimum two properties:
statusMessages
array.
Implementers MAY use the string value of undefined in the value
to indicate that a corresponding status is not defined for the associated
status value, but that it may be defined in the future.
Rules for how to handle various status messages are outside the scope of
normative requirements in this document, but it is assumed that implementers
will document rules for processing various status codes.
|
||||||||
credentialSubject.reference |
The reference property provides a point for implementers to
include a [URL] to material related to the status. An implementer MAY include
the reference property, and if they do, the value MUST be a
[URL] or an array of URLs. Implementers using a statusPurpose of status
are strongly encouraged to provide a reference .
Note: Details around reference
|
{ "@context": [ "https://www.w3.org/ns/credentials/v2" ], "id": "https://example.com/credentials/status/3", "type": ["VerifiableCredential", "BitstringStatusListCredential"], "issuer": "did:example:12345", "validFrom": "2021-04-05T14:27:40Z", "credentialSubject": { "id": "https://example.com/status/3#list", "type": "BitstringStatusList", "statusPurpose": "revocation", "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA" }, "proof": { ... } }
The Working Group is still discussing the unification of a design between status lists with a single state (such as "revoked" or "suspended") and status lists with multiple states (exposed via a series of status messages). We are seeking implementer feedback on what a unified design should look like from an ease of implementation, privacy, and security standpoint.
{ "@context": [ "https://www.w3.org/ns/credentials/v2" ], "id": "https://example.com/credentials/status/3", "type": ["VerifiableCredential", "BitstringStatusListCredential"], "issuer": "did:example:12345", "validFrom": "2021-04-05T14:27:40Z", "credentialSubject": { "id": "https://example.com/status/3#list", "type": "BitstringStatusList", "ttl": 500, "statusPurpose": "status", "reference": "https://example.org/status-dictionary/", "size": 2, "statusMessages": [ {"status":"0x0", "value":"valid"}, {"status":"0x1", "value":"invalid"}, {"status":"0x2", "value":"pending_review"}, ... ], "encodedList": "H4sIAAAAAAAAA-3BMQEAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA" } }
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 BitstringStatusListCredential:
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 BitstringStatusListCredential:
credentialStatus
entry that is a
BitstringStatusListEntry.
statusPurpose
in the credentialStatus
entry in the
credentialToValidate.
statusListCredential
URL, and ensure that all
proofs verify successfully. If the dereference fails, or if any of the proof
verifications fail, return a validation error.
statusPurpose
value in the statusListCredential.
encodedList
property of the
BitstringStatusListCredential.
statusListIndex
property of the
BitstringStatusListEntry.
statusPurpose
of revocation
or suspension
,
return true
if status
is 1
, and return false
if status
has any other value. For other statusPurpose
,
return the corresponding value
of the status
as indicated in the statusMessages
array.
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.
bitstring
, if there is a
corresponding statusListIndex
value in
a credential in issuedCredentials
, set the value to the
appropriate status. The position of the value is computed as statusListIndex
times the size
.
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.
In general, the herd privacy protections offered by this specification can be circumvented by malicious issuers and verifiers. Its privacy benefits can only be realized when issuers and verifiers intend to avoid tracking or sharing the presentation of particular credentials.
A malicious issuer might intentionally attack herd privacy by creating a unique status list per credential issued in order to establish a 1-1 mapping to track when a verifier processes a specific credential. Similarly, they could establish another a 1-1 mapping by using a different cryptographic key for every credential issued that is tracked in a status list.
A malicious verifier might intentionally attack herd privacy by sharing information from presented credentials with a malicious issuer.
What prevents the issuer from hosting several status list bitstrings (one for each credential) and embedding a statusListIndex
value that represents one of those bitstrings at issuance time? This loophole would allow a 1:1 mapping between credential and status list, eliminating the herd privacy guarantees that are integral to this spec.
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.
This section is non-normative.
It is critical that implementers pay particular attention to the way that they encode and decode bitstrings. Failure to do so can result in checking the wrong bitstring index for a given credential, leading to a misinterpretation of its present state (e.g., mistaking a revoked status for an unrevoked status). As stated in Section 2.2 BitstringStatusListCredential, bitstrings are encoded such that the first (zeroth) index refers to the left-most bit of the bitstring array. The diagram below demonstrates the proper layout for an uncompressed bitstring.
For example, if a bitstring is 131,072 bits in size (16KB), the first index will be 0, and the last index will be 131,071.
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.
This section is non-normative.
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "https://example.com/credentials/23894672394",
"type": ["VerifiableCredential"],
"issuer": "did:example:12345",
"validFrom": "2021-04-05T14:27:42Z",
"credentialStatus": {
"id": "https://example.com/credentials/status/3#94567",
"type": "BitstringStatusListEntry",
"statusPurpose": "revocation",
"statusListIndex": "94567",
"statusListCredential": "https://example.com/credentials/status/3"
},
"credentialSubject": {
"id": "did:example:6789",
"type": "Person"
}
}
{ "@context": [ "https://www.w3.org/ns/credentials/v2", "https://www.w3.org/ns/credentials/examples/v2" ], "id": "https://example.com/credentials/status/3", "type": ["VerifiableCredential", "BitstringStatusListCredential"], "issuer": "did:example:12345", "validFrom": "2021-04-05T14:27:40Z", "credentialSubject": { "id": "https://example.com/status/3#list", "type": "BitstringStatusList", "statusPurpose": "revocation", "encodedList": "H4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA" } }
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: